Orchestration layer for AI coding agents. File-based ticket management with MCP tools and tmux session management.
Cortex turns your AI coding assistant into a managed development team. An architect agent breaks down work into tickets, spawns worker agents in isolated tmux sessions, reviews their output, and approves changes—all through a kanban-style workflow.
# Install (latest stable)
curl -fsSL https://github.com/kareemaly/cortex/releases/latest/download/install.sh | bash
# Initialize in your project
cd your-project && cortex init
# Start the architect
cortex architectThe architect will guide you through creating and managing tickets.
- tmux - session management
- git - version control
- AI agent (one of):
- Claude CLI - recommended
- OpenCode
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Architect │
│ ├── Creates tickets in backlog │
│ ├── Spawns worker agents for tickets │
│ ├── Reviews completed work │
│ └── Approves → ticket moves to done │
│ │
│ Worker Agent (per ticket) │
│ ├── Runs in isolated tmux window │
│ ├── Implements the ticket │
│ ├── Calls requestReview when done │
│ └── Waits for architect approval │
│ │
└─────────────────────────────────────────────────────────────────┘
Ticket lifecycle: backlog → progress → review → done
| Command | Description |
|---|---|
cortex init |
Initialize project with .cortex/ directory |
cortex architect |
Start or attach to architect session |
cortex project |
Project TUI |
cortex ticket <id> |
Ticket detail view |
cortex daemon status |
Check daemon status |
cortex upgrade |
Refresh embedded defaults |
cortex eject <path> |
Customize a default prompt |
.cortex/cortex.yaml - project-specific settings:
name: my-project
extend: ~/.cortex/defaults/claude-code
architect:
agent: claude # Options: claude, opencode
args: ["--allowedTools", "mcp__cortex__*"]
ticket:
work: # Default implementation workflow
agent: claude
args: ["--permission-mode", "plan"]
debug: # Root cause analysis workflow
agent: opencode # Mix agents per workflow
research: # Read-only exploration workflow
agent: claude
git:
worktrees: false # Enable git worktrees for ticket isolation~/.cortex/settings.yaml - daemon settings:
port: 4200
bind_address: 127.0.0.1 # use 0.0.0.0 for remote VM deployments
log_level: infoUse cortex eject to copy default prompts for customization:
cortex eject ticket/work/SYSTEM.md # Customize ticket workflow
cortex eject architect/SYSTEM.md # Customize architect behaviorEjected prompts go to .cortex/prompts/.
See CONFIG_DOCS.md for full configuration reference.
- Initialize -
cortex initcreates.cortex/with config and ticket storage - Daemon starts -
cortexdlaunches automatically, serves all projects on port 4200 - Architect session - AI agent with MCP tools for ticket management
- Worker sessions - Each ticket gets a dedicated tmux window with scoped MCP tools
- Review cycle - Workers request review, architect approves
The daemon handles:
- Ticket storage (JSON files in
.cortex/tickets/) - Documentation storage (Markdown with YAML frontmatter in
.cortex/docs/) - Tmux session orchestration
- MCP server for AI agents
- SSE events for real-time updates
make build # Build binaries
make lint # Run linter
make test # Run tests
make install # Build and install to ~/.local/bin/See CONTRIBUTING.md for development setup.
Single cortexd daemon serves all projects over HTTP. All clients (CLI, TUI, MCP) communicate through the daemon API—no direct file access. This enables running the daemon on a remote VM with local clients.
┌─────────────────┐
│ cortex CLI/TUI │──┐
└─────────────────┘ │
┌─────────────────┐ │ HTTP :4200 ┌──────────────────────┐
│ MCP Architect │──┼──────────────▶│ cortexd │
└─────────────────┘ │ │ ├─ HTTP API │
┌─────────────────┐ │ │ ├─ Ticket Store │
│ MCP Ticket │──┘ │ ├─ Tmux management │
└─────────────────┘ │ └─ SSE events │
└──────────────────────┘
See CLAUDE.md for detailed architecture and code paths.
MIT