Skip to content

Getting Started

Prerequisites

  • Python 3.10+
  • At least one supported CLI provider installed and authenticated. See CLI Providers for setup instructions for each.

Installation

pipx install millstone

For local development:

pip install -e .[dev]

For minimal installs by task:

# Tests only
pip install -e .[test]

# Lint/type checks only
pip install -e .[quality]

# Dependency security audit only
pip install -e .[security]

# Packaging/release checks only
pip install -e .[release]

Basic usage

Choose the workflow that matches what you have:

# 1) One task now (no tasklist setup)
millstone --task "add retry logic"

# 2) Existing local backlog file -> migrate once
millstone --migrate-tasklist backlog.md
millstone

# 3) Design -> plan -> execute one objective (skips analyze)
millstone --deliver "Add retry logic"

# 4) New app / fresh repo
millstone --init
millstone --deliver "Build a CLI app for release note generation"

# 5) Full autonomous improvement loop
millstone --cycle

Roadmap-driven flow (no analyze step):

millstone --cycle --roadmap docs/roadmap.md

Run from tasklist directly:

millstone

millstone and millstone -n 1 read tasks from the configured tasklist path (default: .millstone/tasklist.md).

Explore all options:

millstone --help

Scoping remote backlogs

When using a remote tasklist provider millstone delegates reads and writes to the agent's configured MCP server. Add a [millstone.artifacts.tasklist_filter] section to .millstone/config.toml to restrict execution to a specific subset — filter keys are forwarded to the agent as part of the read instruction.

Local tasklist vs remote filters

  • Local .millstone/tasklist.md — best for personal projects, solo maintainers, or when you want explicit control over execution order.
  • MCP provider + filter — best for teams whose backlog lives in a remote service and who want millstone to pull work from the shared board automatically.

Quick example

MCP with Linear — current cycle, millstone label:

[millstone]
tasklist_provider = "mcp"

[millstone.artifacts.tasklist_provider_options]
mcp_server = "linear"

[millstone.artifacts.tasklist_filter]
cycles = ["Cycle 5"]
label  = "millstone"

Omit any key to skip filtering on that dimension. See docs/providers/mcp.md for the full filter reference.

Working directory

millstone creates .millstone/ in your target repository for state, logs, and evaluations.