GitHub Issues are tasks. Milestones are sprints. Labels track status. Pull Requests are deliverables. No servers. No database. No accounts.

Prerequisites

• Node.js 18+
• GitHub CLI (gh) — authenticated via gh auth login
• An AI provider CLI: Claude Code or Codex
• Docker Desktop 4.58+ for sandboxed execution (optional)

Install

npm install -g @locusai/cli

Quick Start

# Initialize in your GitHub repo
locus init

# Plan a sprint from a goal
locus plan "Build user authentication with OAuth"

# Execute the sprint — agents write code, push commits, open PRs
locus run

# Review the PRs with AI
locus review

# Agents address feedback and update the PRs
locus iterate

How It Works

locus plan "your goal"    →  AI breaks the goal into GitHub Issues with execution order
locus run                 →  Agents execute tasks sequentially, push code, create PRs
locus review              →  AI reviews PRs, posts inline comments on GitHub
locus iterate             →  Agents address review feedback until ready to merge

GitHub IS the backend:

| Concept | GitHub Primitive | |---------|-----------------| | Task | Issue | | Sprint | Milestone | | Status | Labels (locus:queued, locus:in-progress, locus:done, locus:failed) | | Priority | Labels (p:critical, p:high, p:medium, p:low) | | Execution Order | Labels (order:1, order:2, ...) | | Deliverable | Pull Request |

CLI Reference

Setup & Configuration

| Command | Description | |---------|-------------| | locus init | Initialize project with .locus/ structure and GitHub labels | | locus config | View and manage settings | | locus upgrade | Self-upgrade to latest version |

Work Modeling

| Command | Alias | Description | |---------|-------|-------------| | locus issue | locus i | Create, list, show, label, and close GitHub issues | | locus sprint | locus s | Create, list, show, reorder, and close sprints | | locus plan | | AI-powered sprint planning from a goal description |

Execution & Review

| Command | Alias | Description | |---------|-------|-------------| | locus run | | Execute sprint tasks or standalone issues with AI agents | | locus exec | locus e | Interactive REPL or one-shot prompt execution | | locus review | | AI code review on pull requests | | locus iterate | | Re-execute tasks with PR feedback context | | locus discuss | | AI-powered architectural discussions | | locus memory | | List, search, and manage structured project memory | | locus commit | | AI-powered commit message generation |

Visibility

| Command | Description | |---------|-------------| | locus status | Dashboard view of project state | | locus logs | View, tail, and manage execution logs | | locus artifacts | View and manage AI-generated artifacts |

Skills

| Command | Description | |---------|-------------| | locus skills | List available agent skills | | locus skills list | List remote skills from the registry | | locus skills list --installed | List locally installed skills | | locus skills install <name> | Install a skill from the registry | | locus skills remove <name> | Uninstall a skill | | locus skills update [name] | Update all or a specific skill | | locus skills info <name> | Show skill details |

Packages

| Command | Description | |---------|-------------| | locus install <name> | Install a community package from npm | | locus uninstall <name> | Remove an installed package | | locus packages | List installed packages | | locus pkg <name> [cmd] | Run a package-provided command | | locus create <name> | Scaffold a new community package |

MCP Server Management

| Command | Description | |---------|-------------| | locus mcp add <template> | Add a server from a built-in template | | locus mcp add-custom | Add a custom MCP server | | locus mcp remove <name> | Remove an MCP server | | locus mcp list | List configured servers | | locus mcp sync | Sync config to provider-specific formats | | locus mcp test <name> | Test an MCP server connection | | locus mcp status | Show config and provider sync status | | locus mcp enable <name> | Enable a server | | locus mcp disable <name> | Disable a server |

Sandbox Management

| Command | Description | |---------|-------------| | locus sandbox | Create provider sandboxes and enable sandbox mode | | locus sandbox claude | Authenticate Claude inside its sandbox | | locus sandbox codex | Authenticate Codex inside its sandbox | | locus sandbox install <pkg> | Install global npm package(s) in provider sandbox(s) | | locus sandbox shell <provider> | Open an interactive shell in a provider sandbox | | locus sandbox logs <provider> | Show provider sandbox logs | | locus sandbox rm | Destroy provider sandboxes and disable sandbox mode | | locus sandbox status | Show current sandbox state |

Command Details

locus plan

AI-powered sprint planning with plan management:

locus plan "Build OAuth login"              # Generate a plan from a goal
locus plan --sprint "v1.0"                  # Assign planned issues to a sprint
locus plan --from-issues --sprint "v1.0"    # Organize existing issues into a plan
locus plan approve <id> <sprintname>        # Create GitHub issues from a plan
locus plan refine <id> "add rate limiting"  # Refine an existing plan with feedback
locus plan list                             # List saved plans
locus plan show <id>                        # Display a saved plan
locus plan --dry-run                        # Preview without creating issues

locus run

Execute sprint tasks or standalone issues with AI agents:

locus run                        # Run all open sprints (parallel)
locus run --sprint "v1.0"        # Run a specific sprint
locus run 42                     # Run a single issue (in worktree)
locus run 42 43 44               # Run multiple issues in parallel
locus run --resume               # Resume an interrupted run
locus run --dry-run              # Preview what would execute
locus run --model claude         # Override AI model
locus run --no-sandbox           # Run without Docker isolation
locus run --sandbox=require      # Fail if Docker sandbox is unavailable

locus exec

Interactive REPL or one-shot prompt execution:

locus exec                          # Start interactive REPL
locus exec "Add error handling"     # One-shot prompt
locus exec -s <session-id>          # Resume a previous session
locus exec sessions list            # List saved sessions
locus exec sessions show <id>       # Show session details
locus exec sessions delete <id>     # Delete a session
locus exec --json-stream            # NDJSON output for IDE integration

locus commit

AI-powered commit message generation from staged changes:

locus commit                # Generate and commit
locus commit --dry-run      # Preview message without committing
locus commit --model <name> # Override AI model

locus memory

Inspect, search, and manage structured project memory:

locus memory list                        # List all memory entries
locus memory list --category architecture  # Filter by category
locus memory search "auth"               # Search entries by keyword
locus memory stats                       # Show per-category statistics
locus memory reset --confirm             # Clear all entries

locus mcp

Multi-provider MCP server management — configure, sync, and manage MCP servers across AI coding agents:

locus mcp add github                     # Add from built-in template
locus mcp add postgres --name mydb       # Add with custom name
locus mcp add-custom --name api --transport stdio --command node --args server.js
locus mcp remove mydb                    # Remove a server
locus mcp list                           # List configured servers
locus mcp list --json                    # JSON output
locus mcp sync                           # Sync to provider configs
locus mcp sync --provider claude         # Sync to specific provider
locus mcp test mydb                      # Test server connection
locus mcp status                         # Show config and sync status
locus mcp enable mydb                    # Enable a server
locus mcp disable mydb                   # Disable a server

Built-in templates: github, postgres, filesystem, fetch, memory.

locus skills

Discover and install agent skills from a centralized registry:

locus skills                      # List available skills
locus skills install <name>       # Install a skill
locus skills remove <name>        # Uninstall a skill
locus skills update               # Update all installed skills
locus skills info <name>          # Show skill details

Workflows

Sprint: plan, execute, review, iterate

locus plan "Add SSO login and role-based access"
locus run
locus review
locus iterate --sprint

Parallel standalone issues

# Run 3 independent issues concurrently
locus run 42 43 44

Resume a failed run

# Pick up where it left off — completed tasks are skipped
locus run --resume

Interactive coding session

# Start a REPL session
locus exec

# Or one-shot
locus exec "Refactor the auth middleware to use JWT"

Key Flags

| Flag | Description | |------|-------------| | -d, --debug | Debug logging | | -h, --help | Show help | | -V, --version | Show version | | --dry-run | Simulate without executing | | --model <name> | Override AI model | | --resume | Resume interrupted runs | | --sprint <name> | Target a specific sprint | | --from-issues | Use existing issues for planning | | --no-sandbox | Disable Docker isolation | | --sandbox=require | Require Docker (fail if unavailable) | | --json-stream | NDJSON output for IDE integration | | -s, --session-id <id> | Resume a REPL session |

Documentation

Full documentation is available at docs.locusai.dev.

License

MIT