llms-full.txt

# Claude Code Ultimate Guide — Full Content for AI Indexing

> This file is optimized for AI/LLM consumption. It contains the condensed guide overview,
> full cheatsheet, complete template list, and FAQ for Claude Code.
>
> Standard llms.txt: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/llms.txt
> Machine-readable index: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/machine-readable/reference.yaml

## Metadata

- Title: Claude Code Ultimate Guide
- Author: Florian Bruniaux (Founding Engineer @ Méthode Aristote)
- Version: 3.41.1
- Last Updated: May 27, 2026
- License: CC BY-SA 4.0
- Repository: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
- Landing: https://cc.bruniaux.com
- Lines of Documentation: 26,058
- Production Templates: 314
- Quiz Questions: 334
- Whitepapers: 11 titles (FR + EN)

---

## What Is Claude Code

Claude Code is Anthropic's official CLI for AI-assisted development. It lets developers interact with Claude directly from the terminal to write, edit, debug, and review code. Unlike IDE plugins, it has full filesystem access, can run shell commands, and works autonomously on multi-step tasks.

This guide is the most comprehensive community resource for Claude Code. It covers everything from installation to production security, with 186 ready-to-use templates for agents, hooks, commands, and skills.

## Who This Guide Is For

- **Beginners**: Install Claude Code, complete first task in 15 minutes
- **Intermediate**: Configure CLAUDE.md memory files, custom agents, hooks
- **Power users**: MCP servers, Trinity pattern, CI/CD integration, multi-agent workflows
- **Tech leads**: Team adoption, security hardening, governance patterns
- **CTOs/CIOs**: ROI, risk, security posture

## Guide Structure (10 Sections + Architecture)

**Architecture Deep Dive** (`guide/architecture.md`):
- Master Loop: `while(tool_call)` — no DAGs, no classifiers, no RAG
- 8 Core Tools: Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite
- Context: ~200K tokens, auto-compact at 75-92%
- Sub-agents: isolated context, max depth=1
- Philosophy: "less scaffolding, more model"

**Main Guide Sections** (`guide/ultimate-guide.md`, 25,368 lines):
1. Quick Start — Installation, first workflow, essential commands
2. Core Concepts — Context management, Plan Mode, Rewind, Mental Model
3. Memory & Settings — CLAUDE.md files, .claude/ folder, precedence rules
4. Agents — Custom AI personas, Tool SEO, orchestration patterns
5. Skills — Reusable knowledge modules (Skills 2.0: Capability Uplift + Encoded Preference, Evals)
6. Commands — Custom slash commands, variable interpolation
7. Hooks — Event-driven automation (PreToolUse, PostToolUse, UserPromptSubmit)
8. MCP Servers — Serena, Context7, Sequential, Playwright, Postgres, grepai
9. Advanced Patterns — Trinity, CI/CD, Tasks API, multi-agent teams, feedback loops
10. Reference — Commands, shortcuts, troubleshooting, checklists

---

## Full Cheatsheet

**Version**: 3.41.1 | **Last Updated**: May 2026

---

### Essential Commands

| Command | Action |
|---------|--------|
| `/help` | Contextual help |
| `/clear` | Reset conversation |
| `/compact` | Free up context |
| `/status` | Session state + context usage |
| `/context` | Detailed token breakdown |
| `/plan` | Enter Plan Mode (no changes) |
| `/execute` | Exit Plan Mode (apply changes) |
| `/model` | Switch model (sonnet/opus/opusplan) |
| `/insights` | Usage analytics + optimization report |
| `/simplify` | Detect over-engineering in changed code + auto-fix |
| `/batch` | Large-scale refactors via 5–30 parallel worktree agents |
| `/teleport` | Teleport session from web |
| `/tasks` | Monitor background tasks |
| `/remote-env` | Configure cloud environment |
| `/remote-control` | Start remote control session (Research Preview, Pro/Max) |
| `/rc` | Alias for /remote-control |
| `/mobile` | Get Claude mobile app download links |
| `/fast` | Toggle fast mode (2.5x speed, 6x cost) |
| `/voice` | Toggle voice input (hold Space to speak, release to send) |
| `/loop [interval] [prompt]` | Run a prompt on repeat (ex: `/loop 5m check the deploy`, default 10m) |
| `/usage` | Token + cost usage per model (v2.1.118, replaces /cost and /stats) |
| `/cost` | Alias for /usage (v2.1.118+) |
| `/stats` | Alias for /usage (v2.1.118+) — Usage graph, favorite model, streak |
| `/recap` | Summarize the current session (v2.1.108) |
| `/effort` | Set thinking effort level: xlow/low/default/high/xhigh (v2.1.111) |
| `/tui` | Show tool calls in TUI mode (v2.1.110) |
| `/focus` | Focus agent on specific files or tasks (v2.1.110) |
| `/less-permission-prompts` | Reduce permission prompt frequency (v2.1.111) |
| `/ultrareview` | Multi-agent cloud code review (v2.1.114) |
| `/proactive` | Enable proactive suggestions alias (v2.1.105) |
| `/undo` | Revert last action (v2.1.108) |
| `/rename [name]` | Name or rename the current session |
| `/copy` | Interactive picker to copy a code block or full response |
| `/debug` | Systematic troubleshooting |
| `/exit` | Quit (or Ctrl+D) |

---

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Shift+Tab` | Cycle permission modes |
| `Esc` × 2 | Rewind (undo) |
| `Ctrl+C` | Interrupt |
| `Ctrl+R` | Search command history |
| `Ctrl+L` | Clear screen (keeps context) |
| `Tab` | Autocomplete |
| `Shift+Enter` | New line |
| `Ctrl+B` | Background tasks |
| `Ctrl+F` | Kill all background agents (double press) |
| `Alt+T` | Toggle thinking |
| `Space` (hold) | Voice input (requires `/voice` enabled) |
| `Ctrl+D` | Exit |

---

### File References

```
@path/to/file.ts    → Reference a file
@agent-name         → Call an agent
!shell-command      → Run shell command
```

---

### Permission Modes

| Mode | Editing | Execution |
|------|---------|-----------|
| Default | Asks | Asks |
| acceptEdits | Auto | Asks |
| Plan Mode | None | None |
| dontAsk | Only if in allow rules | Only if in allow rules |
| bypassPermissions | Auto | Auto (CI/CD only) |

**Shift+Tab** to cycle modes

---

### Memory & Settings

| Level | macOS/Linux | Scope |
|-------|-------------|-------|
| **Project** | `.claude/` | Team (committed) |
| **Personal** | `~/.claude/` | You (all projects) |

**.claude/ Folder Structure:**
```
.claude/
├── CLAUDE.md           # Team memory (instructions)
├── settings.json       # Hooks (committed)
├── settings.local.json # Permissions (not committed)
├── agents/             # Custom agents
├── skills/             # User-invocable skills (slash commands + knowledge modules)
│                       # Since CC 2.1.3: commands/ merged here
│                       # Add disable-model-invocation: true for user-only skills
├── hooks/              # Event scripts
└── rules/              # Auto-loaded rules
```

---

### Context Management (CRITICAL)

| Context % | Status | Action |
|-----------|--------|--------|
| 0-50% | Green | Work freely |
| 50-70% | Yellow | Be selective |
| 70-90% | Orange | `/compact` now |
| 90%+ | Red | `/clear` required |

**Actions by Symptom:**
| Sign | Action |
|------|--------|
| Short responses | `/compact` |
| Frequent forgetting | `/clear` |
| >70% context | `/compact` |
| Task complete | `/clear` |

---

### Plan Mode & Thinking

| Feature | Activation | Usage |
|---------|------------|-------|
| **Plan Mode** | `Shift+Tab × 2` or `/plan` | Explore without modifying |
| **OpusPlan** | `/model opusplan` | Opus for planning, Sonnet for execution |

| Task | Model | Effort |
|------|-------|--------|
| Rename, boilerplate, test gen | Haiku | low |
| Feature dev, debug, refactor | Sonnet | medium–high |
| Architecture, security audit | Opus | high–max |

---

### MCP Servers

| Server | Purpose |
|--------|---------|
| **Serena** | Indexation + session memory + symbol search |
| **grepai** | Semantic search + call graph analysis |
| **Context7** | Library documentation |
| **Sequential** | Structured reasoning |
| **Playwright** | Browser automation |
| **Postgres** | Database queries |

---

### Creating Custom Components

**Agent** (`.claude/agents/my-agent.md`):
```yaml
---
name: my-agent
description: Use when [trigger]
model: sonnet
tools: Read, Write, Edit, Bash
---
# Instructions here
```

**Skill / Command** (`.claude/skills/my-skill.md`, since CC 2.1.3):
```yaml
---
name: my-skill
disable-model-invocation: true  # user-only skill (replaces .claude/commands/)
---
```
```markdown
# Skill Name
Instructions for what to do...
$ARGUMENTS[0] $ARGUMENTS[1] — user args
```

**Hook** (`.claude/hooks/` bash or PowerShell):
```bash
#!/bin/bash
INPUT=$(cat)
# Process JSON input
exit 0  # 0=continue, 2=block
```

---

### Quick Prompting Formula

```
WHAT: [Concrete deliverable]
WHERE: [File paths]
HOW: [Constraints, approach]
VERIFY: [Success criteria]
```

**Example:**
```
Add input validation to the login form.
WHERE: src/components/LoginForm.tsx
HOW: Use Zod schema, show inline errors
VERIFY: Empty email shows error, invalid format shows error
```

---

### CLI Flags Quick Reference

| Flag | Usage |
|------|-------|
| `-p "query"` | Non-interactive mode (CI/CD) |
| `-c` / `--continue` | Continue last session |
| `-r` / `--resume <id>` | Resume specific session |
| `--model sonnet` | Change model |
| `--add-dir ../lib` | Allow access outside CWD |
| `--permission-mode plan` | Plan mode |
| `--tools "Tool1,Tool2"` | Enable specific tools for session |
| `--max-budget-usd 5.00` | Max API spend limit |
| `--system-prompt "..."` | Append custom system prompt |
| `--worktree` / `-w` | Run in isolated git worktree |
| `--dangerously-skip-permissions` | Auto-accept (use carefully) |
| `--debug` | Debug output |

---

### The Golden Rules

1. **Always review diffs** before accepting
2. **Use `/compact`** before context gets critical (>70%)
3. **Be specific** in requests (WHAT, WHERE, HOW, VERIFY)
4. **Plan Mode first** for complex/risky tasks
5. **Create CLAUDE.md** for every project
6. **Commit frequently** after each completed task
7. **Know what's sent** — prompts, files, MCP results → Anthropic (opt-out available)

---

### Quick Decision Tree

```
Simple task       → Just ask Claude
Complex task      → Tasks API to plan first
Risky change      → Plan Mode first
Repeating task    → Create agent or command
Context full      → /compact or /clear
Need docs         → Use Context7 MCP
Deep analysis     → Use Opus (thinking on by default)
```

---

### Cost Optimization

| Model | Use For | Cost |
|-------|---------|------|
| Haiku | Simple fixes, reviews | $ |
| Sonnet | Most development | $$ |
| Opus | Architecture, complex bugs | $$$ |
| OpusPlan | Plan (Opus) + Execute (Sonnet) | $$ |

---

## Template Library (314 templates)

### Agents (23 files)
- `adr-writer.md` — Architecture Decision Records
- `architecture-reviewer.md` — System architecture review
- `code-reviewer.md` — Code quality review
- `devops-sre.md` — DevOps/SRE operations
- `implementer.md` — Feature implementation
- `integration-reviewer.md` — API integration review
- `output-evaluator.md` — AI output evaluation
- `plan-challenger.md` — Challenge implementation plans
- `planner.md` — Task planning
- `planning-coordinator.md` — Multi-agent coordination
- `refactoring-specialist.md` — Code refactoring
- `security-auditor.md` — Security auditing
- `security-patcher.md` — Security patch application
- `test-writer.md` — Test generation
- `analytics-with-eval/` — Full analytics agent with eval framework
- `cyber-defense/` — Multi-agent cyber defense team

### Commands (52 files)
- `audit-agents-skills.md` — Quality audit for .claude/ configs
- `audit-codebase.md` — Full codebase audit
- `catchup.md` — Daily catchup briefing
- `commit.md` — Smart git commit
- `diagnose.md` — Problem diagnosis
- `explain.md` — Code explanation
- `generate-tests.md` — Test suite generation
- `git-worktree.md` — Isolated git worktree workflow
- `git-worktree-status.md` — Worktree status
- `git-worktree-clean.md` — Worktree cleanup
- `git-worktree-remove.md` — Worktree removal
- `optimize.md` — Performance optimization
- `plan-execute.md` — Plan then execute workflow
- `plan-start.md` — Plan mode startup
- `plan-validate.md` — Plan validation
- `pr.md` — Pull request creation
- `refactor.md` — Code refactoring
- `release-notes.md` — Release notes generation
- `learn/` — Interactive learning command

### Hooks (bash + PowerShell)
**Bash hooks:**
- `auto-commit.sh` — Auto commit on file changes
- `dangerous-actions-blocker.sh` — Block rm -rf and destructive commands
- `format-on-save.sh` — Auto-format code files
- `lint-on-edit.sh` — Run linter after edits
- `prompt-injection-detector.sh` — Detect prompt injection attempts
- `run-tests-on-edit.sh` — Run tests after code changes
- `secrets-scanner.sh` — Scan for hardcoded secrets
- `send-notification.sh` — Desktop notifications on task completion
- `session-logger.sh` — Log all session activity
- `smart-context-compressor.sh` — Adaptive context management
- `token-usage-tracker.sh` — Track API token consumption
- `update-changelog.sh` — Auto-update CHANGELOG on commits

**PowerShell hooks** (Windows equivalents for all above)

### Skills (64 modules)
- `ast-grep-patterns.md` — AST-based code search patterns
- `audit-agents-skills/` — Agents/skills quality audit system
- `ccboard/` — Claude Code monitoring dashboard
- `cyber-defense-team/` — Security team coordination
- `design-patterns/` — Software design pattern guidance
- `guide-recap/` — CHANGELOG → social content generator
- `issue-triage/` — GitHub issue prioritization
- `landing-page-generator/` — Landing page from repo
- `pdf-generator.md` — Professional PDF generation (Quarto/Typst)
- `pr-triage/` — PR review prioritization
- `release-notes-generator/` — Multi-format release notes
- `rtk-optimizer/` — Token reduction optimization
- `security-checklist.md` — Security audit checklist
- `skill-creator/` — Create new skills with proper structure
- `talk-pipeline/` — Conference talk preparation pipeline
- `tdd-workflow.md` — Test-Driven Development workflow
- `voice-refine/` — Voice input refinement

### Scripts (15 utility scripts)
- `audit-scan.sh` — Config security audit
- `bridge.py` — Tool bridging utility
- `check-claude.sh` / `.ps1` — Installation health check
- `clean-reinstall-claude.sh` / `.ps1` — Clean reinstall
- `fresh-context-loop.sh` — Automated fresh-context iteration
- `migrate-arguments-syntax.sh` / `.ps1` — Update argument syntax
- `rtk-benchmark.sh` — RTK token savings benchmark
- `session-search.sh` — Search across sessions
- `session-stats.sh` — Session statistics
- `sonnetplan.sh` — OpusPlan workflow automation
- `sync-claude-config.sh` — Sync .claude/ across machines

### Additional Categories
- `claude-md/` — CLAUDE.md templates (7 variants)
- `config/` — Configuration templates (settings.json, etc.)
- `github-actions/` — CI/CD workflow templates
- `integrations/` — Third-party integrations
- `mcp-configs/` — MCP server configuration templates
- `memory/` — Memory file templates
- `modes/` — Custom mode configurations
- `multi-provider/` — Multi-LLM provider setups
- `plugins/` — Plugin templates
- `rules/` — Auto-loaded rules templates
- `semantic-anchors/` — Semantic navigation patterns
- `team-config/` — Team configuration examples
- `templates/` — Generic project templates
- `workflows/` — Step-by-step workflow guides

---

## FAQ

**Q: What is the Claude Code Ultimate Guide?**
A: The most comprehensive community guide for Claude Code (Anthropic's CLI). 26,058 lines of documentation, 314 production-ready templates, 334-question quiz, and security threat database. Free and open-source (CC BY-SA 4.0).

**Q: Is this guide free?**
A: Yes, completely free. The guide is CC BY-SA 4.0 (share and adapt with attribution). Templates are CC0 (copy-paste freely, no attribution needed). No paywall, no login required.

**Q: What's the difference between this and Anthropic's official docs?**
A: This guide goes 10x deeper on practical workflows, templates, security hardening, and real-world patterns. The official docs explain what Claude Code does; this guide teaches you how to use it effectively for production work.

**Q: Do I need a paid Claude plan to use Claude Code?**
A: Claude Code requires an active Claude subscription. Pro ($20/month) is sufficient for most individual developers. Team and Enterprise plans available for organizations.

**Q: What are Hooks in Claude Code?**
A: Hooks are shell scripts (bash or PowerShell) that run automatically before/after Claude tool calls. They enable event-driven automation: block dangerous commands, scan for secrets, auto-format code, run tests after edits, log activity for compliance. They use `exit 0` (continue) or `exit 2` (block) to control Claude's actions.

**Q: What are MCP servers?**
A: Model Context Protocol servers extend Claude's capabilities beyond its built-in tools. Examples: Serena (codebase indexation + session memory), Context7 (library documentation), Sequential (structured multi-step reasoning), Playwright (browser automation), Postgres (database queries). The community has built 1,000+ MCP servers; this guide teaches you to vet them for security.

**Q: What is Plan Mode?**
A: Plan Mode (`Shift+Tab × 2` or `/plan`) is a read-only exploration mode where Claude can analyze your codebase without making any changes. Use it before complex or risky tasks to let Claude research the problem, then switch to execution mode.

**Q: What are Agents in Claude Code?**
A: Agents are custom Claude instances with specific instructions, tools, and personas stored in `.claude/agents/` as markdown files. Examples: a security-auditor that only uses Read/Grep tools, a code-reviewer with specific standards, a devops-sre with infrastructure expertise. They're invoked via `@agent-name` in your prompt.

**Q: What is CLAUDE.md?**
A: CLAUDE.md is a memory file at your project root (or `~/.claude/`) that Claude reads at the start of every session. Use it to define project conventions, tech stack, coding standards, and commands. It's the primary way to give Claude persistent project context without repeating yourself.

**Q: What are Skills?**
A: Skills are reusable knowledge modules stored in `.claude/skills/`. Two types: Capability Uplift (fills model gaps, becomes less necessary as models improve) and Encoded Preference (encodes your team's specific workflow preferences, stays durable). Skills 2.0 (March 2026) adds Benchmark Mode, A/B testing, and Trigger Tuning.

**Q: How do I handle context limits?**
A: Monitor context usage via `/status`. At 70%: run `/compact` to summarize and free context. At 90%: use `/clear` for a fresh start. Use Plan Mode early to explore without consuming context. For long projects, use Tasks API (`CLAUDE_CODE_TASK_LIST_ID`) for cross-session persistence.

**Q: Is Claude Code safe for production use?**
A: With proper hardening, yes. Key steps: never use `bypassPermissions` in production, vet all MCP servers against the threat database (28+ CVEs tracked), use hooks to block dangerous commands, enable audit logging, run `claude doctor` regularly. See `guide/security-hardening.md` for the complete checklist.

---

## Privacy & Data

Claude Code sends to Anthropic servers: your prompts, file contents you reference, MCP tool results.
- Default retention: 5 years (training enabled)
- Opt-out: 30 days retention — https://claude.ai/settings/data-privacy-controls
- Enterprise: 0 retention, no training
- The guide covers this in detail: `guide/data-privacy.md`

---

## Repository

```
claude-code-ultimate-guide/
├── llms.txt                        # This file (short version, for AI indexing)
├── llms-full.txt                   # Full content (you are here)
├── guide/                          # Core documentation
│   ├── ultimate-guide.md           # Complete guide (25,368 lines)
│   ├── cheatsheet.md               # 1-page reference
│   ├── architecture.md             # How Claude Code works internally
│   ├── security-hardening.md       # Security best practices
│   ├── data-privacy.md             # What data is sent to Anthropic
│   └── claude-code-releases.md     # Official release tracking
├── examples/                       # 314 production-ready templates
│   ├── agents/                     # Custom AI personas
│   ├── commands/                   # Legacy slash commands (pre-CC 2.1.3)
│   ├── hooks/                      # Event automation (bash + PowerShell)
│   ├── skills/                     # User-invocable skills (unified since CC 2.1.3)
│   └── scripts/                    # Utility scripts
├── machine-readable/               # LLM/AI consumption
│   ├── reference.yaml              # Machine-optimized index (~2K tokens)
│   └── llms.txt                    # Short version
├── whitepapers/                    # 9 focused PDFs (FR + EN)
└── quiz/                           # 334-question interactive quiz
```

---

## Author & License

**Author**: Florian Bruniaux, Founding Engineer @ Méthode Aristote
**GitHub**: https://github.com/FlorianBruniaux
**License**: Guide = CC BY-SA 4.0 | Templates = CC0 1.0