agtx CLAUDE.md

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]

# 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 written as JSON to ~/.config/agtx/logs/agtx.log (daily rotation, RUST_LOG respected).

Architecture

src/
├── main.rs           # Entry point, CLI arg parsing, AppMode enum, FeatureFlags
├── lib.rs            # Module exports, AppMode, FeatureFlags
├── skills.rs         # Skill constants, agent-native paths, plugin command translation
├── tui/
│   ├── mod.rs        # Re-exports
│   ├── app.rs        # Main App struct, event loop, rendering (largest file)
│   ├── app_tests.rs  # Unit tests for app.rs (included via #[path])
│   ├── board.rs      # BoardState - kanban column/row navigation
│   ├── dep_graph.rs  # Pure dependency-graph model (topological levels, unblocked nodes)
│   ├── input.rs      # InputMode enum for UI states
│   └── shell_popup.rs # Shell popup state, rendering, content trimming
├── db/
│   ├── mod.rs        # Re-exports
│   ├── schema.rs     # Database struct, SQLite operations
│   └── models.rs     # Task, Project, TaskStatus, PhaseStatus, TransitionRequest,
│                     # Notification, RunningAgent, AgentStatus
├── tmux/
│   ├── mod.rs        # Tmux server "agtx", session management
│   └── operations.rs # TmuxOperations trait (mockable for testing)
├── git/
│   ├── mod.rs        # is_git_repo, repo_root, current_branch, diff_stat/diff_full,
│                     # merge_branch, check_merge_conflicts, delete_branch
│   ├── worktree.rs   # Git worktree create/remove/list
│   ├── operations.rs # GitOperations trait (mockable for testing)
│   └── provider.rs   # GitProviderOperations trait (GitHub PR ops)
├── agent/
│   ├── mod.rs        # Agent struct, detection, command builders (all derived from spec.rs)
│   ├── spec.rs       # AgentSpec table — one declarative record per agent + kind enums
│   ├── hook_status.rs # Agent-reported liveness: per-agent event vocabularies,
│                     # what agtx registers, atomic status writes, staleness
│   ├── trust.rs      # Reads each agent's own workspace-trust store; seeds antigravity's
│   ├── trust_tests.rs # Unit tests for trust.rs (included via #[path])
│   └── operations.rs # AgentOperations/CodingAgent traits (mockable)
├── mcp/
│   ├── mod.rs        # Re-exports
│   └── server.rs     # MCP server (JSON-RPC over stdio) — global and project-scoped modes
├── update/
│   ├── mod.rs        # check_for_update() — the whole background check
│   ├── version.rs    # Semver-lite parse/compare + the prerelease policy (pure)
│   ├── check.rs      # Cache TTL, should_check, available (pure but for the file)
│   ├── github.rs     # releases/latest over curl
│   ├── release.rs    # Repo slug + archive naming, shared with install.sh/release.yml
│   └── install.rs    # Download, verify sha256, atomic in-place binary swap
└── config/
    └── mod.rs        # GlobalConfig, ProjectConfig, MergedConfig, PhaseAgentsConfig,
                      # WorktreeConfig, ThemeConfig, WorkflowPlugin, TrustStore

skills/                # Plugin skill files — auto-discovered as /agtx:* (Claude) or @agtx:* (Codex)
├── sweep/SKILL.md     # Sweep skill — push any conversation to the board (/agtx:sweep)
└── brainstorm/SKILL.md # Brainstorm skill — free-form exploration (/agtx:brainstorm)

.claude-plugin/        # Claude Code plugin manifest
├── plugin.json        # Plugin metadata + MCP server registration
└── marketplace.json   # Makes repo discoverable via /plugin marketplace add

.codex-plugin/         # Codex plugin manifest
└── plugin.json        # Plugin metadata (skills + MCP via .mcp.json)

.mcp.json              # Shared MCP server config (used by Codex plugin)

plugins/               # Bundled plugin configs (embedded at compile time)
├── agtx/
│   ├── plugin.toml    # Default workflow with skills and prompts
│   └── skills/        # Builtin skills embedded via include_str! in src/skills.rs:
│       ├── research.md, plan.md, execute.md, review.md
│       ├── orchestrate.md      # Orchestrator agent skill (experimental)
│       └── merge-conflicts.md  # Auto merge-conflict resolution skill
├── agtx-terse/
│   ├── plugin.toml    # Token-efficient variant of agtx workflow
│   └── skills/        # Terse skill overrides with brevity directive
├── gsd/plugin.toml    # Get Shit Done workflow
├── spec-kit/plugin.toml # GitHub spec-kit workflow
├── openspec/plugin.toml # OpenSpec specification framework
├── bmad/plugin.toml   # BMAD Method - AI-driven agile development
├── superpowers/plugin.toml # Superpowers - brainstorming, plans, TDD, subagent-driven dev
├── oh-my-claudecode/plugin.toml # oh-my-claudecode - multi-agent orchestration
├── agent-skills/plugin.toml # Agent Skills - spec-to-ship engineering skills
└── void/plugin.toml   # Plain agent session, no prompting

tests/
├── db_tests.rs        # Database, model, and dependency-graph tests
├── config_tests.rs    # Configuration tests
├── board_tests.rs     # Board navigation tests
├── git_tests.rs       # Git worktree tests
├── agent_tests.rs     # Agent detection and spawn args tests
├── agent_parity_tests.rs # Per-agent behaviour lock (launch/resume/skill paths/syntax)
├── hook_status_tests.rs  # Agent lifecycle-hook status reporting
├── mcp_tests.rs       # MCP server tests
├── update_tests.rs    # Version policy, cache TTL, artifact naming parity, binary swap
├── mock_infrastructure_tests.rs # Mock infrastructure tests
├── shell_popup_tests.rs         # Shell popup logic tests
└── smoke/             # Per-agent smoke tests — real binaries, no mocks, opt-in
    ├── agent_smoke.py      # The runner: scratch repo → TUI in tmux → phases over MCP
    ├── test_agent_smoke.py # Deterministic tests for the harness itself (no tmux/auth)
    ├── agent_matrix.rs     # Dumps AGENT_SPECS + BUNDLED_PLUGINS as JSON for the runner
    │                       # (a [[example]] in Cargo.toml, so `cargo test` compiles it)
    └── README.md           # What it asserts, its outcomes, and what it has found

benchmark/             # SWE-bench harness
docker/                # Container images for sandboxed runs