claude-agent

Files (3)

• SKILL.md
• claude-agent.mjs · scripts/
• claude-monitor.mjs · scripts/

SKILL.md (first lines)

# Claude Agent (wrapper)

> **This runs an autonomous agent with permission prompts disabled.**
> The default permission mode is `bypassPermissions`, because a
> non-interactive run has no one to answer a prompt. The child agent can read,
> write and execute in whatever directory you launch it from. Only give it
> briefs you would be willing to run yourself, and set
> `CLAUDE_PERMISSION_MODE` if you want something stricter.

## Execution

Works in both foreground and background:

```
# Foreground (blocks until done - use a long timeout, runs can take minutes)
Bash(command: "node \"~/.claude/skills/claude-agent/scripts/claude-agent.mjs\" Your prompt here", timeout: 600000)

# Background (non-blocking - you are notified when it finishes)
Bash(command: "node \"~/.claude/skills/claude-agent/scripts/claude-agent.mjs\" Your prompt here", run_in_background: true)
```

Background is preferred when launching multiple agents in parallel.

---

Thin wrapper around `claude -p` (Claude Code CLI) for non-interactive use:

- Provide the prompt via arguments, `PROMPT_FILE`, or stdin (briefs are byte-exact)
- Model selection via `--model` or `CLAUDE_MODEL`
- TRUE session resume via `--resume` / `--continue` or `CLAUDE_SESSION`
- Pre-assign a session id via `--session-id` so the caller owns the handle
- Opt-in live phase/liveness monitor via `--monitor` / `CLAUDE_MONITOR=1`
- Clean reply and session id read straight out of the JSON result — no scraping

## Prerequisites

- **Node 18 or newer** (`node --version`)
- **Claude Code CLI**: `npm install -g @anthropic-ai/claude-code`

Nothing else. The wrapper is a single Node script with no dependencies, so it
does not need bash, `jq`, `python3`, `uuidgen`, GNU grep or GNU sort. It runs
the same on Linux, macOS, WSL, and Windows (PowerShell, cmd, or Git Bash).

## Usage

```bash
# Arguments
node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" Your prompt here

# File via env var (preferred for big briefs - byte-exact off stdin)
PROMPT_FILE=task.md node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs"

# Stdin
cat task.md | node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs"
```

On Windows PowerShell the `VAR=value command` prefix form is not valid syntax.
Use `$env:PROMPT_FILE="task.md"` on its own line first, then run the command.

### Session Resume

```bash
# Resume most recent session in this cwd
node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" --resume latest "Follow-up question"

# Resume by UUID (true resume - preserves full prior context)
node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" --resume 019bf3a2-40ce-7923-b501-3d4ebd00aed3 "Continue"

# Via environment variable
CLAUDE_SESSION=latest node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" "Follow-up"
```

### Pre-assign a Session ID

For NEW sessions the wrapper generates a UUID up-front, so the orchestrator
owns the handle before any output returns. Force a specific id with:

```bash
node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" --session-id <UUID> "Your prompt"
# or
CLAUDE_SESSION_ID=<UUID> node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" "Your prompt"
```

### Model Selection

```bash
# Via flag (alias or full id)
node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" --model sonnet "Your prompt"

# Via environment variable
CLAUDE_MODEL=sonnet node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" "Your prompt"
```

Omit the model to use the CLI default.

### Monitor Mode (live liveness)

Opt-in. Streams live phase and liveness lines to **stderr** while the run is in
flight, and still returns the final reply and session id on **stdout**. The
`[output_file:]` and `[session_id:]` contract is identical to the default mode,
so callers never have to branch.

```bash
PROMPT_FILE=task.md node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" --monitor

# Equivalent via env var alone
CLAUDE_MONITOR=1 node "~/.claude/skills/claude-agent/scripts/claude-agent.mjs" "Your prompt"
```

Monitor mode runs claude with `--output-format stream-json --verbose
--include-partial-messages --include-hook-events`, writes the raw NDJSON to a
sibling `.ndjson` file, feeds the same lines to the bundled
`claude-monitor.mjs` in-process, and extracts the reply and session id from the
terminal `result` event. Stderr shows phase transitions (`thinking` ->
`tool:<name>` -> `idle-between` -> `done`) and declares `STALLED!!` on silence
outside an open tool or hook bracket.

## Environment Variables

From TheSylvester/agentic-coding-tools, MIT.

More from TheSylvester/agentic-coding-tools