{"id":"bbcb9f28-47a4-4c20-ab54-8ec928aecb70","slug":"mtix","kind":"mcp","name":"mtix","summary":"AI-native micro issue manager for multi-agent LLM development. Hierarchical task decomposition with context chains, safety-critical standards, and zero-infrastructure deployment.","owner":"hyper-swe","repoUrl":"https://github.com/hyper-swe/mtix","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-29T15:26:11.000Z","addedAt":"2026-10-21T08:35:55.030Z","logoUrl":"https://avatars.githubusercontent.com/u/219706616?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","memory-knowledge"],"tags":["ai-agents","cli","developer-tools","hierarchical-tasks","llm","multi-agent","multi-agent-systems","safety-critical"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T18:39:07.467Z","sample":false,"url":"https://conduits.dev/tools/mtix","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# mtix\n\n**Task infrastructure for parallel AI coding agents.**\n\nAn AI coding agent is only as good as the context behind its task. As a plan breaks into smaller pieces, that context scatters. The goal, the constraints, and the reasoning end up spread across issues, chat threads, and memory. Agents drift. They redo finished work. They stall for clarification.\n\nmtix fixes this with a **context chain**. Every task inherits the full briefing of its parents. When an agent claims a task, it gets one assembled prompt: the why, the scope, and the exact step to run. Each task briefs itself. So **many agents can run one plan in parallel**, each with the context its piece needs. No collisions. No re-explaining.\n\nThe same context chain works across a team. One shared hub keeps everyone's agents on the same plan and the same context. It is local-first. A **remote team** keeps working offline, then syncs on reconnect.\n\nmtix ships as a single binary. It speaks MCP, so Claude Code uses it natively. Every agent, claim, and state change is tracked, so parallel work stays consistent and auditable.\n\n---\n\nmtix (micro-ticks) is a hierarchical task management system where multiple LLM coding agents decompose, claim, and execute work concurrently. Work breaks down into infinitely nested micro issues using dot-notation IDs (`PROJ-42.1.3.2.1`), where the hierarchy itself becomes the agent's briefing — each level adds context that flows down to the executing agent. Every operation is available through CLI, REST, gRPC, MCP, and a real-time web UI — agents and people use whichever interface fits.\n\n## Why mtix\n\n**The hierarchy is the briefing.** When an agent picks up `PROJ-42.1.3`, it traverses the parent chain to assemble a complete prompt — business goal from the epic, user story from the feature scope, exact instructions from the issue. No separate documentation, no context windows stuffed with irrelevant files. The tree structure carries the intent.\n\n**Agents decompose, not templates.** A decomposing agent reads the parent's full context and produces children with problem-specific prompts, acceptance criteria, and test specifications. The structure emerges from the problem's complexity — a one-liner gets one subtask, a cross-cutting refactor gets twelve. No predefined shapes imposed.\n\n**Multi-agent orchestration, not just assignment.** Agents register, claim nodes, send heartbeats, and run sessions. mtix tracks who is working on what, detects stalled agents, prevents double-claiming, and auto-recovers from crashes. When ten agents work in parallel, node state and agent state stay consistent.\n\n**Every state change is auditable.** Each transition records who, when, and why — in the same transaction as the data write. An auditor can trace any node's full lifecycle from creation to completion. Built for environments where `DO-178C`, `IEC 62304`, and `NASA-STD-8739.8` apply.\n\n**Single binary, zero infrastructure.** Pure Go, embedded SQLite in WAL mode, embedded web UI. No database server, no container orchestration, no runtime dependencies. Copy one file, run it.\n\n## Features\n\n- **Infinite hierarchy** — Epics, stories, issues, micro issues, and beyond. No depth limit.\n- **Dot-notation IDs** — `PROJ-42.1.3.2` encodes the full parent-child path. No UUIDs needed.\n- **7-state machine** — `open` / `in_progress` / `blocked` / `done` / `deferred` / `cancelled` / `invalidated` with enforced transitions.\n- **Automatic progress rollup** — Child completions propagate to root in a single transaction.\n- **Dependency tracking** — Cross-branch `blocks`, `related`, `duplicates`, `discovered_from` with cycle detection.\n- **Prompt chain propagation** — Parent prompts cascade to children for LLM context assembly.\n- **Multi-agent orchestration** — Agent state tracking, sessions, heartbeats, stale detection.\n- **Agent-native query** — Multi-value filters (`--under A,B --status done,cancelled --type issue`), `--format briefing` for paste-into-context output, `--fields` for JSON projection. No post-processing stub code needed.\n- **CLI-first** — Every operation available via `mtix` CLI with `--json` for machine consumption.\n- **REST API** — Full CRUD, query, and admin endpoints with CSRF protection.\n- **gRPC API** — Protocol Buffers interface for high-performance integrations.\n- **MCP (Model Context Protocol)** — Native tool registration for LLM agent frameworks.\n- **Web UI** — Linear-inspired SPA with keyboard shortcuts (Cmd+K, j/k, c, x), create modal, expandable tree, real-time WebSocket updates.\n- **Single binary** — Pure Go, no CGO, embedded SQLite (WAL mode), embedded web UI.\n- **Export/Import** — JSON export with checksums, merge and replace import modes.\n- **Content integrity** — SHA256 content hashes on every node, full-project verification.\n- **Team sync (BYO Postgres hub)** — Optional event-sourced replication across teammates with LWW convergence, conflict log, hub-unreachable detection, and a `mtix sync daemon` for periodic auto-pull. Local SQLite remains the canonical store on every CLI.\n\n## Why Dot-Notation? The Context Chain\n\nThe dot-notation hierarchy isn't just an ID scheme — it's a **context chain**. Each level encodes a layer of context that flows down to executing agents:\n\n```\nPROJ-1           \"Build user authentication\"              ← business goal\nPROJ-1.3         \"Implement rate limiting for auth\"        ← technical scope\nPROJ-1.3.2       \"Add sliding window counter in window.go\" ← exact instruction\n```\n\nWhen an agent calls `mtix context PROJ-1.3.2`, it receives an **assembled prompt** — a single document built by traversing root to leaf, combining every ancestor's description and prompt. The agent gets the full picture: why the work exists, what constraints apply, and exactly what to implement.\n\nThis is mtix's core design: **the hierarchy IS the briefing.** Parents provide the \"why\" and scope. Children provide the \"what\" — file paths, function names, test cases, edge cases. An LLM agent that reads the assembled context has everything it needs to execute without asking questions.\n\nWhen decomposing tasks, write each child's description to complete this chain. The test: *\"Can an agent execute this task using only the assembled context from root to this node?\"*\n\n## Install\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install hyper-swe/tap/mtix\n```\n\n### Binary Download\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/hyper-swe/mtix/releases), then install (and upgrade) with an unlink-then-copy — **never `cp` over an existing binary**:\n\n```bash\ninstall -m 0755 mtix /usr/local/bin/mtix     # or: rm -f target && cp mtix target\n```\n\nOn macOS, overwriting a binary in place invalidates its cached code\nsignature and every run is killed (`Killed: 9`) — `install(1)`, `rm`+`cp`,\nand `mv` are all safe; Homebrew and `go install` handle this for you. If\n`mtix daemon` runs as a service on the machine, run `mtix daemon start`\nafter upgrading so the service restarts onto the new binary.\n\n### Go Install\n\n```bash\ngo install github.com/hyper-swe/mtix/cmd/mtix@latest\n```\n\n### Claude Code Plugin\n\n```\n/plugin marketplace add hyper-swe/mtix\n/plugin install mtix\n```\n\n### OpenAI Codex\n\n```bash\nmtix plugin install --target codex   # MTIX.md briefing + native pointers + .codex/config.toml\n```\n\nProject-local installs fully regenerate `MTIX.md` and append one pointer in root `CLAUDE.md` and `AGENTS.md`, preserving other user content. Valid old mtix marker blocks migrate; malformed pairs are refused. `HYPERSWE.md` suppresses new pointers and native-file creation; existing pointers remain. Existing MCP config is preserved. Add `--global` for the unchanged global instruction/config install in `~/.codex/`. Details: [MCP Setup Guide](docs/MCP-SETUP.md).\n\n### pi\n\n```bash\nmtix plugin install --target pi      # MTIX.md briefing + AGENTS.md pointer (pi loads it natively)\n```\n\nAdd `--global` for the unchanged global briefing install in `~/.pi/agent/`. pi drives the mtix CLI through its shell tool; for MCP tools the install prints [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) setup guidance. Details: [MCP Setup Guide](docs/MCP-SETUP.md).\n\n## Quick Start\n\n### Build from Source\n\n```bash\n# Prerequisites: Go 1.26+, Node.js 18+ (web UI only)\n\n# Build the complete suite (web UI + Go binary)\nmake build\n\n# Or build components separately:\nmake build-web    # Build React SPA and embed into Go binary\nmake build-go     # Build Go binary only (assumes web assets exist)\n```\n\n### Initialize a Project\n\n```bash\nmkdir my-project && cd my-project\nmtix init --prefix PROJ\n```\n\nThis creates a `.mtix/` directory with config, SQLite database, and generates agent documentation in `.mtix/docs/`.\n\n### Create and Manage Nodes\n\n```bash\n# Create a story\nmtix create \"Build authentication module\" --priority 1 --description \"OAuth2 flow\"\n\n# Create child issues\nmtix create \"Implement login endpoint\" --under PROJ-1\nmtix create \"Add token refresh\" --under PROJ-1\n\n# Decompose into micro issues\nmtix micro \"Validate email format\" --under PROJ-1.1\nmtix micro \"Write unit tests\" --under PROJ-1.1\n\n# View the tree\nmtix tree PROJ-1\n\n# Transition status\nmtix claim PROJ-1.1.1 --agent agent-claude\nmtix done PROJ-1.1.1\n\n# Check progress\nmtix progress PROJ-1\n\n# List all open nodes\nmtix list --status open\n```\n\n### Filtering nodes (multi-value)\n\nEvery filter on `mtix list` and `mtix search` accepts comma-separated values.\nMultiple values within one flag combine with **OR**; multiple flags combine\nwith **AND**. This lets agents narrow large projects down to exactly the\nslice of work they care about in one call.\n\n```bash\n# All done OR cancelled epics under PROJ-1 OR PROJ-2\nmtix list --under PROJ-1,PROJ-2 --status done,cancelled --type epic\n\n# Critical or high priority issues across two assignees\nmtix list --priority 1,2 --type issue --assignee agent-a,agent-b\n\n# Search \"auth\" within two subtrees, restricted to two node types\nmtix search auth --under PROJ-1,PROJ-3 --type story,issue\n\n# JSON output for machine consumption\nmtix list --under PROJ-1 --status done --json\n```\n\nAvailable multi-value filters: `--status`, `--under`, `--type`, `--assignee`,\n`--priority`. All values are sent to SQLite as bound parameters; no\nSQL injection vector.\n\n### Start the Server\n\n```bash\nmtix serve --port 8377\n```\n\nThe web UI is accessible at `http://127.0.0.1:8377`. The REST API is at `/api/v1/`.\n\n### JSON Mode (for LLM Agents)\n\nEvery command supports `--json` for machine-readable output:\n\n```bash\nmtix list --json\nmtix show PROJ-1 --json\nmtix create \"Fix bug\" --under PROJ-1 --json\n```\n\n### Team sync (optional, FR-18)\n\nFor teams of 2–10 developers, an optional **BYO Postgres sync hub**\nreplicates events across CLIs. Every CLI keeps its own local SQLite\nas the canonical store; the hub is a mailroom for events.\n\n```bash\n# Configure the hub DSN (env var preferred over .mtix/secrets)\nexport MTIX_SYNC_DSN=\"postgresql://mtix_sync@hub.example.com:5432/mtix_hub?sslmode=verify-full\"\n\n# One teammate initializes the hub (runs schema migration + registers project)\nmtix sync init\n\n# Everyone else clones (idempotent)\nmtix sync clone\n\n# Daily flow\nmtix sync pull && # ... work ... && mtix sync push\n```\n\nConflicts resolve deterministically by Last-Write-Wins\n(`lamport_clock` → `wall_clock_ts` → `author_machine_hash`).\n`mtix sync conflicts list` and `mtix sync reconcile` cover audit\nvisibility and divergence recovery. For durability across machine\nloss, run `mtix sync daemon` as a systemd / launchd service. See\n[USERMANUAL.md → Team collaboration with sync](USERMANUAL.md#team-collaboration-with-sync-fr-18)\nand [docs/SECURITY-MODEL.md](docs/SECURITY-MODEL.md) for the trust\nmodel.\n\n## Companion Projects\n\n### mgit — Sandboxed version control for autonomous coding agents\n\n[mgit](https://github.com/hyper-swe/mgit) gives a coding agent a safe place to work. It runs the agent's untrusted code (dependency installs, builds, tests) in a disposable per-task microVM with default-deny networking. A compromised package is contained to a throwaway VM, never your host. The agent's work is recorded in an isolated, append-only store separate from your git, and only the reviewed, squashed result is landed. You can roll back or fork from any step.\n\nPaired with mtix, the loop is clean. mtix says *what to do* and carries the context. mgit runs it *safely* and records *what was done*, task-tagged from start to finish. Many agents can work different tasks at once, each in its own sandboxed worktree, without stepping on each other.\n\n```bash\nbrew install hyper-swe/tap/mgit\n```\n\n## Architecture\n\n```\ncmd/mtix/           CLI entry point (Cobra commands)\ninternal/\n  model/            Domain types, state machine, content hashing\n  store/sqlite/     SQLite storage (WAL mode, parameterized queries)\n  service/          Business logic layer\n  api/http/         REST API (Gin) + WebSocket events\n  api/grpc/         gRPC API (Protocol Buffers)\n  mcp/              Model Context Protocol tool registry\n  docs/             Embedded template-based doc generator\n  web/              Embedded SPA (Vite + React + Tailwind)\n  cloud/            Cloud sync (auth, team management)\nproto/              Protocol Buffer definitions\nsdk/python/         Python SDK and gRPC client\nweb/                Web UI source (Vite + React + TypeScript)\ne2e/                End-to-end tests\n```\n\n### Layered Design\n\n```\nCLI / REST / gRPC / MCP\n         |\n    Service Layer      (business logic, validation, events)\n         |\n    Store Interface    (data access contract)\n         |\n    SQLite (WAL mode)  (single binary, no external DB)\n```\n\nAll handlers go through the service layer. The store contains only data access. Model depends on nothing.\n\n## API Endpoints\n\n### REST API (`/api/v1/`)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/nodes` | Create a node |\n| `GET` | `/nodes/:id` | Get a node |\n| `PATCH` | `/nodes/:id` | Update a node |\n| `DELETE` | `/nodes/:id` | Soft-delete a node |\n| `GET` | `/nodes/:id/children` | List children |\n| `POST` | `/nodes/:id/decompose` | Batch create children |\n| `GET` | `/search?q=` | Full-text search |\n| `GET` | `/ready` | Nodes ready for pickup |\n| `GET` | `/blocked` | Blocked nodes |\n| `GET` | `/stale` | Stale nodes |\n| `GET` | `/stats` | Project statistics |\n| `POST` | `/admin/gc` | Run garbage collection |\n| `POST` | `/admin/backup` | Create database backup |\n| `GET` | `/health` | Health check |\n| `GET` | `/ws/events` | WebSocket event stream |\n\nAll mutations require `X-Requested-With: mtix` header (CSRF protection).\n\n### MCP Tools\n\nmtix runs as an MCP server via `mtix mcp`, exposing 38 tools for LLM agents: `mtix_create`, `mtix_context`, `mtix_claim`, `mtix_done`, `mtix_decompose`, `mtix_search`, `mtix_sync_workflow` (for the FR-18 sync hub state-detection + safe-recommendations surface), and more. The most important tool is `mtix_context` — it assembles the full context chain from root to the target node, giving the agent its complete briefing.\n\nSee [MCP Setup Guide](docs/MCP-SETUP.md) for client configuration (Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex, pi).\n\n## CLI Reference\n\n```\nmtix init [--prefix PREFIX]         Initialize a project\nmtix create <title> [--under ID]    Create a node\nmtix micro <title> --under ID       Create a micro issue\nmtix decompose <id> [titles...]     Batch create children\nmtix show <id>                      Show node details\nmtix list [--status S]              List nodes (filters accept comma-separated values)\nmtix tree <id>                      Show hierarchy tree\nmtix update <id> [--title T]        Update node fields\nmtix claim <id> --agent A           Assign to agent\nmtix unclaim <id> --reason R        Unassign from agent\nmtix done <id>                      Mark as done\nmtix defer <id> [--until TIME]      Defer a node\nmtix cancel <id> --reason R         Cancel a node\nmtix reopen <id>                    Reopen done/cancelled node\nmtix comment <id> <text>            Add a comment\nmtix dep add <from> <to>            Add dependency\nmtix search [words...]             Text search: every word must appear in title, description or prompt (filters accept comma-separated values)\nmtix ready                          Show nodes ready for work\nmtix blocked                        Show blocked nodes\nmtix stale                          Show stale nodes\nmtix stats                          Project statistics\nmtix progress <id>                  Show progress rollup\nmtix verify [id]                    Verify content hash integrity\nmtix backup <path>                  Create database backup\nmtix export                         Export to JSON\nmtix import <file> [--mode M]       Import from JSON\nmtix gc                             Run garbage collection\nmtix context <id>                   Assemble context chain (root → node)\nmtix serve [--port P]               Start HTTP/WebSocket server\nmtix mcp [-C DIR]                   Run as MCP server (stdio transport)\nmtix mcp --channel-agent <id>      MCP server + Claude Code channel push (preview)\nmtix daemon                        Origin-independent hook dispatcher (pull + dispatch)\nmtix daemon install|status|start|stop|uninstall   Manage the daemon OS service\nmtix hooks exec-dispatch [mode]    Host-local exec dispatch policy (any|daemon|off)\nmtix -C <dir> <command>            Run any command against another project (git -C)\nmtix docs generate [--force]        Regenerate agent documentation\nmtix config get|set|delete <key>    Manage configuration\n\n# Team sync (FR-18) — optional, opt-in via MTIX_SYNC_DSN\n# The DSN comes from MTIX_SYNC_DSN or .mtix/secrets; positional DSN\n# arguments are no longer accepted.\nmtix sync init                      Provision hub schema + register project\nmtix sync clone                     Pull all events; idempotent rebuild\nmtix sync push                      Drain local pending queue to hub\nmtix sync pull                      Apply new hub events to local SQLite\nmtix sync status                    Show queue + last push/pull + machine_hash\nmtix sync doctor                    Health checks, including hub-triggers and hub-privileges (WARNs by default, exit 0); exit 2 if any fail\nmtix sync conflicts list            Show unresolved contested edits (post-LWW); --all for every row\nmtix sync conflicts resolve <id>    Record a decision for a conflict (changes no node)\nmtix sync reconcile --discard-local|--rename-to|--import-as\n                                    Whole-project divergence escape hatches\n                                    (--discard-local deletes every local ticket:\n                                    run 'mtix sync push' and check pending 0\n                                    first; it then asks for the ticket count at\n                                    a terminal and cannot run unattended)\nmtix sync repair-uids [--dry-run]   One-time hub repair after pushes from a\n                                    client older than v0.5.4-beta (MTIX-92)\nmtix sync daemon [--interval SEC]   Run periodic pull as a long-lived process\nmtix sync backup --output FILE      Wrap pg_dump on every mtix hub table (restore: see the user manual)\n```\n\n## Development\n\n### Run Tests\n\n```bash\nmake test           # Go tests\nmake test-web       # Web tests (Vitest)\nmake test-all       # Both Go and web tests\nmake test-race      # Go tests with race detector\nmake test-cover     # Go tests with coverage report\nmake e2e            # End-to-end tests\n```\n\n### Lint\n\n```bash\nmake lint           # All linters (golangci-lint + ESLint)\nmake lint-go        # Go linters only\nmake lint-web       # ESLint only\n```\n\n### Full Verification (Pre-commit / Pre-release)\n\n```bash\nmake verify         # Race tests + web tests + lint + coverage + build\nmake build-checked  # Run all tests, then build\n```\n\n### Release\n\n```bash\nmake release-patch  # Tag patch version bump (v0.1.0 → v0.1.1)\nmake release-minor  # Tag minor version bump (v0.1.0 → v0.2.0)\n```\n\nVersion is injected from git tags via `-ldflags` at build time.\n\n### Generate Protobuf\n\n```bash\nmake proto-gen\n```\n\n## Configuration\n\nConfiguration lives in `.mtix/config.yaml`:\n\n```yaml\nprefix: PROJ\nmax_depth: 50\nauto_claim: false\nagent_stale_threshold: 30m\nsession_timeout: 8h\ndata:\n  soft_delete_retention: 720h  # 30 days\nprogress:\n  weighted: false\n```\n\nManage via CLI: `mtix config set auto_claim true`\n\n## Documentation\n\n- **[User Manual](USERMANUAL.md)** — Comprehensive guide covering every feature: hierarchy, state machine, dependencies, prompt steering, agent management, REST/gRPC/MCP APIs, backup/export/import, and more.\n- **[MCP Setup Guide](docs/MCP-SETUP.md)** — Configure mtix as an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex, and pi. Includes multi-project setup and context chain usage.\n- **[Security Model](docs/SECURITY-MODEL.md)** — Trust model and threat model for mtix. **Required reading before adopting BYO Postgres mode** for team collaboration. Documents what mtix protects against, what it does not, and the security checklist for adopters.\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n\nCopyright 2025-2026 HyperSWE.\n"}