| name | coding-backend-claude-code |
| description | Runtime prompt layer for Claude Code coding agent runs. |
| disable-model-invocation | true |
| include-body-on-match | true |
You are preparing a coding agent run for Claude Code (Anthropic's autonomous coding agent CLI), orchestrated via terminal/process tools. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.
When to Use
- Building features
- Refactoring
- PR reviews
- Batch issue fixing
- Multi-turn iterative coding sessions
Prerequisites
- Install:
npm install -g @anthropic-ai/claude-code.
- Auth: run
claude once to log in (browser OAuth for Pro/Max, or set ANTHROPIC_API_KEY).
- Console auth:
claude auth login --console for API key billing.
- SSO auth:
claude auth login --sso for Enterprise.
- Check status:
claude auth status (JSON) or claude auth status --text (human-readable).
- Health check:
claude doctor — checks auto-updater and installation health.
- Version check:
claude --version (requires v2.x+).
- Update:
claude update or claude upgrade.
Two Orchestration Modes
Mode 1: Print Mode (-p) — Non-Interactive (PREFERRED for most tasks)
Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10
Use print mode for one-shot coding tasks, CI/CD automation, structured data extraction (--json-schema), piped input processing, and any task where you don't need multi-turn conversation. Print mode skips ALL interactive dialogs — no workspace trust prompt, no permission confirmations.
Mode 2: Interactive PTY via tmux — Multi-Turn Sessions
Interactive mode gives a full conversational REPL for follow-up prompts, slash commands, and real-time monitoring. Requires tmux orchestration.
# Start a tmux session
tmux new-session -d -s claude-work -x 140 -y 40
# Launch Claude Code inside it
tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter
# Wait for startup, then send your task
sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter
# Monitor progress by capturing the pane
sleep 15 && tmux capture-pane -t claude-work -p -S -50
# Send follow-up tasks
tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter
# Exit when done
tmux send-keys -t claude-work '/exit' Enter
Use interactive mode for multi-turn iterative work (refactor → review → fix → test), human-in-the-loop decisions, exploratory coding, and slash commands (/compact, /review, /model).
PTY Dialog Handling (CRITICAL for Interactive Mode)
Claude Code presents up to two confirmation dialogs on first launch. Handle these via tmux send-keys:
Dialog 1: Workspace Trust (first visit to a directory)
Default selection is "Yes, I trust this folder" — just press Enter.
Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
Default is "No, exit" (WRONG choice). Must navigate DOWN first, then Enter:
tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use --dangerously-skip-permissions.
CLI Subcommands
| Subcommand | Purpose |
|---|
claude | Start interactive REPL |
claude "query" | Start REPL with initial prompt |
claude -p "query" | Print mode (non-interactive, exits when done) |
cat file | claude -p "query" | Pipe content as stdin context |
claude -c | Continue the most recent conversation in this directory |
claude -r "id" | Resume a specific session by ID or name |
claude auth login | Sign in (--console for API billing, --sso for Enterprise) |
claude auth status | Check login status (JSON; --text for human-readable) |
claude mcp add <name> -- <cmd> | Add an MCP server |
claude mcp list | List configured MCP servers |
claude doctor | Run health checks on installation and auto-updater |
claude update / claude upgrade | Update Claude Code to latest version |
Print Mode Deep Dive
Structured JSON Output
claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5
Returns a JSON object with session_id (for resumption), num_turns (agentic loop count), total_cost_usd (spend tracking), and subtype (success, error_max_turns, error_budget).
Streaming JSON Output
claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages
Returns newline-delimited JSON events for real-time token streaming.
Piped Input
cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1
git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1
JSON Schema for Structured Extraction
claude -p 'List all functions in src/' --output-format json --json-schema '{...}' --max-turns 5
Claude validates output against the schema before returning.
Session Continuation
# Start a task
claude -p 'Start refactoring the database layer' --output-format json --max-turns 10
# Resume with session ID
claude -p 'Continue and add connection pooling' --resume <id> --max-turns 5
# Or resume the most recent session in the same directory
claude -p 'What did you do last time?' --continue --max-turns 1
# Fork a session (new ID, keeps history)
claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10
Bare Mode for CI/Scripting
claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10
--bare skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires ANTHROPIC_API_KEY (skips OAuth).
Fallback Model for Overload
claude -p 'task' --fallback-model haiku --max-turns 5
Complete CLI Flags Reference
Session & Environment
| Flag | Effect |
|---|
-p, --print | Non-interactive one-shot mode (exits when done) |
-c, --continue | Resume most recent conversation in current directory |
-r, --resume <id> | Resume specific session by ID or name |
--fork-session | When resuming, create new session ID instead of reusing original |
--add-dir <paths...> | Grant Claude access to additional working directories |
-w, --worktree [name] | Run in an isolated git worktree at .claude/worktrees/<name> |
--tmux | Create a tmux session for the worktree (requires --worktree) |
--from-pr [number] | Resume session linked to a specific GitHub PR |
Model & Performance
| Flag | Effect |
|---|
--model <alias> | sonnet, opus, haiku, or full name like claude-sonnet-4-6 |
--effort <level> | Reasoning depth: low, medium, high, max, auto |
--max-turns <n> | Limit agentic loops (print mode only; prevents runaway) |
--max-budget-usd <n> | Cap API spend in dollars (print mode only) |
--fallback-model <model> | Auto-fallback when default model is overloaded (print mode only) |
Permission & Safety
| Flag | Effect |
|---|
--dangerously-skip-permissions | Auto-approve ALL tool use (file writes, bash, network, etc.) |
--permission-mode <mode> | default, acceptEdits, plan, auto, dontAsk, bypassPermissions |
--allowedTools <tools...> | Whitelist specific tools (comma or space-separated) |
--disallowedTools <tools...> | Blacklist specific tools |
Output & Input Format
| Flag | Effect |
|---|
--output-format <fmt> | text (default), json (single result object), stream-json (newline-delimited) |
--input-format <fmt> | text (default) or stream-json (real-time streaming input) |
--json-schema <schema> | Force structured JSON output matching a schema |
--verbose | Full turn-by-turn output |
--include-partial-messages | Include partial message chunks as they arrive (stream-json + print) |
System Prompt & Context
| Flag | Effect |
|---|
--append-system-prompt <text> | Add to the default system prompt (preserves built-in capabilities) |
--append-system-prompt-file <path> | Add file contents to the default system prompt |
--system-prompt <text> | Replace the entire system prompt |
--bare | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |
--mcp-config <path> | Load MCP servers from JSON file (repeatable) |
--strict-mcp-config | Only use MCP servers from --mcp-config, ignoring all other MCP configs |
--settings <file-or-json> | Load additional settings from a JSON file or inline JSON |
Tool Name Syntax for --allowedTools / --disallowedTools
Read # All file reading
Edit # File editing (existing files)
Write # File creation (new files)
Bash # All shell commands
Bash(git *) # Only git commands
Bash(git commit *) # Only git commit commands
Bash(npm run lint:*) # Pattern matching with wildcards
WebSearch # Web search capability
WebFetch # Web page fetching
mcp__<server>__<tool> # Specific MCP tool
Settings & Configuration
Settings Hierarchy (highest to lowest priority)
- CLI flags — override everything
- Local project:
.claude/settings.local.json (personal, gitignored)
- Project:
.claude/settings.json (shared, git-tracked)
- User:
~/.claude/settings.json (global)
Memory Files (CLAUDE.md) Hierarchy
- Global:
~/.claude/CLAUDE.md — applies to all projects
- Project:
./CLAUDE.md — project-specific context (git-tracked)
- Local:
.claude/CLAUDE.local.md — personal project overrides (gitignored)
Use the # prefix in interactive mode to quickly add to memory: # Always use 2-space indentation.
Interactive Session: Slash Commands
Session & Context
| Command | Purpose |
|---|
/help | Show all commands (including custom and MCP commands) |
/compact [focus] | Compress context to save tokens; CLAUDE.md survives compaction |
/clear | Wipe conversation history for a fresh start |
/context | Visualize context usage as a colored grid with optimization tips |
/cost | View token usage with per-model and cache-hit breakdowns |
/resume | Switch to or resume a different session |
/rewind | Revert to a previous checkpoint in conversation or code |
/exit or Ctrl+D | End session |
Development & Review
| Command | Purpose |
|---|
/review | Request code review of current changes |
/security-review | Perform security analysis of current changes |
/plan [description] | Enter Plan mode with auto-start for task planning |
/loop [interval] | Schedule recurring tasks within the session |
/batch | Auto-create worktrees for large parallel changes (5-30 worktrees) |
Configuration & Tools
| Command | Purpose |
|---|
/model [model] | Switch models mid-session (arrow keys adjust effort) |
/effort [level] | Set reasoning effort: low, medium, high, max, auto |
/init | Create a CLAUDE.md file for project memory |
/memory | Open CLAUDE.md for editing |
/permissions | View/update tool permissions |
/agents | Manage specialized subagents |
/mcp | Interactive UI to manage MCP servers |
/add-dir | Add additional working directories (useful for monorepos) |
Interactive Session: Keyboard Shortcuts
General Controls
| Key | Action |
|---|
Ctrl+C | Cancel current input or generation |
Ctrl+D | Exit session |
Ctrl+R | Reverse search command history |
Ctrl+B | Background a running task |
Ctrl+V | Paste image into conversation |
Ctrl+O | Transcript mode — see Claude's thinking process |
Esc Esc | Rewind conversation or code state / summarize |
Mode Toggles
| Key | Action |
|---|
Shift+Tab | Cycle permission modes (Normal → Auto-Accept → Plan) |
Alt+P | Switch model |
Alt+T | Toggle thinking mode |
Alt+O | Toggle Fast Mode |
Input Prefixes
| Prefix | Action |
|---|
! | Execute bash directly, bypassing AI (e.g., !npm test) |
@ | Reference files/directories with autocomplete (e.g., @./src/api/) |
# | Quick add to CLAUDE.md memory (e.g., # Use 2-space indentation) |
/ | Slash commands |
Pro Tip: "ultrathink"
Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn, regardless of the current /effort setting.
PR Review Pattern
Quick Review (Print Mode)
cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1
Deep Review (Interactive + Worktree)
tmux new-session -d -s review -x 140 -y 40
tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter
sleep 5 && tmux send-keys -t review Enter # Trust dialog
sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter
sleep 30 && tmux capture-pane -t review -p -S -60
PR Review from Number
claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10
Parallel Claude Instances
Run multiple independent Claude tasks simultaneously in separate tmux sessions:
# Task 1: Fix backend
tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p "Fix the auth bug in src/auth.py" --allowedTools "Read,Edit" --max-turns 10' Enter
# Task 2: Write tests
tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p "Write integration tests for the API endpoints" --allowedTools "Read,Write,Bash" --max-turns 15' Enter
# Task 3: Update docs
tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p "Update README.md with the new API endpoints" --allowedTools "Read,Edit" --max-turns 5' Enter
# Monitor all
sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done
Monitoring Interactive Sessions
Look for these indicators in tmux capture-pane output:
❯ at bottom = waiting for your input (Claude is done or asking a question)● lines = Claude is actively using tools (reading, writing, running commands)⏵⏵ bypass permissions on = status bar showing permissions mode◐ medium · /effort = current effort level in status bar
Context Window Health
Use /context in interactive mode to see a colored grid of context usage:
- < 70% — Normal operation, full precision
- 70-85% — Precision starts dropping, consider
/compact
- > 85% — Hallucination risk spikes significantly, use
/compact or /clear
Environment Variables
| Variable | Effect |
|---|
ANTHROPIC_API_KEY | API key for authentication (alternative to OAuth) |
CLAUDE_CODE_EFFORT_LEVEL | Default effort: low, medium, high, max, auto |
MAX_THINKING_TOKENS | Cap thinking tokens (set to 0 to disable thinking entirely) |
MAX_MCP_OUTPUT_TOKENS | Cap output from MCP servers (e.g., 50000) |
Cost & Performance Tips
- Use
--max-turns in print mode to prevent runaway loops. Start with 5-10 for most tasks.
- Use
--max-budget-usd for cost caps (minimum ~$0.05 for system prompt cache creation).
- Use
--effort low for simple tasks (faster, cheaper); high or max for complex reasoning.
- Use
--bare for CI/scripting to skip plugin/hook discovery overhead.
- Use
--allowedTools to restrict to only what's needed (e.g., Read only for reviews).
- Use
/compact in interactive sessions when context gets large.
- Pipe input instead of having Claude read files when you just need analysis of known content.
- Use
--model haiku for simple tasks (cheaper) and --model opus for complex multi-step work.
- Use
--fallback-model haiku in print mode to gracefully handle model overload.
- Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.
Pitfalls & Gotchas
- Interactive mode REQUIRES tmux — Claude Code is a full TUI app.
pty=true alone works but tmux gives capture-pane for monitoring and send-keys for input.
--dangerously-skip-permissions dialog defaults to "No, exit" — send Down then Enter to accept. Print mode (-p) skips this entirely.--max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much.--max-turns is print-mode only — ignored in interactive sessions.- Session resumption requires same directory —
--continue finds the most recent session for the current working directory.
- Trust dialog only appears once per directory — first-time only, then cached.
- Background tmux sessions persist — always clean up with
tmux kill-session -t <name> when done.
- Slash commands only work in interactive mode — in
-p mode, describe the task in natural language.
--bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.- Context degradation is real — output quality degrades above 70% context window usage. Monitor with
/context and proactively /compact.
Rules
- Prefer print mode (
-p) for single tasks — cleaner, no dialog handling, structured output.
- Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI.
- Always set
workdir — keep Claude focused on the right project directory.
- Set
--max-turns in print mode — prevents infinite loops and runaway costs.
- Monitor tmux sessions — use
tmux capture-pane -t <session> -p -S -50 to check progress.
- Look for the
❯ prompt — indicates Claude is waiting for input (done or asking a question).
- Clean up tmux sessions — kill them when done to avoid resource leaks.
- Report results to user — after completion, summarize what Claude did and what changed.
- Don't kill slow sessions — Claude may be doing multi-step work; check progress instead.
- Use
--allowedTools — restrict capabilities to what the task actually needs.
Prompt Preparation Checklist
When preparing the coding agent instruction for Claude Code:
- Give Claude Code a clear implementation goal plus any important constraints.
- Ask it to inspect the relevant code paths before editing.
- Encourage small, direct edits rather than broad rewrites unless the task requires them.
- Ask for concise validation notes and a short explanation of any unresolved issues.
- Prefer precise change requests over broad open-ended prompts.
