locus init

Initialize Locus in a GitHub repository. Creates the .locus/ directory, config.json, labels, and project context files.

Initialize Locus in the current GitHub repository. This command sets up the directory structure, configuration, project context templates, GitHub labels, and .gitignore entries needed to use Locus.

Running locus init is idempotent. Re-running it updates the configuration without overwriting user-edited files like LOCUS.md.

Usage

locus init

What It Does

The init command performs these steps in order:

1. Verify git repository -- confirms the current directory is a git repo.

2. Check GitHub CLI -- ensures gh is installed and authenticated.

3. Detect repo context -- reads the GitHub remote to determine owner, repo, and defaultBranch.

4. Create .locus/ directory structure -- creates subdirectories for sessions, discussions, artifacts, plans, and logs.

5. Generate config.json -- writes default configuration with detected GitHub values. On re-init, existing AI, agent, sprint, and logging settings are preserved.

6. Generate LOCUS.md -- creates a template for project context that AI agents read before every task. Skipped if the file already exists.

7. Create .locus/memory/ directory -- creates the structured memory system with category files (architecture.md, conventions.md, decisions.md, preferences.md, debugging.md). If a legacy LEARNINGS.md exists, entries are automatically migrated and the file is deleted.

8. Create GitHub labels -- ensures all Locus labels exist on the repository (priority, type, status, and agent:managed).

9. Update .gitignore -- adds entries for Locus runtime files (config, sessions, logs, worktrees).

Directory Structure

After initialization, the .locus/ directory looks like this:

.locus/
  config.json          # Project configuration (gitignored)
  LOCUS.md             # Project context for AI agents (committed)
  memory/              # Structured memory system (committed)
    architecture.md    # Package ownership, module boundaries, data flow
    conventions.md     # Code style, naming, patterns
    decisions.md       # Trade-off rationale
    preferences.md     # User corrections, rejected approaches
    debugging.md       # Non-obvious gotchas, environment quirks
  sessions/            # REPL session data (gitignored)
  discussions/         # Architectural discussions
  artifacts/           # Generated artifacts
  plans/               # Sprint plans
  logs/                # Execution logs (gitignored)

GitHub Labels

The following labels are created on the repository:

Category	Labels
Priority	p:critical, p:high, p:medium, p:low
Type	type:feature, type:bug, type:chore, type:refactor, type:docs
Status	locus:queued, locus:in-progress, locus:in-review, locus:done, locus:failed
Agent	agent:managed

Prerequisites

• A git repository with a GitHub remote

• GitHub CLI (gh) installed and authenticated (gh auth login)

Examples

# Initialize in the current repo
locus init

# After initialization, edit the project context
vim .locus/LOCUS.md

Next Steps

After initializing:

1. Edit .locus/LOCUS.md to describe your project, tech stack, conventions, and development workflow.

2. Create issues: locus issue create "My first task"

3. Plan a sprint: locus plan "Build feature X"

4. Start coding: locus exec