Claude Code — Visual Reference
Claude Code — Visual Reference
Section titled “Claude Code — Visual Reference”All diagrams in one place. Quick visual overview of Claude Code’s key concepts. For detailed docs → Ultimate Guide | Cheatsheet
Interactive Mermaid diagrams available: For 40 interactive diagrams covering model selection, agent lifecycle, memory hierarchy, multi-agent patterns, security threats, and more — see guide/diagrams/. This file contains ASCII versions of key concepts.
20 diagrams: 8 new (this file) + 12 from existing guides, all consolidated here.
Table of Contents
Section titled “Table of Contents”New diagrams:
Architecture & Internals: 5. Master Loop 6. Hook Event Flow 7. Data Privacy Flow
Security: 8. MCP Rug Pull Attack 9. Docker Sandbox Architecture
Decision Trees: 10. Search Tool Selection 11. Trust Calibration Flow 12. Adoption Decision Tree 13. Methodology Selection
Workflows: 14. Research → Spec → Code 15. Review Auto-Correction Loop 16. PDF Pipeline Stack
Development & Learning: 17. TDD Red-Green-Refactor Cycle 18. UVAL Protocol Flow
Security (extended): 19. Security 3-Layer Defense 20. Secret Exposure Timeline
1. Context Management Zones
Section titled “1. Context Management Zones”How to react based on context window usage (check with /status):
Context Usage0% 50% 70% 90% 100%├───────────┼───────────┼───────────┼──────────┤│ GREEN │ YELLOW │ ORANGE │ RED ││ work │ selective │ /compact │ /clear ││ freely │ with care │ NOW │ required │└───────────┴───────────┴───────────┴──────────┘ ▲ ▲ │ │ Be selective Risk: forgetting about reads instructions, and tool use hallucinationsActions by zone:
- Green (0-50%) — Full speed. Read files, explore freely.
- Yellow (50-70%) — Be selective. Avoid unnecessary file reads.
- Orange (70-90%) — Run
/compactimmediately. Context is degrading. - Red (90%+) — Run
/clearand restart. Responses are unreliable.
→ Source: ultimate-guide.md:1335
2. Permission Modes Cycle
Section titled “2. Permission Modes Cycle”Cycle through modes with Shift+Tab:
Shift+Tab Shift+Tab ┌──────────┐ ────────────→ ┌───────────────┐ ────────────→ ┌───────────┐ │ DEFAULT │ │ AUTO-ACCEPT │ │ PLAN MODE │ │ │ │ │ │ │ │ edit=ask │ │ edit=auto │ │ edit=no │ │ exec=ask │ │ exec=ask │ │ exec=no │ └──────────┘ ←──────────── └───────────────┘ ←──────────── └───────────┘ Shift+Tab Shift+TabWhen to use each mode:
| Mode | Use when… | Risk level |
|---|---|---|
| Default | Normal development — review each change | Low |
| Auto-accept | Trusted tasks (formatting, refactoring) | Medium |
| Plan mode | Complex/risky operations — explore safely first | None |
Shortcuts:
Shift+Tab— Cycle to next modeShift+Tab × 2— Jump to plan mode from default/plan— Enter plan mode directly/execute— Exit plan mode
→ Source: ultimate-guide.md:760
3. Workflow Pipeline (9 Steps)
Section titled “3. Workflow Pipeline (9 Steps)”The recommended workflow for every task:
┌─────────┐ ┌──────────┐ ┌────────────┐ ┌─────────────┐ │ 1.START │───→│ 2./status│───→│ 3. plan? │───→│ 4. describe │ │ claude │ │ check ctx│ │ Shift+Tab×2│ │ WHAT/WHERE │ └─────────┘ └──────────┘ │ (if risky) │ │ HOW/VERIFY │ └────────────┘ └──────┬──────┘ │ ┌───────────────────────────────────────────────────┘ │ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 5.review │───→│ 6. y/n │───→│ 7. test │───→│ 8.commit │───→│9./compact│ │ diff │ │ accept? │ │ run │ │ when done│ │ when >70%│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘Key principles:
- Step 2: Always check context before starting. If >70%,
/compactfirst. - Step 3: Use plan mode for anything risky, complex, or multi-file.
- Step 4: Be specific — vague prompts produce vague results.
- Step 5: Read every diff. Never blindly accept.
- Step 9: Compact after each task to stay in the green zone.
→ Source: ultimate-guide.md:277
4. Quick Decision Tree
Section titled “4. Quick Decision Tree”What to do based on your situation:
What do you need?│├─ Simple task ─────────────────→ Just ask Claude│├─ Complex task│ ├─ Single session ───────────→ /plan + Tasks API│ └─ Multi-session ────────────→ Tasks API + CLAUDE_CODE_TASK_LIST_ID│├─ Repeating task ──────────────→ Create agent or command│├─ Context >70% ────────────────→ /compact│├─ Context >90% ────────────────→ /clear (restart conversation)│├─ Need library docs ───────────→ Context7 MCP│├─ Deep debugging ──────────────→ Opus model + Alt+T (thinking)│├─ UI from design ──────────────→ Figma MCP or screenshot input│└─ Team rollout ────────────────→ Read adoption-approaches.md→ Source: reference.yaml (decide section)
5. Master Loop
Section titled “5. Master Loop”The entire architecture is a simple while loop — no DAG, no classifier, no RAG.
┌─────────────────────────────────────────────────────────────┐│ CLAUDE CODE MASTER LOOP │├─────────────────────────────────────────────────────────────┤│ ││ ┌──────────────┐ ││ │ Your Prompt │ ││ └──────┬───────┘ ││ │ ││ ▼ ││ ┌──────────────────────────────────────────────────────┐ ││ │ │ ││ │ CLAUDE REASONS │ ││ │ (No classifier, no routing layer) │ ││ │ │ ││ └────────────────────────┬─────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────┐ ││ │ Tool Call? │ ││ └───────┬────────┘ ││ │ ││ YES │ NO ││ ┌─────────────────┴─────────────────┐ ││ │ │ ││ ▼ ▼ ││ ┌────────────┐ ┌────────────┐ ││ │ Execute │ │ Text │ ││ │ Tool │ │ Response │ ││ │ │ │ (DONE) │ ││ └─────┬──────┘ └────────────┘ ││ │ ││ ▼ ││ ┌─────────────┐ ││ │ Feed Result │ ││ │ to Claude │──────────────────┐ ││ └─────────────┘ │ ││ │ ││ ▼ ││ ┌────────────────┐ ││ │ LOOP BACK │ ││ │ (Next turn) │ ││ └────────────────┘ ││ │└─────────────────────────────────────────────────────────────┘→ Source: architecture.md:84
6. Hook Event Flow
Section titled “6. Hook Event Flow”How hooks intercept Claude Code’s execution pipeline:
┌─────────────────────────────────────────────────────────┐│ EVENT FLOW │├─────────────────────────────────────────────────────────┤│ ││ User types message ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ UserPromptSubmit │ ← Add context (git status) ││ └────────────────────┘ ││ │ ││ ▼ ││ Claude decides to run tool (e.g., Edit) ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ PreToolUse │ ← Security check ││ └────────────────────┘ ││ │ ││ ▼ (if allowed) ││ Tool executes ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ PostToolUse │ ← Auto-format ││ └────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘→ Source: ultimate-guide.md:6327
7. Data Privacy Flow
Section titled “7. Data Privacy Flow”What data leaves your machine when using Claude Code:
┌─────────────────────────────────────────────────────────────┐│ YOUR LOCAL MACHINE │├─────────────────────────────────────────────────────────────┤│ • Prompts you type ││ • Files Claude reads (including .env if not excluded!) ││ • MCP server results (SQL queries, API responses) ││ • Bash command outputs ││ • Error messages and stack traces │└───────────────────────┬─────────────────────────────────────┘ │ ▼ HTTPS┌─────────────────────────────────────────────────────────────┐│ ANTHROPIC API │├─────────────────────────────────────────────────────────────┤│ • Processes your request ││ • Stores conversation based on retention policy ││ • May use data for model training (if not opted out) │└─────────────────────────────────────────────────────────────┘→ Source: data-privacy.md:24
8. MCP Rug Pull Attack
Section titled “8. MCP Rug Pull Attack”How a malicious MCP server can exploit the one-time approval model:
┌─────────────────────────────────────────────────────────────┐│ 1. Attacker publishes benign MCP "code-formatter" ││ ↓ ││ 2. User adds to ~/.claude.json, approves once ││ ↓ ││ 3. MCP works normally for 2 weeks (builds trust) ││ ↓ ││ 4. Attacker pushes malicious update (no re-approval!) ││ ↓ ││ 5. MCP exfiltrates ~/.ssh/*, .env, credentials │└─────────────────────────────────────────────────────────────┘MITIGATION: Version pinning + hash verification + monitoring→ Source: security-hardening.md:33
9. Docker Sandbox Architecture
Section titled “9. Docker Sandbox Architecture”Full isolation for autonomous Claude Code sessions:
┌──────────────────────────────────────────────────────────┐│ HOST MACHINE ││ ││ ┌────────────────────────────────────────────────────┐ ││ │ DOCKER SANDBOX (microVM) │ ││ │ │ ││ │ ┌──────────────┐ ┌───────────────────────────┐ │ ││ │ │ Claude Code │ │ Private Docker daemon │ │ ││ │ │ (--dsp mode) │ │ (isolated from host) │ │ ││ │ └──────────────┘ └───────────────────────────┘ │ ││ │ │ ││ │ ┌──────────────────────────────────────────────┐ │ ││ │ │ Workspace: ~/my-project (synced with host) │ │ ││ │ │ Same absolute path as host │ │ ││ │ └──────────────────────────────────────────────┘ │ ││ │ │ ││ │ Base: Ubuntu, Node.js, Python 3, Go, Git, │ ││ │ Docker CLI, GitHub CLI, ripgrep, jq │ ││ │ User: non-root 'agent' with sudo │ ││ └────────────────────────────────────────────────────┘ ││ ││ Host Docker daemon: NOT accessible from sandbox ││ Host filesystem: NOT accessible (except workspace) │└──────────────────────────────────────────────────────────┘→ Source: sandbox-isolation.md:87
10. Search Tool Selection
Section titled “10. Search Tool Selection”3-level decision tree for choosing the right search tool:
Level 1: What Do You Know?
Do you know the EXACT text/pattern?│├─ YES → Use rg (ripgrep)│ ├─ Known function name: rg "createSession"│ ├─ Known import: rg "import.*React"│ └─ Known pattern: rg "async function"│└─ NO → Go to Level 2Level 2: What Are You Looking For?
What's your search intent?│├─ "Find by MEANING/CONCEPT"│ → Use grepai│ └─ Example: grepai search "payment validation logic"│├─ "Find FUNCTION/CLASS definition"│ → Use Serena│ └─ Example: serena find_symbol --name "UserController"│├─ "Find by CODE STRUCTURE"│ → Use ast-grep│ └─ Example: async without error handling│└─ "Understand DEPENDENCIES" → Use grepai trace └─ Example: grepai trace callers "validatePayment"Level 3: Optimization
Found too many results?│├─ rg → Add --type filter or narrow path├─ grepai → Add --path filter or use trace├─ Serena → Filter by symbol type (function/class)└─ ast-grep → Add constraints to pattern→ Source: search-tools-mastery.md:75
11. Trust Calibration Flow
Section titled “11. Trust Calibration Flow”How much to review AI-generated code based on risk level:
┌─────────────────────────────────────────────────────────┐│ TRUST CALIBRATION FLOW │├─────────────────────────────────────────────────────────┤│ ││ AI generates code ││ │ ││ ▼ ││ ┌──────────────┐ ││ │ What type? │ ││ └──────────────┘ ││ │ │ │ ││ ▼ ▼ ▼ ││ Boiler Business Security ││ -plate logic critical ││ │ │ │ ││ ▼ ▼ ▼ ││ Skim Test + Full review ││ only review + tools ││ │ │ │ ││ └──────┴────────┘ ││ │ ││ ▼ ││ Tests pass? ──No──► Debug & fix ││ │ ││ Yes ││ │ ││ ▼ ││ Ship it ││ │└─────────────────────────────────────────────────────────┘→ Source: ultimate-guide.md:1182
12. Adoption Decision Tree
Section titled “12. Adoption Decision Tree”How to choose your Claude Code adoption strategy:
Starting Claude Code?│├─ Need to ship today?│ └─ YES → Turnkey Quickstart│ └─ NO ↓│├─ Team needs shared conventions?│ └─ YES → Turnkey + document what matters to you│ └─ NO ↓│├─ Want to understand before configuring?│ └─ YES → Autonomous Learning Path│ └─ NO → Turnkey, adjust as you go→ Source: adoption-approaches.md:51
13. Methodology Selection
Section titled “13. Methodology Selection”Which development methodology to use:
┌─ "I want quality code" ────────────→ workflows/tdd-with-claude.md│├─ "I want to spec before code" ─────→ workflows/spec-first.md│├─ "I need to plan architecture" ────→ workflows/plan-driven.md│├─ "I'm iterating on something" ─────→ workflows/iterative-refinement.md│└─ "I need methodology theory" ──────→ methodologies.md→ Source: methodologies.md:24
14. Research → Spec → Code
Section titled “14. Research → Spec → Code”Using Perplexity for research, then Claude Code for implementation:
┌─────────────────────────────────────────────────────────┐│ 1. PERPLEXITY (Deep Research) ││ "Research best practices for JWT refresh tokens ││ in Next.js 15. Include security considerations, ││ common pitfalls, and library recommendations." ││ ││ → Output: 2000-word spec with sources │└───────────────────────────┬─────────────────────────────┘ ↓ Export as spec.md┌─────────────────────────────────────────────────────────┐│ 2. CLAUDE CODE ││ > claude ││ "Implement JWT refresh tokens following spec.md. ││ Use the jose library as recommended." ││ ││ → Output: Working implementation with tests │└─────────────────────────────────────────────────────────┘→ Source: ai-ecosystem.md:155
15. Review Auto-Correction Loop
Section titled “15. Review Auto-Correction Loop”Iterative code review pattern where Claude reviews, fixes, and re-reviews:
┌─────────────────────────────────────────┐│ Review Auto-Correction Loop ││ ││ Review (identify issues) ││ ↓ ││ Fix (apply corrections) ││ ↓ ││ Re-Review (verify fixes) ││ ↓ ││ Converge (minimal changes) → Done ││ ↑ ││ └──── Repeat (max iterations) │└─────────────────────────────────────────┘→ Source: iterative-refinement.md:354
16. PDF Pipeline Stack
Section titled “16. PDF Pipeline Stack”Quarto + Typst stack for generating professional PDFs:
┌─────────────────────────────────────────────────┐│ Your .qmd File ││ (Markdown + YAML frontmatter) │└─────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────┐│ Quarto ││ (Document rendering engine) ││ • Processes YAML metadata ││ • Handles extensions ││ • Manages output formats │└─────────────────────────────────────────────────┘ │ ┌─────────────┴─────────────┐ ▼ ▼┌─────────────────────┐ ┌─────────────────────┐│ Pandoc │ │ Typst ││ (MD → AST → ?) │ │ (Typography/PDF) ││ • Markdown parser │ │ • Modern engine ││ • AST transforms │ │ • Fast compilation ││ • Format bridges │ │ • No LaTeX needed │└─────────────────────┘ └─────────────────────┘ │ ▼┌─────────────────────────────────────────────────┐│ document.pdf ││ (Professional typography output) │└─────────────────────────────────────────────────┘→ Source: pdf-generation.md:58
17. TDD Red-Green-Refactor Cycle
Section titled “17. TDD Red-Green-Refactor Cycle”The iterative loop at the heart of Test-Driven Development:
┌──────────────────────────┐ │ │ ▼ │ ┌──────────────┐ │ │ 🔴 RED │ │ │ │ │ │ Write a │ │ │ failing │ │ │ test │ │ └──────┬───────┘ │ │ │ │ Tests FAIL │ │ (expected) │ ▼ │ ┌──────────────┐ │ │ 🟢 GREEN │ │ │ │ │ │ Write │ │ │ minimal │ │ │ code to │ │ │ pass │ │ └──────┬───────┘ │ │ │ │ Tests PASS │ │ (minimal) │ ▼ │ ┌──────────────┐ │ │ 🔵 REFACTOR│ │ │ │ │ │ Clean up │ │ │ while tests │ │ │ stay green │ │ └──────┬───────┘ │ │ │ │ Next feature │ └───────────────────────────┘
Key rules: RED → Test must FAIL before writing implementation GREEN → Write ONLY enough code to pass (no more) REFACTOR → Improve structure, tests must stay green REPEAT → One feature at a time, always in this orderSource: workflows/tdd-with-claude.md:78
18. UVAL Protocol Flow
Section titled “18. UVAL Protocol Flow”Systematic framework for learning with AI without losing your edge:
┌────────────────────────────────────────────────────────────┐ │ UVAL PROTOCOL │ │ (Use AI without losing your edge) │ └────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ U │ │ V │ │ A │ │ L │ │UNDERSTAND│────→│ VERIFY │────→│ APPLY │────→│ LEARN │ │ │ │ │ │ │ │ │ │ 15-min │ │ Can you │ │ Modify │ │ Capture │ │ rule: │ │ explain │ │ the code │ │ insights │ │ │ │ it back? │ │ yourself │ │ for long │ │ 1.State │ │ │ │ │ │ term │ │ problem│ │ Test: │ │ Tasks: │ │ │ │ 2.Brain- │ │ explain │ │ • Extend │ │ Methods: │ │ storm │ │ to a │ │ • Modify │ │ • Notes │ │ 3.Find │ │ colleague│ │ • Debug │ │ • Teach │ │ gaps │ │ without │ │ • Adapt │ │ • Blog │ │ 4.Ask │ │ looking │ │ to new │ │ • Review │ │ smart │ │ at code │ │ context│ │ later │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ ◄── Repeat per concept ──► │ └───────────────────────────────────────────────────┘
If VERIFY fails → go back to UNDERSTAND (you copied, didn't learn) If APPLY fails → go back to VERIFY (you memorized, didn't understand)Source: learning-with-ai.md:208
19. Security 3-Layer Defense
Section titled “19. Security 3-Layer Defense”The full security document (security-hardening.md) organized as 3 defense layers:
┌─────────────────────────────────────────────────────────────┐ │ SECURITY 3-LAYER DEFENSE │ ├─────────────────────────────────────────────────────────────┤ │ │ │ TIME ──────────────────────────────────────────────────► │ │ Before During After │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │ │ │ LAYER 1 │ │ LAYER 2 │ │ LAYER 3 │ │ │ │ PREVENTION │ │ DETECTION │ │ RESPONSE │ │ │ │ │ │ │ │ │ │ │ │ • MCP vetting │ │ • Prompt inject │ │ • Secret │ │ │ │ workflow │ │ detection │ │ rotation │ │ │ │ • Version │ │ • Output │ │ • MCP │ │ │ │ pinning │ │ scanning │ │ isolation │ │ │ │ • .claudeignore │ │ • Anomaly │ │ • History │ │ │ │ • Input hooks │ │ monitoring │ │ rewriting │ │ │ │ • Safe MCP list │ │ • Secret leak │ │ • Incident │ │ │ │ • Permissions │ │ detection │ │ reporting │ │ │ │ • Integrity │ │ • Unicode/ANSI │ │ • Post-mortem │ │ │ │ scanning │ │ filtering │ │ & rotation │ │ │ │ │ │ │ │ │ │ │ │ GOAL: Block │ │ GOAL: Catch │ │ GOAL: Limit │ │ │ │ threats at │ │ attacks in │ │ damage and │ │ │ │ entry points │ │ real-time │ │ recover fast │ │ │ └─────────────────┘ └─────────────────┘ └───────────────┘ │ │ │ │ Adoption path: │ │ Solo dev → Layer 1 basics (output scanner) │ │ Team → Layer 1 + 2 (+ injection hooks) │ │ Enterprise → All 3 layers (+ ZDR + verification) │ │ │ └─────────────────────────────────────────────────────────────┘Source: security-hardening.md:24/205/345
20. Secret Exposure Timeline
Section titled “20. Secret Exposure Timeline”Emergency response when a secret (API key, token, password) is exposed:
SECRET EXPOSED — Emergency Response Timeline ═══════════════════════════════════════════════════════════
0 min 15 min 1 hour 24 hours │ │ │ │ ▼ ▼ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ ⏱️ FIRST 15 MIN │ │ ⏱️ FIRST HOUR │ │ ⏱️ FIRST 24H │ │ Stop the │ │ Assess damage │ │ Remediate │ │ bleeding │ │ │ │ │ │ │ │ 3. Audit git │ │ 6. Rotate ALL │ │ 1. REVOKE key │ │ history │ │ related │ │ immediately │ │ (rewrite if │ │ credentials │ │ (AWS/GH/ │ │ pushed) │ │ │ │ Stripe) │ │ │ │ 7. Notify team │ │ │ │ 4. Scan deps │ │ /compliance │ │ 2. Confirm │ │ for leaked │ │ (GDPR/SOC2) │ │ exposure │ │ keys │ │ │ │ scope │ │ │ │ 8. Document │ │ (local or │ │ 5. Check CI/CD │ │ incident │ │ pushed?) │ │ logs │ │ timeline │ │ │ │ │ │ │ └──────────────────┘ └─────────────────┘ └────────────────┘
SEVERITY GUIDE: ┌─────────────────────────────────────────────────────────┐ │ Local only (not pushed) → Revoke + rotate (steps 1-2) │ │ Pushed to remote → Full timeline (steps 1-8) │ │ Public repo exposure → Assume compromised, rotate │ │ EVERYTHING, check for abuse │ └─────────────────────────────────────────────────────────┘Source: security-hardening.md:347
Back to Guide README | Cheatsheet | Main README