Skip to content

Architecture

Jump to bottom
Alex Coulombe edited this page Jun 28, 2026 · 1 revision

Architecture

Claude Fleet has three layers. Each one is independent — you can use them in any combination.

Layer 1: The Shared Knowledge Base (Git)

This is the core of the fleet. It's a private git repo that every machine clones to ~/knowledge/. It serves as:

  • An inbox — inbox/<machine>.md holds pending tasks for each machine
  • A memory — daily/ logs what happened, decisions/ records why, intelligence/techniques/ captures gotchas and reusable patterns
  • A coordination layer — sessions/active/ holds session board entries; triggers/ holds claimed inbox items

Every agent reads CLAUDE.md at the KB root at session start. That file contains routing tables that tell it exactly where to look for any kind of information. This is what makes the KB "self-routing" — agents don't have to search blindly.

~/knowledge/
├── CLAUDE.md           ← Navigation guide. Every session reads this first.
├── inbox/
│   ├── alpha.md        ← Tasks for machine alpha
│   └── beta.md         ← Tasks for machine beta
├── daily/              ← Per-machine session logs (YYYY-MM-DD-machine.md)
├── intelligence/
│   ├── techniques/     ← Reusable engineering patterns and gotchas
│   └── decisions/      ← Architecture decision records
├── fleet/
│   └── roster.md       ← Machine inventory and capabilities
├── projects/           ← Per-project context
├── sessions/
│   └── active/         ← Live session board (one file per session)
└── triggers/           ← Claimed inbox items with status tracking

Conflict avoidance: Each machine only writes to its own files. Session entries are one-file-per-session so two sessions never edit the same file. Daily logs are per-machine. This keeps git merges trivial.

Layer 2: Claude Code Hooks

Hooks are what make the fleet autonomous. Claude Code calls shell commands at lifecycle events:

Hook Script What it does
SessionStart session-board-show.sh Registers this session on the board; prints who else is active and what they're holding
SessionStart kb-inbox-check.sh Pulls the KB; injects pending inbox items into Claude's context as top-priority instructions
Stop kb-session-end.sh Commits and pushes any KB changes; ensures nothing is lost
Stop notify-human.js Sends a Telegram notification (✅ done / ❌ error / ⚠️ needs you)
SessionEnd session-board-checkout.sh Removes this session from the board
PostToolUse check-notifications.sh Polls a local directory for mid-session messages from other machines; delivers them within ~60 seconds

You configure hooks in ~/.claude/settings.json — the one file that lives in ~/.claude/. All scripts live in ~/claude-fleet/.

Layer 3: Telegram (Optional)

Two separate Telegram components serve different purposes:

Fleet bot (telegram/fleet-bot/) — a Node.js bot that receives Claude Code's turn-guard notifications and lets you approve, stop, or resume sessions from your phone. Works alongside any Claude session on any machine.

Channel plugin (telegram/channel-addons/) — extends the official claude --channels plugin:telegram session with rate-limit awareness. One fleet machine (typically an always-on machine like a home server) runs the channel session, and you interact with it by messaging the bot. This is the "remote Claude on your phone" experience.

You don't need Telegram at all for the inbox and KB to work. Telegram adds the notification layer and the phone-control layer on top.

How a Task Flows Through the Fleet

You write a task to inbox/beta.md → git push
                    │
            (beta's next session start)
                    │
            kb-inbox-check.sh pulls the KB
                    │
            Task is injected into Claude's context
                    │
            Claude processes the task
            (reads projects/, asks questions via inbox/alpha.md, etc.)
                    │
            kb-session-end.sh commits results to the KB, pushes
                    │
            notify-human.js → Telegram: "✅ Task complete"

Beta can write back to inbox/alpha.md if it needs alpha to do something. Alpha picks it up on its next session start. Neither machine needs to be online at the same time.

Session Board

When multiple sessions run concurrently, the session board prevents them from stepping on each other's singleton resources (a build engine, a physical device, a booted simulator):

session-board.sh board

ACTIVE SESSIONS — 2 entries

● alpha/ue-build   building  claim: ue-build-engine, AVP-device   eta: ~14:30   hb: 2m ago
    Unreal 5.6 · ~/git/MyApp @ feat/lighting
    doing: baking lightmaps for scene B

● beta/research    active    claim: -                              eta: -        hb: 1m ago
    Claude Sonnet 4.6 · ~/knowledge
    doing: summarizing product feedback

Before starting a build or installing to a device, any session can check the board and see what's claimed. The claim: field is the key one — if ue-build-engine is claimed, you wait or coordinate.

Model Routing

The fleet uses a three-tier routing model to keep costs down:

Tier Provider Typical tasks
Local Ollama on any fleet machine Summarization, reformatting, simple classification — free
Mid-tier Gemini 2.5 Flash / NVIDIA NIM Research, large-file analysis, code generation at scale
Claude Anthropic Orchestration, judgment, novel architecture, final review

Confidence thresholds for delegation: 90%+ = auto-dispatch to cheaper tier; 70–89% = ask first; below 70% = Claude handles.

Within Claude itself: Haiku 4.5 for mechanical edits → Sonnet 4.6 for implementation (default, ~80% of tasks) → Opus 4.8 for novel architecture or subtle root causes.

Clone this wiki locally