{"id":45345451,"url":"https://github.com/fynnfluegge/agtx","last_synced_at":"2026-04-01T17:44:29.353Z","repository":{"id":339655676,"uuid":"1152720637","full_name":"fynnfluegge/agtx","owner":"fynnfluegge","description":"Multi-session AI coding terminal manager - autonomously orchestrate Claude, Codex, Gemini, OpenCode, Cursor","archived":false,"fork":false,"pushed_at":"2026-03-26T18:39:28.000Z","size":381,"stargazers_count":698,"open_issues_count":9,"forks_count":55,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-27T07:50:38.445Z","etag":null,"topics":["claude","claude-code","codex","cursor","gemini","opencode","spec-driven-development","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fynnfluegge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":null,"dco":null,"cla":null}},"created_at":"2026-02-08T10:24:00.000Z","updated_at":"2026-03-26T19:37:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fynnfluegge/agtx","commit_stats":null,"previous_names":["fynnfluegge/agtx"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/fynnfluegge/agtx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fynnfluegge%2Fagtx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fynnfluegge%2Fagtx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fynnfluegge%2Fagtx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fynnfluegge%2Fagtx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fynnfluegge","download_url":"https://codeload.github.com/fynnfluegge/agtx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fynnfluegge%2Fagtx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["claude","claude-code","codex","cursor","gemini","opencode","spec-driven-development","vibe-coding"],"created_at":"2026-02-21T11:08:52.044Z","updated_at":"2026-04-01T17:44:29.346Z","avatar_url":"https://github.com/fynnfluegge.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[//]: \u003cimg src=\"https://github.com/user-attachments/assets/54ac039b-085e-490b-aacc-36c8e244e313\" width=\"428\" /\u003e\n\n# agtx\n\n\u003cdiv align=\"left\"\u003e\n    \n\u003e **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.\n\u003e \n\u003e **Let different AI coding agents collaborate** autonomously on the same task with automatic session switching and context awareness -  \n\u003e e.g. **Gemini** → research | **Claude** → implement | **Codex** → review\n\n\u003c/div\u003e\n\n[![CI](https://github.com/fynnfluegge/agtx/actions/workflows/ci.yml/badge.svg)](https://github.com/fynnfluegge/agtx/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/fynnfluegge/agtx)](https://github.com/fynnfluegge/agtx/releases)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n---\n\n\u003cimg width=\"840\" src=\"https://github.com/user-attachments/assets/45858e09-ab61-422b-b708-db060c73a900\" /\u003e\n\n[//]:  \u003cimg width=\"840\" src=\"https://github.com/user-attachments/assets/42f71a6c-424c-4cc4-80fc-dc9bb8ba1467\" /\u003e\n\n\u003cbr/\u003e\n\n[//]: \u003cimg width=\"1486\" height=\"680\" src=\"https://github.com/user-attachments/assets/45858e09-ab61-422b-b708-db060c73a900\" /\u003e\n\n[//]: \u003c![Xnapper-2026-02-14-09 36 33 (1)](https://github.com/user-attachments/assets/fce21a9c-2fe1-4b14-8f24-55e058531370)\u003e\n\n\u003c/div\u003e\n\n## Why agtx?\n\nAI 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.\n\nWith 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.\n\n\u003e [!TIP]\n\u003e Check out the [Contributing](#contributing) section or have a look at [`good first issues`](https://github.com/fynnfluegge/agtx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get involved and become a contributor ⭐️ \n\n## Features\n\n- **Orchestrator agent**: A dedicated AI agent that autonomously manages your kanban board via [MCP](https://modelcontextprotocol.io) — delegates to coding agents, advances phases, checks for merge conflicts ([experimental](#orchestrator-agent-experimental))\n- **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\n- **Parallel execution**: Every task gets its own git worktree and tmux window — run as many agents as needed, simultaneously\n- **Spec-driven plugins**: Plug in [GSD](https://github.com/fynnfluegge/get-shit-done-cc), [Spec-kit](https://github.com/github/spec-kit), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [BMAD](https://github.com/bmad-code-org/BMAD-METHOD), [Superpowers](https://github.com/obra/superpowers) — or define your own with a single TOML file\n- **Multi-project dashboard**: Manage agent sessions across all projects via a single TUI\n- **Works with**: [Claude Code](https://github.com/anthropics/claude-code) | [Codex](https://github.com/openai/codex) | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | [OpenCode](https://github.com/sst/opencode)  | [Cursor Agent](https://cursor.com/docs/cli/overview) | [Copilot](https://github.com/github/copilot-cli)\n\n\u003e [!NOTE]\n\u003e Just need a plain coding agent session manager with **full human-in-the-loop control** and **no automatic spec-driven skill execution and orchestration** on advancing tasks?\n\u003e\n\u003e Choose the **`void` plugin** and enjoy the kanban coding agent board - with full human control.\n\n## Quick Start\n\n```bash\n# Install\ncurl -fsSL https://raw.githubusercontent.com/fynnfluegge/agtx/main/install.sh | bash\n\n# Run in any git repository\ncd your-project \u0026\u0026 agtx\n```\n\n```bash\n# Dashboard mode — manage all projects\nagtx -g\n\n# Orchestrator mode — let an AI manage the board for you\nagtx --experimental\n```\n\n\u003e [!NOTE]\n\u003e Add `.agtx/` to your project's `.gitignore` to avoid committing worktrees and local task data.\n\n```bash\n# Install from source\ncargo build --release\ncp target/release/agtx ~/.local/bin/\n```\n\u003c/details\u003e\n\n### Requirements\n\n- **tmux** — agent sessions run in a dedicated tmux server\n- **gh** (optional) — GitHub CLI for PR operations\n\n## Usage\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `h/l` or `←/→` | Move between columns |\n| `j/k` or `↑/↓` | Move between tasks |\n| `o` | Create new task |\n| `R` | Enter research mode |\n| `↩` | Open task (view agent session) |\n| `m` | Move task forward in workflow |\n| `r` | Resume task (Review → Running) / Move back (Running → Planning) |\n| `p` | Next phase (Review → Planning, cyclic plugins only) |\n| `d` | Show git diff |\n| `x` | Delete task |\n| `/` | Search tasks |\n| `P` | Select spec-driven workflow plugin |\n| `O` | Toggle orchestrator agent (`--experimental`) |\n| `e` | Toggle project sidebar |\n| `q` | Quit |\n\n### Task Creation Wizard\n\nPress `o` to create a new task. The wizard guides you through:\n1. **Title** — enter a short task name\n2. **Plugin** — select a workflow plugin (auto-skipped if only one option)\n3. **Prompt** — write a detailed task description with inline references\n\nThe agent is configured at the project level via `config.toml` (not per-task).\n\n### Task Description Editor\n\nWhen writing a task description, you can reference files, skills, and other tasks inline:\n\n| Key | Action |\n|-----|--------|\n| `#` or `@` | Fuzzy search and insert a file path |\n| `/` | Fuzzy search and insert an agent skill/command (at line start or after space) |\n| `!` | Fuzzy search and insert a task reference (at line start or after space) |\n\n\n### Agent Session Features\n\n- Sessions automatically resume when moving Review → Running\n- Full conversation context is preserved across the task lifecycle\n- View live agent output in the task popup\n- **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.\n\n## Configuration\n\nConfig file location: `~/.config/agtx/config.toml`\n\n### Worktree Base Branch\n\nagtx creates a new git worktree for each task. By default it auto-detects the base branch in this\norder: `main`, then `master`, then the current branch. You can override this to force a specific\nbase branch (for example `dev` or `develop`).\n\nGlobal worktree defaults can be set here:\n\n```toml\n# ~/.config/agtx/config.toml\n[worktree]\nbase_branch = \"dev\"\n```\n\n### Project Configuration\n\nPer-project settings can be placed in `.agtx/config.toml` at the project root:\n\n```toml\n# Base branch used when creating new task worktrees (optional)\nbase_branch = \"dev\"\n\n# Files to copy from project root into each new worktree (comma-separated)\n# Paths are relative and preserve directory structure\ncopy_files = \".env, .env.local, web/.env.local\"\n\n# Shell command to run inside the worktree after creation and file copying\ninit_script = \"scripts/init_worktree.sh\"\n```\n\n`base_branch` controls which branch new task worktrees are created from. If omitted or empty, agtx\nauto-detects `main`, `master`, or falls back to the current branch.\n\nThese options run during the Backlog → Research/Planning/Running transition, after worktree creation\nand before the agent session starts.\n\n### Per-Phase Agent Configuration\n\nBy default, all phases use `default_agent`. You can override the agent for specific phases globally or per project:\n\n```toml\n# ~/.config/agtx/config.toml\ndefault_agent = \"claude\"\n\n[agents]\nresearch = \"gemini\"\nplanning = \"claude\"\nrunning = \"claude\"\nreview = \"codex\"\n```\n\n```toml\n# .agtx/config.toml (project override — takes precedence over global)\n[agents]\nrunning = \"codex\"\n```\n\n## Plugins\n\nPlug 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.\n\nPress `P` to switch plugins. Ships with 7 built-in:\n\n| Plugin | Description |\n|--------|-------------|\n| **void** | Plain agent session - no prompting or skills, task description prefilled in input |\n| **agtx** (default) | Built-in workflow with skills and prompts for each phase |\n| **gsd** | [Get Shit Done](https://github.com/fynnfluegge/get-shit-done-cc) - structured spec-driven development with interactive planning |\n| **spec-kit** | [Spec-Driven Development](https://github.com/github/spec-kit) by GitHub - specifications become executable artifacts |\n| **openspec** | [OpenSpec](https://github.com/Fission-AI/OpenSpec) - lightweight AI-guided specification framework |\n| **bmad** | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) - AI-driven agile development with structured phases |\n| **superpowers** | [Superpowers](https://github.com/obra/superpowers) - brainstorming, plans, TDD, subagent-driven development |\n\n### Agent Compatibility\n\nCommands are written once in canonical format and automatically translated per agent:\n\n| Canonical (plugin.toml) | Claude / Gemini | Codex | OpenCode | Cursor |\n|--------------------------|-----------------|-------|----------|--------|\n| `/agtx:plan` | `/agtx:plan` | `$agtx-plan` | `/agtx-plan` | `/agtx-plan` |\n\n|  | Claude | Codex | Gemini | OpenCode | Cursor | Copilot |\n|--|:------:|:-----:|:------:|:--------:|:------:|:-------:|\n| **agtx** | ✅ | ✅ | ✅ | ✅ | ✅ | 🟡 |\n| **gsd** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |\n| **spec-kit** | ✅ | ✅ | ✅ | ✅ | ✅ | 🟡 |\n| **openspec** | ✅ | ✅ | ✅ | ✅ | ✅ | 🟡 |\n| **bmad** | ✅ | ✅ | ✅ | ✅ | ✅ | 🟡 |\n| **superpowers** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **void** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n✅ Skills, commands, and prompts fully supported · 🟡 Prompt only, no interactive skill support · ❌ Not supported\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCreating a Plugin\u003c/b\u003e\u003c/summary\u003e\n\nPlace your plugin at `.agtx/plugins/\u003cname\u003e/plugin.toml` in your project root (or `~/.config/agtx/plugins/\u003cname\u003e/plugin.toml` for global use). It will appear in the plugin selector automatically.\n\n**Minimal example** — a plugin that uses custom slash commands:\n\n```toml\nname = \"my-plugin\"\ndescription = \"My custom workflow\"\n\n[commands]\nresearch = \"/my-plugin:research {task}\"\nplanning = \"/my-plugin:plan\"\nrunning = \"/my-plugin:execute\"\nreview = \"/my-plugin:review\"\n\n[prompts]\nplanning = \"Task: {task}\"\n```\n\n**Full reference** with all available fields:\n\n```toml\nname = \"my-plugin\"\ndescription = \"My custom workflow\"\n\n# Shell command to run in the worktree after creation, before the agent starts.\n# {agent} is replaced with the agent name (claude, codex, gemini, etc.)\ninit_script = \"npm install --prefix .my-plugin --{agent}\"\n\n# Restrict to specific agents (empty or omitted = all agents supported)\nsupported_agents = [\"claude\", \"codex\", \"gemini\", \"opencode\"]\n\n# Extra directories to copy from project root into each worktree.\n# Agent config dirs (.claude, .gemini, .codex, .github/agents, .config/opencode)\n# are always copied automatically.\ncopy_dirs = [\".my-plugin\"]\n\n# Individual files to copy from project root into each worktree.\n# Merged with project-level copy_files from .agtx/config.toml.\ncopy_files = [\"PROJECT.md\", \"REQUIREMENTS.md\"]\n\n# When true, enables Review → Planning transition via the `p` key.\n# Each cycle increments the phase counter ({phase} placeholder).\n# Use this for multi-milestone workflows (e.g. plan → execute → review → next milestone).\ncyclic = false\n\n# Artifact files that signal phase completion.\n# When detected, the task shows a checkmark instead of the spinner.\n# Supports * wildcard for one directory level (e.g. \"specs/*/plan.md\").\n# Use {phase} for cycle-aware paths (replaced with the current cycle number).\n# Omitted phases show no completion indicator.\n[artifacts]\nresearch = \".my-plugin/research.md\"\nplanning = \".my-plugin/{phase}/plan.md\"\nrunning = \".my-plugin/{phase}/summary.md\"\nreview = \".my-plugin/{phase}/review.md\"\n\n# Slash commands sent to the agent via tmux for each phase.\n# Written in canonical format (Claude/Gemini style): /namespace:command\n# Automatically transformed per agent:\n#   Claude/Gemini: /my-plugin:plan (unchanged)\n#   OpenCode:      /my-plugin-plan (colon -\u003e hyphen)\n#   Codex:         $my-plugin-plan (slash -\u003e dollar, colon -\u003e hyphen)\n# Omitted phases fall back to agent-native agtx skill invocation\n# (e.g. /agtx:plan for Claude, $agtx-plan for Codex).\n# Set to \"\" to skip sending a command for that phase.\n# Use {phase} for cycle-aware commands (replaced with the current cycle number).\n# Use {task} to inline the task description.\n[commands]\npreresearch = \"/my-plugin:research {task}\"  # Used only when no research artifacts exist yet\nresearch = \"/my-plugin:discuss {phase}\"\nplanning = \"/my-plugin:plan {phase}\"\nrunning = \"/my-plugin:execute {phase}\"\nreview = \"/my-plugin:review {phase}\"\n\n# Prompt templates sent as task content after the command.\n# {task} = task title + description, {task_id} = unique task ID, {phase} = cycle number.\n# Omitted phases send no prompt (the skill/command handles instructions).\n[prompts]\nresearch = \"Task: {task}\"\n\n# Text patterns to wait for in the tmux pane before sending the prompt.\n# Useful when a command triggers an interactive prompt that must appear first.\n# Polls every 500ms, times out after 5 minutes.\n[prompt_triggers]\nresearch = \"What do you want to build?\"\n\n# Files/dirs to copy from worktree back to project root after a phase completes.\n# Triggered automatically when the phase artifact is detected (spinner → checkmark).\n# Useful for sharing research artifacts (specs, plans) across worktrees.\n[copy_back]\nresearch = [\"PROJECT.md\", \"REQUIREMENTS.md\", \".my-plugin\"]\n\n# Auto-dismiss interactive prompts that appear before the prompt trigger.\n# Each rule fires when ALL detect patterns are present and the pane is stable.\n# Response is newline-separated keystrokes (e.g. \"2\\nEnter\" sends \"2\" then Enter).\n[[auto_dismiss]]\ndetect = [\"Map codebase\", \"Skip mapping\", \"Enter to select\"]\nresponse = \"2\\nEnter\"\n```\n\n**What happens at each phase transition:**\n\n1. The **command** is sent to the agent via tmux (e.g., `/my-plugin:plan`)\n2. If a **prompt_trigger** is set, agtx waits for that prompt trigger to appear in the tmux pane\n3. The **prompt** is sent with `{task}`, `{task_id}`, and `{phase}` replaced\n4. agtx polls for the **artifact** file — when found, the spinner becomes a checkmark\n5. If **copy_back** is configured, artifacts are copied from worktree to project root on completion\n6. If the agent appears idle (no output for 15s), the spinner becomes a pause icon\n\n**Phase gating:** Whether a phase can be entered directly from Backlog is derived from the plugin config. If a phase's command or prompt contains `{task}`, it can receive task context and is accessible from Backlog. If neither has `{task}`, the phase depends on a prior phase and is blocked until that artifact exists. For example, OpenSpec's `/opsx:propose {task}` allows direct Backlog → Planning, but `/opsx:apply` (no `{task}`) blocks Backlog → Running until proposal artifacts exist.\n\n**Preresearch fallback:** When pressing `R` on a task, if `preresearch` is configured and no research artifacts from `copy_back` exist in the project root yet, the `preresearch` command is used instead of `research`. This lets plugins run a one-time project setup (e.g. `/gsd:new-project`) before switching to the regular research command for subsequent tasks. If the plugin has no research command at all (e.g. OpenSpec), pressing `R` shows a warning.\n\n**Cyclic workflows:** When `cyclic = true`, pressing `p` in Review moves the task back to Planning with an incremented phase counter. This enables multi-milestone workflows where each cycle (plan → execute → review) produces artifacts in a separate `{phase}` directory.\n\n**Custom skills:** If your plugin provides its own skill files, place them in the plugin directory:\n\n```\n.agtx/plugins/my-plugin/\n├── plugin.toml\n└── skills/\n    ├── agtx-plan/SKILL.md\n    ├── agtx-execute/SKILL.md\n    └── agtx-review/SKILL.md\n```\n\nThese override the built-in agtx skills and are automatically deployed to each agent's native discovery path (`.claude/commands/`, `.codex/skills/`, `.gemini/commands/`, etc.) in every worktree.\n\n\u003c/details\u003e\n\n## How It Works\n\n### Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                      agtx TUI                           │\n├─────────────────────────────────────────────────────────┤\n│  Backlog  │  Planning  │  Running  │  Review  │  Done   │\n│  ┌─────┐  │  ┌─────┐   │  ┌─────┐  │  ┌─────┐ │         │\n│  │Task1│  │  │Task2│   │  │Task3│  │  │Task4│ │         │\n│  └─────┘  │  └─────┘   │  └─────┘  │  └─────┘ │         │\n└─────────────────────────────────────────────────────────┘\n                    │           │\n                    ▼           ▼\n┌─────────────────────────────────────────────────────────┐\n│                 tmux server \"agtx\"                      │\n│  ┌────────────────────────────────────────────────────┐ │\n│  │ Session: \"my-project\"                              │ │\n│  │  ┌────────┐  ┌────────┐  ┌────────┐                │ │\n│  │  │Window: │  │Window: │  │Window: │                │ │\n│  │  │task2   │  │task3   │  │task4   │                │ │\n│  │  │(Claude)│  │(Claude)│  │(Claude)│                │ │\n│  │  └────────┘  └────────┘  └────────┘                │ │\n│  └────────────────────────────────────────────────────┘ │\n│  ┌────────────────────────────────────────────────────┐ │\n│  │ Session: \"other-project\"                           │ │\n│  │  ┌───────────────────┐                             │ │\n│  │  │ Window:           │                             │ │\n│  │  │ some_other_task   │                             │ │\n│  │  └───────────────────┘                             │ │\n│  └────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n                    │           │\n                    ▼           ▼\n            ┌───────────────────────────┐\n            │   Git Worktrees           │\n            │  .agtx/worktrees/task2/   │\n            │  .agtx/worktrees/task3/   │\n            │  .agtx/worktrees/task4/   │\n            └───────────────────────────┘\n```\n\n### Tmux Structure\n\n- **Server**: All sessions run on a dedicated tmux server named `agtx`\n- **Sessions**: Each project gets its own tmux session (named after the project)\n- **Windows**: Each task gets its own window within the project's session\n\n```bash\n# List all sessions\ntmux -L agtx list-sessions\n\n# List all windows across sessions\ntmux -L agtx list-windows -a\n\n# Attach to the agtx server\ntmux -L agtx attach\n```\n\n### Data Storage\n\n- **Database**: `~/Library/Application Support/agtx/` (macOS) or `~/.local/share/agtx/` (Linux)\n- Config: `~/.config/agtx/config.toml`\n- **Worktrees**: `.agtx/worktrees/` in each project\n- **Tmux**: Dedicated server `agtx` with per-project sessions\n\n## Orchestrator Agent (Experimental)\n\n\u003e Press `O` and walk away. Come back to changes ready to merge.\n\nThe 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.\n\n```bash\nagtx --experimental   # then press O\n```\n\n**What it does:**\n- Monitors tasks in Planning and Running\n- Advances tasks automatically as phases complete (Planning → Running → Review)\n- Respects plugin phase rules — checks `allowed_actions` before each transition\n- Detects stuck tasks (idle for 1+ minute without a phase artifact) and reads the agent pane to diagnose the cause\n- Nudges stuck agents, answers CLI prompts automatically, or escalates to you with a reason when human input is needed\n\n**You triage. It executes.** Move tasks from Backlog into Planning or Running — the orchestrator handles the rest. Merging is your call.\n\n### MCP Integration\n\nThe orchestrator communicates with agtx through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). 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.\n\n```\n┌─────────────-┐     MCP (stdio)     ┌──────────────┐     SQLite     ┌─────┐\n│ Orchestrator │ ←─────────────────→ │  MCP Server  │ ←────────────→ │ DB  │\n│ (Claude Code)│                     │ (agtx serve) │                └──┬──┘\n└──────┬───────┘                     └──────────────┘                   │\n       │  push-when-idle notifications                                  │\n┌──────┴───────┐                                                        │\n│   TUI (agtx) │ ←───────────────────────────────────────────────────--─┘\n└──────────────┘\n```\n\n**MCP tools available to the orchestrator:**\n\n| Tool | Description |\n|------|-------------|\n| `list_tasks` | List all tasks, optionally filtered by status |\n| `get_task` | Get task details including `allowed_actions` for valid transitions |\n| `move_task` | Queue a state transition (the TUI executes it with full side effects) |\n| `get_transition_status` | Check if a queued transition completed or errored |\n| `check_conflicts` | Non-destructive merge conflict detection against the default branch |\n| `get_notifications` | Manually fetch pending notifications (backup — usually pushed automatically) |\n| `read_pane_content` | Read the last N lines of a task's agent tmux pane |\n| `send_to_task` | Send a message to a task's agent pane (Planning/Running only) |\n\n**How it works:**\n1. When you press `O`, the TUI registers the MCP server with the orchestrator agent via `claude mcp add-json --scope local`\n2. The orchestrator receives phase completion notifications pushed to its tmux pane when idle\n3. It reacts by calling `get_task` to check `allowed_actions`, then `move_task` to advance the task\n4. The TUI processes the transition request, executes all side effects (agent switching, skill deployment, prompt sending), and updates the database\n5. 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\n6. Escalated tasks show a `⚠` badge on the kanban board; opening the task popup shows the reason and dismisses the flag\n7. MCP registration is cleaned up when the orchestrator is stopped\n\n## Contributing\n\nContributions are welcome! Whether it's a bug fix, new plugin, agent integration, or documentation improvement.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. Here's the short version:\n\n```bash\n# Fork \u0026 clone\ngit clone https://github.com/\u003cyou\u003e/agtx \u0026\u0026 cd agtx\n\n# Build \u0026 test\ncargo build \u0026\u0026 cargo test --features test-mocks\n```\n\n### Good First Contributions\n\nNot sure where to start? Here are some ideas:\n\n- **Write a plugin** — A single `plugin.toml` is all you need. See [Creating a Plugin](#plugins) for the full reference\n- **Add a new agent** — Integrate your favorite AI coding CLI. See the [architecture docs](CLAUDE.md) for how agents are structured\n- **Improve documentation** — Found something unclear? Help others by improving it\n- **Report bugs** — Open an [issue](https://github.com/fynnfluegge/agtx/issues). Reproduction steps are always appreciated\n- **Browse open issues** — Check the [`good first issue`](https://github.com/fynnfluegge/agtx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label for beginner-friendly tasks\n\n## Development\n\nSee [CLAUDE.md](CLAUDE.md) for full architecture docs and development patterns.\n\n```bash\n# Build\ncargo build\n\n# Run tests (includes mock-based tests)\ncargo test --features test-mocks\n\n# Build release\ncargo build --release\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffynnfluegge%2Fagtx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffynnfluegge%2Fagtx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffynnfluegge%2Fagtx/lists"}