Agent Deck
One terminal TUI to run, monitor, and switch between every Claude Code, Codex, and Gemini CLI session — with forks, worktrees, cost tracking, and phone-controlled orchestration.
The tool wraps existing agent CLIs with relatively low intrusion; destructive paths have protections (uninstall --keep-data, transcripts preserved on session remove), .worktreeinclude secret copying has guardrails (gitignored-only, no overwrite), and SECURITY.md declares Dependabot/govulncheck/CodeQL/SHA-pinning/SLSA attestation. Deductions: the govulncheck and Dependabot configs themselves are not in the provided files (asserted only); high-privilege surfaces exist — env_file sourced into shells, curl|bash install, SSH/Telegram remote control — without independent user-confirmation or least-privilege documentation; the conductor pushes session state to external Telegram/Slack/Discord channels with a thin description of sensitive-data boundaries.
README and workflow docs are internally consistent (the v1.7.42→v1.7.70 removal/reinstatement narrative; the v1.10.9-11 unattested-release gap corroborated across SECURITY.md and workflows/README.md); go.mod pins dependencies; conductor tests cover stderr classification and failure paths. Deductions: the supplied test fragment covers only a small part of the conductor bridge; availability of external CLIs (claude/codex/tmux/git versions) is confirmable only at documentation level; actual runtime failure-message quality of the TUI is not directly shown.
Audience and scenarios are exceptionally clear (multi-project multi-agent terminal session management), with explicit platform (macOS/Linux/WSL), git 2.32+, and tmux requirements, and precisely defined keybindings/CLI triggers. Deductions: native Windows and non-tmux environments are not addressed; capability boundaries are mostly narrative (e.g., codex fork needs a specific CLI version) without a systematic boundary list.
Excellent information architecture (install → quick start → features → docs → FAQ), multiple install methods including uninstall notes, unusually candid known limitations (unsigned releases, removed workflow, no group-sprawl gate all documented), complete MIT license with copyright line. Deductions: no CHANGELOG file appears in the evidence (version notes are scattered through README); maintenance is primarily single-person with co-maintainers still being recruited, so long-term commitment is aspirational; naming stability is documented as convention, not enforcement.
Clear marginal value: one TUI for many AI agents with forking, worktrees, cost tracking, and phone-controlled conductor — feature-dense for its class. Deductions: output usability (actual TUI/web experience) cannot be verified statically; a large dependency tree (GCP pubsub, grpc, websocket) plus resident components (bridge daemon, heartbeat) raise the cost for users who only want simple session management, so cost-benefit depends on using the full feature set.
Key claims are traceable (issue links #602, #1760, #1759, #682; human-runnable scripts like scripts/verify-per-group-claude-config.sh; directly executable gh attestation verify command), and phrases like 'verified with codex-cli 0.137.0' and 'hand check is not a signature' separate fact from inference. Deductions: many performance claims (85-90% memory savings, ~3s auto-recovery, PRs validated within a day) carry no supporting data; cross-source corroboration covers only a few points (the release gap); everything else rests on the single README source; this was a static review with no execution.
- The conductor/watcher pushes session state and content to external Telegram/Slack/Discord channels; verify bot-token storage and message-content sensitivity boundaries before deploying.
- install.sh uses curl | bash, and v1.10.9–v1.10.11 shipped without SLSA attestation (self-disclosed); prefer a checksum-verifiable install and run gh attestation verify.
- .worktreeinclude can copy .env, secrets/, and other gitignored files into new worktrees, multiplying secret copies across worktrees — clean up accordingly.
- per-group/per-conductor env_file is sourced into tmux panes, and the precedence chain (env > conductor > group > profile > global) is complex; misconfiguration can attach sessions to the wrong account.
- The tool depends on external CLIs (claude, codex, tmux, git ≥2.32 for sparse features); missing prerequisites may silently degrade or disable features.
- Publisher is unverified (identity unknown) and maintenance is primarily single-person with co-maintainers being recruited — long-term maintenance intensity is uncertain.
What does this agent do, and when should you use it?
Agent Deck is a terminal session manager for AI coding agents, written in Go on top of tmux and a Bubble Tea TUI. It gives you a single view of every agent session — running, waiting, idle, or error — with groups, fuzzy search, session forking, git worktree isolation, and a cost dashboard. Beyond the TUI it ships a web UI (default 127.0.0.1:8420), CLI subcommands, and optional Telegram/Slack remote channels. Its 'Conductor' mechanism lets one persistent agent session supervise all others, auto-responding when confident and escalating to your phone when not. The project is MIT-licensed and runs on macOS, Linux, and Windows via WSL.
Agent Deck spawns each AI agent (Claude Code, Codex, Gemini CLI, OpenCode, Copilot, Crush, Cursor, and custom tools) in a tmux pane and uses smart polling to detect status, shown as ● running, ◐ waiting, ○ idle, ✕ error. Core operations: agent-deck add . -c claude registers a directory as a session; f/F forks Claude/OpenCode/Pi/Codex sessions via each tool's native fork, inheriting worktree, uncommitted state, and Docker isolation; session send delivers multiline prompts; session switch-account migrates a conversation file into another Claude account's config dir and resumes; the MCP Manager (m) toggles MCP servers per project or globally without editing config files; the Skills Manager (s) attaches Claude skills from a managed pool, writing .agent-deck/skills.toml; the git worktree subsystem creates isolated working directories with .worktreeinclude copying and .agent-deck/worktree-setup.sh/worktree-destruction.sh hooks; conductor setup creates a supervising agent session with optional Telegram/Slack bridges; watcher create provides webhook, GitHub (HMAC-SHA256 verified), ntfy, and Slack event adapters with SQLite deduplication; the cost dashboard ($) reads Claude transcripts via hooks, prices 15 models with daily refresh, and enforces budget limits; a Docker sandbox runs sessions in containers with host tool auth shared in.
- A developer running Claude Code across many projects who needs one terminal view of all running/waiting sessions and one-keystroke switching
- A team running multiple agents on the same repo, using git worktrees so each agent works on its own branch without conflicts
- A cost-conscious individual tracking API spend via the cost dashboard with daily/weekly/monthly budget limits (80% warning, 100% hard stop)
- A remote worker who wants phone-based fleet control through the Conductor's Telegram/Slack bridge and escalation alerts
- An engineer in a large monorepo using sparse checkout, letting new worktrees inherit the sparse configuration to avoid full checkouts
- A user who needs different Claude accounts per session group, via per-group
CLAUDE_CONFIG_DIRandenv_fileoverrides
What are this agent's strengths and limitations?
- Multi-tool unification: Claude Code, Gemini CLI, OpenCode, Codex, Copilot, Crush, Cursor, DeepSeek Harness, and custom tools are all managed in one TUI, with integration depth tiered per tool
- Conductor + Watcher orchestration: one persistent agent session supervises the fleet, with Telegram/Slack remote channels and four event adapters (webhook, GitHub with HMAC verification, ntfy, Slack) deduplicated in SQLite
- Context-preserving forking: quick fork creates a worktree, carries uncommitted state, and matches Docker isolation by default, using each tool's native fork
- Thorough cost visibility: 15 priced models with daily price refresh, multi-scope budget limits, and historical transcript backfill via
costs sync - Actively maintained: the README states PRs are validated within about a day and community fixes ship regularly, with co-maintainers being recruited
- Hard runtime dependency on tmux; environments without tmux (native non-WSL Windows) are not supported
- Integration depth skews toward Claude Code: automatic cost collection works fully only via Claude hooks; Gemini/Codex/MiniMax rely on output parsing explicitly marked untested
- Several features are documented as untested (Gemini/Codex cost parsing, budget hard stops), so production reliability needs your own validation
- Full Codex status detection requires manually installing a notify hook (
agent-deck codex-hooks install), and Codex forking requires a codex CLI supportingcodex fork(verified with codex-cli 0.137.0) - Large configuration surface: config.toml spans groups, profiles, conductors, worktree, fork, docker, and costs sections, which raises the learning curve
How do you install or deploy this agent?
Works on macOS, Linux, and Windows (WSL). Simplest: curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash, then run agent-deck. Alternatives: Homebrew brew install asheshgoplani/tap/agent-deck; Go go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest; from source git clone https://github.com/asheshgoplani/agent-deck.git && cd agent-deck && make install. Uninstall with agent-deck uninstall (--keep-data preserves sessions).
How do you use this agent?
Launch the TUI with agent-deck. Key entry points: agent-deck add . -c claude adds the current directory as a Claude session; n opens the new-session dialog (Ctrl+S creates, Enter advances fields); Enter attaches, Ctrl+Q detaches; f/F fork; A/Shift+U archive/unarchive; m opens the MCP Manager, s the Skills Manager, $ the Cost Dashboard, / fuzzy search, ? full help. Fleet orchestration: create a Telegram bot via @BotFather, run agent-deck conductor setup work --description "Work fleet", then agent-deck session start conductor-work, then message the bot /status. Web UI: agent-deck web (default http://127.0.0.1:8420; --read-only for browsers; --token to protect the API). Remote management: agent-deck remote add dev user@dev-box, then remote sessions, remote attach, remote drain. Configuration lives in $XDG_CONFIG_HOME/agent-deck/config.toml (default ~/.config/agent-deck/config.toml). For Codex status detection, run agent-deck codex-hooks install first.
How does this agent compare with similar options?
The README positions Agent Deck as an agent-session layer over tmux and explicitly aligns .worktreeinclude semantics with Claude Code Desktop's worktree gitignored-file copying; it also supports Codex-compatible custom-tool forking. No direct competitor is named, but compared with raw tmux it adds status detection, cost tracking, and Conductor orchestration that tmux alone does not provide.
FAQ
Does it cost money, and does it collect telemetry?
agent-deck telemetry enable); AGENTDECK_TELEMETRY=0 or DO_NOT_TRACK=1 hard-disable it. Your agents' API costs are billed by their respective tools, and Agent Deck's dashboard helps you track them.Do I have to use Claude Code?
[tools.*] in config.toml — but Claude Code has the deepest integration (status, MCP, fork, resume, cost hooks).What happens when a session errors or gets stuck?
R restarts a session; the Conductor notifies you when children move to waiting/error/idle, and an optional Watchdog daemon auto-restarts critical sessions.Is the web UI safe to expose on the network?
--token or --token-file, otherwise it is refused, since it would expose an unauthenticated remote-code-execution surface; MCP admin API routes are only available with a token.Will multiple agents editing the same repo conflict?
.worktreeinclude for gitignored files and setup/destruction scripts; worktree finish merges the branch and cleans up in one step.