Skip to main content
Run all of the following commands from the root of the project you want to track. Substrate creates its files in a .substrate/ directory at that location — this is the working directory your agent runtime must also use when it spawns the MCP server.
1

Initialize a .substrate/ directory

Create a blank Substrate workspace in your project:
Or start with the bundled web-delivery starter — a ready-made board with a Spec → Plan → Build → Review → QA → Done pipeline and pre-configured gates:
You can also pass a path to a local directory that contains a published workflow definition in place of a template name.
2

Open the local inspector

Start the read-only web inspector to browse your board:
This opens the inspector at http://localhost:7475. If that port is already in use, Substrate scans ports 7475–7499 and prints the URL it actually bound. The board view auto-refreshes within seconds as task state changes.
3

Connect your agent

Register the stdio MCP server with your agent runtime, then ask the agent to call whoami to confirm the connection. Full instructions are in the MCP setup guide.
4

Let the agent work

Once connected, your agent follows this loop:
Every write operation returns an envelope that names the policies that fired. Your agent uses that feedback to stay within the workflow’s rails without any additional prompting.

​
What gets created

After substrate init, your project gains the following structure:
.substrate/
Commit config.json and your boards/ and members/ files. They are your workflow definition — versioned, diffable, and reviewable like any other code.
Workflow definitions travel with git; task state does not. This is deliberate. A fresh clone or a new git worktree starts with an empty database. Read the worktrees and clones guide before you create a worktree — there are sharp consequences if the MCP server resolves to the wrong .substrate/.

​
Next steps

MCP Setup

Register the stdio MCP server and install the agent skill for Claude Code.

How It Works

Understand boards, stages, gates, and the policy envelope in depth.