Getting Started with Locus

Locus is an AI-native project management platform for engineering teams. Plan sprints, manage tasks, and coordinate documentation in the cloud—while AI agents run securely on your machine to build, test, and document your software.

Prerequisites

Node.js: v18 or higher (using npx).
Git: Your project must be a git repository.
Locus Account: You need an API Key from the Locus Cloud dashboard.
AI CLI: Install the provider you plan to use (claude or codex) and ensure it is on your PATH.

Installation

You can install Locus globally:


bash
npm install -g @locusai/cli

Or run it directly using npx:


bash
npx @locusai/cli --help

Quick Start

1. Initialize Locus

Run this command in the root of your existing project to set up the configuration:


bash
locus init

This creates a .locus directory with your project configuration and a CLAUDE.md context file.

2. Index Your Codebase

Before the agent can work effectively, it needs to understand your code. Run the indexer:


bash
locus index

This generates a semantic map of your project that allows the agent to navigate and understand dependencies.

3. Start the Agent

Now you're ready to let the agent work! You'll need your credentials from the web dashboard.


bash
locus run --api-key YOUR_KEY

The agent will:

Connect to the Locus Cloud.
Check for assigned tasks in the backlog.
Pull the next high-priority task.
Execute the work LOCALLY on your machine.
Push changes and report status back to the cloud.

4. Direct Execution (Optional)

If you just want to ask a question or perform a one-off task without using the Locus Cloud:


bash
locus exec "Explain the project structure"

Tip

Use --provider codex to run with Codex instead of Claude.

Detailed Documentation

Now that you have initialized Locus, choose your preferred way of working:

Using with Editors (MCP): Connect Locus mainly with Cursor, Windsurf, or VSCode.
Using Terminal Agent: Run Locus as a standalone background process in your terminal.