Skip to content

README.md

Latest commit

 

History

History
325 lines (249 loc) · 11.5 KB

README.md

File metadata and controls

325 lines (249 loc) · 11.5 KB

Locus

GitHub-native AI engineering CLI

Turn GitHub issues into shipped code — plan sprints, execute tasks with AI agents, and iterate on feedback.

GitHub Stars @locusai/cli License Documentation

Documentation · Quick Start · GitHub · Issues

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

Prerequisites

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