How jianyyu/jarvis works
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: manager.go Session mgr · daemon.go Daemon core · dashboard.go Dashboard · messages.go Protocol
Components 19
Jarvis CLI
User-facing dashboard and command surface
- jarvis · Main user-facing controller binary
cmd/jarvis/main.go - Dashboard · Interactive session list, actions, and views
internal/tui/dashboard.go - Formatters · Shared presentation and formatting helpers
internal/ui/format.go
Session Control
Orchestration, protocol, and session lifecycle
- Session mgr · Creates, attaches, resumes, and coordinates sessions
internal/session/manager.go - Attach flow · Connects the user process to an existing live session
internal/session/attach.go - Resume flow · Reconnects to detached sessions with persisted state
internal/session/resume.go - JSONL log · Structured session event and output log handling
internal/session/jsonl.go - Protocol · Messages and encoding for jarvis to sidecar communication
internal/protocol/messages.go
Sidecar Runtime
Daemon that owns the live terminal session
- Sidecar · Per-session background process that owns Claude in a PTY
cmd/sidecar/main.go - Daemon core · Runs the sidecar control loop and lifecycle handling
internal/sidecar/daemon.go - PTY · Terminal interface to the live Claude process
internal/sidecar/pty.go - Ring buffer · Buffers terminal output for replay and reattach
internal/sidecar/ringbuf.go - Status · Structured runtime status and progress reporting
internal/sidecar/status.go
Local State
Filesystem-backed metadata and runtime paths
- Store · Persists sessions, folders, and metadata under the local state dir
internal/store/session.go - Config · User and runtime configuration
internal/config/config.go - Paths · Centralizes filesystem locations for local state
internal/paths/paths.go - Worktree · Optional git worktree and branch setup for sessions
internal/worktree/worktree.go
External Tools
Outside executables and integrations
- Claude Code · Terminal-backed child process driven by the sidecar
- ~/.jarvis · On-disk home for sessions, folders, and config
Connections 24
- 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