Skip to content

Run a guided coding session

MCP onlyIntermediate~15 min

When your coding agent fixes a bug or builds a feature, you can have it leave a trail your team can use: it checks Hadron for what you already know before it starts, saves its plan and anything non-obvious it learns, and records the session when it is done. The next person — or agent — to touch the same area finds that work instead of rediscovering it.

There is nothing extra to install. If your agent is connected to Hadron, you start a guided session by asking for one.

What to say to your agent

At the start of a task:

"Start a Hadron session for this task: fix the /api/users pagination cutoff. Before you change any code, search our Hadron memories for anything about pagination and tell me what you found. Save your plan as a node in our engineering memory before you start; if you can't write there, tell me and ask where to save it instead. When you learn something non-obvious, save it as a node too. When we're done, end the session with a one-line summary."

Name the memory you want the plan and findings saved in ("in our eng-notes memory") if you have more than one. Your agent can only save to a memory it can write to. Without the "tell me and ask" clause, an agent that can't write to the memory you named may save the nodes somewhere else, and a memory it can write to may be read by different people.

If your project uses Spec Kit, leave out the "save your plan" sentence: plan.md is the plan. See Under Spec Kit.

If you can reach more than one Hadron App, say which one first ("use the Platform App") — starting a session needs an active App.

The agent tells you what it found in Hadron before it changes any code, gives you a link to each node it saved, and ends the session when the work is done.

The six steps

A guided session is a convention your agent follows, not something Hadron enforces: the hosted Hadron MCP server keeps no phases and checks no order. Asking for the steps by name is what makes them happen.

# Step Question Tool the agent uses
1 Task What are we doing, and why? hadron_start_session (the description is the task statement)
2 Gather What do we already know? hadron_find_nodes, hadron_get_node
3 Plan What's the approach? hadron_create_node — or under Spec Kit, plan.md
4 Implement Do the work Coding tools, tests — outside Hadron
5 Capture What did we learn? hadron_create_node / hadron_update_node
6 Close Summarise and record hadron_end_session
  • Implement is outside Hadron by design. The session records what was done and why, not every edit.
  • To continue earlier work, start a new session and pass the earlier session's id as prevSessionId, so the two are chained.

hadron-client is retired for now

Earlier versions of this page described levels (basic, guided, learn) and dedicated save-task and save-plan tools. Those belonged to hadron-client, a local MCP proxy that is retired for now. Everything on this page uses the hosted Hadron MCP server.

Worked example: fix a bug in Claude Code

A realistic flow. The user pings Claude Code with a bug report; Claude opens a session, gathers context, plans, fixes, captures.

1. Open the session

User: Fix the pagination bug in /api/users — it stops at page 5.
      It's tracked as issue #142.

Claude calls hadron_start_session:

{
  "description": "Fix /api/users pagination cutoff at page 5 (issue #142)",
  "type": "DEVELOPER",
  "repo": "org/project",
  "branch": "main"
}

The tool returns the session ID. The hosted server does not return a phase list — the phases are a convention the agent follows (see The six steps).

2. Gather context

Before reading code, Claude consults Hadron memory — past sessions on pagination, design notes, anything relevant:

{ "tool": "hadron_find_nodes", "arguments": { "query": "pagination users endpoint" } }

A few hits come back. Claude reads the most promising one:

{ "tool": "hadron_get_node", "arguments": { "urn": "hrn:node:acme.com:eng-notes:decisions:pagination-buffer-size" } }

Found: a 2026-Q1 decision to cap the per-request buffer at 500. That's almost certainly the cutoff — five pages of 100. Plausible root cause; worth checking.

3. Plan

Claude writes a node summarising the approach:

{
  "tool": "hadron_create_node",
  "arguments": {
    "urn": "hrn:node:acme.com:eng-notes:sessions:fix-users-pagination:plan",
    "name": "Plan: fix /api/users pagination cutoff",
    "content": "Hypothesis: hardcoded buffer of 500 in api/users.ts caps results at five pages of 100. Plan: (1) confirm the constant, (2) lift it to config or remove, (3) extend the test to fetch page 6, (4) verify on local server. Risk: other callers of the same constant may rely on the cap; grep before changing."
  }
}

Under Spec Kit, this step writes to plan.md instead — the file is the plan. Don't double-write.

4. Implement

Claude does the code work outside Hadron — reads api/users.ts, finds the constant, lifts it to config, writes a test, runs the suite. Standard editor and Bash tool calls.

This step doesn't touch the MCP tool surface. The implementation goes into git as a commit.

5. Capture findings

The fix lands and the test passes. Before closing, Claude saves what was learned:

{
  "tool": "hadron_create_node",
  "arguments": {
    "urn": "hrn:node:acme.com:eng-notes:sessions:fix-users-pagination:findings",
    "name": "Buffer cap was an artefact of an old in-memory store",
    "nodeType": "record",
    "tags": ["pagination", "api", "incident-followup"],
    "content": "The 500-row buffer cap was set when /api/users was an in-memory list. Postgres-backed since 2026-02; the cap is now misleading. Removed the constant, added a test that fetches page 6 to lock the regression."
  }
}

This finding is now searchable. The next time someone runs hadron_find_nodes("pagination buffer"), this record surfaces.

6. Close

{
  "tool": "hadron_end_session",
  "arguments": {
    "id": "019e0659662d7433a109eb2f6e105000",
    "summary": "Removed buffer cap on /api/users. Cap was a stale 2026-Q1 constant. Test added for page 6. Issue #142.",
    "turnCount": 14,
    "errorCount": 0
  }
}

The session is closed. The summary is a label on the session row, shown in your organization's Sessions list in the portal. It is not searchable, and nobody inherits it. If the session is bound to a worker, write what the next session needs in handoff instead — see Teams, workers, and sessions.

Pass prNumber at start only when a pull request already exists: it records a PR number, not an issue number. The agent can also pass inputTokens and outputTokens at close to record what the session cost (see hadron_end_session).

Under Spec Kit

If your project uses Spec Kit, the six steps run alongside Spec Kit's chain (/speckit-specify → /speckit-clarify → /speckit-plan → /speckit-tasks → /speckit-implement → /speckit-finalize), not instead of it:

  • plan.md is the saved plan — don't also save a plan node.
  • Capture findings with hadron_create_node / hadron_update_node as you go.
  • Always end the session with hadron_end_session, even after /speckit-finalize has run.

The Spec Kit Hadron hooks don't run on the hosted server

Spec Kit's Hadron extension hooks — speckit.hadron.recall and speckit.hadron.capture — call hadron-client's tools, so they don't work with the hosted MCP server (spec-kits#85). Ask your agent to gather and capture instead, as above.

When sessions go wrong

Common failure modes:

Symptom What's happening Fix
Forgot to call hadron_end_session The session is still open in the database. Future analytics read it as in-progress. Call hadron_end_session with the session ID. The summary you pass is recorded after the fact.
Findings get lost between steps Capturing at end-of-session means context has decayed by the time you write. Ask the agent to capture immediately when a non-obvious finding emerges, not at the end.
Empty hadron_find_nodes results everywhere The search ran somewhere you didn't expect, not "the topic isn't covered." Search never uses the active memory: with no memory named, it runs under the active scope, the active App's memories, the active organization, or — failing all three — your own user-owned memories. Read the scope line at the top of the result, then name the memory (memoryUrn) or pass allMemories: true. See Search scopes.
Spec Kit and the session feel like duplicate work They're not — the session is bookkeeping, Spec Kit is the workflow. Don't write plan.md and a plan node both. Pick one location per artefact. Under Spec Kit, files in specs/<NNN>/ are authoritative.