CLAUDE.md · fynnfluegge/agtx

Sections

1. Quick Start
2. Architecture
3. Key Concepts
4. Keyboard Shortcuts
5. Code Patterns
6. Building & Testing
7. Common Tasks
8. Supported Agents
9. Future Enhancements

First lines (shown under the repo's Apache-2.0 license)

# AGTX - Terminal Kanban for Coding Agents

A terminal-native kanban board for managing multiple coding agent sessions (Claude Code, Codex, Gemini, Copilot, OpenCode, Cursor, Grok, Antigravity) with isolated git worktrees.

## Quick Start

```bash
# Build
cargo build --release

# Run in a git project directory
./target/release/agtx

# Or run in dashboard mode (no git project required)
./target/release/agtx -g

# Enable experimental features (orchestrator agent)
./target/release/agtx --experimental

# Never run init_script / cleanup_script from project or plugin config
./target/release/agtx --no-init-scripts

# Trust the current project's config (enables its scripts and copy_files)
./target/release/agtx trust

# Run the MCP server (global mode, or project-scoped with a path)
./target/release/agtx mcp-serve [path]

# Serve the board to a phone (feature = "serve"; loopback needs no pairing)
./target/release/agtx serve [path] [--host 0.0.0.0] [--port 8787] [--tunnel private|public]
./target/release/agtx serve --devices          # paired devices
./target/release/agtx serve --revoke <id>      # or --revoke-all

# Record an agent lifecycle event (invoked by agent hooks, not by hand)
./target/release/agtx hook --env <agent> [--event <Name>] < payload.json

# Version, and self-update to the latest GitHub release
./target/release/agtx --version
./target/release/agtx update [--check]
```

Logs are JSON at `~/.config/agtx/logs/agtx.log` (daily rotation, `RUST_LOG` respected).

## Architecture

```
src/
├── main.rs           # Entry point, CLI arg parsing, AppMode, FeatureFlags
├── lib.rs            # Module exports
├── skills.rs         # Skill constants, agent-native paths, plugin command translation
├── tui/
│   ├── app.rs        # Main App struct, event loop, rendering (largest file)
│   ├── board.rs      # BoardState - kanban column/row navigation
│   ├── config_editor.rs # In-TUI config form: declared fields, two matches
│   ├── dep_graph.rs  # Pure dependency-graph model (topological levels, unblocked nodes)
│   ├── help.rs       # The `?` overlay's binding table (declared)
│   ├── input.rs      # InputMode enum
│   ├── serve_control.rs # The `W` overlay: run `agtx serve` as a child, manage devices
│   ├── shell_popup.rs # Shell popup state, rendering, content trimming
│   ├── text_input.rs # Shared line editor: buffer + byte caret, motion, deletion
│   ├── wizard.rs     # Task create/edit wizard state
│   └── *_tests.rs    # Unit tests included via #[path]
├── db/{schema.rs (SQLite ops), models.rs (Task, Project, TaskStatus, PhaseStatus, ...)}
├── tmux/
│   ├── mod.rs        # Tmux server "agtx", session management
│   ├── operations.rs # TmuxOperations trait (mockable)
│   ├── input.rs      # PaneInput/PaneInputSink, the input broker, both backends
│   └── control.rs    # Persistent `tmux -C` client, frame parser, command encoder
├── git/{mod.rs (repo/branch/diff/merge/conflicts), worktree.rs, operations.rs, provider.rs}
├── agent/
│   ├── mod.rs        # Agent struct, detection, command builders (derived from spec.rs)
│   ├── spec.rs       # AgentSpec table — one declarative record per agent + kind enums
│   ├── hook_status.rs # Agent-reported liveness: event vocabularies, atomic status writes
│   ├── trust.rs      # Reads each agent's own workspace-trust store
│   └── operations.rs # AgentOperations/CodingAgent traits (mockable)
├── core/{actions.rs (allowed_actions + CallerKind), input.rs (submit_message, parking)}
├── mcp/server.rs     # MCP server (JSON-RPC over stdio) — global and project-scoped modes
├── web/              # `agtx serve` — the board over HTTP (feature = "serve")
│   └── mod.rs, routes.rs, writes.rs, ws.rs, state.rs, auth.rs, assets.rs, qr.rs, tunnel.rs
├── update/{mod.rs, version.rs, check.rs, github.rs, release.rs, install.rs}
└── config/mod.rs     # GlobalConfig, ProjectConfig, MergedConfig, WorkflowPlugin, TrustStore

web/                   # The mobile PWA — plain ES modules, no build step
└── index.html, app.js, api.js, ansi.js, app.css, sw.js, manifest.webmanifest, icons

skills/                # Plugin skill files — /agtx:* (Claude) or @agtx:* (Codex)
└── sweep/, brainstorm/, oneshot/ SKILL.md

.claude-plugin/, .codex-plugin/, .mcp.json   # Plugin manifests + shared MCP config

plugins/               # Bundled plugin configs (embedded at compile time)
├── agtx/ (plugin.toml + skills: research, plan, execute, review, orchestrate, merge-conflicts)
└── agtx-terse/, gsd/, spec-kit/, openspec/, bmad/, superpowers/,
    oh-my-claudecode/, agent-skills/, void/  (each plugin.toml)

tests/
├── db_, config_, board_, git_, agent_ tests.rs
├── agent_parity_tests.rs  # Per-agent behaviour lock (launch/resume/skill paths/syntax)
├── hook_status_, mcp_, update_, mock_infrastructure_, shell_popup_ tests.rs
├── tmux_control_tests.rs  # Real-tmux pane input — opt-in via AGTX_TMUX_IT=1
└── smoke/             # Per-agent smoke tests — real binaries, no mocks, opt-in
    └── agent_smoke.py, test_agent_smoke.py, agent_matrix.rs, README.md

benchmark/ (SWE-bench harness), docker/ (sandbox images)
```

## Key Concepts

### Task Workflow
```
Backlog → Planning → Running → Review → Done
```

- **Backlog**: Task ideas. Also hosts the optional **Research** phase (`R`), which runs in place. No separate `Research` status — `TaskStatus` is `Backlog | Planning | Running | Review | Done`; Backlog's display name is `backlog/research`.
- **Planning**: Creates git worktree at `{worktree_dir}/{slug}` (default `.agtx/worktrees/{slug}`), copies files, runs init script, deploys skills, starts agent.
- **Running**: Agent implementing. **Review**: optionally create PR; tmux window stays open; can resume. **Done**: cleanup worktree + tmux window (branch kept locally), runs `cleanup_script` first.
- Backlog can skip to Running (`M`); Running can go back to Planning (`r`).

**Removing a worktree** — `RealGitOps::remove_worktree` (`git/operations.rs`); all cleanup paths (Review→Done, force-move, delete `x`) go through it on a background thread. Refuses a main working tree (no-op `Ok`); `is_main_working_tree` checks the toplevel (`--show-toplevel`), not just the git dir. A failed removal prunes (`git worktree prune`) and returns `Err`. `delete_task_resources` removes the worktree independently of a branch; `delete_branch` (`git branch -D`) stays paired with having had a worktree.

**Reaping spawned processes** — `kill-window` misses processes backgrounded into their own group. `reap_task_processes` finds them by environment (`AGTX_TASK_ID` set on the window by `create_window`, inherited by children — catches daemons) and by descent from the pane (backstop, runs before `kill_window`). `processes_for_task` reads `/proc/<pid>/environ` else `ps`. A root pid (0/1) or agtx's own pid is refused. Children signalled before parents (TERM then KILL) via the `kill` command.

**agtx's own files excluded from git** — `exclude_agtx_files_from_git` writes `AGTX_WRITTEN_PATHS` into `$GIT_COMMON_DIR/info/exclude` at worktree setup (per-worktree `info/exclude` is ignored by git). Exclude patterns affect untracked files only. Makes `git add -A` safe in the phase skills.

**The phase skills commit** — `execute.md` and `review.md` end by committing (Done requires a clean tree; merging requires commits).

**A repository with no commits** — `has_no_commits` → `create_initial_commit` (`git commit --allow-empty -m init`), since a worktree must be cut from a commit. `detect_main_branch` checks the exit status of its `git rev-parse --abbrev-ref HEAD` fallback.

### Workflow Plugins
Plugins customize the lifecycle per phase. A plugin is `plugin.toml` defining: **commands** (slash commands sent per phase, auto-translated; supports `preresearch` + `research`), **prompts** (`{task}`/`{task_id}`/`{phase}` templates), **artifacts** (completion paths, `*` wildcards), **prompt_triggers** (text to wait for), **init_script** (`{agent}` placeholder), **copy_dirs**/**copy_files**/**copy_back**, **cyclic** (Review→Planning with incrementing phase, `p`), **clear_context_on_advance** (send a clear-context command before the phase skill; Claude `/clear`, pi `/new`, no-op for the rest), **supported_agents** (whitelist, empty = all), **auto_dismiss**.

Phase gating is derived from config: a phase whose command/prompt contains `{task}` can be entered directly from Backlog; otherwise it needs a prior phase artifact. A phase with no command AND no prompt (void) is ungated. No `research_required` flag.

Resolution: project-local `.agtx/plugins/{name}/` → global `~/.config/agtx/plugins/{name}/` → bundled (`load_task_plugin` falls back to bundled). `discover_custom_plugins` (`src/skills.rs`) surfaces on-disk plugins alongside `BUNDLED_PLUGINS` in the board selector (`P`) and wizard (project-local shadows global; bundled-name collisions skipped; filtered by `supported_agents`). Each task stores its plugin name explicitly; switching the project plugin only affects new tasks.

### Skill System
Skills are markdown with YAML frontmatter deployed to agent-native paths in worktrees. Canonical copy always at `.agtx/skills/agtx-plan/SKILL.md`.

| Agent | Skill path |
|-------|-----------|
| claude | `.claude/commands/agtx/plan.md` |
| gemini | `.gemini/commands/agtx/plan.toml` (TOML) |
| codex | `.codex/skills/agtx-plan/SKILL.md` |
| cursor | `.cursor/skills/agtx-plan/SKILL.md` |
| grok | `.grok/skills/agtx-plan/SKILL.md` |
| antigravity | `.agents/skills/agtx-plan/SKILL.md` (vendor-neutral) |
| opencode | `.opencode/command/agtx-plan.md` (frontmatter stripped) |
| copilot | `.github/agents/agtx/plan.md` |

`write_skills_to_worktree()` also drops a **per-agent MCP config** pointing at `agtx mcp-serve <project>`:

| Agent | File | Format |
|-------|------|--------|
| claude | `.mcp.json` | JSON, `mcpServers` |
| codex | `.codex/config.toml` | TOML, `[mcp_servers.agtx]` |
| gemini | `.gemini/settings.json` | JSON, `mcpServers` + `trust: true` |
| cursor | `.cursor/mcp.json` | JSON, `mcpServers` |
| grok | `.grok/config.toml` | TOML, `[mcp_servers.agtx]` |
| antigravity | `.agents/mcp_config.json` | JSON, `mcpServers` |
| opencode | opencode config | JSON, `mcp` |