Skip to content

Run a guided coding session

MCP onlyIntermediate~15 min

Hadron's guided session pattern is the canonical loop for AI-driven coding work: open a session, gather context, plan, implement, capture findings, close. The pattern produces a durable record of what was done, why, and what was learned — queryable later by you, by other agents, or by your future teammates.

This page is a worked end-to-end example using Claude Code connected to a Hadron MCP server. For the protocol's detailed specification, read the guided-sessions reference in hadron-client after this page.

Why bother

A guided session adds roughly five tool calls to a coding task. In return:

  • The work is auditable — hadron_find_nodes over the session's records reconstructs what you did and why.
  • Findings persist — the next time you (or anyone) hits a similar task, hadron_find_nodes surfaces the prior work as context.
  • Sessions are reviewable — agents reviewing past work get a consistent shape to walk through.
  • Token spend is measurable — pass inputTokens and outputTokens to hadron_end_session and they are recorded on the session. They are optional, so nothing is recorded unless the agent passes them.

If you're doing a one-off, throwaway change, skip it. If you're in a project where institutional memory matters, use it every time.

The six phases

# Phase Question Typical tool
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 (a plan node) — or under Spec Kit, plan.md
4 Implement Do the work Coding tools, Bash, tests — outside Hadron
5 Capture What did we learn? hadron_create_node / hadron_update_node
6 Close Summarise and record hadron_end_session

Two phase notes:

  • The hadron-client reference mentions dedicated tools for saving the task, saving the plan and resuming. Those exist only in hadron-client, as h-save-session-task, h-save-plan and h-resume-session; the hosted Hadron MCP server has no equivalent. On the hosted server the task statement lives in the description you pass to hadron_start_session, and the plan lives as either a node via hadron_create_node, or — under Spec Kit — as plan.md in the feature directory. Resume is implicit — start a fresh session and pass prevSessionId to chain it to the prior one.
  • Phase 4 ("Implement") is outside Hadron by design. The protocol records what you did, not how. Use whatever coding tools your project uses.

Levels: basic, guided, learn

Levels are a hadron-client feature

Levels exist only when your editor reaches Hadron through hadron-client, the local MCP proxy. The hosted Hadron MCP server — what you connect with OAuth in Claude Desktop or Claude Code — has no levels and enforces no phases: there, the phases are a convention you ask your agent to follow. hadron-client's current guided prompt also runs seven phases, adding a Review phase before capture; this page has not caught up with that yet (#306).

In hadron-client, .hadron/config.json carries a defaultLevel:

Level Behavior
basic Minimal overhead. Sessions are still recorded; the phases are not enforced.
guided The phases are enforced through hooks — reading a node is refused until the task has been saved.
learn Same as guided plus structured feedback after every read. Useful for building familiarity with a new codebase.

The level is set per-project; sessions inherit it. Switch by editing .hadron/config.json's defaultLevel field.

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 #142.

Claude calls hadron_start_session:

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

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

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 phase 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. PR #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.

Under Spec Kit

If your project uses Spec Kit, the 6-phase protocol runs alongside Spec Kit's chain (/speckit-specify → /speckit-clarify → /speckit-plan → /speckit-tasks → /speckit-implement → /speckit-finalize), not instead of it. The two are complementary:

  • The 6 phases are bookkeeping markers under Spec Kit. plan.md is the saved plan — don't also call hadron_create_node for a plan node. Memory updates flow through hadron_create_node / hadron_update_node directly (or via the speckit.hadron.capture hook), not through a separate hadron_update_memory step.
  • Always call hadron_end_session at close, even when Spec Kit's /speckit-finalize has run.

The hooks speckit.hadron.recall (at before_specify) and speckit.hadron.capture (at after_plan and after_implement) do the gathering and capturing automatically. You wire them once in .specify/extensions.yml and they fire at the canonical phases.

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 phases Capturing at end-of-session means context has decayed by the time you write. Capture immediately when a non-obvious finding emerges, not at the end. The hooks help under Spec Kit.
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-type node both. Pick one location per artefact. Under Spec Kit, files in specs/<NNN>/ are authoritative.