mtix — Gerenciador de Micro Issues para Agentes IA
hyper-swe/mtix
Orquestração multi-agente com hierarquia como briefing, auditável e sem infraestrutura
Ver no GitHubSistema de gerenciamento hierárquico de tarefas otimizado para agentes LLM que geram código. Decompõe trabalho em micro issues aninhadas com IDs em notação de ponto (PROJ-42.1.3.2), onde a hierarquia em si funciona como briefing do agente. Disponível via CLI, REST, gRPC, MCP e interface web em tempo real.
Instalação
npx convez-ai hyper-swe/mtix1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenação de múltiplos agentes LLM decompostos em tarefas paralelas com contexto hierárquico
- Rastreamento de micro tarefas em padrões de desenvolvimento dirigido por IA
- Auditoria completa de ciclo de vida de tarefas para padrões críticos de segurança (DO-178C, IEC 62304, NASA-STD-8739.8)
Veredito

mtix é uma ferramenta especializada para times que usam agentes LLM em larga escala: resolve o problema real de orquestração, auditoria e propagação de contexto em hierarchias profundas. Excelente para desenvolvimento dirigido por IA com requisitos de conformidade; overhead desnecessário para projetos simples ou sem múltiplos agentes simultâneos.
README
A tradução para o português deste README ainda está na fila.
mtix
Multi-agent micro issue manager for code-generating LLMs.
mtix (micro-tix) 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.2encodes the full parent-child path. No UUIDs needed. - 7-state machine —
open/in_progress/blocked/done/deferred/cancelled/invalidatedwith enforced transitions. - Automatic progress rollup — Child completions propagate to root in a single transaction.
- Dependency tracking — Cross-branch
blocks,related,duplicates,discovered_fromwith 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 briefingfor paste-into-context output,--fieldsfor JSON projection. No post-processing stub code needed. - CLI-first — Every operation available via
mtixCLI with--jsonfor 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 daemonfor 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.
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://mtix_sync@hub.example.com: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 — Surgical rollback for LLM coding agents
mgit provides task-tagged micro-commits, surgical rollback, and auto-squash for LLM agents. When paired with mtix, agents micro-commit during each task, rollback wrong decisions without losing correct work, and auto-squash on mtix done. mtix handles what to do; mgit handles how to safely do it.
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/)
| Method | Path | Description |
|---|---|---|
POST | /nodes | Create a node |
GET | /nodes/:id | Get a node |
PATCH | /nodes/:id | Update a node |
DELETE | /nodes/:id | Soft-delete a node |
GET | /nodes/:id/children | List children |
POST | /nodes/:id/decompose | Batch create children |
GET | /search?q= | Full-text search |
GET | /ready | Nodes ready for pickup |
GET | /blocked | Blocked nodes |
GET | /stale | Stale nodes |
GET | /stats | Project statistics |
POST | /admin/gc | Run garbage collection |
POST | /admin/backup | Create database backup |
GET | /health | Health check |
GET | /ws/events | WebSocket event stream |
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 [--project DIR] Run as MCP server (stdio transport)
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.