# jianyyu/jarvis architecture

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

- Interactive diagram: https://gitdiagram.com/jianyyu/jarvis
- Repository: https://github.com/jianyyu/jarvis

## Overview

1. **Two-process architecture**
   - The repo builds two binaries: `jarvis` (`cmd/jarvis`) and `jarvis-sidecar` (`cmd/sidecar`).
   - `jarvis` is the user-facing CLI/TUI controller.
   - `jarvis-sidecar` is a per-session background daemon that owns the live Claude Code process.

2. **Primary runtime boundary**
   - The key separation is between the dashboard process and the session daemon.
   - `jarvis` communicates with the sidecar over a **Unix socket** using a custom protocol.
   - The sidecar communicates with Claude Code through a **PTY**, which is what allows attach/detach behavior similar to `tmux`.

3. **Session lifecycle**
   - Sessions can be created, attached, detached, resumed, renamed, marked done, and deleted.
   - When attached, the user interacts with the live PTY session.
   - When detached, the sidecar keeps Claude running in the background and persists enough state to reattach later with resume semantics.

4. **Dashboard and command surface**
   - `internal/tui` implements the interactive dashboard using Bubble Tea-style TUI patterns.
   - It presents sessions, folders, status, search, and keyboard-driven actions.
   - `internal/ui` appears to hold shared formatting/rendering helpers used by the TUI.

5. **Session orchestration layer**
   - `internal/session` is the coordination layer for session creation, attach, resume, and JSONL handling.
   - This layer sits between the CLI/TUI and persistence/daemon boundaries.
   - It likely encapsulates the logic for deciding whether to start a new sidecar, reconnect to an existing one, or resume Claude.

6. **Protocol boundary**
   - `internal/protocol` defines the messages and codec used between `jarvis` and `jarvis-sidecar`.
   - This is an important architectural seam because it keeps the UI process decoupled from PTY/session internals.
   - The protocol likely carries status, output, control commands, and lifecycle events.

7. **Sidecar internals**
   - `internal/sidecar` contains the PTY daemon implementation.
   - The daemon owns the child Claude process, reads/writes terminal data, and exposes status back to the dashboard.
   - Supporting pieces like `ringbuf.go` suggest buffered terminal output for replay or attachment, while `status.go` suggests structured progress/state reporting.

8. **Persistence and local state**
   - `internal/store` is the file-backed persistence layer.
   - The README indicates state is stored under `~/.jarvis/`, including sessions, folders, and config.
   - `atomic.go` suggests crash-safe file updates, which matters because multiple processes may read/write session metadata over time.

9. **Organization model**
   - `internal/store/folder.go` and `internal/tui` folder-related commands show that sessions are grouped into folders, not just a flat list.
   - This is a user-facing data model on top of sessions, likely stored separately from the session records themselves.
   - The architecture therefore has both **session state** and **organization metadata** as first-class persisted entities.

10. **Configuration and path handling**
    - `internal/config` manages settings, while `internal/paths` centralizes filesystem locations.
    - This keeps all runtime state anchored to a predictable local directory layout and avoids scattering path logic across the app.

11. **Git/worktree integration**
    - `internal/worktree` indicates optional integration with git worktrees/branches when initializing a session.
    - This is not the main control plane, but it matters because it ties session creation to project context and branch isolation.

12. **Claude Code integration**
    - The system is built around the external Claude Code CLI, not a custom agent runtime.
    - `JARVIS_SESSION_ID` is injected into session environments so Claude-side slash commands can talk back to Jarvis-managed session metadata.
    - That makes Claude Code an execution target inside the sidecar-managed PTY rather than a peer service.

13. **Data flow summary**
    - User input enters `jarvis` through the TUI or CLI commands.
    - `jarvis` reads/writes local state, then sends commands over the socket to the relevant sidecar.
    - The sidecar drives Claude in a PTY, streams status/output back, and persists enough live context for later reattachment.
    - Folder/session metadata stays on disk in the Jarvis state directory so the dashboard survives restarts.

14. **Testing and mock boundaries**
    - `integration_test.go` plus `testdata/mock_claude.go` indicate the repo includes end-to-end coverage with a mocked Claude executable.
    - That reflects the architecture’s key external boundary: behavior depends on a terminal-backed child process, so testing needs a fake Claude runner.

15. **What to draw in an architecture diagram**
    - Show three main nodes: user/TUI (`jarvis`), daemon (`jarvis-sidecar`), and Claude Code.
    - Connect `jarvis` to `jarvis-sidecar` with a Unix socket.
    - Connect sidecar to Claude with a PTY.
    - Add local persistence under `~/.jarvis/` for sessions, folders, and config.
    - Optionally show git/worktree integration as a side dependency of session initialization.

Main entry points: [`internal/session/manager.go`](https://github.com/jianyyu/jarvis/blob/main/internal/session/manager.go) (Session mgr), [`internal/sidecar/daemon.go`](https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/daemon.go) (Daemon core), [`internal/tui/dashboard.go`](https://github.com/jianyyu/jarvis/blob/main/internal/tui/dashboard.go) (Dashboard), [`internal/protocol/messages.go`](https://github.com/jianyyu/jarvis/blob/main/internal/protocol/messages.go) (Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Jarvis CLI"]
  node_n_cmd_jarvis["jarvis<br/>CLI/TUI binary<br/>[main.go]"]
  node_n_tui["Dashboard<br/>Bubble Tea TUI<br/>[dashboard.go]"]
  node_n_ui["Formatters<br/>render helpers<br/>[format.go]"]
end

subgraph group_g_control["Session Control"]
  node_n_session_mgr["Session mgr<br/>orchestration layer<br/>[manager.go]"]
  node_n_attach["Attach flow<br/>session attach<br/>[attach.go]"]
  node_n_resume["Resume flow<br/>session resume<br/>[resume.go]"]
  node_n_jsonl["JSONL log<br/>session transcript<br/>[jsonl.go]"]
  node_n_protocol["Protocol<br/>socket codec<br/>[messages.go]"]
end

subgraph group_g_sidecar["Sidecar Runtime"]
  node_n_sidecar["Sidecar<br/>daemon binary<br/>[main.go]"]
  node_n_daemon["Daemon core<br/>session daemon<br/>[daemon.go]"]
  node_n_pty["PTY<br/>terminal bridge<br/>[pty.go]"]
  node_n_ringbuf["Ring buffer<br/>output buffer<br/>[ringbuf.go]"]
  node_n_status["Status<br/>state model<br/>[status.go]"]
end

subgraph group_g_persistence["Local State"]
  node_n_store[("Store<br/>file-backed state<br/>[session.go]")]
  node_n_config["Config<br/>settings<br/>[config.go]"]
  node_n_paths["Paths<br/>fs layout<br/>[paths.go]"]
  node_n_worktree["Worktree<br/>git integration<br/>[worktree.go]"]
end

subgraph group_g_external["External Tools"]
  node_n_claude{{"Claude Code<br/>external CLI"}}
  node_n_fs[("~/.jarvis<br/>local state dir")]
end

node_n_cmd_jarvis -->|"starts"| node_n_tui
node_n_tui -->|"renders with"| node_n_ui
node_n_tui -->|"issues actions"| node_n_session_mgr
node_n_session_mgr -->|"speaks"| node_n_protocol
node_n_session_mgr -->|"reads/writes"| node_n_store
node_n_session_mgr -->|"uses"| node_n_config
node_n_session_mgr -->|"resolves"| node_n_paths
node_n_session_mgr -->|"initializes"| node_n_worktree
node_n_session_mgr -->|"delegates"| node_n_attach
node_n_session_mgr -->|"delegates"| node_n_resume
node_n_session_mgr -->|"logs"| node_n_jsonl
node_n_sidecar -->|"contains"| node_n_daemon
node_n_daemon -->|"owns"| node_n_pty
node_n_daemon -->|"buffers"| node_n_ringbuf
node_n_daemon -->|"reports"| node_n_status
node_n_daemon -->|"serves"| node_n_protocol
node_n_daemon -->|"spawns"| node_n_claude
node_n_store -->|"persists in"| node_n_fs
node_n_config -->|"loaded from"| node_n_fs
node_n_paths -->|"anchors"| node_n_fs
node_n_worktree -->|"prepares context"| node_n_claude
node_n_cmd_jarvis -->|"connects to"| node_n_sidecar
node_n_protocol -->|"controls"| node_n_daemon
node_n_tui -->|"lists"| node_n_store

click node_n_cmd_jarvis "https://github.com/jianyyu/jarvis/blob/main/cmd/jarvis/main.go"
click node_n_tui "https://github.com/jianyyu/jarvis/blob/main/internal/tui/dashboard.go"
click node_n_ui "https://github.com/jianyyu/jarvis/blob/main/internal/ui/format.go"
click node_n_session_mgr "https://github.com/jianyyu/jarvis/blob/main/internal/session/manager.go"
click node_n_attach "https://github.com/jianyyu/jarvis/blob/main/internal/session/attach.go"
click node_n_resume "https://github.com/jianyyu/jarvis/blob/main/internal/session/resume.go"
click node_n_jsonl "https://github.com/jianyyu/jarvis/blob/main/internal/session/jsonl.go"
click node_n_protocol "https://github.com/jianyyu/jarvis/blob/main/internal/protocol/messages.go"
click node_n_sidecar "https://github.com/jianyyu/jarvis/blob/main/cmd/sidecar/main.go"
click node_n_daemon "https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/daemon.go"
click node_n_pty "https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/pty.go"
click node_n_ringbuf "https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/ringbuf.go"
click node_n_status "https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/status.go"
click node_n_store "https://github.com/jianyyu/jarvis/blob/main/internal/store/session.go"
click node_n_config "https://github.com/jianyyu/jarvis/blob/main/internal/config/config.go"
click node_n_paths "https://github.com/jianyyu/jarvis/blob/main/internal/paths/paths.go"
click node_n_worktree "https://github.com/jianyyu/jarvis/blob/main/internal/worktree/worktree.go"

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_n_cmd_jarvis,node_n_tui,node_n_ui toneBlue
class node_n_session_mgr,node_n_attach,node_n_resume,node_n_jsonl,node_n_protocol toneAmber
class node_n_sidecar,node_n_daemon,node_n_pty,node_n_ringbuf,node_n_status toneMint
class node_n_store,node_n_config,node_n_paths,node_n_worktree toneRose
class node_n_claude,node_n_fs toneIndigo
```

## Components

### Jarvis CLI

User-facing dashboard and command surface

- [jarvis](https://github.com/jianyyu/jarvis/blob/main/cmd/jarvis/main.go): CLI/TUI binary · Main user-facing controller binary · `cmd/jarvis/main.go`
- [Dashboard](https://github.com/jianyyu/jarvis/blob/main/internal/tui/dashboard.go): Bubble Tea TUI · Interactive session list, actions, and views · `internal/tui/dashboard.go`
- [Formatters](https://github.com/jianyyu/jarvis/blob/main/internal/ui/format.go): render helpers · Shared presentation and formatting helpers · `internal/ui/format.go`

### Session Control

Orchestration, protocol, and session lifecycle

- [Session mgr](https://github.com/jianyyu/jarvis/blob/main/internal/session/manager.go): orchestration layer · Creates, attaches, resumes, and coordinates sessions · `internal/session/manager.go`
- [Attach flow](https://github.com/jianyyu/jarvis/blob/main/internal/session/attach.go): session attach · Connects the user process to an existing live session · `internal/session/attach.go`
- [Resume flow](https://github.com/jianyyu/jarvis/blob/main/internal/session/resume.go): session resume · Reconnects to detached sessions with persisted state · `internal/session/resume.go`
- [JSONL log](https://github.com/jianyyu/jarvis/blob/main/internal/session/jsonl.go): session transcript · Structured session event and output log handling · `internal/session/jsonl.go`
- [Protocol](https://github.com/jianyyu/jarvis/blob/main/internal/protocol/messages.go): socket codec · Messages and encoding for jarvis to sidecar communication · `internal/protocol/messages.go`

### Sidecar Runtime

Daemon that owns the live terminal session

- [Sidecar](https://github.com/jianyyu/jarvis/blob/main/cmd/sidecar/main.go): daemon binary · Per-session background process that owns Claude in a PTY · `cmd/sidecar/main.go`
- [Daemon core](https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/daemon.go): session daemon · Runs the sidecar control loop and lifecycle handling · `internal/sidecar/daemon.go`
- [PTY](https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/pty.go): terminal bridge · Terminal interface to the live Claude process · `internal/sidecar/pty.go`
- [Ring buffer](https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/ringbuf.go): output buffer · Buffers terminal output for replay and reattach · `internal/sidecar/ringbuf.go`
- [Status](https://github.com/jianyyu/jarvis/blob/main/internal/sidecar/status.go): state model · Structured runtime status and progress reporting · `internal/sidecar/status.go`

### Local State

Filesystem-backed metadata and runtime paths

- [Store](https://github.com/jianyyu/jarvis/blob/main/internal/store/session.go): file-backed state · Persists sessions, folders, and metadata under the local state dir · `internal/store/session.go`
- [Config](https://github.com/jianyyu/jarvis/blob/main/internal/config/config.go): settings · User and runtime configuration · `internal/config/config.go`
- [Paths](https://github.com/jianyyu/jarvis/blob/main/internal/paths/paths.go): fs layout · Centralizes filesystem locations for local state · `internal/paths/paths.go`
- [Worktree](https://github.com/jianyyu/jarvis/blob/main/internal/worktree/worktree.go): git integration · Optional git worktree and branch setup for sessions · `internal/worktree/worktree.go`

### External Tools

Outside executables and integrations

- **Claude Code**: external CLI · Terminal-backed child process driven by the sidecar
- **~/.jarvis**: local state dir · On-disk home for sessions, folders, and config

## Connections

- jarvis → Dashboard: starts · Launches the interactive dashboard
- Dashboard → Formatters: renders with · Uses shared formatting and presentation helpers
- Dashboard → Session mgr: issues actions · Creates, attaches, resumes, renames, and deletes sessions
- Session mgr → Protocol: speaks · Sends control messages over the sidecar socket
- Session mgr → Store: reads/writes · Loads and persists session and folder metadata
- Session mgr → Config: uses · Resolves runtime settings and behavior
- Session mgr → Paths: resolves · Finds local state locations
- Session mgr → Worktree: initializes · Optionally prepares a project worktree for a session
- Session mgr → Attach flow: delegates · Handles live attach behavior
- Session mgr → Resume flow: delegates · Handles reconnect and resume behavior
- Session mgr → JSONL log: logs · Maintains structured session transcripts
- Sidecar → Daemon core: contains · Binary entrypoint runs the daemon core
- Daemon core → PTY: owns · Controls the live terminal session
- Daemon core → Ring buffer: buffers · Keeps recent output for reattach and replay
- Daemon core → Status: reports · Publishes session state and lifecycle updates
- Daemon core → Protocol: serves · Implements the socket protocol endpoint
- Daemon core → Claude Code: spawns · Launches Claude Code inside the PTY
- Store → ~/.jarvis: persists in · Writes metadata under the Jarvis state directory
- Config → ~/.jarvis: loaded from · Reads configuration from local state
- Paths → ~/.jarvis: anchors · Defines the base directory layout
- Worktree → Claude Code: prepares context · Supports project isolation before session start
- jarvis → Sidecar: connects to · Opens the Unix socket to a session daemon
- Protocol → Daemon core: controls · Carries session control and lifecycle messages
- Dashboard → Store: lists · Displays sessions and folders from disk
