coding-backend-claude-code

name: coding-backend-claude-codedescription: Runtime prompt layer for Claude Code coding agent runs.disable-model-invocation: 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

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

Model & Performance

Permission & Safety

Output & Input Format

System Prompt & Context

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)

1. CLI flags — override everything
2. Local project: .claude/settings.local.json (personal, gitignored)
3. Project: .claude/settings.json (shared, git-tracked)
4. User: ~/.claude/settings.json (global)

Memory Files (CLAUDE.md) Hierarchy

1. Global: ~/.claude/CLAUDE.md — applies to all projects
2. Project: ./CLAUDE.md — project-specific context (git-tracked)
3. 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

Development & Review

Configuration & Tools

Interactive Session: Keyboard Shortcuts

General Controls

Mode Toggles

Input Prefixes

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

Cost & Performance Tips

1. Use --max-turns in print mode to prevent runaway loops. Start with 5-10 for most tasks.
2. Use --max-budget-usd for cost caps (minimum ~$0.05 for system prompt cache creation).
3. Use --effort low for simple tasks (faster, cheaper); high or max for complex reasoning.
4. Use --bare for CI/scripting to skip plugin/hook discovery overhead.
5. Use --allowedTools to restrict to only what's needed (e.g., Read only for reviews).
6. Use /compact in interactive sessions when context gets large.
7. Pipe input instead of having Claude read files when you just need analysis of known content.
8. Use --model haiku for simple tasks (cheaper) and --model opus for complex multi-step work.
9. Use --fallback-model haiku in print mode to gracefully handle model overload.
10. Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.

Pitfalls & Gotchas

1. 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.
2. --dangerously-skip-permissions dialog defaults to "No, exit" — send Down then Enter to accept. Print mode (-p) skips this entirely.
3. --max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much.
4. --max-turns is print-mode only — ignored in interactive sessions.
5. Session resumption requires same directory — --continue finds the most recent session for the current working directory.
6. Trust dialog only appears once per directory — first-time only, then cached.
7. Background tmux sessions persist — always clean up with tmux kill-session -t <name> when done.
8. Slash commands only work in interactive mode — in -p mode, describe the task in natural language.
9. --bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.
10. Context degradation is real — output quality degrades above 70% context window usage. Monitor with /context and proactively /compact.

Rules

1. Prefer print mode (-p) for single tasks — cleaner, no dialog handling, structured output.
2. Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI.
3. Always set workdir — keep Claude focused on the right project directory.
4. Set --max-turns in print mode — prevents infinite loops and runaway costs.
5. Monitor tmux sessions — use tmux capture-pane -t <session> -p -S -50 to check progress.
6. Look for the ❯ prompt — indicates Claude is waiting for input (done or asking a question).
7. Clean up tmux sessions — kill them when done to avoid resource leaks.
8. Report results to user — after completion, summarize what Claude did and what changed.
9. Don't kill slow sessions — Claude may be doing multi-step work; check progress instead.
10. 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.