| name | claude-code-invoke-once |
| description | Programmatically invoke Claude Code via the `claude` CLI (headless `-p`, `--output-format json|stream-json`, `--resume`/`--continue`) to automate tasks like producing code review reports for specific files/dirs, investigating an issue, or drafting an implementation plan. Use when you need scriptable, machine-readable output and/or session-persistent multi-turn workflows with Claude Code. |
Claude Code Invoke Once
Quick start (shell)
One-shot (machine-readable JSON):
claude -p "Summarize this repo" --output-format json
If you use a Claude wrapper (executable, .sh, or shell alias), substitute it for claude (example: claude-wrapper -p ...).
Streaming progress/events (JSONL):
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Persist multi-turn state and resume later (deterministic automation):
session_id="$(claude -p "Start a review" --output-format json | jq -r '.session_id')"
claude -p "Continue that review" --resume "$session_id" --output-format json
Heartbeats and deadlines
- For long-running work, prefer streaming (
--output-format stream-json, optionally with --include-partial-messages) so stdout emits a steady heartbeat (one JSON object per line).
- Do not add timeouts or terminate the Claude process while it is still working unless one of these applies: (1) the user explicitly requested a deadline (for example: "up to 5 minutes"), (2) the process is clearly stalled, or (3) the process is in an error state (for example: lost connection, timeout, invalid API key, non-zero exit failure).
- Do not interrupt simply because intermediate output appears to drift from the prompt; let Claude run to normal completion and evaluate the final result afterward.
Workflow decision
- Need a single final answer: use
--output-format json and parse .result.
- Need realtime progress: use
--output-format stream-json and parse one JSON object per stdout line.
- Need multi-turn state: persist
.session_id and call --resume <session_id> for subsequent turns (prefer over --continue in automation).
Session handling (must follow)
- If the user provides a
session_id, always use --resume <session_id> for the next Claude Code call.
- If the user says “continue latest chat”, “continue last chat”, or similar, use the most recently captured
session_id from this conversation.
- If the user does not provide a
session_id and does not explicitly request a continuation, determine from context whether they want to persist the previous Claude session. If unclear, start a new session.
Example prompts (to trigger this skill)
- “Use Claude Code to make a review report of
src/ and tests/.”
- “Use Claude Code to look into the issue of: <paste error/log>.”
- “Use Claude Code to make an implementation plan for: <feature/PRD>.”
Integration rules (don’t skip)
- Treat
stdout as the machine channel; treat stderr as diagnostics.
- Assume output schemas can evolve; parse defensively and avoid hard-coding event keys.
- Store the returned
session_id if you will send follow-up prompts in a later process/run.
Credentials (optional)
Ensure your chosen Claude command can authenticate in your environment (for example by exporting env vars or sourcing an env file before running the command).
Resources
- Full guide:
references/howto-control-claude-code-programmatically.md
