agtx

An AI agent that manages other coding agents in a terminal kanban board - Add tasks. Press one key. An orchestrator agent picks it up, plans, and delegates to multiple coding agents running in parallel. Come back to changes ready to merge.

Let different AI coding agents collaborate autonomously on the same task with automatic session switching and context awareness -
e.g. Gemini → research | Claude → implement | Codex → review

---

AI coding tools give you one agent, one task, one terminal. agtx gives you a kanban board where multiple coding agents work in parallel — each in its own git worktree, each in its own tmux window, running autonomously through a spec-driven workflow managed by an orchestrator agent.

With the orchestrator, you don't even manage the board yourself. An AI agent picks up tasks, delegates work, and ensures getting things done through planning, implementation, review and resolving conflicts — while you focus on what matters: research, defining tasks, and merging changes.

• Orchestrator agent: A dedicated AI agent that autonomously manages your kanban board via MCP — delegates to coding agents, advances phases, checks for merge conflicts (experimental)
• Multi-agent task lifecycle: Configure different agents per workflow phase — e.g. Gemini for research, Claude for implementation, Codex for review — with automatic agent switching
• Parallel execution: Every task gets its own git worktree and tmux window — run as many agents as needed, simultaneously
• Spec-driven plugins: Plug in GSD, Spec-kit, OpenSpec, BMAD, Superpowers — or define your own with a single TOML file
• Multi-project dashboard: Manage agent sessions across all projects via a single TUI
• Works with: Claude Code | Codex | Gemini CLI | OpenCode | Cursor Agent | Copilot

# Install
curl -fsSL https://raw.githubusercontent.com/fynnfluegge/agtx/main/install.sh | bash

# Run in any git repository
cd your-project && agtx

# Dashboard mode — manage all projects
agtx -g

# Orchestrator mode — let an AI manage the board for you
agtx --experimental

# Install from source
cargo build --release
cp target/release/agtx ~/.local/bin/

• tmux — agent sessions run in a dedicated tmux server
• gh (optional) — GitHub CLI for PR operations

Press o to create a new task. The wizard guides you through:

1. Title — enter a short task name
2. Plugin — select a workflow plugin (auto-skipped if only one option)
3. Prompt — write a detailed task description with inline references

The agent is configured at the project level via config.toml (not per-task).

When writing a task description, you can reference files, skills, and other tasks inline:

• Sessions automatically resume when moving Review → Running
• Full conversation context is preserved across the task lifecycle
• View live agent output in the task popup
• Auto merge-conflict resolution: When a Review task becomes idle, agtx checks for merge conflicts with the default branch. If conflicts are detected, the agent is automatically instructed to resolve them.

Config file location: ~/.config/agtx/config.toml

Per-project settings can be placed in .agtx/config.toml at the project root:

# Files to copy from project root into each new worktree (comma-separated)
# Paths are relative and preserve directory structure
copy_files = ".env, .env.local, web/.env.local"

# Shell command to run inside the worktree after creation and file copying
init_script = "scripts/init_worktree.sh"

Both options run during the Backlog → Research/Planning/Running transition, after worktree creation and before the agent session starts.

By default, all phases use default_agent. You can override the agent for specific phases globally or per project:

# ~/.config/agtx/config.toml
default_agent = "claude"

[agents]
research = "gemini"
planning = "claude"
running = "claude"
review = "codex"

# .agtx/config.toml (project override — takes precedence over global)
[agents]
running = "codex"

Plug any spec-driven framework into the task lifecycle. Define commands, prompts, and artifacts — agtx handles phase gating, artifact polling, worktree sync, agent switching, and autonomous execution.

Press P to switch plugins. Ships with 7 built-in:

Commands are written once in canonical format and automatically translated per agent:

✅ Skills, commands, and prompts fully supported · 🟡 Prompt only, no interactive skill support · ❌ Not supported

name = "my-plugin"
description = "My custom workflow"

[commands]
research = "/my-plugin:research {task}"
planning = "/my-plugin:plan"
running = "/my-plugin:execute"
review = "/my-plugin:review"

[prompts]
planning = "Task: {task}"

name = "my-plugin"
description = "My custom workflow"

# Shell command to run in the worktree after creation, before the agent starts.
# {agent} is replaced with the agent name (claude, codex, gemini, etc.)
init_script = "npm install --prefix .my-plugin --{agent}"

# Restrict to specific agents (empty or omitted = all agents supported)
supported_agents = ["claude", "codex", "gemini", "opencode"]

# Extra directories to copy from project root into each worktree.
# Agent config dirs (.claude, .gemini, .codex, .github/agents, .config/opencode)
# are always copied automatically.
copy_dirs = [".my-plugin"]

# Individual files to copy from project root into each worktree.
# Merged with project-level copy_files from .agtx/config.toml.
copy_files = ["PROJECT.md", "REQUIREMENTS.md"]

# When true, enables Review → Planning transition via the `p` key.
# Each cycle increments the phase counter ({phase} placeholder).
# Use this for multi-milestone workflows (e.g. plan → execute → review → next milestone).
cyclic = false

# Artifact files that signal phase completion.
# When detected, the task shows a checkmark instead of the spinner.
# Supports * wildcard for one directory level (e.g. "specs/*/plan.md").
# Use {phase} for cycle-aware paths (replaced with the current cycle number).
# Omitted phases show no completion indicator.
[artifacts]
research = ".my-plugin/research.md"
planning = ".my-plugin/{phase}/plan.md"
running = ".my-plugin/{phase}/summary.md"
review = ".my-plugin/{phase}/review.md"

# Slash commands sent to the agent via tmux for each phase.
# Written in canonical format (Claude/Gemini style): /namespace:command
# Automatically transformed per agent:
#   Claude/Gemini: /my-plugin:plan (unchanged)
#   OpenCode:      /my-plugin-plan (colon -> hyphen)
#   Codex:         $my-plugin-plan (slash -> dollar, colon -> hyphen)
# Omitted phases fall back to agent-native agtx skill invocation
# (e.g. /agtx:plan for Claude, $agtx-plan for Codex).
# Set to "" to skip sending a command for that phase.
# Use {phase} for cycle-aware commands (replaced with the current cycle number).
# Use {task} to inline the task description.
[commands]
preresearch = "/my-plugin:research {task}"  # Used only when no research artifacts exist yet
research = "/my-plugin:discuss {phase}"
planning = "/my-plugin:plan {phase}"
running = "/my-plugin:execute {phase}"
review = "/my-plugin:review {phase}"

# Prompt templates sent as task content after the command.
# {task} = task title + description, {task_id} = unique task ID, {phase} = cycle number.
# Omitted phases send no prompt (the skill/command handles instructions).
[prompts]
research = "Task: {task}"

# Text patterns to wait for in the tmux pane before sending the prompt.
# Useful when a command triggers an interactive prompt that must appear first.
# Polls every 500ms, times out after 5 minutes.
[prompt_triggers]
research = "What do you want to build?"

# Files/dirs to copy from worktree back to project root after a phase completes.
# Triggered automatically when the phase artifact is detected (spinner → checkmark).
# Useful for sharing research artifacts (specs, plans) across worktrees.
[copy_back]
research = ["PROJECT.md", "REQUIREMENTS.md", ".my-plugin"]

# Auto-dismiss interactive prompts that appear before the prompt trigger.
# Each rule fires when ALL detect patterns are present and the pane is stable.
# Response is newline-separated keystrokes (e.g. "2\nEnter" sends "2" then Enter).
[[auto_dismiss]]
detect = ["Map codebase", "Skip mapping", "Enter to select"]
response = "2\nEnter"

.agtx/plugins/my-plugin/
├── plugin.toml
└── skills/
    ├── agtx-plan/SKILL.md
    ├── agtx-execute/SKILL.md
    └── agtx-review/SKILL.md

┌─────────────────────────────────────────────────────────┐
│                      agtx TUI                           │
├─────────────────────────────────────────────────────────┤
│  Backlog  │  Planning  │  Running  │  Review  │  Done   │
│  ┌─────┐  │  ┌─────┐   │  ┌─────┐  │  ┌─────┐ │         │
│  │Task1│  │  │Task2│   │  │Task3│  │  │Task4│ │         │
│  └─────┘  │  └─────┘   │  └─────┘  │  └─────┘ │         │
└─────────────────────────────────────────────────────────┘
                    │           │
                    ▼           ▼
┌─────────────────────────────────────────────────────────┐
│                 tmux server "agtx"                      │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Session: "my-project"                              │ │
│  │  ┌────────┐  ┌────────┐  ┌────────┐                │ │
│  │  │Window: │  │Window: │  │Window: │                │ │
│  │  │task2   │  │task3   │  │task4   │                │ │
│  │  │(Claude)│  │(Claude)│  │(Claude)│                │ │
│  │  └────────┘  └────────┘  └────────┘                │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Session: "other-project"                           │ │
│  │  ┌───────────────────┐                             │ │
│  │  │ Window:           │                             │ │
│  │  │ some_other_task   │                             │ │
│  │  └───────────────────┘                             │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                    │           │
                    ▼           ▼
            ┌───────────────────────────┐
            │   Git Worktrees           │
            │  .agtx/worktrees/task2/   │
            │  .agtx/worktrees/task3/   │
            │  .agtx/worktrees/task4/   │
            └───────────────────────────┘

• Server: All sessions run on a dedicated tmux server named agtx
• Sessions: Each project gets its own tmux session (named after the project)
• Windows: Each task gets its own window within the project's session

# List all sessions
tmux -L agtx list-sessions

# List all windows across sessions
tmux -L agtx list-windows -a

# Attach to the agtx server
tmux -L agtx attach

• Database: ~/Library/Application Support/agtx/ (macOS) or ~/.local/share/agtx/ (Linux)
• Config: ~/.config/agtx/config.toml
• Worktrees: .agtx/worktrees/ in each project
• Tmux: Dedicated server agtx with per-project sessions

Press O and walk away. Come back to changes ready to merge.

The orchestrator is an AI agent that drives other AI agents to completion. You triage tasks into Planning or Running — the orchestrator takes over from there, advancing each task through its phases until it lands in Review, ready for you to merge.

agtx --experimental   # then press O

What it does:

• Monitors tasks in Planning and Running
• Advances tasks automatically as phases complete (Planning → Running → Review)
• Respects plugin phase rules — checks allowed_actions before each transition
• Detects stuck tasks (idle for 1+ minute without a phase artifact) and reads the agent pane to diagnose the cause
• Nudges stuck agents, answers CLI prompts automatically, or escalates to you with a reason when human input is needed

You triage. It executes. Move tasks from Backlog into Planning or Running — the orchestrator handles the rest. Merging is your call.

The orchestrator communicates with agtx through the Model Context Protocol (MCP). agtx ships with a built-in MCP server (agtx serve) that exposes the kanban board as a set of tools over JSON-RPC via stdio.

┌─────────────-┐     MCP (stdio)     ┌──────────────┐     SQLite     ┌─────┐
│ Orchestrator │ ←─────────────────→ │  MCP Server  │ ←────────────→ │ DB  │
│ (Claude Code)│                     │ (agtx serve) │                └──┬──┘
└──────┬───────┘                     └──────────────┘                   │
       │  push-when-idle notifications                                  │
┌──────┴───────┐                                                        │
│   TUI (agtx) │ ←───────────────────────────────────────────────────--─┘
└──────────────┘

MCP tools available to the orchestrator:

How it works:

1. When you press O, the TUI registers the MCP server with the orchestrator agent via claude mcp add-json --scope local
2. The orchestrator receives phase completion notifications pushed to its tmux pane when idle
3. It reacts by calling get_task to check allowed_actions, then move_task to advance the task
4. The TUI processes the transition request, executes all side effects (agent switching, skill deployment, prompt sending), and updates the database
5. If a task has been idle for 1+ minute without a phase artifact, the orchestrator is notified — it reads the pane with read_pane_content, then either nudges the agent with send_to_task or calls move_task with escalate_to_user to flag it for your attention
6. Escalated tasks show a ⚠ badge on the kanban board; opening the task popup shows the reason and dismisses the flag
7. MCP registration is cleaned up when the orchestrator is stopped

Contributions are welcome! Whether it's a bug fix, new plugin, agent integration, or documentation improvement.

See CONTRIBUTING.md for the full guide. Here's the short version:

# Fork & clone
git clone https://github.com/<you>/agtx && cd agtx

# Build & test
cargo build && cargo test --features test-mocks

Not sure where to start? Here are some ideas:

• Write a plugin — A single plugin.toml is all you need. See Creating a Plugin for the full reference
• Add a new agent — Integrate your favorite AI coding CLI. See the architecture docs for how agents are structured
• Improve documentation — Found something unclear? Help others by improving it
• Report bugs — Open an issue. Reproduction steps are always appreciated
• Browse open issues — Check the good first issue label for beginner-friendly tasks

See CLAUDE.md for full architecture docs and development patterns.

# Build
cargo build

# Run tests (includes mock-based tests)
cargo test --features test-mocks

# Build release
cargo build --release