Skip to main content
Substrate is a single binary that you install once and use across projects. There is nothing to sign up for and nothing to configure globally — each project keeps its own state in a local .substrate/ directory. This guide walks you through building from source, linking the binary to your PATH, and installing the agent skill.

​
Requirements

  • Node.js 20 or later
  • macOS or Linux (primary support; Windows is best-effort — WSL is recommended on Windows)
  • A package manager: pnpm is used for the build steps below
Substrate v0.7.0 is a pre-release and is not yet published to npm. Once it is, you will be able to run it directly with npx @diegoferreyra/substrate <command> without any installation steps.

​
Install from source

1

Clone and build

Clone the repository and build the binary from source.
2

Link the binary globally

Add substrate to your PATH by creating a global link.
After this step, the substrate command is available in any directory. When Substrate reaches npm, the equivalent will be npx @diegoferreyra/substrate <command>.
3

Install the agent skill

Copy the packaged agent skill into Claude’s skills directory.
This writes to ~/.claude/skills/substrate and stamps the skill with the binary’s current version. The skill teaches your agent conventions like calling whoami first, using optimistic concurrency, and reading the policy envelope — so you do not have to restate those instructions every session. See MCP setup for details.

​
Verify the installation

Run the help command to confirm substrate is on your PATH and check the reported version:
The output opens with the version line — for example, Substrate v0.7.0 — …. There is no separate --version flag in v0.7.0. Inside any project that already has a .substrate/ directory, you can run a deeper health check:
This prints your environment details and the substrate health status for that project, and exits with a non-zero code if it finds problems.
Run substrate diagnose any time you see unexpected behavior. It is the fastest way to rule out environment and path issues.
If substrate is not found after linking, check that your global pnpm bin directory is on your PATH. Run pnpm bin --global to find the directory and add it to your shell profile if needed.

​
Next steps

Quickstart

Initialize a board in your project and start the local inspector.

Upgrading

Pull the latest source, rebuild, and re-link to upgrade an existing install.