.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.
Substrate is not the Polkadot Substrate blockchain framework. This is a work tracker built specifically for AI coding agents.
Why not a todo list, CLAUDE.md, or GitHub Issues?
Those tools lack two things that matter for agent-driven workflows:State that survives the context window
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.Enforcement at the moment of the action
A
transition_guard returns transition_blocked at the instant of the offending write, with perfectly timed feedback — not after the fact.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
Installation
Install the
substrate binary from a local clone and put it on your PATH.Quickstart
Initialize a
.substrate/, start the inspector, and run your first board in minutes.Connect an Agent
Register the stdio MCP server with your agent runtime and verify the connection.
Author a Workflow
Define boards, stages, fields, and transition gates as versioned JSON.
Substrate v0.7.0 is a pre-release and is not yet published to npm. See the installation guide for instructions on building from source.