claude-code-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Claude Code Agent Skill

Run an agentic task on the local device via the `claude` CLI (Claude Code).

## How to choose between blocking and async mode

| Use **blocking** (`async: false`) | Use **async** (`async: true`)           |
| --------------------------------- | --------------------------------------- |
| Quick one-shot tasks (<30s)       | Long builds, refactors, multi-file work |
| Single follow-up questions        | Parallel agents / multiple worktrees    |
| Simple shell automation           | Tasks that may take minutes             |

**Default heuristic:** if the task sounds like it will take more than ~20 seconds (build, analyse a big repo, write many files), use async mode.

---

## Mode A — Blocking (quick tasks)

```bash
cd "${workdir:-$HOME}" && \
claude \
  --print \
  --output-format json \
  --model "${model:-sonnet}" \
  --max-budget-usd "${budget_usd:-2.0}" \
  ${session_id:+--resume "$session_id"} \
  ${skip_permissions:+--dangerously-skip-permissions} \
  ${worktree:+-w "$worktree"} \
  --allowedTools "Bash,Edit,Read,Write,Glob,Grep,LS,Task,TodoRead,TodoWrite,WebFetch,WebSearch" \
  "$prompt"
```

Parse the JSON result:

- `result` — final text answer / summary
- `session_id` — save this to resume later
- `is_error` / `stop_reason` — detect failures
- `total_cost_usd` — report cost to the user

---

## Mode B — Async (long-running tasks, non-blocking)

Async mode always uses `--dangerously-skip-permissions` because the process runs
without a TTY and cannot respond to interactive permission prompts. The
`skip_permissions` parameter is only relevant for blocking mode (Mode A).

Uses the native `process` tool — no tmux required.

### Step 1: Write the prompt to a temp file

Use the `bash` tool to write the prompt safely (avoids all shell escaping/injection
issues with multi-line or quote-heavy prompts):

```bash
PROMPT_FILE="/tmp/cca-$(date +%s).prompt"
cat > "$PROMPT_FILE" << 'PROMPT_EOF'
${prompt}
PROMPT_EOF
echo "$PROMPT_FILE"
```

### Step 2: Start the agent

Use `process action:start` — returns a `session_id` immediately:

```
process action:start
  command: "cat \"$PROMPT_FILE\" | claude --print --output-format json --model ${model:-sonnet} --max-budget-usd ${budget_usd:-2.0} --dangerously-skip-permissions ${session_id:+--resume \"$session_id\"} ${worktree:+-w \"$worktree\"} --allowedTools \"Bash,Edit,Read,Write,Glob,Grep,LS,Task,TodoRead,TodoWrite,WebFetch,WebSearch\""
  workdir: "${workdir:-$HOME}"
```

→ Save the returned `session_id`. Report it to the user immediately. Do NOT wait.

### Step 3: Poll for completion

When the user asks for a status update (or after a reasonable wait), check:

```
process action:poll
  session_id: "<session_id from step 2>"
```

- `running: true` → still working, check again later
- `running: false` + `exit_code: 0` → done successfully → proceed to step 4
- `running: false` + `exit_code: <non-zero>` → failed → fetch logs and report error

### Step 4: Retrieve output

```
process action:log
  session_id: "<session_id>"
  lines: 500
```

Parse the `stdout` field as JSON (same fields as blocking mode):

- `result` — final text answer / summary
- `session_id` — save this to resume the Claude session later
- `is_error` / `stop_reason` — detect failures
- `total_cost_usd` — report cost to the user

If `is_error` is true, also check `stderr` from the log output for diagnostics.

### Step 5: Cleanup

```
process action:kill
  session_id: "<session_id>"
```

Then remove the temp prompt file:

```bash
rm -f "$PROMPT_FILE"
```

---

From cedricziel/assistant, MIT.

More from cedricziel/assistant