Run a guided coding session¶
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¶
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:
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.mdis the saved plan — don't also save a plan node.- Capture findings with
hadron_create_node/hadron_update_nodeas you go. - Always end the session with
hadron_end_session, even after/speckit-finalizehas 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. |
Related¶
- Install in Claude Code — connect your agent to Hadron in the first place.
- Install Hadron with the install script —
one-liner for
.mcp.jsonand the Spec Kit extension. - CLI vs. MCP for a coding agent — which surface a coding agent should reach for, compared on the axis that usually decides it.