# How Locus Works

Locus is a GitHub-native AI engineering CLI. It turns GitHub Issues into code changes by orchestrating AI agents that read your codebase, implement tasks, and open pull requests -- all through the tools you already use.

There is no custom backend, no dashboard, and no separate account. GitHub **is** the backend. Authentication is handled entirely by the GitHub CLI (`gh auth login`).

***

## The Pipeline

Every Locus workflow follows a four-stage pipeline:

{% @mermaid/diagram content="graph LR
A\[Plan] --> B\[Execute]
B --> C\[Review]
C --> D\[Iterate]
D -.->|repeat if needed| C" %}

### 1. Plan

Define what needs to be done. You can create issues manually or let AI generate a structured sprint plan from a high-level directive.

```bash
# AI-generated sprint plan
locus plan "Add user authentication with OAuth"

# Or create issues directly
locus issue create "Add login page" --type feature --priority high
```

Planning produces GitHub Issues with labels for priority, type, and execution order, grouped under a GitHub Milestone (the sprint).

### 2. Execute

AI agents pick up issues and implement them. In sprint mode, tasks run sequentially on a single branch. For standalone issues, tasks run in parallel using git worktrees.

```bash
# Run all open sprints (auto-detected)
locus run

# Run a single issue
locus run 42

# Run multiple issues in parallel
locus run 42 43 44
```

The agent reads the issue description, your project instructions (`LOCUS.md`), accumulated learnings (`.locus/memory/`), and repository context to build a rich prompt. It then delegates to an AI provider (Claude or Codex) that makes the actual code changes.

### 3. Review

Each completed task produces a pull request on GitHub. AI reviews the PR and posts inline feedback.

```bash
locus review
```

### 4. Iterate

If a PR needs changes, Locus reads the review comments and sends them back to the AI agent for a targeted follow-up pass.

```bash
locus iterate 15
```

The agent receives the PR diff and all review comments, then makes focused changes without rewriting code from scratch.

***

## Architecture

{% @mermaid/diagram content="graph TB
subgraph "Your Machine"
CLI\[Locus CLI]
AI\_Claude\[Claude CLI]
AI\_Codex\[Codex CLI]
Sandbox\[Docker Sandbox]
end

```
subgraph "GitHub"
    Issues[Issues]
    Milestones[Milestones]
    Labels[Labels]
    PRs[Pull Requests]
end

CLI -->|orchestrates| AI_Claude
CLI -->|orchestrates| AI_Codex
CLI -->|optional isolation| Sandbox
Sandbox -->|runs| AI_Claude
Sandbox -->|runs| AI_Codex
CLI -->|reads/writes via gh| Issues
CLI -->|reads/writes via gh| Milestones
CLI -->|reads/writes via gh| Labels
CLI -->|reads/writes via gh| PRs" %}
```

**Key points:**

* Locus does not contain an AI model. It orchestrates external AI CLIs (Claude or Codex).
* All state lives in GitHub -- issues, milestones, labels, and PRs.
* Docker sandboxes provide optional isolation for safe execution.
* The `gh` CLI handles all GitHub API communication.

***

## GitHub-Native Data Model

| Locus Concept | GitHub Primitive |
| ------------- | ---------------- |
| Tasks         | Issues           |
| Sprints       | Milestones       |
| Metadata      | Labels           |
| Deliverables  | Pull Requests    |
| Auth          | `gh auth login`  |

There is no database, no API server, and no cloud service. Every operation is a `gh` CLI call.

***

## Context Injection

Before every task, Locus assembles a prompt from multiple sources:

{% @mermaid/diagram content="graph LR
A\[LOCUS.md<br>Project instructions] --> P\[Prompt Builder]
B\[.locus/memory/<br>Categorized learnings] --> P
C\[Issue body + comments<br>Task requirements] --> P
D\[Sprint diff<br>Previous task changes] --> P
E\[File tree<br>Repo structure] --> P
P --> F\[AI Agent]" %}

| Source                | Purpose                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| `LOCUS.md`            | Project instructions, conventions, architecture                                      |
| `.locus/memory/`      | Categorized learnings (architecture, conventions, decisions, preferences, debugging) |
| Issue body + comments | Task requirements and discussion                                                     |
| Sprint diff           | Changes from previous tasks (sprint mode only)                                       |
| Repository file tree  | Structural awareness                                                                 |

**LOCUS.md** is the primary file you edit to teach the AI about your project. It lives at the repository root and is read before every execution.

**`.locus/memory/`** stores lessons learned during development, organized into five category files. Entries are captured automatically after sessions and can be managed via `locus memory`.

***

## Recovery Model

Locus persists execution state to `.locus/run-state/` (one file per sprint) so that interrupted or failed runs can be resumed:

{% @mermaid/diagram content="graph LR
A\[Run starts] --> B\[Task 1: done]
B --> C\[Task 2: failed]
C --> D\[State saved]
D --> E\["locus run --resume"]
E --> F\[Task 2: retry]
F --> G\[Task 3: continue]" %}

If a task fails or the process is interrupted:

```bash
locus run --resume
```

Resume mode picks up at the first failed or pending task. Completed tasks are skipped. On full success, the run state file is cleaned up.

***

## Directory Structure

After initialization, Locus creates a `.locus/` directory in your project root:

```
.locus/
  config.json          # Project configuration (provider, model, sprint settings)
  run-state/           # Active run progress, per-sprint (auto-managed)
  LOCUS.md             # Project instructions for AI agents
  memory/              # Structured memory system (5 category files)
  logs/                # Execution logs
  sessions/            # REPL session history
  worktrees/           # Git worktrees for parallel execution
```

Sensitive files (`config.json`, `run-state/`, `sessions/`, `logs/`, `worktrees/`) are added to `.gitignore` during init. `LOCUS.md` and `.locus/memory/` should be committed so the entire team benefits from accumulated context.

## Related Docs

* [Execution Model](/workflow-deep-dives/execution-model.md)
* [Sprints and Issues](/workflow-deep-dives/sprints-and-issues.md)
* [Built-In Tools](/core-strengths/overview.md)
* [Auto-Approval Mode](/core-strengths/auto-approval-mode.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.locusai.dev/workflow-deep-dives/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.