Architecture

An overview of the project structure, package responsibilities, and key dependencies.

---

Top-level layout

agent-dashboard/
├── Makefile
├── VERSION
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── SECURITY.md
├── release-please-config.json
├── install.sh                         # binary installer (plugins are registered separately via each host's marketplace)
├── agent-dashboard.tmux               # optional tmux keybinding (prefix + D)
├── settings.example.toml              # default settings (copied by installer)
├── go.mod / go.sum
├── cmd/
│   ├── dashboard/                     # TUI entry point
│   ├── web/                           # web server entry point
│   ├── skillgen/                      # generates adapter skills from adapters/skills-src/
│   ├── populate-quotes/               # bulk quote fetcher for SQLite cache
│   └── recompute-claude-usage/        # rebuilds usage totals from transcripts
├── internal/                          # core packages (see below)
├── adapters/skills-src/               # single source tree for workflow skills (make gen-skills)
├── adapters/claude-code/              # Claude Code plugin adapter (generated skills; see Adapter reference)
├── adapters/codex/                    # Codex plugin adapter (generated skills; hooks ship inside the plugin bundle)
└── schema/
    └── agent-state.schema.json        # JSON Schema for agent state files

Internal packages

internal/
├── codex/           # Codex state and conversation readers
├── config/          # agent profile + TOML settings loader
├── conversation/    # JSONL parsing, subagent discovery (routes per harness)
├── db/              # SQLite operations (usage + quotes)
├── diagrams/        # mermaid diagram capture, storage, and rendering
├── domain/          # shared type definitions (Agent, Message, Harness, etc.)
├── gh/              # GitHub CLI helpers (CODEOWNERS, merge args)
├── git/             # thin layer over git subprocess invocations
├── harness/         # harness registry + per-harness spawn commands (claude/, codex/)
├── lock/            # singleton instance lock
├── mocks/           # mockery-generated test mocks
├── repo/            # git topology facts (worktrees, repo roots)
├── repowin/         # repo-to-tmux-window matching
├── skills/          # plugin skill discovery + codex skill guard
├── state/           # agent state structs + file I/O
├── tmux/            # tmux integration helpers
├── tui/             # Bubble Tea UI (model, view, keys, commands)
├── usage/           # token counting + pricing
├── web/             # web server, handlers, OAuth, SSE, static assets
└── zsuggest/        # z-plugin frecency suggestions

Key packages

internal/tui/ — The Bubble Tea TUI. The model, view, and update loop live here, along with the diff viewer, banner, keybindings, and styles. All external command execution goes through a Runner interface for testability.

internal/state/ — Reads and writes per-agent JSON state files in ~/.agent-dashboard/agents/. The TUI polls these files and uses fsnotify for instant updates.

internal/conversation/ — Incrementally parses JSONL conversation logs. Tracks file offsets to avoid re-reading entire logs on each poll.

internal/web/ — The mobile companion web server. Serves the PWA, handles Google OAuth, and streams state updates via Server-Sent Events.

Key dependencies

Package	Purpose
bubbletea	TUI framework
bubbles	Viewport, text input, spinner
lipgloss	ANSI styling
glamour	Markdown rendering
chroma	Syntax highlighting
go-gitdiff	Git diff parsing
toml	Settings file parsing
sqlx	SQL query helper
modernc.org/sqlite	Pure Go SQLite
fsnotify	File system watcher
oauth2	Google OAuth

Data flow

Claude Code session
  └─ adapter hooks fire on tool calls / state changes
     └─ write JSON to ~/.agent-dashboard/agents/<session>.json
        └─ dashboard reads via fsnotify + polling
           ├─ TUI renders in terminal
           └─ web server streams via SSE to mobile PWA