field guide · setup

Connect once.
Then never re-explain your project.

5 steps · ~2 minutes · any MCP agent · you never hand-build the tree

Sign in, mint a token

Sign in with GitHub, open Tokens, and create one. The raw value is shown once, so copy it then. Only a hash is stored: a lost token is replaced, never recovered. That page also prints a ready command with your token already in it.

Register the server

One line, and Claude Code registers Heartwood itself. --scope user makes it available in every project and folder. Without it the default local scope binds only to the current directory. After running it, open a fresh Claude Code session — MCP tools load at session start.

quick connect

claude mcp add --transport http --scope user heartwood https://heartwood.wlankabl.com/mcp --header "Authorization: Bearer YOUR_HW_TOKEN"

or wire it by hand in .mcp.json

.mcp.json

{
  "mcpServers": {
    "heartwood": {
      "type": "http",
      "url": "https://heartwood.wlankabl.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_HW_TOKEN" }
    }
  }
}

Let the agent build it

Open a fresh session and paste this. The agent interviews you, then creates the first roots and branches itself. You curate, you do not type nodes.

bootstrap prompt

Capture this project's durable truth as a Heartwood tree.

1. Confirm you can reach the Heartwood MCP server: call list_trees. If that errors, Heartwood is not connected, so tell me and stop here.
2. Call the build_guide tool to load Heartwood's full authoring guide.
3. Follow that guide end to end: choose the right treeId, understand the project, ask me what it needs, and build the tree.

Auto-load your roots

Optional, but it is the whole point. Point a SessionStart hook at your protected core so every new chat loads it first, before any task. In .claude/settings.local.json:

.claude/settings.local.json

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command",
        "command": "curl -s -H \"Authorization: Bearer YOUR_HW_TOKEN\" https://heartwood.wlankabl.com/trees/YOUR_TREE_ID/roots" } ] }
    ]
  }
}

How the tree behaves

Build deepest, most stable truths as roots, details below them. Hardness falls as you go deeper. It is computed server-side from a node's position and load; a proposed number is clamped into the structurally allowed band, never taken at face value.

Changing a hard node is gated: the server shows the cascade it would invalidate, and the change proceeds only on explicit confirmation. Keep volatile data, prices, dates, metrics, versions, out of the tree entirely. The field notes go deeper.