agtx

Quick Start • Features • Usage • Mobile • Skills • Oneshot • MCP Server • Plugins • Orchestrator • Configuration

---

//:

//:

//:

Features

• Supported Agents:  Claude Code Codex Grok Cursor OpenCode Antigravity Gemini CLI Copilot pi
• Parallel Multi-agent task lifecycle: Configure different agents per workflow phase — e.g. Grok for research, Claude for implementation, Codex for review — with automatic agent switching and context handover.
• Multi-project Kanban board: Manage agent sessions across all projects via a single TUI without leaving your terminal.
• Vim-native Keybindings: Control the board and agent sessions with your Vim-powered muscle memory.
• Mobile support: Press W and scan the QR for an installable web app with the board, task details, diffs and the agent's live terminal — including a keyboard, so you can answer a permission prompt without going back to your desk. Over your wifi, or from anywhere via your tailnet. See Mobile.
• Orchestrator agent (experimental): A dedicated agent that autonomously manages your kanban board via MCP — delegates to coding agents, advances phases, checks for merge conflicts.
• Oneshot skill: Give a coding agent session a goal with /agtx:oneshot and it runs the whole board unattended — plans the work in milestone waves, starts tasks, unblocks the workers, judges Review, and merges each task. See Oneshot Skill.
• Brainstorm & Sweep skills: Capture ideas and push them to the board from any coding agent session — /agtx:brainstorm to explore freely, /agtx:sweep to decompose and create tasks with one confirmation step.
• Spec-driven plugins: Plug in GSD, Spec-kit, OpenSpec, BMAD, Superpowers and more — fully customizable. Ddefine your own workflow via a single TOML file. See Plugins how to create a plugin.

[!NOTE] Just need a plain coding-agent session-manager with full human-in-the-loop control and no spec-driven skill execution and orchestration on advancing tasks?

Choose the void plugin and enjoy agtx as a batteries included multi-agent session-manager.

Quick Start

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

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

[!NOTE] Add .agtx/ to your project's .gitignore to avoid committing worktrees and local task data.

# Install from source — `serve` adds the mobile board (`W`), and the
# published binaries are built with it
cargo build --release --features serve
cp target/release/agtx ~/.local/bin/

Updating

agtx checks GitHub once a day for a newer release and shows ⬆ 0.2.8 [u] in the board header when there is one. Press u for the details and one key to install it, or from a shell:

agtx update          # download, verify and replace this binary in place
agtx update --check  # report only; exits 1 when an update is available
agtx --version

Requirements

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

Usage

Keyboard Shortcuts

Key	Action
h/l or ←/→	Move between columns
j/k or ↑/↓	Move between tasks
o	Create new task
R	Enter research mode
↩	Open task (view agent session)
Ctrl+f	Open the task popup fullscreen; press again to return to windowed mode
m	Move task forward in workflow
r	Resume task (Review → Running) / Move back (Running → Planning)
p	Next phase (Review → Planning, cyclic plugins only)
d	Show git diff
x	Delete task
/	Search tasks
P	Select spec-driven workflow plugin
,	Open the config editor
?	Show every keyboard shortcut
u	Update agtx (only shown when a new release is available)
W	Serve the board to a phone (QR pairing, device list)
O	Toggle orchestrator agent (--experimental)
e	Toggle project sidebar
q	Quit

Task Creation Wizard

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

Task Description Editor

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

Key	Action
# or @	Fuzzy search and insert a file path
/	Fuzzy search and insert an agent skill/command (at line start or after space)
!	Fuzzy search and insert a task reference (at line start or after space)

Agent Sessions

Each task runs in its own tmux window with a dedicated coding agent. The session persists across the entire task lifecycle — you can open the task popup at any time to see live agent output, or press Ctrl+f to open it fullscreen inside agtx.

• Persistent context: The agent's full conversation history is preserved across Planning → Running → Review
• Resume from Review: Moving a task back to Running simply reconnects to the existing session — no re-initialization needed
• Inline view: Press ↩ on any active task to open a scrollable tmux view inside the TUI
• Fullscreen: Press Ctrl+f to expand the task popup inside agtx. Press Ctrl+f again for windowed mode or Ctrl+q to return to the board.
• Auto merge-conflict resolution: When a Review task becomes idle, agtx checks for merge conflicts with the default branch using a non-destructive virtual merge (git merge-tree). If conflicts are detected, the agent is automatically sent the /agtx:merge-conflicts skill to resolve them and re-commit

Why agtx? - The blackboard model

Most AI coding tools give you one agent, one task, one terminal. agtx is built on a different and much older idea: the blackboard system.

A blackboard system is an approach where a common knowledge base — the blackboard — is iteratively updated by a diverse group of specialist knowledge sources, starting from a problem specification and ending with a solution. Each specialist writes a partial solution to the blackboard when the state on the board matches what it can contribute.

— after Blackboard system, Wikipedia (CC BY-SA)

That architecture was designed for problems that are too ill-defined for a single solver and too interdependent to split cleanly up front. Shipping software with coding agents is exactly that problem, so agtx implements the model directly:

The dependency graph gives the blackboard its structure. Tasks references they build on, forming a graph of partial solutions - agtx holds downstream tasks until their dependencies reach Review or Done, then carries the relevant diffs and artifacts into the dependent task's context.

…

Blackboard model	In agtx
The blackboard — a shared repository of the problem, partial solutions and contributed information	The kanban board, its dependency graph, and everything the phases leave behind: specs, plans, diffs, reviews, and phase artifacts. Every agent reads from and writes to the same board
Knowledge sources — independent specialists that never talk to each other, only to the board	Eight coding agent CLIs, each running in its own git worktree and tmux window. No agent can see another's context — they exchange only what lands on the board
Control shell — decides opportunistically which specialist runs next	Plugin phase gates determine when a task can advance; the dependency graph determines which tasks are ready to start; and the orchestrator agent coordinates the board over MCP

Mobile

Press W on the board to serve it to your phone. agtx prints a QR code; scanning it pairs the device and opens an installable web app with the board, task details, git diffs, and the agent's live terminal — including a keyboard, so you can answer a permission prompt from wherever you are.

# Or start it yourself, without the TUI
agtx serve                       # this machine only
agtx serve --tunnel              # your tailnet — anywhere, your devices only
agtx serve --devices             # list paired devices
agtx serve --revoke          # revoke one; --revoke-all for the lot

Two keys in the overlay, each a whole action: s serves to the local network, t serves via your tailnet.

[!IMPORTANT] agtx never opens a port on its own. Serving lasts for as long as that agtx runs: quit it and the server stops, so the next time you want the board on your phone you press W then s/t again. Pairing does not change this — it is a credential, not a trigger, and a paired phone whose Mac is not serving just times out.

[!NOTE] This needs a binary built with --features serve. The released ones are; a local cargo build --release without it reports "this build has no web server" under both options.

Setup — on your wifi

Works in about thirty seconds, and needs nothing installed.

1. Run agtx in a project and press W
2. Press s
3. Point your phone's camera at the QR code — the phone must be on the same wifi
4. In Safari or Chrome: Share → Add to Home Screen

That last step is what turns it into an app: its own icon, no address bar, and the pairing remembered so you never scan again — but you still press W then s to start serving each time you run agtx.

The URL here is a private address like 192.168.1.20, which exists only on your network. It will not work on mobile data — if you leave the house, the app will sit there timing out. That is what the tailnet option below is for.

Setup — from anywhere, via Tailscale

A few minutes once, then it is the same two taps forever. Your board becomes reachable from your phone on any network, while staying invisible to everyone else.

One-time, on your Mac and your phone:

1. Install Tailscale on both
2. Sign both into the same account — they need to be on one tailnet
3. Enable Serve for your tailnet. It is off by default and is a separate switch from installing Tailscale — the step most people miss. The simplest way is to just press t in agtx once: Tailscale refuses with a one-time link that enables it for this machine, and agtx prints that link rather than swallowing it. Follow it, then press t again.

Once more, to install the app:

1. Run agtx, press W, press t
2. Scan the QR, and Share → Add to Home Screen

Then, every time you want the board on your phone: run agtx, press W, press t. That is all — the pairing is remembered, so there is no QR to scan; what you are starting is the server.

Now the icon on your home screen works on 5G, on hotel wifi, anywhere — the address is an HTTPS name on your tailnet, and only devices signed into it can resolve or reach it.

When it does not work

What you see	What it means
Unavailable: install Tailscale and sign this machine in	t needs Tailscale on this machine. Install it, or use s for wifi.
Unavailable: Tailscale is installed but not signed in	Run tailscale up.
could not start the tunnel: … Serve is not enabled on your tailnet	The one-time switch above. agtx relays Tailscale's ow