# jp290/claude-fleet architecture

> Architecture diagram of the GitHub repository jp290/claude-fleet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jp290/claude-fleet
- Repository: https://github.com/jp290/claude-fleet

## Overview

Claude Fleet is a self-hosted browser dashboard for coordinating persistent coding-agent sessions. The main workflow is owner authentication, session or task creation, isolated lane execution, then server-controlled rebase and verification before landing; optional post-land audits and conflict review extend that lifecycle. The graph retains documented UI, adapters, queue/program, sharing, and remote-helper capabilities. Sampled server and helper code support selected connections; unsampled capability wiring is kept conservative.

Main entry points: [`server.ts`](https://github.com/jp290/claude-fleet/blob/main/server.ts) (HTTP and WebSocket server), [`server/proc.ts`](https://github.com/jp290/claude-fleet/blob/main/server/proc.ts) (Isolated lanes), [`helper-daemon/daemon.ts`](https://github.com/jp290/claude-fleet/blob/main/helper-daemon/daemon.ts) (Pull-based helper daemon), [`src/client.ts`](https://github.com/jp290/claude-fleet/blob/main/src/client.ts) (Fleet dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard and access"]
  node_server["HTTP and WebSocket server<br/>[server.ts]"]
  node_auth["Token and share auth<br/>[auth.ts]"]
  node_browser["Fleet dashboard UI<br/>[client.ts]"]
  node_shareui["Read-only share UI<br/>[share.ts]"]
  node_share["Share service<br/>[transport.ts]"]
end

subgraph group_execution["Agent execution"]
  node_slots["Persistent slots<br/>[tmux.ts]"]
  node_harness["Agent harness adapters<br/>[server.ts]"]
  node_lane["Isolated lanes<br/>[proc.ts]"]
  node_transcripts["Transcript and conversation<br/>[transcript-read.ts]"]
end

subgraph group_delivery["Task delivery"]
  node_tasks["Task queue<br/>[server.ts]"]
  node_dispatcher["Lane dispatcher<br/>[server.ts]"]
  node_programs["Supervising programs<br/>[server.ts]"]
  node_land["Rebase and land gate<br/>[server.ts]"]
  node_verify["Verify command"]
end

subgraph group_oversight["Review and support"]
  node_audit["Post-land audit<br/>[server.ts]"]
  node_review["Conflict and lane review<br/>[merge-prompt.ts]"]
  node_ledger[("Lane outcome ledgers<br/>[persist.ts]")]
  node_helper["Remote helper portal<br/>[server.ts]"]
  node_daemon["Pull-based helper daemon<br/>[daemon.ts]"]
end

node_owner(("Owner"))
node_filesystem[("Git repositories")]
node_tmux["tmux"]
node_agent["Agent CLI"]
node_suite["Verify suite"]
node_remote["Remote helper machine"]

node_owner -->|"uses"| node_browser
node_browser -->|"API requests"| node_server
node_server -->|"checks access"| node_auth
node_server -->|"manages sessions"| node_slots
node_slots -->|"controls sessions"| node_tmux
node_server -->|"starts agents"| node_harness
node_harness -->|"spawns"| node_agent
node_server -->|"creates worktrees"| node_lane
node_lane -->|"checks out branches"| node_filesystem
node_server -->|"reads output"| node_transcripts
node_server -->|"files and releases"| node_tasks
node_tasks -->|"released tasks"| node_dispatcher
node_dispatcher -->|"starts lanes"| node_lane
node_server -->|"supervises"| node_programs
node_programs -->|"files tasks"| node_tasks
node_server -->|"runs land"| node_land
node_land -->|"rebases and advances"| node_filesystem
node_land -->|"runs command"| node_verify
node_verify -->|"executes"| node_suite
node_land -->|"routes conflicts"| node_review
node_server -->|"schedules audit"| node_audit
node_audit -->|"audits main"| node_filesystem
node_server -->|"records outcomes"| node_ledger
node_shareui -->|"requests shared view"| node_server
node_server -->|"serves sharing"| node_share
node_share -->|"checks share access"| node_auth
node_server -->|"serves helper jobs"| node_helper
node_daemon -.->|"pulls jobs and reports"| node_helper
node_daemon -.->|"runs suite remotely"| node_remote

click node_server "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_auth "https://github.com/jp290/claude-fleet/blob/main/server/auth.ts"
click node_browser "https://github.com/jp290/claude-fleet/blob/main/src/client.ts"
click node_shareui "https://github.com/jp290/claude-fleet/blob/main/src/share.ts"
click node_share "https://github.com/jp290/claude-fleet/blob/main/server/transport.ts"
click node_slots "https://github.com/jp290/claude-fleet/blob/main/server/tmux.ts"
click node_harness "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_lane "https://github.com/jp290/claude-fleet/blob/main/server/proc.ts"
click node_transcripts "https://github.com/jp290/claude-fleet/blob/main/server/transcript-read.ts"
click node_tasks "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_dispatcher "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_programs "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_land "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_audit "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_review "https://github.com/jp290/claude-fleet/blob/main/merge-prompt.ts"
click node_ledger "https://github.com/jp290/claude-fleet/blob/main/server/persist.ts"
click node_helper "https://github.com/jp290/claude-fleet/blob/main/server.ts"
click node_daemon "https://github.com/jp290/claude-fleet/blob/main/helper-daemon/daemon.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_auth,node_browser,node_shareui,node_share toneBlue
class node_slots,node_harness,node_lane,node_transcripts,node_filesystem toneAmber
class node_tasks,node_dispatcher,node_programs,node_land,node_verify toneMint
class node_audit,node_review,node_ledger,node_helper,node_daemon toneRose
class node_owner,node_tmux,node_agent,node_suite,node_remote toneIndigo
```

## Components

### Dashboard and access

- [HTTP and WebSocket server](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Token and share auth](https://github.com/jp290/claude-fleet/blob/main/server/auth.ts): `server/auth.ts`
- [Fleet dashboard UI](https://github.com/jp290/claude-fleet/blob/main/src/client.ts): `src/client.ts`
- [Read-only share UI](https://github.com/jp290/claude-fleet/blob/main/src/share.ts): `src/share.ts`
- [Share service](https://github.com/jp290/claude-fleet/blob/main/server/transport.ts): `server/transport.ts`

### Agent execution

- [Persistent slots](https://github.com/jp290/claude-fleet/blob/main/server/tmux.ts): `server/tmux.ts`
- [Agent harness adapters](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Isolated lanes](https://github.com/jp290/claude-fleet/blob/main/server/proc.ts): `server/proc.ts`
- [Transcript and conversation](https://github.com/jp290/claude-fleet/blob/main/server/transcript-read.ts): `server/transcript-read.ts`

### Task delivery

- [Task queue](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Lane dispatcher](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Supervising programs](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Rebase and land gate](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- **Verify command**

### Review and support

- [Post-land audit](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Conflict and lane review](https://github.com/jp290/claude-fleet/blob/main/merge-prompt.ts): `merge-prompt.ts`
- [Lane outcome ledgers](https://github.com/jp290/claude-fleet/blob/main/server/persist.ts): `server/persist.ts`
- [Remote helper portal](https://github.com/jp290/claude-fleet/blob/main/server.ts): `server.ts`
- [Pull-based helper daemon](https://github.com/jp290/claude-fleet/blob/main/helper-daemon/daemon.ts): `helper-daemon/daemon.ts`

### Other components

- **Owner**
- **Git repositories**
- **tmux**
- **Agent CLI**
- **Verify suite**
- **Remote helper machine**

## Connections

- Owner → Fleet dashboard UI: uses
- Fleet dashboard UI → HTTP and WebSocket server: API requests
- HTTP and WebSocket server → Token and share auth: checks access
- HTTP and WebSocket server → Persistent slots: manages sessions
- Persistent slots → tmux: controls sessions
- HTTP and WebSocket server → Agent harness adapters: starts agents
- Agent harness adapters → Agent CLI: spawns
- HTTP and WebSocket server → Isolated lanes: creates worktrees
- Isolated lanes → Git repositories: checks out branches
- HTTP and WebSocket server → Transcript and conversation: reads output
- HTTP and WebSocket server → Task queue: files and releases
- Task queue → Lane dispatcher: released tasks
- Lane dispatcher → Isolated lanes: starts lanes
- HTTP and WebSocket server → Supervising programs: supervises
- Supervising programs → Task queue: files tasks
- HTTP and WebSocket server → Rebase and land gate: runs land
- Rebase and land gate → Git repositories: rebases and advances
- Rebase and land gate → Verify command: runs command
- Verify command → Verify suite: executes
- Rebase and land gate → Conflict and lane review: routes conflicts
- HTTP and WebSocket server → Post-land audit: schedules audit
- Post-land audit → Git repositories: audits main
- HTTP and WebSocket server → Lane outcome ledgers: records outcomes
- Read-only share UI → HTTP and WebSocket server: requests shared view
- HTTP and WebSocket server → Share service: serves sharing
- Share service → Token and share auth: checks share access
- HTTP and WebSocket server → Remote helper portal: serves helper jobs
- Pull-based helper daemon → Remote helper portal: pulls jobs and reports
- Pull-based helper daemon → Remote helper machine: runs suite remotely