mtix

Task infrastructure for parallel AI coding agents.

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

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

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

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

mtix (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 humans use whichever interface fits.

Why mtix

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.

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.

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.

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.

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.

Features

• Infinite hierarchy — Epics, stories, issues, micro issues, and beyond. No depth limit.
• Dot-notation IDs — PROJ-42.1.3.2 encodes the full parent-child path. No UUIDs needed.
• 7-state machine — open / in_progress / blocked / done / deferred / cancelled / invalidated with enforced transitions.
• Automatic progress rollup — Child completions propagate to root in a single transaction.
• Dependency tracking — Cross-branch blocks, related, duplicates, discovered_from with cycle detection.
• Prompt chain propagation — Parent prompts cascade to children for LLM context assembly.
• Multi-agent orchestration — Agent state tracking, sessions, heartbeats, stale detection.
• 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.
• CLI-first — Every operation available via mtix CLI with --json for machine consumption.
• REST API — Full CRUD, query, and admin endpoints with CSRF protection.
• gRPC API — Protocol Buffers interface for high-performance integrations.
• MCP (Model Context Protocol) — Native tool registration for LLM agent frameworks.
• Web UI — Linear-inspired SPA with keyboard shortcuts (Cmd+K, j/k, c, x), create modal, expandable tree, real-time WebSocket updates.
• Single binary — Pure Go, no CGO, embedded SQLite (WAL mode), embedded web UI.
• Export/Import — JSON export with checksums, merge and replace import modes.
• Content integrity — SHA256 content hashes on every node, full-project verification.
• 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.

Why Dot-Notation? The Context Chain

The 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:

PROJ-1           "Build user authentication"              ← business goal
PROJ-1.3         "Implement rate limiting for auth"        ← technical scope
PROJ-1.3.2       "Add sliding window counter in window.go" ← exact instruction

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

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

When 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?"

Install

Homebrew (macOS/Linux)

brew install hyper-swe/tap/mtix

Binary Download

Download pre-built binaries from GitHub Releases, then install (and upgrade) with an unlink-then-copy — never cp over an existing binary:

install -m 0755 mtix /usr/local/bin/mtix     # or: rm -f target && cp mtix target

On macOS, overwriting a binary in place invalidates its cached code signature and every run is killed (Killed: 9) — install(1), rm+cp, and mv are all safe; Homebrew and go install handle this for you. If mtix daemon runs as a service on the machine, run mtix daemon start after upgrading so the service restarts onto the new binary.

Go Install

go install github.com/hyper-swe/mtix/cmd/mtix@latest

Claude Code Plugin

/plugin marketplace add hyper-swe/mtix
/plugin install mtix

OpenAI Codex

mtix plugin install --target codex   # AGENTS.md briefing + MCP server in .codex/config.toml

Existing files are never modified — add --global for ~/.codex/. Details: MCP Setup Guide.

pi

mtix plugin install --target pi      # AGENTS.md briefing (pi loads it natively)

pi drives the mtix CLI through its shell tool; for MCP tools the install prints pi-mcp-adapter setup guidance. Details: MCP Setup Guide.

Quick Start

Build from Source

# Prerequisites: Go 1.25+, Node.js 18+ (web UI only)

# Build the complete suite (web UI + Go binary)
make build

# Or build components separately:
make build-web    # Build React SPA and embed into Go binary
make build-go     # Build Go binary only (assumes web assets exist)

Initialize a Project

mkdir my-project && cd my-project
mtix init --prefix PROJ

This creates a .mtix/ directory with config, SQLite database, and generates agent documentation in .mtix/docs/.

Create and Manage Nodes

# Create a story
mtix create "Build authentication module" --priority 1 --description "OAuth2 flow"

# Create child issues
mtix create "Implement login endpoint" --under PROJ-1
mtix create "Add token refresh" --under PROJ-1

# Decompose into micro issues
mtix micro "Validate email format" --under PROJ-1.1
mtix micro "Write unit tests" --under PROJ-1.1

# View the tree
mtix tree PROJ-1

# Transition status
mtix claim PROJ-1.1.1 --agent agent-claude
mtix done PROJ-1.1.1

# Check progress
mtix progress PROJ-1

# List all open nodes
mtix list --status open

Filtering nodes (multi-value)

Every filter on mtix list and mtix search accepts comma-separated values. Multiple values within one flag combine with OR; multiple flags combine with AND. This lets agents narrow large projects down to exactly the slice of work they care about in one call.

# All done OR cancelled epics under PROJ-1 OR PROJ-2
mtix list --under PROJ-1,PROJ-2 --status done,cancelled --type epic

# Critical or high priority issues across two assignees
mtix list --priority 1,2 --type issue --assignee agent-a,agent-b

# Search "auth" within two subtrees, restricted to two node types
mtix search --query auth --under PROJ-1,PROJ-3 --type story,issue

# JSON output for machine consumption
mtix list --under PROJ-1 --status done --json

Available multi-value filters: --status, --under, --type, --assignee, --priority. All values are sent to SQLite as bound parameters; no SQL injection vector.

Start the Server

mtix serve --port 8377

The web UI is accessible at http://127.0.0.1:8377. The REST API is at /api/v1/.

JSON Mode (for LLM Agents)

Every command supports --json for machine-readable output:

mtix list --json
mtix show PROJ-1 --json
mtix create "Fix bug" --under PROJ-1 --json

Team sync (optional, FR-18)

For teams of 2–10 developers, an optional BYO Postgres sync hub replicates events across CLIs. Every CLI keeps its own local SQLite as the canonical store; the hub is a mailroom for events.

# Configure the hub DSN (env var preferred over .mtix/secrets)
export MTIX_SYNC_DSN="postgresql://[email protected]:5432/mtix_hub?sslmode=verify-full"

# One teammate initializes the hub (runs schema migration + registers project)
mtix sync init

# Everyone else clones (idempotent)
mtix sync clone

# Daily flow
mtix sync pull && # ... work ... && mtix sync push

Conflicts resolve deterministically by Last-Write-Wins (lamport_clock → wall_clock_ts → author_machine_hash). mtix sync conflicts list and mtix sync reconcile cover audit visibility and divergence recovery. For durability across machine loss, run mtix sync daemon as a systemd / launchd service. See USERMANUAL.md → Team collaboration with sync and docs/SECURITY-MODEL.md for the trust model.

Companion Projects

mgit — Sandboxed version control for autonomous coding agents

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.

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

brew install hyper-swe/tap/mgit

Architecture

cmd/mtix/           CLI entry point (Cobra commands)
internal/
  model/            Domain types, state machine, content hashing
  store/sqlite/     SQLite storage (WAL mode, parameterized queries)
  service/          Business logic layer
  api/http/         REST API (Gin) + WebSocket events
  api/grpc/         gRPC API (Protocol Buffers)
  mcp/              Model Context Protocol tool registry
  docs/             Embedded template-based doc generator
  web/              Embedded SPA (Vite + React + Tailwind)
  cloud/            Cloud sync (auth, team management)
proto/              Protocol Buffer definitions
sdk/python/         Python SDK and gRPC client
web/                Web UI source (Vite + React + TypeScript)
e2e/                End-to-end tests

Layered Design

CLI / REST / gRPC / MCP
         |
    Service Layer      (business logic, validation, events)
         |
    Store Interface    (data access contract)
         |
    SQLite (WAL mode)  (single binary, no external DB)

All handlers go through the service layer. The store contains only data access. Model depends on nothing.

API Endpoints

REST API (/api/v1/)

All mutations require X-Requested-With: mtix header (CSRF protection).

MCP Tools

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

See MCP Setup Guide for client configuration (Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex, pi).

CLI Reference

mtix init [--prefix PREFIX]         Initialize a project
mtix create <title> [--under ID]    Create a node
mtix micro <title> --under ID       Create a micro issue
mtix decompose <id> [titles...]     Batch create children
mtix show <id>                      Show node details
mtix list [--status S]              List nodes (filters accept comma-separated values)
mtix tree <id>                      Show hierarchy tree
mtix update <id> [--title T]        Update node fields
mtix claim <id> --agent A           Assign to agent
mtix unclaim <id> --reason R        Unassign from agent
mtix done <id>                      Mark as done
mtix defer <id> [--until TIME]      Defer a node
mtix cancel <id> --reason R         Cancel a node
mtix reopen <id>                    Reopen done/cancelled node
mtix comment <id> <text>            Add a comment
mtix dep add <from> <to>            Add dependency
mtix search [--query Q]             Full-text search (filters accept comma-separated values)
mtix ready                          Show nodes ready for work
mtix blocked                        Show blocked nodes
mtix stale                          Show stale nodes
mtix stats                          Project statistics
mtix progress <id>                  Show progress rollup
mtix verify [id]                    Verify content hash integrity
mtix backup <path>                  Create database backup
mtix export                         Export to JSON
mtix import <file> [--mode M]       Import from JSON
mtix gc                             Run garbage collection
mtix context <id>                   Assemble context chain (root → node)
mtix serve [--port P]               Start HTTP/WebSocket server
mtix mcp [-C DIR]                   Run as MCP server (stdio transport)
mtix mcp --channel-agent <id>      MCP server + Claude Code channel push (preview)
mtix daemon                        Origin-independent hook dispatcher (pull + dispatch)
mtix daemon install|status|start|stop|uninstall   Manage the daemon OS service
mtix hooks exec-dispatch [mode]    Host-local exec dispatch policy (any|daemon|off)
mtix -C <dir> <command>            Run any command against another project (git -C)
mtix docs generate [--force]        Regenerate agent documentation
mtix config get|set|delete <key>    Manage configuration

# Team sync (FR-18) — optional, opt-in via MTIX_SYNC_DSN
mtix sync init [DSN]                Provision hub schema + register project
mtix sync clone [DSN]               Pull all events; idempotent rebuild
mtix sync push                      Drain local pending queue to hub
mtix sync pull                      Apply new hub events to local SQLite
mtix sync status                    Show queue + last push/pull + machine_hash
mtix sync doctor                    5 health checks; exit 2 if any fail
mtix sync conflicts list            Show contested edits (post-LWW)
mtix sync conflicts resolve <id>    Override LWW for a specific conflict
mtix sync reconcile --discard-local|--rename-to|--import-as
                                    Whole-project divergence escape hatches
mtix sync daemon [--interval SEC]   Run periodic pull as a long-lived process
mtix sync backup --output FILE      Wrap pg_dump on the 5 mtix-owned tables

Development

Run Tests

make test           # Go tests
make test-web       # Web tests (Vitest)
make test-all       # Both Go and web tests
make test-race      # Go tests with race detector
make test-cover     # Go tests with coverage report
make e2e            # End-to-end tests

Lint

make lint           # All linters (golangci-lint + ESLint)
make lint-go        # Go linters only
make lint-web       # ESLint only

Full Verification (Pre-commit / Pre-release)

make verify         # Race tests + web tests + lint + coverage + build
make build-checked  # Run all tests, then build

Release

make release-patch  # Tag patch version bump (v0.1.0 → v0.1.1)
make release-minor  # Tag minor version bump (v0.1.0 → v0.2.0)

Version is injected from git tags via -ldflags at build time.

Generate Protobuf

make proto-gen

Configuration

Configuration lives in .mtix/config.yaml:

prefix: PROJ
max_depth: 50
auto_claim: false
agent_stale_threshold: 30m
session_timeout: 8h
data:
  soft_delete_retention: 720h  # 30 days
progress:
  weighted: false

Manage via CLI: mtix config set auto_claim true

Documentation

• User Manual — Comprehensive guide covering every feature: hierarchy, state machine, dependencies, prompt steering, agent management, REST/gRPC/MCP APIs, backup/export/import, and more.
• MCP Setup Guide — 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.
• Security Model — 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.

License

Licensed under the Apache License, Version 2.0.

Copyright 2025-2026 HyperSWE.