Architecture

Deep-dive into the Claude Code agent system architecture.

Architecture Overview


  ┌───────────────────────────────────┐
  │  User Input Layer                 │
  │  (Terminal, Telegram, etc.)       │
  └────────────────┬──────────────────┘
                   │
                   ▼
  ┌───────────────────────────────────┐
  │  Claude Code CLI                  │
  │  (commands, agents, hooks)        │
  └────────────────┬──────────────────┘
                   │
        ┌──────────┼──────────┐
        │          │          │
        ▼          ▼          ▼
  ┌───────────┐┌───────────┐┌─────────────┐
  │  Slash    ││  Agents   ││ Skill Packs │
  │  Commands ││  (.md     ││ (multi-step)│
  │  (.md)    ││  personas)││             │
  └─────┬─────┘└─────┬─────┘└──────┬──────┘
        │             │             │
        └─────────────┼─────────────┘
                      │
                      ▼
  ┌───────────────────────────────────┐
  │  Python Scripts Layer             │
  │  (data fetchers, parsers)         │
  └────────────────┬──────────────────┘
                   │
     ┌──────┬──────┼──────┬──────┐
     │      │      │      │      │
     ▼      ▼      ▼      ▼      ▼
  ┌──────┐┌──────┐┌──────┐┌──────┐┌──────────┐
  │ APIs ││ DBs  ││Files ││Apple ││ External │
  │Google││SQLite││JSONL ││Notes ││ 1Pass    │
  │GitHub││      ││ .md  ││Health││ Telegram │
  └──┬───┘└──┬───┘└──┬───┘└──┬───┘└────┬─────┘
     │       │       │       │         │
     └───────┴───────┼───────┴─────────┘
                     │
                     ▼
  ┌───────────────────────────────────┐
  │  Knowledge Vault                  │
  │  (PARA + knowledge base)          │
  └───────────────────────────────────┘

Key Design Principles

Principle	What It Means
Deterministic + Probabilistic	Scripts for repeatable tasks, LLM for reasoning
Hooks enforce correctness	Pre/post hooks validate work, inject context
PARA structure	Projects, Areas, Resources, Archives — consistent everywhere
Symlinks for portability	Commands/agents live in vault, symlinked to `~/.claude/`
Credential vault for secrets	No hardcoded credentials — everything via `op` CLI or env vars

Sections

Components — Agents, commands, and skill packs
Data Flow — How data moves through the system
Scheduling — Time-based, event-based, and hybrid patterns