agtx: Instructions file for Claude Code

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

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