lodestar-cli 0.1.1

Agent-native repo orchestration for multi-agent coordination in Git repositories

Lodestar

Agent-native repo orchestration for multi-agent coordination in Git repositories.

Lodestar is a Python CLI tool that enables multiple AI agents (or humans) to work together on tasks in a Git repository without stepping on each other's toes. It provides atomic task claiming with leases, dependency tracking, and inter-agent messaging—all without requiring a central coordinator or human scheduler.

Why Lodestar?

When multiple agents work in the same repository, chaos ensues: duplicate work, merge conflicts, and broken dependencies. Lodestar solves this by providing:

• Task claiming with leases: Agents atomically claim tasks with TTL-based expiration (no daemons required)
• Dependency-aware scheduling: Tasks automatically become available when their dependencies are verified
• Clean Git history: Task definitions live in .lodestar/spec.yaml (committed), while execution state lives in runtime.sqlite (gitignored)
• No central server: Everything runs locally using SQLite for race-free coordination

Key Features

• Multi-Agent Coordination: Multiple agents can work simultaneously without conflicts through atomic task claims
• Lease-Based Claims: Tasks are claimed with time-limited leases that auto-expire, preventing stuck locks
• Two-Plane State Model: Clean separation between task definitions (spec) and execution state (runtime)
• Dependency Tracking: DAG-based task scheduling with automatic readiness detection
• PRD Context Delivery: Tasks carry just-enough product intent from PRDs—frozen excerpts, section refs, and drift detection
• Self-Documenting CLI: Every command supports --json, --schema, and --explain flags for programmatic access
• Progressive Discovery: No-args commands suggest next actions to guide workflows
• Agent Messaging: Built-in inter-agent communication for handoffs and coordination

Installation

Using uv (recommended)

uv add lodestar-cli

Using pip

pip install lodestar-cli

Using pipx (for global install)

pipx install lodestar-cli

Verify the installation:

lodestar --version

Quick Start

Initialize a repository and complete your first task:

# Initialize Lodestar in your Git repository
lodestar init

# Check repository health
lodestar doctor

# Create a task
lodestar task create \
  --id "TASK-001" \
  --title "Set up project structure" \
  --description "Create initial directory layout" \
  --priority 1 \
  --label feature

# Join as an agent
lodestar agent join
# Output: Registered as agent A1234ABCD

# Find available work
lodestar task next

# Claim a task (prevents other agents from taking it)
lodestar task claim TASK-001 --agent A1234ABCD

# Do your work...
# git add, git commit, etc.

# Mark task as done
lodestar task done TASK-001

# Verify completion (unblocks dependent tasks)
lodestar task verify TASK-001

# Delete a task (soft-delete, preserves in spec.yaml)
lodestar task delete TASK-002

# Check status
lodestar status

For development/testing, use uv run lodestar instead of lodestar to run from source.

Architecture Overview

Lodestar uses a two-plane state model that separates concerns:

Plane	Purpose	Location	Git Status
Spec Plane	Task definitions, dependencies, acceptance criteria	.lodestar/spec.yaml	Committed
Runtime Plane	Agent state, leases, heartbeats, messages	.lodestar/runtime.sqlite	Gitignored

This separation provides:

• Clean Git history: No noise from lease claims or heartbeats in version control
• Easy resets: Delete runtime.sqlite to start fresh without losing task definitions
• Reproducibility: Same spec produces same task graph on any machine
• Multi-machine support: Each machine has its own runtime state but shares the task definitions

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     Git Repository                          │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ .lodestar/spec.yaml (committed)                     │    │
│  │  - Task definitions                                 │    │
│  │  - Dependencies (DAG)                               │    │
│  │  - Priorities & labels                              │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ .lodestar/runtime.sqlite (gitignored)               │    │
│  │  - Registered agents                                │    │
│  │  - Active leases (task claims)                      │    │
│  │  - Task status (ready/done/verified)                │    │
│  │  - Inter-agent messages                             │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Tasks flow through states: ready → done → verified. A task becomes claimable when it's ready and all its dependencies are verified. Tasks can also be soft-deleted (status set to deleted) to hide them from normal views while preserving history.

PRD Context Delivery

Tasks can carry product intent from a PRD, so executing agents don't need to re-read the full document:

# Get PRD context for a task
lodestar task context TASK-001

# Create a task with PRD context attached
lodestar task create \
    --id "TASK-002" \
    --title "Implement password reset" \
    --prd-source PRD.md \
    --prd-ref "#password-reset" \
    --prd-excerpt "Reset tokens must expire after 15 minutes..."

When claiming a task, context is delivered automatically. If the PRD has changed since task creation, you'll get a drift warning.

Documentation

Full documentation is available in the docs/ directory:

• Getting Started - Installation and first steps
• Concepts - Architecture and core concepts
  • Two-Plane Model
  • Task Lifecycle
  • Lease Mechanics
  • PRD Context Delivery
• CLI Reference - Complete command documentation
• Guides - How-to guides for common workflows
  • Agent Workflow
  • CI Integration

You can also browse the docs locally:

uv run mkdocs serve

Contributing

Contributions are welcome! This project uses Lodestar for its own task management (dogfooding).

Development Setup

# Clone the repository
git clone https://github.com/lodestar-cli/lodestar.git
cd lodestar

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check src tests
uv run ruff format src tests

# Serve documentation locally
uv run mkdocs serve

Using Lodestar to Contribute

This repository uses Lodestar for task management. To contribute:

1. Run uv run lodestar status to see available work
2. Find tasks with uv run lodestar task next
3. Claim a task before working: uv run lodestar task claim <id> --agent <your-agent-id>
4. Make your changes and commit
5. Mark complete: uv run lodestar task done <id>
6. Verify: uv run lodestar task verify <id>

See CLAUDE.md for detailed development guidelines.

Testing Standards

Before committing, ensure all checks pass:

uv run ruff check src tests          # Linting
uv run ruff format --check src tests # Format check
uv run pytest                        # Tests
uv run mkdocs build                  # Docs build

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• PyPI: lodestar-cli
• Repository: github.com/lodestar-cli/lodestar
• Issues: github.com/lodestar-cli/lodestar/issues
• Documentation: docs/