claude-code

# Claude Code Claude Code (`claude` binary) is Anthropic's agentic coding CLI. Markus invokes it via `invoke_coding_tool({ tool: "claude-code", ... })`. Use it for complex, multi-turn coding tasks where deep reasoning and broad file exploration are needed. ## Installation ```bash npm install -g @anthropic-ai/claude-code claude --version ``` Verify with `markus doctor`. Requires authentication via one of: `ANTHROPIC_API_KEY` env var, `ANTHROPIC_BASE_URL` for custom endpoints, or interactive `claude` login. ## How Markus Invokes Claude Code Markus runs Claude Code in non-interactive print mode with structured streaming output: ```bash claude --print --output-format stream-json --verbose --max-turns 50 --permission-mode bypassPermissions "<prompt>" ``` | Flag | Purpose | |---|---| | `--print` | Non-interactive mode — runs to completion without user input | | `--output-format stream-json` | Emits structured JSON events for progress parsing | | `--verbose` | Detailed progress output | | `--max-turns 50` | Allows up to 50 agent turns for complex tasks | | `--permission-mode bypassPermissions` | Auto-approves all file edits and commands — required because `--print` mode has no interactive stdin for approval prompts | Additional args can be configured per-deployment via `CodingToolConfig.defaultArgs`. ## Stream-JSON Output Each stdout line is a JSON event. Key event types: | Event type | Meaning | |---|---| | `assistant` with `text` content | Progress message / reasoning summary | | `assistant` with `tool_use` | File edit, shell command, or other tool invocation | | `result` | Final outcome with cost and token data | The `result` event includes: - `result` — Final summary text - `input_tokens`, `output_tokens` — Token usage - `cache_read_tokens`, `cache_write_tokens` — Prompt cache stats - `cost_usd` — Estimated cost in USD Markus parses these into progress events (`file_edit`, `progress`, `completed`) and extracts cost reports automatically. ## CLAUDE.md Context File When you pass `task_id` to `invoke_coding_tool`, Markus writes a `CLAUDE.md` file in the repository root before invoking Claude Code. This file contains: - Task title, description, status, and priority - Subtasks, notes, and deliverables - Requirement and project context - Upstream/downstream dependency summaries - Markus CLI commands for reporting progress Claude Code reads `CLAUDE.md` automatically as project context. **Do not delete or overwrite it** during a session — it is regenerated each invocation. If the repo already has a permanent `CLAUDE.md`, Markus overwrites it for the session. Consider restoring project-level content after the task if needed. ## Usage Patterns ### Complex Refactor ``` invoke_coding_tool({ tool: "claude-code", prompt: "Refactor the auth module to use dependency injection. Move AuthService to src/services/, update all imports, keep existing test behavior. Run the test suite when done.", workdir: "/path/to/repo", task_id: "task-123" }) ``` ### Debug and Fix ``` invoke_coding_tool({ tool: "claude-code", prompt: "Tests in packages/core/test/auth.test.ts are failing with 'token expired'. Find the root cause in src/auth/ and fix without changing the public API. Show which tests pass after the fix.", workdir: "/path/to/repo", task_id: "task-123" }) ``` ### Explore Then Implement For unfamiliar codebases, ask Claude Code to explore first: ``` "Read the codebase structure under src/coding-tools/. Then implement the feature described in the task context. Start by listing the files you plan to modify." ``` ## Retry Strategies for Long Tasks Claude Code supports up to 50 turns, but long tasks can still stall or partially complete. ### If the session completes but work is incomplete Re-invoke with explicit remaining scope: ``` "Previous session modified src/foo.ts and src/bar.ts but did not update tests. Complete the test coverage for the changes in src/foo.ts. Do not re-modify files that are already correct." ``` ### If the session fails or times out 1. Check `git status` in `workdir` for partial changes 2. Either apply partial work with `coding_tool_apply` or discard with `git checkout -- .` 3. Retry with a **smaller scope** — one module or one feature at a time ### If Claude Code loops or over-edits Add constraints to the prompt: ``` "Modify ONLY files under src/handlers/. Do not touch tests, config, or unrelated packages." ``` ### Escalation after 2 retries Switch to `codex` for a targeted fix, or edit directly with `file_edit`. ## Model and Effort Selection Claude Code supports per-invocation model and effort overrides: ``` invoke_coding_tool({ tool: "claude-code", prompt: "...", model: "sonnet", // default: tool's own default (usually sonnet) effort: "medium", // low | medium | high | xhigh | max }) ``` ### Model guidance | Model | Best for | Cost note | |---|---|---| | `haiku` | Simple subagent tasks, quick checks | Cheapest option | | `sonnet` | Most coding work — default choice | Good balance of cost and capability | | `opus` | Complex architecture, multi-file refactors, unfamiliar codebases | ~15x more expensive per token than Sonnet | | `fable` | Creative or documentation tasks | Specialized | **Strategy:** Start with `sonnet` (or the user's `defaultModel`). Only use `opus` when: - Sonnet attempt failed or produced poor results - The task involves complex reasoning across 10+ files - Architecture decisions or trade-off analysis is required **Warning:** Opus is approximately 15x more expensive than Sonnet per token. A task that costs $0.30 with Sonnet could cost $4.50 with Opus. **Voluntarily call `request_user_approval` before using Opus for any task expected to run more than a few turns.** ### Effort guidance - `low` — Simple edits, typo fixes, config changes - `medium` — Standard development tasks (default) - `high` — Complex reasoning, multi-step problem solving ### Budget cap If the user has set `maxBudgetPerSessionUsd`, Markus passes it as `--max-budget-usd` to Claude Code. This is a **hard limit enforced by Claude Code** — the session terminates if the budget is reached. Claude Code is the only tool with this enforced budget mechanism. When working under a budget cap: - Prefer `sonnet` over `opus` to stay within budget - Split large tasks so each invocation stays within the per-session limit - Monitor `cost.estimatedCostUsd` in results to gauge remaining budget capacity ## Cost Awareness Claude Code is the most capable but potentially most expensive coding tool. It provides the **best cost visibility** — every result includes token counts and USD estimates: ```json { "cost": { "estimatedCostUsd": 0.45, "inputTokens": 85000, "outputTokens": 12000, "cacheReadTokens": 40000, "source": "tool_output" } } ``` **Cost-saving practices:** - Scope prompts tightly — avoid "refactor everything" - Split large tasks into sequential focused invocations - Use `codex` for trivial fixes instead of Claude Code - Leverage prompt caching (repeated context in CLAUDE.md is cache-friendly) - Review `cost.estimatedCostUsd` before chaining multiple invocations - Use `effort: "low"` for simple edits, `effort: "high"` only for complex reasoning - Prefer `sonnet` — only escalate to `opus` when justified Report unusually high costs (> $1 per invocation) in a task note for visibility. ## Best Practices - Write prompts with explicit file boundaries and test commands - Always pass `task_id` so CLAUDE.md carries full task context - Watch progress output for `file_edit` events to track what's changing - Verify `result.testResult` before calling `coding_tool_apply` - Prefer Claude Code when the task requires reading 5+ files to understand context - Check `cost.estimatedCostUsd` after each invocation and factor it into your next decision ## Quality Verification Loop For complex tasks, chain Claude Code invocations: 1. **Plan**: `invoke_coding_tool({ tool: "claude-code", mode: "plan", prompt: "Analyze and plan..." })` 2. **Implement**: `invoke_coding_tool({ tool: "claude-code", prompt: "Implement the plan..." })` 3. **Verify**: Check `result.testResult`. If failures exist, re-invoke with: "Fix these test failures: <output>" 4. **Apply**: Only after tests pass — `coding_tool_apply({ session_id, commit_message })` Never apply changes from a session where tests failed. ## Cost Management - Start with the default model. Only escalate to more expensive models for tasks that demonstrably need deeper reasoning. - Check `cost.estimatedCostUsd` after each invocation and note it in task progress. - For exploratory work, set a mental budget — if cost exceeds expectations, split into smaller focused invocations. ## Rules - **DO** use for multi-file refactors and exploratory coding - **DO** monitor token/cost data in the response - **DO** break very large tasks into sequential invocations - **DO** start with `sonnet` and only escalate to `opus` when needed - **DO** request user approval before using `opus` for long tasks - **DO NOT** use for one-line fixes — use `codex` or direct edit instead - **DO NOT** ignore failed tests in the result — iterate until they pass - **DO NOT** use `opus` by default — its cost can surprise users