[繁體中文](README.zh-TW.md) [![CI](https://github.com/suzuke/agend-terminal/actions/workflows/ci.yml/badge.svg)](https://github.com/suzuke/agend-terminal/actions/workflows/ci.yml) [![Crates.io](https://img.shields.io/crates/v/agend-terminal)](https://crates.io/crates/agend-terminal) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) ![Status: Pre-alpha](https://img.shields.io/badge/Status-Pre--alpha-orange) # AgEnD Terminal > **Status:** Current product overview > **Audience:** Operators and contributors > **Authority:** Protected-main source and linked current guides > **Last verified:** 2026-09-22 at `main@62b28f36` Orchestrate AI coding agents — not just run them. ![AgEnD Terminal — orchestrating a fleet of AI coding agents in a multi-pane TUI](docs/tui-screenshot.png) Declare your entire AI dev team in one `fleet.yaml`. AgEnD Terminal launches each agent as a long-lived PTY process, can isolate branch-bound work in daemon-managed git worktrees, wires up inter-agent communication via built-in MCP tools, and keeps everything running with auto-respawn and context handover. ## Features - **Fleet-as-code** — One YAML file declares every agent's backend, role, working directory, and team membership. `agend-terminal start` brings the whole fleet up. - **6 backends** — Claude Code, Codex, Kiro, OpenCode, Antigravity CLI, and Grok Build. Swap backends by changing one field. - **Built-in agent coordination** — Agents delegate tasks, query each other, and broadcast updates through 34 MCP tools. No glue code. - **Automatic git worktree isolation** — Branch-bound tasks and instances can use daemon-managed worktrees. Unbound instances use their configured workspace. - **Crash recovery with context handover** — Agents auto-respawn and resume their conversation. Exponential backoff, health monitoring, and hung detection built in. - **Remote control** — Drive the fleet through a multi-pane TUI, Telegram, or Discord. Get notifications when agents need attention. ## Quick Start ```bash cargo install agend-terminal agend-terminal quickstart # Interactive setup in 2 minutes agend-terminal app # Launch the TUI — every agent's pane in one screen ``` ### Unattended setup (CI / scripts) `quickstart --unattended` never reads stdin and never waits on the network — missing required input is a clear error and a non-zero exit, not a hang. The backend is the first one detected on `PATH` (errors out listing install commands if none); Telegram is optional and comes from the environment: ```bash # Minimal (no Telegram — channel block is generated commented-out): agend-terminal quickstart --unattended # With Telegram (token is stored unverified; the daemon validates at startup): AGEND_TELEGRAM_BOT_TOKEN=123:abc \ AGEND_TELEGRAM_GROUP_ID=-1001234567890 \ agend-terminal quickstart --unattended ``` Re-runs are idempotent: an existing `fleet.yaml` is never overwritten, and an existing `.env` token is only replaced when `AGEND_TELEGRAM_BOT_TOKEN` is explicitly set (e.g. a CI token rotation). Example GitHub Actions step: ```yaml - name: Bootstrap agend-terminal env: AGEND_TELEGRAM_BOT_TOKEN: ${{ secrets.AGEND_TELEGRAM_BOT_TOKEN }} run: | cargo install agend-terminal agend-terminal quickstart --unattended ``` ## Architecture ```mermaid graph LR Op[Operator] -->|TUI / Telegram / Discord| D[Daemon] F[fleet.yaml] --> D D --> A1[Agent PTY
Claude Code] D --> A2[Agent PTY
Codex] D --> A3[Agent PTY
Kiro] D --> AN[Agent PTY
...] A1 <-->|MCP bridge| A2 A2 <-->|MCP bridge| A3 A1 <-->|MCP bridge| A3 D ---|managed worktree for branch-bound work| G[(Git repo)] D ---|health monitor
auto-respawn| A1 ``` ## Why Not tmux? | | tmux + shell scripts | agend-terminal | |---|---|---| | Input injection | `send-keys` race conditions | Atomic PTY write | | Output capture | Screen scraping | VTerm state tracking | | Agent health | Manual monitoring | Auto-respawn + state detection | | Multi-agent comms | Custom IPC | Built-in MCP tools | | Git isolation | Manual worktrees | Managed worktrees for branch-bound work | ## Backends | Backend | Command | Status | |---------|---------|--------| | Claude Code | `claude` | Tested | | Kiro CLI | `kiro-cli` | Tested | | Codex | `codex` | Tested | | OpenCode | `opencode` | Tested | | Antigravity CLI | `agy` | Tested | | Grok Build | `grok` | Experimental | > Gemini CLI was retired in [#1580](https://github.com/suzuke/agend-terminal/issues/1580) (it sunsets 2026-06-18 for free/Pro/Ultra tiers). Antigravity CLI (`agy`) is its official successor and a **supported** Fleet MCP backend ([#1547](https://github.com/suzuke/agend-terminal/issues/1547)). A `gemini` backend in fleet.yaml now spawns as a generic `Raw` backend. > agy refuses any workspace whose path has a dot-prefixed (hidden) ancestor, so daemon agents stored under a hidden `$AGEND_HOME` were invisible to it. The daemon now creates a non-hidden link (`/` → the hidden real workspace) and spawns agy with `$PWD` pointed at that link, clearing agy's hidden-path guard while the real files stay under `$AGEND_HOME`. `configure_agy` writes the project-scoped `.agents/mcp_config.json` + `.agents/AGENTS.md` (agy's official Customization Roots), so `agy` loads the fleet `send`/`inbox`/`task` tools like every other backend. ## Feature stability Everything is **pre-alpha** (see the banner up top) — this table is *relative* maturity to set expectations, not a production-readiness guarantee. Tiers can change between minor versions. | Tier | Meaning | |---|---| | Beta | Heavily exercised, broad test coverage; behavior mostly settled | | Experimental | Works but young or narrowly exercised; expect rough edges + changes | | Opt-in | Off by default; enable via a Cargo feature or env flag | | Area | Tier | Notes | |---|---|---| | Fleet orchestration (`fleet.yaml`, PTY spawn, supervision, auto-respawn) | Beta | Core path; extensive tests | | Git worktree isolation | Beta | Branch-bound worktree lease / release / GC | | MCP coordination tools (34) | Beta | `send` / `inbox` / `task` / … | | Task board | Beta | Append-only event log (schema v2) | | Telegram channel | Beta | Primary channel; polling, bindings, and notifications | | Claude Code / Codex / Kiro / OpenCode backends | Beta | Tested | | Antigravity CLI (`agy`) backend | Experimental | Newer ([#1547](https://github.com/suzuke/agend-terminal/issues/1547)); workspace-link shim | | Grok Build backend | Experimental | Newer; generic state detection with project-scoped MCP and skills | | Shadow Observer state plane | Experimental | Default-on high-confidence Hook/Stream corrections ([#2413](https://github.com/suzuke/agend-terminal/issues/2413)); kill-switches `AGEND_SHADOW_OBSERVER=0` and `AGEND_OBSERVED_DISPATCH=0` | | CI watch + PR auto-close sweep | Experimental | GitHub / GitLab / Bitbucket pollers | | Ephemeral cross-backend workers | Experimental · opt-in, no MCP surface | #2547: `ephemeral` MCP tool retired (zero calls); tracking/reap infra retained pending #2548 P1. Real backend gated by `AGEND_EPHEMERAL_REAL_BACKEND` | | Discord channel | Experimental · opt-in | `--features discord` | | Menu-bar tray | Experimental · opt-in | `--features tray` | Kill-switches and feature flags are documented in [env vars](docs/env-vars.md) and [configuration](docs/FEATURE-configuration.md). ## Documentation **Start here:** - [Quick Start Guide](docs/FEATURE-quickstart.md) — First-run walkthrough - [Fleet Configuration](docs/FEATURE-fleet.md) — `fleet.yaml` reference - [CLI Reference](docs/CLI.md) — All subcommands - [MCP Tools](docs/MCP-TOOLS.md) — 34 agent coordination tools - [Known Issues](docs/KNOWN_ISSUES.md) — Intentionally-deferred items; check before filing an issue - [**Documentation Index**](docs/README.md) — Full bilingual map of every guide and reference
Feature guides **Core** - [Agent Interaction](docs/FEATURE-agent-interaction.md) - [TUI Interface](docs/FEATURE-tui.md) - [Skills System](docs/FEATURE-skills.md) - [Communication](docs/FEATURE-communication.md) - [Task Board](docs/FEATURE-task-board.md) - [Teams](docs/FEATURE-teams.md) - [Git Worktree Isolation](docs/FEATURE-worktree.md) **Advanced** - [CI Watch](docs/FEATURE-ci-watch.md) - [Health & Monitoring](docs/FEATURE-health.md) - [Dispatch Idle Tracking](docs/FEATURE-dispatch-idle.md) - [Channels (Telegram/Discord)](docs/FEATURE-channels.md) - [Decision Records](docs/FEATURE-decisions.md) - [Schedules & Deployments](docs/FEATURE-schedules.md) **Maintenance** - [Service Management](docs/FEATURE-service.md) - [Diagnostics](docs/FEATURE-diagnostics.md) - [Configuration](docs/FEATURE-configuration.md)
Reference - [Architecture](docs/architecture.md) — Worktree isolation, health monitoring, Telegram lifecycle, daemon design - [Git Behavior](docs/GIT-BEHAVIOR.md) — What the daemon modifies in spawned agents' git environment - [Incident Runbook](docs/RUNBOOK.md) — Recovery procedures, CI outages, and a context-isolated Claude recipe - [Contributing](CONTRIBUTING.md) - [Changelog](CHANGELOG.md)
## Git Behavior agend-terminal modifies git behavior for spawned agents (PATH shim, commit trailers, deny matrix, daemon-managed worktrees). Your own terminal is **not** affected. Read [`docs/GIT-BEHAVIOR.md`](docs/GIT-BEHAVIOR.md) before starting the daemon. ## Contributing Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). All commits must be signed off (`git commit -s`) to certify the [Developer Certificate of Origin](DCO); CI enforces this on every pull request. ## License Licensed under the [Apache License 2.0](LICENSE).