[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-73274":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":45,"readmeContent":46,"aiSummary":47,"trendingCount":16,"starSnapshotCount":16,"syncStatus":48,"lastSyncTime":49,"discoverSource":50},73274,"agent-deck","asheshgoplani\u002Fagent-deck","asheshgoplani","Terminal session manager for AI coding agents. One TUI for Claude, Gemini, OpenCode, Codex, and more.","https:\u002F\u002Fdiscord.gg\u002Fe4xSs6NBN8",null,"Go",2675,319,7,16,0,42,97,287,126,29.52,"MIT License",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"ai-agent","ai-agents","ai-coding-assistant","aider","bubble-tea","claude-code","cli","codex","developer-tools","discord","gemini-cli","golang","mcp","productivity","session-manager","terminal","tmux","tui","2026-06-12 02:03:11","\u003Cdiv align=\"center\">\n\n\u003C!-- Status Grid Logo -->\n\u003Cimg src=\"site\u002Flogo.svg\" alt=\"Agent Deck Logo\" width=\"120\">\n\n# Agent Deck\n\n**Your AI agent command center**\n\n[![GitHub Stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fasheshgoplani\u002Fagent-deck?style=for-the-badge&logo=github&color=yellow&labelColor=1a1b26)](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fstargazers)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fasheshgoplani\u002Fagent-deck\u002Ftotal?style=for-the-badge&logo=github&color=bb9af7&labelColor=1a1b26)](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Freleases)\n[![Go Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGo-1.24+-00ADD8?style=for-the-badge&logo=go&labelColor=1a1b26)](https:\u002F\u002Fgo.dev)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-9ece6a?style=for-the-badge&labelColor=1a1b26)](LICENSE)\n[![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPlatform-macOS%20%7C%20Linux%20%7C%20WSL-7aa2f7?style=for-the-badge&labelColor=1a1b26)](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck)\n[![Latest Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fasheshgoplani\u002Fagent-deck?style=for-the-badge&color=e0af68&labelColor=1a1b26)](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Freleases)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1469423271144587379?style=for-the-badge&logo=discord&logoColor=white&label=Discord&color=5865F2&labelColor=1a1b26)](https:\u002F\u002Fdiscord.gg\u002Fe4xSs6NBN8)\n\n[Features](#features) . [Conductor](#conductor) . [Install](#installation) . [Quick Start](#quick-start) . [Docs](#documentation) . [Discord](https:\u002F\u002Fdiscord.gg\u002Fe4xSs6NBN8) . [FAQ](#faq)\n\n\u003C\u002Fdiv>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Ask AI about Agent Deck\u003C\u002Fb>\u003C\u002Fsummary>\n\n**Option 1: Claude Code Skill** (recommended for Claude Code users)\n```bash\n\u002Fplugin marketplace add asheshgoplani\u002Fagent-deck\n\u002Fplugin install agent-deck@agent-deck-help\n```\nThen ask: *\"How do I set up MCP pooling?\"*\n\n**Option 2: OpenCode** (has built-in Claude skill compatibility)\n```bash\n# Create skill directory\nmkdir -p ~\u002F.claude\u002Fskills\u002Fagent-deck\u002Freferences\n\n# Download skill and references\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Fasheshgoplani\u002Fagent-deck\u002Fmain\u002Fskills\u002Fagent-deck\u002FSKILL.md \\\n  > ~\u002F.claude\u002Fskills\u002Fagent-deck\u002FSKILL.md\nfor f in cli-reference config-reference tui-reference troubleshooting; do\n  curl -sL \"https:\u002F\u002Fraw.githubusercontent.com\u002Fasheshgoplani\u002Fagent-deck\u002Fmain\u002Fskills\u002Fagent-deck\u002Freferences\u002F${f}.md\" \\\n    > ~\u002F.claude\u002Fskills\u002Fagent-deck\u002Freferences\u002F${f}.md\ndone\n```\nOpenCode will auto-discover the skill from `~\u002F.claude\u002Fskills\u002F`.\n\n**Option 3: Any LLM** (ChatGPT, Claude, Gemini, etc.)\n```\nRead https:\u002F\u002Fraw.githubusercontent.com\u002Fasheshgoplani\u002Fagent-deck\u002Fmain\u002Fllms-full.txt\nand answer: How do I fork a session?\n```\n\n\u003C\u002Fdetails>\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe4f55917-435c-45ba-92cc-89737d0d1401\n\n## The Problem\n\nRunning Claude Code on 10 projects? OpenCode on 5 more? Another agent somewhere in the background?\n\n**Managing multiple AI sessions gets messy fast.** Too many terminal tabs. Hard to track what's running, what's waiting, what's done. Switching between projects means hunting through windows.\n\n## The Solution\n\n**Agent Deck is mission control for your AI coding agents.**\n\nOne terminal. All your agents. Complete visibility.\n\n- **See everything at a glance** — running, waiting, or idle status for every agent instantly\n- **Switch in milliseconds** — jump between any session with a single keystroke\n- **Stay organized** — groups, search, notifications, and git worktrees keep everything manageable\n\n## Features\n\n### Fork Sessions\n\nTry different approaches without losing context. Fork any Claude conversation instantly. Each fork inherits the full conversation history.\n\n- Press `f` for quick fork, `F` to customize name\u002Fgroup\n- Fork your forks to explore as many branches as you need\n\n### MCP Manager\n\nAttach MCP servers without touching config files. Need web search? Browser automation? Toggle them on per project or globally. Agent Deck handles the restart automatically.\n\n- Press `m` to open, `Space` to toggle, `Tab` to cycle scope (LOCAL\u002FGLOBAL), type to jump\n- Define your MCPs once in `~\u002F.agent-deck\u002Fconfig.toml`, then toggle per session — see [Configuration Reference](skills\u002Fagent-deck\u002Freferences\u002Fconfig-reference.md)\n\n### Skills Manager\n\nAttach\u002Fdetach Claude skills per project with a managed pool workflow.\n\n- Press `s` to open Skills Manager for a Claude session\n- Available list is pool-only (`~\u002F.agent-deck\u002Fskills\u002Fpool`) to keep attach\u002Fdetach deterministic\n- Apply writes project state to `.agent-deck\u002Fskills.toml` and materializes into `.claude\u002Fskills`\n- Type-to-jump is supported in the dialog (same pattern as MCP Manager)\n\n### Per-group Claude config\n\nAgent Deck supports per-group `CLAUDE_CONFIG_DIR` and `env_file` overrides. Useful when a single profile hosts groups that should authenticate against different Claude accounts — for example, a personal profile hosting a `conductor` group pinned to `~\u002F.claude-work` while other groups stay on `~\u002F.claude`.\n\nOverride any group by adding a `[groups.\"\u003Cname>\".claude]` table to `~\u002F.agent-deck\u002Fconfig.toml`:\n\n```toml\n[groups.\"conductor\".claude]\nconfig_dir = \"~\u002F.claude-work\"\nenv_file = \"~\u002Fgit\u002Fwork\u002F.envrc\"\n```\n\nLookup priority: `env > group > profile > global > default`. The `env_file` is `source`d into the tmux pane before `claude` (or the custom command) execs, so any exports it contains become part of the session environment.\n\nHuman-watchable verification: `bash scripts\u002Fverify-per-group-claude-config.sh`. The harness creates two throwaway groups, launches one normal and one custom-command session, and prints a pass\u002Ffail table.\n\n#### Per-conductor Claude config (v1.5.4)\n\nConductors are first-class agent-deck entities (see `agent-deck conductor setup`). Each conductor can carry its own Claude `config_dir` and `env_file` via a top-level `[conductors.\u003Cname>.claude]` block:\n\n```toml\n[conductors.gsd-v154.claude]\nconfig_dir = \"~\u002F.claude-work\"\nenv_file = \"~\u002Fgit\u002Fwork\u002F.envrc\"\n```\n\nThe conductor name is the string you passed to `agent-deck conductor setup \u003Cname>` — it's the same name that appears in session titles (`conductor-\u003Cname>`).\n\n**Precedence chain** (most-specific → least-specific):\n\n1. `CLAUDE_CONFIG_DIR` env var\n2. `[conductors.\u003Cname>.claude]` (when the session is a conductor session, i.e. Title starts with `conductor-`)\n3. `[groups.\"\u003Cgroup>\".claude]` (PR #578)\n4. `[profiles.\u003Cprofile>.claude]`\n5. `[claude]` (global)\n6. `~\u002F.claude` (default)\n\nThis means a single `[conductors.gsd-v154.claude]` line replaces the need to duplicate the config into `[groups.\"conductor\".claude]` — the conductor block scopes to exactly that conductor, not to every conductor that shares the `conductor` group.\n\nBackward compat: sessions in the `conductor` group with NO matching `[conductors.\u003Cname>.claude]` block continue to resolve via `[groups.\"conductor\".claude]` as they did in v1.5.4 Phase 1–3.\n\nCloses [issue #602](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fissues\u002F602).\n\n### MCP Socket Pool\n\nRunning many sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, reducing MCP memory usage by 85-90%. Connections auto-recover from MCP crashes in ~3 seconds via a reconnecting proxy. Enable with `pool_all = true` in [config.toml](skills\u002Fagent-deck\u002Freferences\u002Fconfig-reference.md).\n\n### Search\n\nPress `\u002F` to fuzzy-search across all sessions. Filter by status with `!` (running), `@` (waiting), `#` (idle), `$` (error). Press `G` for global search across all Claude conversations.\n\n### Keyboard navigation (v1.7.60)\n\nTwo tiers of keybindings move the cursor around the session list. The global tier is unchanged from earlier versions; the `Alt+` tier (added in v1.7.60) restricts movement to the current group only. Press `?` in the TUI to see the full table in-app.\n\n| Scope | Keys | What it does |\n|---|---|---|\n| **Global (flat list)** | `j` \u002F `k` or `↓` \u002F `↑` | Move cursor down \u002F up through every item |\n| Global | `gg` | Jump to top of list |\n| Global | `G` | Open global search across all Claude conversations |\n| Global | `1`–`9` | Jump to Nth root group header |\n| Global | `\u002F` | Open fuzzy search across all sessions |\n| **Group (current group only)** | `Alt+j` \u002F `Alt+k` | Next \u002F previous session in current group (skips group boundaries) |\n| Group | `Alt+1`–`Alt+9` | Jump to Nth session within the current group |\n| Group | `Alt+g` \u002F `Alt+G` | First \u002F last session in current group |\n| Group | `Alt+\u002F` | Open fuzzy search filtered to the current group's sessions |\n\n\"Current group\" is derived from the cursor position: on a session it's that session's group; on a group header it's that group; on a window it's the parent session's group. On a group boundary `Alt+j` \u002F `Alt+k` no-op rather than spilling into the next group.\n\n### Status Detection\n\nSmart polling detects what every agent is doing right now:\n\n| Status | Symbol | What It Means |\n|--------|--------|---------------|\n| **Running** | `●` green | Agent is actively working |\n| **Waiting** | `◐` yellow | Needs your input |\n| **Idle** | `○` gray | Ready for commands |\n| **Error** | `✕` red | Something went wrong |\n\n### Notification Bar\n\nWaiting sessions appear right in your tmux status bar. Press `Ctrl+b`, release, then press `1`–`6` to jump directly to them.\n\n```\n⚡ [1] frontend [2] api [3] backend\n```\n\n### Git Worktrees\n\nMultiple agents can work on the same repo without conflicts. Each worktree is an isolated working directory with its own branch.\n\n- `agent-deck add . -c claude --worktree feature\u002Fa --new-branch` creates a session in a new worktree\n- `agent-deck add . --worktree feature\u002Fb -b --location subdirectory` places the worktree under `.worktrees\u002F` inside the repo\n- `agent-deck worktree finish \"My Session\"` merges the branch, removes the worktree, and deletes the session\n- `agent-deck worktree cleanup` finds and removes orphaned worktrees\n\nConfigure the default worktree location in `~\u002F.agent-deck\u002Fconfig.toml`:\n\n```toml\n[worktree]\ndefault_location = \"subdirectory\"  # \"sibling\" (default), \"subdirectory\", or a custom path\n```\n\n`sibling` creates worktrees next to the repo (`repo-branch`). `subdirectory` creates them inside it (`repo\u002F.worktrees\u002Fbranch`). A custom path like `~\u002Fworktrees` or `\u002Ftmp\u002Fworktrees` creates repo-namespaced worktrees at `\u003Cpath>\u002F\u003Crepo_name>\u002F\u003Cbranch>`. The `--location` flag overrides the config per session.\n\n#### Worktree Setup Script\n\nGitignored files (`.env`, `.mcp.json`, etc.) aren't copied into new worktrees. To automate this, create a setup script at `.agent-deck\u002Fworktree-setup.sh` in your repo. Agent-deck runs it automatically after creating a worktree.\n\n```sh\n#!\u002Fbin\u002Fsh\nfor f in .env .env.local .mcp.json; do\n    [ -f \"$AGENT_DECK_REPO_ROOT\u002F$f\" ] && cp \"$AGENT_DECK_REPO_ROOT\u002F$f\" \"$AGENT_DECK_WORKTREE_PATH\u002F$f\"\ndone\n```\n\nThe script receives two environment variables:\n- `AGENT_DECK_REPO_ROOT` — path to the main repository\n- `AGENT_DECK_WORKTREE_PATH` — path to the new worktree\n\nThe script runs via `sh -e` with a 60-second timeout. If it fails, the worktree is still created — you'll see a warning but the session proceeds normally.\n\n#### Bare repositories and worktrees\n\nAgent-deck supports two flavors of the [bare-repo layout](https:\u002F\u002Fgit-scm.com\u002Fdocs\u002Fgit-worktree) where every worktree is a peer (no \"main\" checkout). The two are distinguished by convention — the basename of the bare git dir.\n\n##### Nested `.bare\u002F` layout\n\nThe bare git metadata sits inside a normal-looking project dir at `.bare\u002F`:\n\n```\nproject\u002F\n├── .bare\u002F                         # bare git repo (holds refs, objects, HEAD)\n├── .agent-deck\u002F\n│   └── worktree-setup.sh          # shared setup script (optional)\n├── worktree-a\u002F                    # linked worktree on branch-a\n│   └── .git                       # file: gitdir: ..\u002F.bare\u002Fworktrees\u002Fworktree-a\n└── worktree-b\u002F                    # linked worktree on branch-b\n    └── .git\n```\n\n##### True-bare-at-root layout\n\nThe result of a plain `git clone --bare repo.git`: the directory itself *is* the bare repo and linked worktrees live as direct children alongside its internal files:\n\n```\nproject.git\u002F                       # this dir IS the bare repo\n├── HEAD, config, objects\u002F, refs\u002F, packed-refs, worktrees\u002F, ...\n├── .agent-deck\u002F\n│   └── worktree-setup.sh          # shared setup script (optional)\n├── main\u002F                          # linked worktree on main\n│   └── .git                       # file: gitdir: ..\u002Fworktrees\u002Fmain\n└── feature-x\u002F                     # linked worktree on feature-x\n    └── .git\n```\n\nHow agent-deck resolves these layouts (v1.7.58+ for nested, v1.9.10+ for at-root):\n\n- **All three handles work.** `agent-deck add \u003Cproject-root>`, `agent-deck add \u003Cbare-dir>`, and `agent-deck add \u003Clinked-worktree>` all resolve to the same project root. For the nested layout that's the dir holding `.bare\u002F`. For the at-root layout that's the bare dir itself (`project.git\u002F`). Every linked worktree is treated as equal.\n- **The project root is where shared config lives.** Place `.agent-deck\u002Fworktree-setup.sh` at `\u003CprojectRoot>\u002F.agent-deck\u002Fworktree-setup.sh`. Agent-deck looks for it at exactly that path — it does not search individual worktrees. In the at-root layout that means `.agent-deck\u002F` lives *inside* the bare dir alongside `HEAD` and `objects\u002F`.\n- **`AGENT_DECK_REPO_ROOT` inside the setup script points to the project root.** Same as above — for at-root that's the bare dir itself.\n- **New worktree location** depends on the layout:\n  - **Nested:** follows your `[worktree]` setting. `default_location = \"subdirectory\"` lands worktrees at `\u003CprojectRoot>\u002F.worktrees\u002F\u003Cbranch>`; `\"sibling\"` lands them next to the project dir.\n  - **At-root:** auto-overrides `sibling`\u002F`subdirectory` and lands new worktrees as direct children of the bare dir (`\u003CbareDir>\u002F\u003Cbranch>`) — neither default makes sense when the project root *is* the bare repo. The `path_template` config still wins if you want a fully custom path.\n\nExample — create a new worktree against a bare repo from anywhere:\n\n```sh\n# Nested .bare\u002F layout\nagent-deck add project\u002F -c claude --worktree feature\u002Fc --new-branch\nagent-deck add project\u002F.bare -c claude --worktree feature\u002Fc --new-branch\nagent-deck add project\u002Fworktree-a -c claude --worktree feature\u002Fc --new-branch\n# All three resolve to project\u002F, create project\u002F.worktrees\u002Ffeature-c\u002F, run project\u002F.agent-deck\u002Fworktree-setup.sh.\n\n# True-bare-at-root layout\nagent-deck add project.git\u002F -c claude --worktree feature\u002Fc --new-branch\nagent-deck add project.git\u002Fmain -c claude --worktree feature\u002Fc --new-branch\n# Both resolve to project.git\u002F, create project.git\u002Ffeature-c\u002F, run project.git\u002F.agent-deck\u002Fworktree-setup.sh.\n```\n\n`agent-deck worktree list` and `agent-deck worktree finish` work from any of those locations.\n\nCommon gotchas:\n\n- **`.agent-deck\u002F` must live at the project root.** For nested layouts that's next to `.bare\u002F`; for at-root layouts that's inside the bare dir. If you commit `.agent-deck\u002F` into a specific branch's worktree instead, agent-deck will not find it — the lookup resolves to the project root, not the current worktree.\n- **Detection is by convention: basename `.bare` ⇒ nested layout, anything else ⇒ at-root.** A bare repo named something other than `.bare` inside a project dir (e.g. `project\u002F.git-bare\u002F`) is treated as at-root if you point at it directly. For a fully nested layout, use the canonical name `.bare`.\n- **If you keep a `.git` file at the project root** pointing to `.bare\u002F` (a variant some tutorials recommend), point `agent-deck add` at `.bare\u002F` or at a linked worktree rather than at the project root — the `.git` file shadows the bare-repo detection path.\n\n### Docker Sandbox\n\nRun sessions inside isolated Docker containers. The project directory is bind-mounted read-write, so agents work on your code while the rest of the system stays protected.\n\n- Check \"Run in Docker sandbox\" when creating a session, or set `default_enabled = true` in config\n- Press `T` on a sandboxed session to open a container shell\n- `agent-deck try \"task description\"` runs a one-shot sandboxed session\n\nHost tool auth (Claude, Gemini, Codex, etc.) is automatically shared into containers via shared sandbox directories — no re-authentication needed. On macOS, Keychain credentials are extracted too.\n\n```toml\n[docker]\ndefault_enabled = true\nmount_ssh = true\nauto_cleanup = true    # Remove containers when sessions end (default: true)\n```\n\nSet `auto_cleanup = false` to keep containers alive after session termination, which is useful for debugging container state or inspecting logs.\n\nSee the [Docker Sandbox Guide](skills\u002Fagent-deck\u002Freferences\u002Fsandbox.md) for the full reference including overlay details, custom images, and troubleshooting.\n\n### Conductor\n\nConductors are persistent agent sessions that monitor and orchestrate all your other sessions. They watch for sessions that need help, auto-respond when confident, and escalate to you when they can't. Optionally connect **Telegram** and\u002For **Slack** for remote control.\n\nCreate as many conductors as you need per profile:\n\n```bash\n# First-time setup (asks about Telegram\u002FSlack, then creates the conductor)\nagent-deck -p work conductor setup ops --description \"Ops monitor\"\n\n# Add more conductors to the same profile (no prompts)\nagent-deck -p work conductor setup infra --description \"Infra watcher\"\nagent-deck conductor setup personal --description \"Personal project monitor\"\n\n# Run a conductor on Codex instead of Claude Code\nagent-deck -p work conductor setup review --agent codex --description \"Codex reviewer\"\n\n# Use a custom agent endpoint via environment variables\nagent-deck conductor setup glm-bot \\\n  -env ANTHROPIC_BASE_URL=https:\u002F\u002Fapi.z.ai\u002Fapi\u002Fanthropic \\\n  -env ANTHROPIC_AUTH_TOKEN=\u003Ctoken> \\\n  -env ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5\n\n# Or use an env file\nagent-deck conductor setup glm-bot -env-file ~\u002F.conductor.env\n```\n\nEach conductor gets its own directory, identity, and settings:\n\n```\n~\u002F.agent-deck\u002Fconductor\u002F\n├── CLAUDE.md           # Shared knowledge for Claude conductors\n├── AGENTS.md           # Shared knowledge for Codex conductors\n├── bridge.py           # Bridge daemon (Telegram\u002FSlack, if configured)\n├── ops\u002F\n│   ├── CLAUDE.md       # Identity: \"You are ops, a conductor for the work profile\"\n│   ├── meta.json       # Config: name, profile, description, env vars\n│   ├── state.json      # Runtime state\n│   └── task-log.md     # Action log\n└── review\u002F\n    ├── AGENTS.md\n    └── meta.json\n```\n\nClaude conductors use `CLAUDE.md`. Codex conductors use `AGENTS.md`. Shared `POLICY.md` and `LEARNINGS.md` remain agent-neutral.\n\n**CLI commands:**\n\n```bash\nagent-deck conductor list                    # List all conductors\nagent-deck conductor list --profile work     # Filter by profile\nagent-deck conductor status                  # Health check (all)\nagent-deck conductor status ops              # Health check (specific)\nagent-deck conductor teardown ops            # Stop a conductor\nagent-deck conductor teardown --all --remove # Remove everything\n```\n\n**Telegram bridge** (optional): Connect a Telegram bot for mobile monitoring. The bridge routes messages to specific conductors using a `name: message` prefix:\n\n```\nops: check the frontend session      → routes to conductor-ops\ninfra: restart all error sessions    → routes to conductor-infra\n\u002Fstatus                              → aggregated status across all profiles\n```\n\n**Slack bridge** (optional): Connect a Slack bot for channel-based monitoring via Socket Mode. The bot listens in a dedicated channel and replies in threads to keep the channel clean. Uses the same `name: message` routing, plus slash commands:\n\n```\nops: check the frontend session      → routes to conductor-ops (reply in thread)\n\u002Fad-status                           → aggregated status across all profiles\n\u002Fad-sessions                         → list all sessions\n\u002Fad-restart [name]                   → restart a conductor\n\u002Fad-help                             → list available commands\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Slack setup\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. Create a Slack app at [api.slack.com\u002Fapps](https:\u002F\u002Fapi.slack.com\u002Fapps)\n2. Enable **Socket Mode** → generate an app-level token (`xapp-...`)\n3. Under **OAuth & Permissions**, add bot scopes: `chat:write`, `channels:history`, `channels:read`, `app_mentions:read`\n4. Under **Event Subscriptions**, subscribe to bot events: `message.channels`, `app_mention`\n5. If using slash commands, create: `\u002Fad-status`, `\u002Fad-sessions`, `\u002Fad-restart`, `\u002Fad-help`\n6. Install the app to your workspace\n7. Invite the bot to your channel (`\u002Finvite @botname`)\n8. Run `agent-deck conductor setup \u003Cname>` and enter your bot token (`xoxb-...`), app token (`xapp-...`), and channel ID (`C01234...`)\n\n\u003C\u002Fdetails>\n\nBoth Telegram and Slack can run simultaneously — the bridge daemon handles both concurrently and relays responses on-demand, plus periodic heartbeat alerts to configured platforms.\n\n**Built-in status-driven notifications**: conductor setup also installs a transition notifier daemon (`agent-deck notify-daemon`) that watches status transitions and sends parent nudges when child sessions move `running -> waiting|error|idle`.\n\nDispatch can be suppressed at two scopes (PR #580, v1.7.34):\n\n```toml\n# Global kill switch in ~\u002F.agent-deck\u002Fconfig.toml (default: true)\n[notifications]\ntransition_events = false\n```\n\n```bash\n# Per-session at creation\nagent-deck add --no-transition-notify -c claude .\nagent-deck -p work launch . --no-transition-notify -c claude -m \"Do task\"\n\n# Per-session at runtime\nagent-deck session set-transition-notify worker off\nagent-deck session set-transition-notify worker on\n```\n\nSuppression only affects dispatch — the parent link itself is unchanged. Deferred\u002Fretried events also honour the flag (guard is in `transition_notifier.dispatch` as well as both daemon entry points).\n\n**Heartbeat-driven monitoring**: heartbeats still run on the configured interval (default 15 minutes) as a secondary safety net. If a conductor response includes `NEED:`, the bridge forwards that alert to Telegram and\u002For Slack.\n\n**Telegram conductor topology (v1.7.22+)**: each conductor bot must own exactly one channel-owning session. Activate telegram per-session via `--channels plugin:telegram@claude-plugins-official` and inject `TELEGRAM_STATE_DIR` via `[conductors.\u003Cname>.claude].env_file` in `~\u002F.agent-deck\u002Fconfig.toml`. Do NOT set `enabledPlugins.\"telegram@claude-plugins-official\"=true` in a profile's `settings.json` — that leaks a poller to every claude session under the profile. agent-deck emits warnings (`GLOBAL_ANTIPATTERN`, `DOUBLE_LOAD`, `WRAPPER_DEPRECATED`) when it detects these setups. Full guidance: [Telegram conductor topology](skills\u002Fagent-deck\u002FSKILL.md#telegram-conductor-topology-v1722).\n\n**Permission prompts during automation**: if a conductor keeps pausing on permission requests, set `[claude].allow_dangerous_mode = true` (or `dangerous_mode = true`) in `~\u002F.agent-deck\u002Fconfig.toml`, then run `agent-deck session restart conductor-\u003Cname>`. See [Troubleshooting](skills\u002Fagent-deck\u002Freferences\u002Ftroubleshooting.md#conductor-keeps-asking-for-permissions).\n\n**Legacy external watcher scripts**: optional only. `~\u002F.agent-deck\u002Fevents\u002F` is not required for notification routing.\n\n**Launching sessions from inside a conductor**:\n\n```bash\n# Inherit current conductor as parent (default when AGENT_DECK_SESSION_ID is set)\nagent-deck -p work launch . -t \"child-task\" -c claude -m \"Do task\"\n\n# Keep parent notifications and still force a custom group\nagent-deck -p work launch . -t \"review-phantom\" -g ard -c claude -m \"Review dataset\"\n\n# Tool command with extra args is supported directly\nagent-deck -p work launch . -c \"codex --dangerously-bypass-approvals-and-sandbox\"\n```\n\nWhen `--cmd` includes extra args, agent-deck auto-wraps the tool command so args are preserved reliably.\nUse `--no-parent` only when you explicitly want to disable parent routing\u002Fnotifications.\n\n#### Channels (Telegram \u002F Slack)\n\nChannels are how a conductor talks to you remotely. Each conductor pairs **one-to-one** with its own bot — bots are not shared between conductors. `agent-deck conductor setup` walks you through the pairing during creation.\n\nKey constraints:\n\n- **One bot per conductor.** The Telegram Bot API delivers updates via long-poll; a second consumer on the same token causes 409 conflicts and dropped messages.\n- **Plugin must be installed under the conductor's Claude profile but never globally enabled.** Per-session activation happens via the `channels = [\"plugin:telegram@claude-plugins-official\"]` field on the conductor's session record. A globally-enabled plugin leaks pollers into every Claude session under that profile.\n- **Bot tokens** live in the per-conductor channel state directory at `\u003Cstate-dir>\u002F.env` (chmod 600). Never committed to git.\n\nSlack pairing follows the same one-bot-per-conductor pattern. See [documentation\u002FCONDUCTOR.md](documentation\u002FCONDUCTOR.md) for the full ten-minute quickstart, including @BotFather steps, profile config, and verification commands.\n\n#### See also\n\n- [documentation\u002FCONDUCTOR.md](documentation\u002FCONDUCTOR.md) — full conductor guide with channel pairing walkthrough\n- [documentation\u002FWATCHDOG.md](documentation\u002FWATCHDOG.md) — optional auto-restart daemon that complements conductors\n\n### Watchers\n\nWatchers listen for inbound events (webhooks, push notifications, GitHub events, Slack messages) and route them to conductor sessions so running agents can act on them automatically. Four adapter types ship today:\n\n| Type | Use case | Required flags |\n|------|----------|----------------|\n| `webhook` | Generic HTTP POST listener for any service that can fire a webhook | `--port` |\n| `github` | GitHub repository webhooks (issues, PRs, pushes) with HMAC-SHA256 verification | `--secret` |\n| `ntfy` | [ntfy.sh](https:\u002F\u002Fntfy.sh) push-notification topics (phone \u002F browser → conductor) | `--topic` |\n| `slack` | Slack messages via a Cloudflare Worker bridge into an ntfy topic | `--topic` |\n\n```bash\n# Create, start, test — mirrors the four examples from `agent-deck watcher --help`\nagent-deck watcher create webhook  --name my-webhook  --port 9000\nagent-deck watcher create github   --name gh-alerts   --secret $GITHUB_WEBHOOK_SECRET\nagent-deck watcher create ntfy     --name phone       --topic my-private-topic\nagent-deck watcher create slack    --name team-slack  --topic my-slack-topic\n\nagent-deck watcher start  \u003Cname>\nagent-deck watcher list                # health + events\u002Fhour per watcher\nagent-deck watcher status \u003Cname>       # detail view including recent events\nagent-deck watcher test   \u003Cname>       # fire a synthetic event to verify routing\n```\n\nRouting rules live under `~\u002F.agent-deck\u002Fwatcher\u002F\u003Cname>\u002Fclients.json` — edit to pick which conductor\u002Fgroup receives which events. Use `agent-deck watcher routes` to see the currently-loaded rules across all watchers.\n\n**Conversational setup (recommended for first-time use):**\n\n```bash\nagent-deck watcher install-skill watcher-creator\n```\n\nThen, inside a Claude Code session started by agent-deck, ask: *\"Use the watcher-creator skill to set up a GitHub watcher\"*. The skill walks through adapter selection, required settings, and emits the exact `agent-deck watcher create` command to run.\n\nSafety notes:\n- The GitHub adapter enforces HMAC-SHA256 signature verification on every webhook — a missing\u002Finvalid signature drops the event.\n- Events are deduplicated in SQLite by `(watcher_name, event_id)`, so retries from the sender do not double-fire the conductor.\n- Watchers keep per-adapter health in `~\u002F.agent-deck\u002Fwatcher\u002F\u003Cname>\u002Fstate.json`; the TUI watcher panel (press `w`) surfaces this in real time.\n\n**Doorbell rule:** watchers are triggers, not launchers. They forward a short event string to the conductor and let the conductor decide what to do. A watcher should never call `agent-deck launch` or `agent-deck add` directly — those calls run outside any conductor's process and have no `$AGENTDECK_INSTANCE_ID`, so the spawned session becomes an orphan whose status events never route back. Use `agent-deck session send \u003Cconductor> \"[event] hint\"` from the watcher and let the conductor fan out from there.\n\n#### See also\n\n- [documentation\u002FWATCHERS.md](documentation\u002FWATCHERS.md) — full watcher guide with adapter recipes, custom external watchers, security guarantees, and gotchas\n\n### Multi-Tool Support\n\nAgent Deck works with any terminal-based AI tool:\n\n| Tool | Integration Level |\n|------|-------------------|\n| **Claude Code** | Full (status, MCP, fork, resume) |\n| **Gemini CLI** | Full (status, MCP, resume) |\n| **OpenCode** | Status detection, organization |\n| **Codex** | Status detection, organization, conductor |\n| **Crush** (charmbracelet\u002Fcrush) | Status detection, organization, launch |\n| **Cursor** (terminal) | Status detection, organization |\n| **Custom tools** | Configurable via `[tools.*]` in config.toml |\n\n### Cost Tracking Dashboard\n\nTrack token usage and costs across all your AI agent sessions in real-time.\n\n- **Automatic collection** — Claude Code hook integration reads transcript files on each turn. Gemini\u002FCodex\u002FMiniMax support via output parsing (untested)\n- **14 models priced** — Claude Opus 4.6\u002F4.7, Sonnet 4.6, Haiku 4.5, Gemini Pro\u002FFlash, GPT-4o\u002F4.1, o3, o4-mini, MiniMax M2.7\u002FM2.7-highspeed\u002FM2.5\u002FM2.5-highspeed with daily price refresh\n- **TUI dashboard** — press `$` to view today\u002Fweek\u002Fmonth costs, top sessions, model breakdown\n- **Web dashboard** — `\u002Fcosts` page with Chart.js charts, group drill-down, session detail views, SSE live updates\n- **Budget limits** — configurable daily\u002Fweekly\u002Fmonthly\u002Fper-group\u002Fper-session limits with 80% warning and 100% hard stop (untested)\n- **Historical sync** — `agent-deck costs sync` backfills cost data from existing Claude transcript files\n- **Recompute costs** — `agent-deck costs recompute` recalculates `cost_microdollars` for every cost event using current pricing data. Useful after a pricing-data update to retroactively price events that landed at $0 because the model was missing from the pricer. Pass `--dry-run` to preview.\n- **Export** — CSV\u002FJSON export from web dashboard\n\n```toml\n# Optional config (~\u002F.agent-deck\u002Fconfig.toml)\n[costs]\nretention_days = 90\n\n[costs.budgets]\ndaily_limit = 50.00\nweekly_limit = 200.00\n\n[costs.pricing.overrides]\n\"custom-model\" = { input_per_mtok = 1.0, output_per_mtok = 5.0 }\n```\n\n#### Customizing the status-line cost segment\n\nThe home status bar shows a brief cost line drawn from the seven windows below. The default renders `$X.XX today`; configure `cost_line_template` to surface different windows or a per-profile layout. Variables substitute as `$X.XX`; unknown placeholders pass through literally so typos surface in the output.\n\n| Variable | Window |\n|---|---|\n| `{cost_today}` | Today (00:00 local) |\n| `{cost_yesterday}` | Prior day |\n| `{cost_this_week}` | Monday-start of this week |\n| `{cost_last_week}` | Prior Monday to Sunday |\n| `{cost_this_month}` | First of this month |\n| `{cost_last_month}` | Prior calendar month |\n| `{cost_projected}` | Rolling 7-day average times 30 |\n\n```toml\n[costs]\ncost_line_template = \"{cost_today} today | {cost_this_week} wk\"\ncost_line_hide_when_zero = true   # default; hide when every recognized var is $0.00\n\n[profiles.work.costs]\ncost_line_template = \"{cost_yesterday} yda | {cost_today} today | {cost_projected}\u002Fmo\"\n```\n\nResolution chain: `profiles.\u003Cactive>.costs.cost_line_template > [costs].cost_line_template > hardcoded \"{cost_today} today\"`. Setting the template to an empty string explicitly disables the segment.\n\n### Socket Isolation (v1.7.50+)\n\nRun agent-deck on its own tmux server so it never touches your interactive tmux's config, bindings, or sessions. Opt-in via a single config line:\n\n```toml\n# ~\u002F.agent-deck\u002Fconfig.toml\n[tmux]\nsocket_name = \"agent-deck\"\n```\n\nWith this set, every agent-deck session is spawned as `tmux -L agent-deck …` — a fully isolated tmux server whose socket lives at `$TMUX_TMPDIR\u002Ftmux-\u003Cuid>\u002Fagent-deck` (or `\u002Ftmp\u002Ftmux-\u003Cuid>\u002Fagent-deck` when `TMUX_TMPDIR` is unset, the standard tmux fallback). Your regular tmux server at `default` is never touched.\n\n**What this buys you:**\n- `[tmux].inject_status_line`, bind-key, and global `set-option` mutations stay on the agent-deck server. Your personal status bar, plugins, and theme are untouched.\n- A stray `tmux kill-server` in your shell cannot take agent-deck's managed sessions down with it.\n- `tmux -L agent-deck ls` from the shell shows exactly agent-deck's sessions — no mixing with your own work sessions.\n- Fixes [#276](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fissues\u002F276) and [#687](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fissues\u002F687) at the root, not via per-option sentinels.\n\n**Default behavior unchanged.** Leave `socket_name` unset (the default) and agent-deck behaves exactly like v1.7.46: it uses your default tmux server. This is a pure opt-in.\n\n**What socket isolation does not cover.** `socket_name` isolates agent-deck from *other* tmux servers on the host — a `tmux kill-server` in your shell, a stray `set-option -g` from your personal config, or an interactive session competing for the same socket. It does **not** harden agent-deck's own tmux server against bugs inside tmux itself. If agent-deck's internal session churn trips a tmux bug (for example, a control-mode race in older tmux builds), that failure happens on the isolated socket just as it would on the default one. The isolation boundary is \"other tmux instances,\" not \"all possible tmux crashes.\" Keep your tmux up to date alongside agent-deck.\n\n**Per-session override.** The `agent-deck add` and `agent-deck launch` commands both accept `--tmux-socket \u003Cname>` to override the installation-wide default for one session:\n\n```bash\n# One-off isolated session even though config says otherwise\nagent-deck add --tmux-socket experiment -c claude .\nagent-deck launch --tmux-socket experiment -c claude -m \"Try the risky thing\"\n```\n\nPrecedence at session creation: `--tmux-socket` flag > `[tmux].socket_name` > empty.\n\n**Immutable after creation.** Each session captures its socket name in SQLite at creation time. Changing `socket_name` in config later does **not** migrate existing sessions — they stay on the socket they were created on, so restart\u002Frevive cycles keep reaching the right tmux server. This is deliberate: mixing sockets mid-life would strand sessions on an unreachable server.\n\n**Migrating existing sessions.** There's no `migrate-socket` subcommand in this release. To move an existing session onto an isolated socket:\n\n1. Set `[tmux].socket_name = \"agent-deck\"` in your config.\n2. Stop the session (`agent-deck session stop \u003Cname>`) — this kills the tmux pane on the old server.\n3. Restart it (`agent-deck session start \u003Cname>`) — agent-deck will see TmuxSocketName=`\"\"` on the stored Instance, spawn a fresh pane on the old server, and keep it there. To force it onto the new socket, edit `~\u002F.agent-deck\u002F\u003Cprofile>\u002Fstate.db`:\n   ```sql\n   UPDATE instances SET tmux_socket_name = 'agent-deck' WHERE id = '\u003Csession-id>';\n   ```\n   then restart agent-deck. Subsequent starts will spawn on `tmux -L agent-deck`.\n4. Easier: delete the old session with `agent-deck rm \u003Cname>` and re-create it with `agent-deck add` — the new row picks up the config-wide default.\n\nA proper `session migrate-socket` subcommand is tracked for phase 2.\n\n**`TMUX_TMPDIR` is honored.** Socket path resolution follows tmux's standard rules: if you set `TMUX_TMPDIR=\u002Fcustom\u002Fdir`, agent-deck's socket lives at `\u002Fcustom\u002Fdir\u002Ftmux-\u003Cuid>\u002Fagent-deck`. No extra config needed.\n\n### Feedback\n\nFound a bug or have an idea? Send feedback without leaving your terminal. Press `Ctrl+E` in the TUI to open the FeedbackDialog, or run `agent-deck feedback` from the shell to submit a rating and a short note.\n\nFeedback posts to a public GitHub Discussion at [Feedback Hub](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fdiscussions\u002F600) so other users can read along, comment, and upvote. The CLI submit path uses `gh api graphql` under your local GitHub authentication — no telemetry, no third-party services.\n\n- Press `Ctrl+E` from the main TUI to open the dialog\n- Or run `agent-deck feedback` from the CLI (rating 1-5)\n- **Nothing is sent until you explicitly type `y` at the confirmation prompt.** Before the prompt, the CLI shows (1) the public URL the comment will land on, (2) that it posts via the `gh` CLI using your account, (3) your GitHub username as it will appear, and (4) the exact body that will be posted. Default answer is **N** — pressing Enter declines.\n- If `gh` fails (auth required, not installed, network), the CLI prints an error and exits non-zero. No clipboard or browser fallback is triggered on the CLI path.\n- A private\u002Fanonymous feedback channel is being designed for a future release — track in [#679](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fissues\u002F679).\n\n**Feedback prompt frequency** (v1.7.41+): the TUI's auto-prompt is paced so brand-new users aren't asked on their first few launches. The first prompt appears only after **7 launches or 3 days** of use, whichever comes later. If you dismiss it, agent-deck waits **14 days** before asking again. You'll see at most **3 prompts per version**, and pressing `n` at any step opts you out permanently — use `agent-deck feedback` or `Ctrl+E` to re-enable on demand. Opt-out always wins over every pacing gate.\n\n### Remote Instances\n\nManage agent-deck instances running on remote SSH servers from your local terminal. Remote sessions appear alongside local sessions in the TUI and all CLI commands.\n\n```bash\n# Register a remote\nagent-deck remote add dev user@dev-box\n\n# agent-deck is installed automatically if missing on the remote\nagent-deck remote add prod user@prod-server --agent-deck-path \u002Fusr\u002Flocal\u002Fbin\u002Fagent-deck\n\n# List configured remotes\nagent-deck remote list\n\n# Browse sessions across all remotes (or one specific remote)\nagent-deck remote sessions\nagent-deck remote sessions dev\n\n# Attach to a remote session\nagent-deck remote attach dev my-session\n\n# Keep remote binaries up to date\nagent-deck remote update          # all remotes\nagent-deck remote update dev      # specific remote\n```\n\nRemote configuration is stored under `[remotes]` in `~\u002F.agent-deck\u002Fconfig.toml`. All `remote` subcommands support `--json` output for scripting. Run `agent-deck remote --help` for the full flag reference.\n\n### Reaching services running inside remote sessions\n\nIf you run a dev server, REPL, or web UI inside a remote session and want to reach it from your local browser, use **[Tailscale](https:\u002F\u002Ftailscale.com)** rather than ad-hoc SSH port forwarding. Tailscale gives every machine on your tailnet a direct IP, so a service on `localhost:3000` of your remote box is reachable at `http:\u002F\u002F\u003Cremote-tailnet-ip>:3000` from your laptop with no `-L`\u002F`-R` setup, no port collisions when multiple sessions share a remote, and no ControlMaster edge cases.\n\nSetup once:\n1. Install Tailscale on your local machine and on each remote: `curl -fsSL https:\u002F\u002Ftailscale.com\u002Finstall.sh | sh`\n2. `sudo tailscale up` on both ends, sign in with the same account\n3. Use the remote's tailnet IP (or MagicDNS name) in your browser\n\nThis is why agent-deck does not ship native SSH `-L`\u002F`-R` forwarding: Tailscale solves the same problem more robustly with no per-session configuration.\n\n## Installation\n\n**Works on:** macOS, Linux, Windows (WSL)\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fasheshgoplani\u002Fagent-deck\u002Fmain\u002Finstall.sh | bash\n```\n\nThen run: `agent-deck`\n\n\u003Cdetails>\n\u003Csummary>Other install methods\u003C\u002Fsummary>\n\n**Homebrew**\n```bash\nbrew install asheshgoplani\u002Ftap\u002Fagent-deck\n```\n\n**Go**\n```bash\ngo install github.com\u002Fasheshgoplani\u002Fagent-deck\u002Fcmd\u002Fagent-deck@latest\n```\n\n**From Source**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck.git && cd agent-deck && make install\n```\n\n\u003C\u002Fdetails>\n\n### Claude Code Skill\n\nInstall the agent-deck skill for AI-assisted session management:\n\n```bash\n\u002Fplugin marketplace add asheshgoplani\u002Fagent-deck\n\u002Fplugin install agent-deck@agent-deck\n```\n\n\u003Cdetails>\n\u003Csummary>Uninstalling\u003C\u002Fsummary>\n\n```bash\nagent-deck uninstall              # Interactive uninstall\nagent-deck uninstall --keep-data  # Remove binary only, keep sessions\n```\n\nSee [Troubleshooting](skills\u002Fagent-deck\u002Freferences\u002Ftroubleshooting.md#uninstalling) for full details.\n\n\u003C\u002Fdetails>\n\n## Quick Start\n\n```bash\nagent-deck                        # Launch TUI\nagent-deck add . -c claude        # Add current dir with Claude\nagent-deck session fork my-proj   # Fork a Claude session\nagent-deck session remove my-proj # Remove stopped\u002Ferrored session from registry (transcripts preserved)\nagent-deck mcp attach my-proj exa # Attach MCP to session\nagent-deck skill attach my-proj docs --source pool --restart # Attach skill + restart\nagent-deck web                    # Start web UI on http:\u002F\u002F127.0.0.1:8420\n```\n\n### Web Mode\n\nOpen the left menu + browser terminal UI:\n\n```bash\nagent-deck web\n```\n\nRead-only browser mode (output only):\n\n```bash\nagent-deck web --read-only\n```\n\nChange the listen address (default: `127.0.0.1:8420`):\n\n```bash\nagent-deck web --listen 127.0.0.1:9000\n```\n\nProtect API + WebSocket access with a bearer token:\n\n```bash\nagent-deck web --token my-secret\n# then open: http:\u002F\u002F127.0.0.1:8420\u002F?token=my-secret\n```\n\n### Key Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `Enter` | Attach to session |\n| `n` | New session |\n| `f` \u002F `F` | Fork (quick \u002F dialog) |\n| `m` | MCP Manager |\n| `s` | Skills Manager |\n| `$` | Cost Dashboard |\n| `M` | Move session to group |\n| `S` | Settings |\n| `\u002F` \u002F `G` | Search \u002F Global search |\n| `r` | Restart session |\n| `d` | Delete |\n| `S` | Settings |\n| `T` | Container shell (sandboxed sessions) |\n| `?` | Full help |\n\nSee [TUI Reference](skills\u002Fagent-deck\u002Freferences\u002Ftui-reference.md) for all shortcuts and [CLI Reference](skills\u002Fagent-deck\u002Freferences\u002Fcli-reference.md) for all commands.\n\n## Documentation\n\n**User guides** — start here if you are new:\n\n| Guide | What's Inside |\n|-------|---------------|\n| [Conductor](documentation\u002FCONDUCTOR.md) | What a conductor is, quickstart, channel pairing, state files, multi-conductor setups |\n| [Skills](documentation\u002FSKILLS.md) | User-level vs pool skills, authoring, attach\u002Fdetach, when to use which tier |\n| [Watchdog](documentation\u002FWATCHDOG.md) | Optional Python daemon that auto-restarts critical sessions and nudges stuck children |\n| [Watchers](documentation\u002FWATCHERS.md) | Event-forwarding framework: doorbell model, built-in adapters, custom watchers, gotchas |\n\n**References** — drill into specifics:\n\n| Guide | What's Inside |\n|-------|---------------|\n| [CLI Reference](skills\u002Fagent-deck\u002Freferences\u002Fcli-reference.md) | Commands, flags, scripting examples |\n| [Configuration](skills\u002Fagent-deck\u002Freferences\u002Fconfig-reference.md) | config.toml, MCP setup, custom tools, socket pool, skills registry paths, docker |\n| [Docker Sandbox](skills\u002Fagent-deck\u002Freferences\u002Fsandbox.md) | Containers, overlays, custom images, troubleshooting |\n| [TUI Reference](skills\u002Fagent-deck\u002Freferences\u002Ftui-reference.md) | Keyboard shortcuts, status indicators, navigation |\n| [Troubleshooting](skills\u002Fagent-deck\u002Freferences\u002Ftroubleshooting.md) | Common issues, debugging, recovery, uninstalling |\n\nAdditional resources:\n- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute\n- [CHANGELOG.md](CHANGELOG.md) — release history\n- [llms-full.txt](llms-full.txt) — full context for LLMs\n\n### Updates\n\nAgent Deck checks for updates automatically.\n- Standalone\u002Fmanual install: run `agent-deck update` to install.\n- Homebrew install: run `brew upgrade asheshgoplani\u002Ftap\u002Fagent-deck`.\n- Optional: set `auto_update = true` in [config.toml](skills\u002Fagent-deck\u002Freferences\u002Fconfig-reference.md) for automatic update prompts.\n\n## FAQ\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>How is this different from just using tmux?\u003C\u002Fb>\u003C\u002Fsummary>\n\nAgent Deck adds AI-specific intelligence on top of tmux: smart status detection (knows when Claude is thinking vs. waiting), session forking with context inheritance, MCP management, global search across conversations, and organized groups. Think of it as tmux plus AI awareness.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Can I use it on Windows?\u003C\u002Fb>\u003C\u002Fsummary>\n\nYes, via WSL (Windows Subsystem for Linux). [Install WSL](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall), then run the installer inside WSL. WSL2 is recommended for full feature support including MCP socket pooling.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Can I use different Claude accounts\u002Fconfigs per profile?\u003C\u002Fb>\u003C\u002Fsummary>\n\nYes. Set a global Claude config dir, then add optional per-profile overrides in `~\u002F.agent-deck\u002Fconfig.toml`:\n\n```toml\n[claude]\nconfig_dir = \"~\u002F.claude\"             # Global default\n\n[profiles.work.claude]\nconfig_dir = \"~\u002F.claude-work\"        # Work account\n```\n\nRun with the target profile:\n\n```bash\nagent-deck -p work\n```\n\nYou can verify which Claude config path is active with:\n\n```bash\nagent-deck hooks status\nagent-deck hooks status -p work\n```\n\nSee [Configuration Reference](skills\u002Fagent-deck\u002Freferences\u002Fconfig-reference.md#claude-section) for full details.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Will it interfere with my existing tmux setup?\u003C\u002Fb>\u003C\u002Fsummary>\n\nNo. Agent Deck creates its own tmux sessions with the prefix `agentdeck_*`. Your existing sessions are untouched. The installer backs up your `~\u002F.tmux.conf` before adding optional config, and you can skip it with `--skip-tmux-config`.\n\n\u003C\u002Fdetails>\n\n## Development\n\n```bash\nmake build    # Build\nmake test     # Test\nmake lint     # Lint\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## Star History\n\nIf Agent Deck saves you time, give us a star! It helps others discover the project.\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=asheshgoplani\u002Fagent-deck&type=Date)](https:\u002F\u002Fstar-history.com\u002F#asheshgoplani\u002Fagent-deck&Date)\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n\u003Cdiv align=\"center\">\n\nBuilt with [Bubble Tea](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) and [tmux](https:\u002F\u002Fgithub.com\u002Ftmux\u002Ftmux)\n\n**[Docs](skills\u002Fagent-deck\u002Freferences\u002F) . [Discord](https:\u002F\u002Fdiscord.gg\u002Fe4xSs6NBN8) . [Issues](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fissues) . [Discussions](https:\u002F\u002Fgithub.com\u002Fasheshgoplani\u002Fagent-deck\u002Fdiscussions)**\n\n\u003C\u002Fdiv>\n","Agent Deck 是一个终端会话管理器，专为AI编码助手设计。它提供了一个统一的文本用户界面（TUI），支持Claude、Gemini、OpenCode、Codex等多个AI代理。该项目采用Go语言开发，具有良好的跨平台兼容性，适用于macOS、Linux及WSL环境。其核心功能包括多会话管理和切换、会话状态跟踪以及通过CLI进行操作等。非常适合需要同时处理多个AI编码任务的开发者使用，能够显著提高工作效率和代码管理能力。",2,"2026-06-11 03:44:49","high_star"]