{"id":49488339,"url":"https://github.com/takezoh/agent-roost","last_synced_at":"2026-05-01T03:03:15.147Z","repository":{"id":350715290,"uuid":"1202215044","full_name":"takezoh/agent-roost","owner":"takezoh","description":"Command your AI agent fleet with zero friction. A tmux-native mission control for overseeing multiple agent sessions across all your projects.","archived":false,"fork":false,"pushed_at":"2026-04-28T16:10:33.000Z","size":3091,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T18:13:59.792Z","etag":null,"topics":["agent-dashboard","agent-session-manager","tmux"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/takezoh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-05T18:46:44.000Z","updated_at":"2026-04-22T15:24:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/takezoh/agent-roost","commit_stats":null,"previous_names":["takezoh/agent-roost"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/takezoh/agent-roost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takezoh%2Fagent-roost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takezoh%2Fagent-roost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takezoh%2Fagent-roost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takezoh%2Fagent-roost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/takezoh","download_url":"https://codeload.github.com/takezoh/agent-roost/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takezoh%2Fagent-roost/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32483406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-dashboard","agent-session-manager","tmux"],"created_at":"2026-05-01T03:03:14.298Z","updated_at":"2026-05-01T03:03:15.129Z","avatar_url":"https://github.com/takezoh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Roost\n\n**Run many AI agents in parallel without losing track of any of them.**\n\nAgent Roost is a tmux-based control surface for running Claude, Codex, Gemini, and other CLI agents across all your projects at once. It replaces the manual work of opening tabs, remembering which agent is doing what, and checking back for completion.\n\n### What it does\n\n- **Launch an agent without typing commands.** Select a project from the list and Roost handles the directory, environment, and command for you.\n- **See every agent's status at a glance.** Each session shows whether the agent is running, waiting for your input, awaiting tool approval, or idle. No tab-switching to find out who needs you.\n- **Jump into any session instantly.** Move the cursor over a session for a live preview; press Enter to take over. Supervise dozens of concurrent tasks without losing focus.\n- **Keep agents running after you disconnect.** Built on tmux, so closing the UI or dropping the connection doesn't stop the work.\n- **Run each agent in its own sandbox.** Optional per-project devcontainer with brokered AWS / gcloud / SSH credentials and a policy-gated host-exec channel. Long-lived secrets stay on the host; the container only sees short-lived tokens or stdio.\n\n## Requirements\n\n- Go 1.26+\n- tmux 3.2+\n\n## Installation\n\n```bash\nmake install\n```\n\nInstalls to `~/.local/bin/roost`.\n\n## Usage\n\n```bash\nroost\n```\n\nCreates a tmux session (or attaches to an existing one) and launches with a 3-pane layout.\n\n### Hook Setup\n\nRegister roost hooks so agent status (● ◆ ◇ ○ ■) updates in real time. Run once per agent type:\n\n```bash\nroost claude setup    # registers hooks in ~/.claude/settings.json\nroost codex setup     # registers hooks in ~/.codex/\nroost gemini setup    # registers hooks in ~/.gemini/settings.json\n```\n\nHooks are idempotent — re-running adds only missing entries and never overwrites existing config.\n\nWithout hooks, roost still launches sessions but status detection degrades to polling (idle detection only).\n\n### Key Bindings\n\n**Prefix bindings** work regardless of which pane is focused (pane navigation, detach, palette open).\n**SESSIONS pane bindings** are active only when the SESSIONS pane is focused (session operations).\n\n#### Prefix Keys\n\nDefault prefix: `Ctrl+b` (same as tmux default). Configurable via `[tmux] prefix`.\n\n| Key | Action |\n|------|-----------|\n| `prefix Space` | Toggle MAIN ↔ SESSIONS pane |\n| `prefix Escape` | Preview project |\n| `prefix z` | Zoom MAIN pane |\n| `prefix d` | Detach (tmux stays alive; re-run `roost` to resume) |\n| `prefix q` | Quit all (tmux session is destroyed) |\n| `prefix p` | Command palette |\n| `prefix C-p` | Push driver palette (overlay a new agent onto the current session) |\n\n#### Command Palette (`prefix p`)\n\nDisplayed as a popup. Filter tools by typing, press Enter to execute.\n\n```text\n\u003e new█\n▸ new-session       Create session\n  create-project    Create new project dir and start session\n```\n\n| Tool | Description |\n|--------|------|\n| `new-session` | Create session |\n| `create-project` | Create new project dir and start session |\n| `stop-session` | Stop session |\n| `detach` | Detach (keep session) |\n| `shutdown` | Shutdown (discard sessions) |\n\n#### SESSIONS Pane Bindings\n\n| Key | Action |\n|------|-----------|\n| `j`/`k` or `↑`/`↓` | Select session (previews in MAIN pane) |\n| `Enter` | Switch to selected session → return to MAIN |\n| `n` | Quick launch (default command) |\n| `N` | Launch with command selection |\n| `d` | Stop session |\n| `Tab` | Collapse/expand project |\n| `1`-`5` | Toggle status filter (Running / Waiting / Idle / Stopped / Pending) |\n| `0` | Reset filter |\n| `[` / `]` | Cycle workspace (shown only when 2+ workspaces exist) |\n| `` ` `` | Reset workspace filter to All |\n\n### Session States\n\n| Display | State |\n|------|------|\n| `●` green | Running (producing output) |\n| `◆` yellow | Waiting (awaiting input) |\n| `◇` yellow | Pending approval (awaiting tool execution permission) |\n| `○` gray | Idle (no output for 30+ seconds) |\n| `■` red | Stopped |\n\n## Configuration\n\n```toml\n# ~/.roost/settings.toml\n\n# data_dir = \"\"                 # Override config/data directory (default: ~/.roost)\n\n[log]\nlevel = \"info\"                  # \"debug\" | \"info\" | \"warn\" | \"error\"\n\n[tmux]\nsession_name = \"roost\"\nprefix = \"C-b\"                  # Prefix key\npane_ratio_horizontal = 75      # Main pane width % (1-99)\npane_ratio_vertical = 75        # Main pane height % (1-99)\n\n[monitor]\npoll_interval_ms = 1000         # Background polling interval\nfast_poll_interval_ms = 100     # Polling interval while TUI is active\nidle_threshold_sec = 30         # Seconds of silence before \"Idle\" (○)\n\n[session]\nauto_name = true                # Auto-generate session names\ndefault_command = \"shell\"       # Command run by `n` (quick launch)\ncommands = [                    # Commands available via `N`\n  \"claude\",\n  \"codex\",\n  \"gemini\",\n  \"shell\",\n]\npush_commands = [               # Commands available via push-driver palette\n  \"shell\",\n  \"git diff\",\n  \"git diff --staged\",\n]\n\n[projects]\nproject_roots = [\"~/projects\"]       # Subdirs of each root become projects\nproject_paths = [\"~/myproject\"] # Explicit project paths\n\n[sandbox]\nmode = \"devcontainer\"               # \"direct\" (default) | \"devcontainer\"\n\n[sandbox.devcontainer]\n# extra_create_args = []            # appended to \"docker create\"\n# env_script = \"\"                   # script that prints KEY=VALUE lines for a project\n# host_path_mount_prefix = \"\"       # prefix for the auto-mounted workspace inside the container\n                                    # empty (default): mirror host path as-is (e.g. /home/u/proj → /home/u/proj)\n                                    # \"/mnt\": prepend prefix (e.g. /home/u/proj → /mnt/home/u/proj)\n                                    # ignored when devcontainer.json sets workspaceFolder or workspaceMount\n\n# [sandbox.proxy]                   # credential proxy — see docs/sandbox-setup.md\n# aws_profiles = [\"default\"]        # populate per-provider keys to activate\n\n[driver]\n# summarize_command = \"claude -p --model=haiku --no-session-persistence --setting-sources user\"\n# summarize_command = \"codex exec --ephemeral --model gpt-4o-mini -\"\n# summarize_command = \"gemini -p '' -m gemini-2.5-flash-lite\"\n\n[drivers.claude]\nshow_thinking = false           # Show extended thinking blocks in MAIN pane\n\n# Desktop notifications — empty rules = disabled.\n# Each rule AND-combines driver / command / project / kind.\n# Empty string or \"*\" on any axis means \"match any\".\n# Driver / command / project are glob patterns (path.Match);\n# project supports \"~\" expansion.\n\n[[notifications.rules]]\n# claude requests tool approval under ~/projects/prjA\ndriver  = \"claude\"\nproject = \"~/projects/prjA\"\nkind    = \"pending_approval\"\n\n[[notifications.rules]]\n# any agent finishes its turn\nkind = \"done\"\n```\n\nWorks with default values even without a config file.\n\n### Per-Project Configuration\n\nEach project directory can have its own `.roost/settings.toml`:\n\n```toml\n# \u003cproject-dir\u003e/.roost/settings.toml\n\n[workspace]\nname = \"work\"    # Group this project under a named workspace\n```\n\nThe workspace switcher chip bar appears in the SESSIONS pane automatically when\ntwo or more distinct workspaces exist, and is hidden for single-workspace setups.\nProjects without a settings file fall back to the `default` workspace.\n\n## Sandbox\n\nRun each agent inside a project-scoped devcontainer, isolating filesystem, network, and credentials per project.\n\n- Setup and config: [docs/sandbox-setup.md](docs/sandbox-setup.md)\n- Architecture and security model: [docs/sandbox.md](docs/sandbox.md)\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakezoh%2Fagent-roost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftakezoh%2Fagent-roost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakezoh%2Fagent-roost/lists"}