> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# Substrate: Local-First Work Tracker for AI Coding Agents

> Substrate stores boards, tasks, and workflow gates in your repo. Agents read and write over MCP stdio. No accounts, no cloud, no telemetry.

Substrate keeps your development process out of the agent's head and in your repo. You define the process once as data — boards, stages, fields, and gates — and every agent that touches the project reads the same durable state from `.substrate/` and is held to the same rails at write time. It runs as a single binary inside your project: agents read and write boards, tasks, comments, and policies over a stdio MCP server while you watch the same data in a localhost web UI. Everything stays local — a JSON definition of your workflow plus a SQLite database of runtime state.

<Note>
  Substrate is not the Polkadot Substrate blockchain framework. This is a work tracker built specifically for AI coding agents.
</Note>

## Why not a todo list, CLAUDE.md, or GitHub Issues?

Those tools lack two things that matter for agent-driven workflows:

<CardGroup cols={2}>
  <Card title="State that survives the context window" icon="database">
    Harness todo lists evaporate when context resets. CLAUDE.md is durable but unstructured. GitHub Issues lives outside the repo. Substrate's state lives in `.substrate/` — a new session or a second agent reads exactly where work stands.
  </Card>

  <Card title="Enforcement at the moment of the action" icon="shield-check">
    A `transition_guard` returns `transition_blocked` at the instant of the offending write, with perfectly timed feedback — not after the fact.
  </Card>
</CardGroup>

## What Substrate is not

Substrate is **not** a verifier — gates are self-attested. It is **not** a permission system — team membership is descriptive. It is **not** multiplayer or hosted. It is a local-first, repo-resident process tracker that gives agents a shared, structured, enforceable view of work.

## How it works

Your workflow travels with git as committed JSON in `.substrate/boards/`. Runtime task state lives in `.substrate/data.sqlite`, which is gitignored by design. The MCP server (`substrate mcp`) is spawned by your agent runtime as a child process — no port, no daemon, no network connection required.

## Start here

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/getting-started/installation">
    Install the `substrate` binary from a local clone and put it on your PATH.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Initialize a `.substrate/`, start the inspector, and run your first board in minutes.
  </Card>

  <Card title="Connect an Agent" icon="robot" href="/getting-started/mcp-setup">
    Register the stdio MCP server with your agent runtime and verify the connection.
  </Card>

  <Card title="Author a Workflow" icon="pen-to-square" href="/authoring/overview">
    Define boards, stages, fields, and transition gates as versioned JSON.
  </Card>
</CardGroup>

<Info>
  Substrate v0.7.0 is a pre-release and is not yet published to npm. See the [installation guide](/getting-started/installation) for instructions on building from source.
</Info>