[繁體中文](README.zh-TW.md)
[](https://github.com/suzuke/agend-terminal/actions/workflows/ci.yml)
[](https://crates.io/crates/agend-terminal)
[](LICENSE)

# 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.

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).