Run Dot Agent Deck

Run dot-agent-deck

dot-agent-deck is a Rust TUI/CLI that orchestrates terminal agent sessions: a ratatui dashboard talking over Unix-socket protocols to a portable-pty-spawned daemon. Day-to-day driving lives in .claude/skills/run-dot-agent-deck/driver.sh — it shells out the binary against a fresh tempdir sandbox (so it does NOT attach to the developer's real daemon and render their actual workflow), captures the dashboard with tmux, and verifies clean shutdown.

All paths are relative to the repo root.

Why a sandbox

dot-agent-deck binds Unix sockets and flocks lock files at user-global paths ($XDG_RUNTIME_DIR/dot-agent-deck/*, fallback $HOME/.cache/dot-agent-deck/). If you launch the TUI without redirecting these:

• It attaches to your already-running daemon and shows your real Claude sessions in the dashboard (verified — it picked mine up).
• Or it contends on your daemon's lock files and fails to start.
• hooks install rewrites your shell rc files.

The driver redirects every relevant env var (DOT_AGENT_DECK_SOCKET, DOT_AGENT_DECK_ATTACH_SOCKET, DOT_AGENT_DECK_LOCK_DIR, DOT_AGENT_DECK_STATE_DIR, DOT_AGENT_DECK_CONFIG, DOT_AGENT_DECK_SESSION, plus HOME, XDG_RUNTIME_DIR, XDG_STATE_HOME) into a fresh tempdir per run, so the smoke is hermetic.

Prerequisites

apt-get install -y tmux              # already present on this container

Rust toolchain via rustup (cargo 1.95+ / rustc 1.95+ verified). No other system libraries needed — the binary statically links vt100, portable-pty, crossterm, etc.

Build

cargo build --release

Release build because the TUI's render path benefits — debug builds visibly stutter. Optimized build takes ~25 s clean, ~1 s incremental.

Run (agent path) — driver.sh

./.claude/skills/run-dot-agent-deck/driver.sh all

Subcommands:

• cli — non-interactive surface only: --version, --help, init, validate. ~0.1 s. Right for PRs that touch the CLI or config-loading code paths.
• tui — launches the dashboard under tmux, waits for first paint, saves a capture-pane screenshot, drives the Ctrl+C → Enter quit dialog, verifies the tmux session ends cleanly. ~1.5 s.
• all — both, in order. Default.

Output of a clean run:

== CLI smoke ==
dot-agent-deck 0.25.0
Created ./.dot-agent-deck.toml
Config is valid.
   init + validate OK in sandbox project
== TUI smoke ==
   screenshot saved to /tmp/dad-screenshot.txt (40 lines)
   TUI exited cleanly
OK

The screenshot lands at /tmp/dad-screenshot.txt (override with DAD_SCREENSHOT=...). A clean sandbox shows:

                                   No active sessions. Press Ctrl+n to create a pane.

...

[Back to Pane Ctrl+D] [New Pane Ctrl+N] [Close Ctrl+W] [Toggle Layout Ctrl+T] [Help ?] [Quit Ctrl+C] [Filter /]
[Rename r] [Generate g] [Scheduled Tasks s]

The bottom rows are the persistent button bar (it replaced the old Ctrl+n: new Ctrl+w: close … status-bar legend), and it is mode-aware: the capture above is command mode, so the first button reads [Back to Pane Ctrl+D] and [Close Ctrl+W] is live. Inside a pane the first reads [Command Mode Ctrl+D] and [Close Ctrl+W] is dimmed, because Ctrl+W closes only from command mode. On a narrow terminal the bar wraps to more rows rather than dropping buttons.

No active sessions is the signal that the sandbox is isolated — a non-isolated run would render whatever sessions your real daemon knows about.

Override the binary path with DAD_BIN=... to smoke an alternate build (e.g. target/debug/dot-agent-deck for faster iteration).

Run (human path)

./target/release/dot-agent-deck

Opens the dashboard against the user's REAL state — useful only as the developer running on a workstation with hooks install'd agent hooks. Useless headless. The driver above is the agent path.

Test

cargo test

~1.5 minutes on this container; 800+ tests. Covers the daemon protocol, PTY orchestration, delegate dispatch, and F12 reattach paths — most PRs that touch internals are verified by cargo test alone, not by the driver. The driver is for the TUI/CLI surface and the screenshot artifact.

Also gate before commit (per CLAUDE.md rules 2 and 5):

cargo xtask affected-checks --run

It prints and runs what the change needs, stopping at the first failure. For a change with any Rust, build input or unmapped path in it, that is:

cargo fmt --check
cargo clippy --workspace --all-targets --features e2e,e2e-live -- -D warnings
cargo test-fast

and for a change that is only mapped text (docs, skills, changelog.d/, .github/, PRDs, CLAUDE.md and the like), it is the xtask tests plus the root-package tests that read those files. Every clippy flag is load-bearing and CLAUDE.md rule 2 is the authority. --all-targets --features e2e per issue #407 and e2e-live per issue #502: without them the tests/e2e_*.rs files compile to empty crates (all of them without e2e, the real-agent ones without e2e-live), so clippy reports clean over code it never saw. e2e-live matters most of the four — it is the only thing in CI that type-checks the real-agent ones, because no test that reaches a real agent runs on a runner. --workspace per issue #436, or the xtask/* members are linted by no gate.