A field manual
for agentic CLIs.

Opus 4.8 is the current default — defaults to high effort; xhigh is for your hardest tasks. Fast mode on 4.8 now costs 2× the standard rate for 2.5× the speed. If your CLAUDE.md or scripts still pin claude-opus-4-7, you're off the default path — re-baseline prompts and token budgets against 4.8. v2.1.154

Dynamic workflows + /workflows — ask Claude to create a workflow and it orchestrates work across tens-to-hundreds of background agents for large, complex tasks; /workflows watches, pauses, resumes, and saves runs. The /effort ultracode level pairs xhigh reasoning with automatic workflow orchestration. Reach for this when a task is too big for one agent but you don't want to hand-decompose it. v2.1.154 · workflows

fallbackModel setting + interactive --fallback-model — configure up to three fallback models tried in order when the primary is overloaded or unavailable; the flag now applies to interactive sessions too, and Claude retries a turn once on the fallback when the API throws an unexpected non-retryable error. Set this so overload degrades gracefully instead of hard-failing a session. v2.1.166

Glob deny rules + startup validation — deny rules now accept a glob in the tool-name position ("*" denies all tools); allow rules reject non-MCP globs, and unknown tool names in deny rules warn at startup. Use "*" as a default-deny baseline and allowlist up from there. v2.1.166

Hardened cross-session messaging — messages relayed via SendMessage from other Claude sessions no longer carry user authority: receivers refuse relayed permission requests and auto mode blocks them. One compromised session can no longer escalate privilege in another. v2.1.166

requiredMinimumVersion / requiredMaximumVersion managed settings — Claude Code refuses to start if its version is outside the allowed range and points the user to an approved version. For admins pinning a known-good range across a team. v2.1.163

/plugin list — lists installed plugins with --enabled / --disabled filters. Audit what's actually loaded without opening the full plugin menu. v2.1.163

Agent view — claude agents (Research Preview) — a single list of every Claude Code session, whether running, blocked on you, or done. Run claude agents to dispatch, attach, and detach background sessions from one dashboard. v2.1.139 · agent view

/goal — set a completion condition and Claude keeps working across turns until it's met, with a live elapsed/turns/tokens overlay. Works in interactive, -p, and Remote Control. Use it for "don't stop until the build is green" loops instead of babysitting each turn. v2.1.139 · goal

Plugins in .claude/skills auto-load — no marketplace required; claude plugin init <name> scaffolds one in place. Drop a plugin in the directory and it's live next session. v2.1.157

Parallel tool-call failure isolation — a failed Bash command no longer cancels the other calls in the same batch; each tool returns its own result independently. Batched tool calls are now safe to fire even when one might fail. v2.1.161

Skill / agent / command folder protection — --dangerously-skip-permissions no longer auto-allows writes to .claude/skills/, .claude/agents/, or .claude/commands/. Closes the auto-mode loophole where an agent could rewrite the rules it runs under. v2.1.13X · May 2026

worktree.baseRef (fresh | head) — base ref for --worktree, EnterWorktree, and agent-isolation worktrees. Default fresh = origin/<default>. Set head if you want unpushed local commits carried into new worktrees. Behavior change vs prior versions. v2.1.131 · May 7, 2026

Monitor tool — streams events from background scripts so an agent can react to long-running processes (build, deploy, watch) without polling. Pairs naturally with run_in_background bash. May 2026

$CLAUDE_EFFORT in hooks — hooks now receive effort.level via JSON input and $CLAUDE_EFFORT as an env var. Same branching pattern that landed for skills, now in hooks: lighter checks on medium, full audit on xhigh. v2.1.131 · May 7, 2026

Built-in slash commands invokable via Skill tool — the model can now call /init, /review, /security-review etc. itself, instead of waiting for a human to type them. Lets a planning agent run a security review as part of its work. May 2026

settings.autoMode.hard_deny — classifier rules that unconditionally block actions in auto mode. Use for "never auto-do X" patterns the regular permission system can't express. v2.1.136 · May 8, 2026

/model warns before mid-conversation switch — switching models mid-session re-reads the full history uncached. The warning prevents accidental token blowup; switch only when the cost is worth it. May 2026

MCP servers persist across /clear — fixes the silent disconnection that hit VS Code, JetBrains, and the Agent SDK after /clear. If your .mcp.json servers were vanishing post-clear, this is the fix. v2.1.136 · May 8, 2026

claude project purge [path] — wipes all Claude Code state for a project (transcripts, tasks, file history, config entry). Supports --dry-run, -y, -i, --all. Project hygiene without grepping ~/.claude. v2.1.126

Session recap + /recap — on return, Claude shows what happened while the terminal was unfocused. Configurable in /config; force-on with CLAUDE_CODE_ENABLE_AWAY_SUMMARY when telemetry is disabled. May 2026

Custom themes — build and ship palettes via /theme or as a plugin. A team can publish one theme and everyone picks it up through /plugin marketplace. May 2026

claude ultrareview [target] CLI — non-interactive /ultrareview for CI or scripts. --json for raw output, exits 0 on completion or 1 on failure. May 2026

Bash directory recovery — Bash tool no longer becomes permanently unusable when the cwd is deleted or moved mid-session. Reliability fix worth knowing if you've ever hit this. May 2026

MCP transient errors auto-retry — servers that hit a startup error now auto-retry up to 3 times instead of staying disconnected. /mcp shows tool counts and flags servers that connected with zero tools. May 2026

xhigh effort — xhigh sits between high and max on Opus models, set via /effort, --effort, or the model picker. On Opus 4.8 it's the level for your hardest tasks; max remains session-only. Other models fall back to high. v2.1.111 · v2.1.154

Auto mode needs no opt-in — auto mode no longer requires a consent flag on first-party plans. On Bedrock/Vertex/Foundry, opt in with CLAUDE_CODE_ENABLE_AUTO_MODE=1 for Opus 4.7 and 4.8. v2.1.152 · v2.1.158

State the work type. "Quick question" / "feature spec" / "code session" / "QA run". Sets expectations both ways and lets the agent pick the right depth.

Interview before building. Have the agent ask you the hard questions first. Requirements, edge cases, data model, security posture. Then spec in a fresh session.

Explore → Plan → Implement → Verify → Commit. Plan mode (/plan) for unknowns. Use /ultraplan for large refactors that need review before execution.

Writer/Reviewer split. One session writes. A fresh one reviews. No self-bias. Install the code-review plugin to get this automatically on every PR.

Give verification. Tests, screenshots, expected output, /security-review. LSP plugins give automatic diagnostics after every edit — the highest-ROI plugin you can install.

Two corrections max. Third fail → /clear and rewrite the prompt. Don't Goodhart: optimize for clarity, not length.

"Be conservative" reads literally. A review prompt that says "only report high-severity issues," "don't nitpick," or "be conservative" now causes Opus 4.7 to investigate at the same depth — but report fewer findings, because it's filtering against your stated bar more faithfully than 4.6 did. If you want everything surfaced, drop the soft phrasing. opus-4.7 best practices

Higher effort thinks more on later turns. 4.7 ramps reasoning depth in long sessions, especially at xhigh. Token usage for the same task can rise vs Opus 4.6. Tightener: /clear earlier, scope the task, or drop to /effort medium for routine work. opus-4.7 best practices

Updated tokenizer. Same prompt may consume a different number of tokens than under 4.6. If you've tuned a prompt to fit a specific budget, re-measure. opus-4.7 best practices

Be honest about your technical level. If you write "I'm not technically sound" the agent will take over decisions it shouldn't — architecture, schema design, security. If you say "I make logical and system-design decisions; you write the code," it will ask real technical questions instead.

Less is more. Would removing this line cause mistakes? No? Cut it. Bloated CLAUDE.md (>5 KB) starts losing rules to context pressure.

Identity, not instructions. Put "who I am, tech stack, communication style, safety rules" in CLAUDE.md. Put task procedures in skills.

Push it to git. Shared project context compounds over time. Every teammate and every session benefits.

Update after every mistake. When the agent got something wrong, the fix is a line in CLAUDE.md or a skill, not a repeat correction next session.

Conditional hooks — if field using permission-rule syntax like Bash(git *). Hook only runs for matching commands, massively reduces spawning overhead. v2.1.85

Hooks in skill/subagent frontmatter — scoped to the component's lifecycle, only run when the component is active.

New events: CwdChanged, FileChanged, PostCompact, PermissionDenied, StopFailure, TaskCreated, WorktreeCreate, Elicitation, ElicitationResult.

Async hooks, HTTP hooks, prompt hooks, MCP tool hooks — more ways to react without shelling out.

Stop / SubagentStop return additionalContext — these hooks can now feed Claude guidance and keep the turn going without being treated as a hook error. Use it to inject "you're not done — also check X" instead of hard-blocking. v2.1.163

MessageDisplay event — transform or hide assistant message text as it's displayed. For redaction or formatting passes on output. v2.1.152

SessionStart: reloadSkills + sessionTitle — a startup hook can install skills and make them live in the same session (reloadSkills: true), and set the session title via hookSpecificOutput.sessionTitle. v2.1.152

Skills / commands can set disallowed-tools — frontmatter that removes tools from the model while the skill is active. Lock a doc-writing skill out of Bash, for instance. v2.1.152

Hook args: string[] + continueOnBlock — exec-form args spawn the command without a shell (no quoting of path placeholders); continueOnBlock: true on PostToolUse feeds the rejection reason back to Claude and continues. v2.1.139

Morning alignment. Pull yesterday's wins, open reminders, tickets, PRs. Energy check (sharp / steady / recovering). Pick 1–3 leverage items for the day with a protected thinking block.

Evening review. Lead with wins, not scores. What shipped, what's blocked, which products got attention. Process carry-overs. Prep tomorrow's draft.

Friday pulse. 5-line week retro: product attention days, top 3 shipped, bounced-all-week items, Monday leverage candidate.

/schedule — Cloud scheduled tasks. Runs on Anthropic-managed infrastructure, so the task runs even when your computer is off. Conversational setup. cloud schedule

/loop [interval] [prompt] — bundled skill. Session-scoped recurring prompt. Dies when the session exits. Put a default prompt in .claude/loop.md. scheduled tasks

Desktop scheduled tasks — run on your machine, with direct access to your local files and tools. Separate from cloud tasks. desktop schedule

CLAUDE.md — identity & instructions. Who you are, tech stack, communication style. The onboarding doc your agent reads in 2 seconds. Under 5 KB.

heartbeat.md — what's in progress right now. Active deployments, current sprint, open blockers. Update every session.

MEMORY.md — index of persistent learnings. Each memory is a separate .md file. Cap at 15, merge aggressively.

decisions.md — the why behind choices. Why approach A over B. Future-you will thank you.

ROUTE.md — folder map and quick paths. Direct lookup, no exploration.

Find something similar. A screenshot, a working component, a reference repo, a public design. Feed it to the agent before asking for a new version.

Describe the delta, not the whole thing. "Like this, but with RLS at the tab level and tenant-agnostic IDs" beats "build an RLS dashboard."

Spell out business rules. AI won't infer financial years, tenant scoping, or regulatory constraints. If it matters, write it in the prompt.

Watch for hardcoded IDs. Agents love to copy literal IDs from examples. Always templatize tenant and environment identifiers before shipping.

Long threads = worse output. Token cost rises. Hallucinations creep in. Auto-compact carries the most recent skill invocations forward within a 25K-token budget (5K per skill), so older invocations get dropped. Plan accordingly.

Close, don't continue. When a conversation gets long, close it. Start fresh. Update CLAUDE.md with what you learned.

/rewind — rewind to a previous point or summarize from here. Trim the fat without starting over.

Invest in docs, not prompts. Two days of clear project docs beats two weeks of prompt-tweaking. You will re-enter the same problem.

Kitchen-sink sessions. One task drifts into three. /clear between unrelated work.

Correction loops. 3+ corrections = polluted context. Rewrite the prompt and start fresh.

Bloated CLAUDE.md. Past 5 KB, rules get lost to context pressure. Move procedures to skills.

Unscoped exploration. "Investigate everything" fills context. Scope or use a subagent.

Ship without verification. Plausible ≠ correct. No tests, no confidence. LSP plugins give free diagnostics.

Trusting memory over sources. If you didn't read the docs this session, don't claim what's in them. Ask the agent to fetch and verify.

Pull the official CHANGELOG. gh api repos/anthropics/claude-code/contents/CHANGELOG.md. That's the ground truth.

Cross-check the commands reference. code.claude.com/docs/en/commands. Removed commands must be removed here too.

Extract durable, user-relevant changes. Skip internal fixes and edge cases. Keep features, new commands, hook events, meaningful defaults.

Translate the capability into workflow consequences. What should a user do differently now?

Cite every claim. Version tag from CHANGELOG, or direct link to docs. Anything unverified does not ship.

Commit on a feature branch, open a PR. Review before merge, even for content-only changes.