Skip to content

Run a guided coding session

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 — h-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, h-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 — h-end-session records token counts for every session.

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? h-start-session (the description is the task statement)
2 Gather What do we already know? h-find-nodes, h-read-node
3 Plan What's the approach? h-add-node (a plan-type node) — or under Spec Kit, plan.md
4 Implement Do the work Coding tools, Bash, tests — outside Hadron
5 Capture What did we learn? h-add-node / h-update-node
6 Close Summarise and record h-end-session

Two phase notes:

  • The hadron-client reference mentions h-save-session-task, h-save-plan, and h-resume-session as dedicated tools. They aren't shipped. The task statement lives in the description you pass to h-start-session; the plan lives as either a plan-type node via h-add-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

.hadron/config.json carries a defaultLevel:

Level Behavior
basic Minimal overhead. Sessions are still recorded; the 6 phases are not enforced.
guided The 6 phases are enforced through hooks — the agent prompts you for the next phase if you skip ahead.
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 h-start-session:

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

The tool returns a session ID and a 6-phase protocol hint.

2. Gather context

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

{ "tool": "h-find-nodes", "arguments": { "query": "pagination users endpoint" } }

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

{ "tool": "h-read-node", "arguments": { "loc": "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 plan-type node summarising the approach:

{
  "tool": "h-add-node",
  "arguments": {
    "loc": "sessions:fix-users-pagination:plan",
    "name": "Plan: fix /api/users pagination cutoff",
    "nodeType": "plan",
    "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": "h-add-node",
  "arguments": {
    "loc": "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 h-find-nodes("pagination buffer"), this record surfaces.

6. Close

{
  "tool": "h-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 searchable; the token counts feed usage analytics.

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 h-add-node for a plan node. Memory updates flow through h-add-node / h-update-node directly (or via the speckit.hadron.capture hook), not through a separate h-update-memory step.
  • Always call h-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 h-end-session The session is still open in the database. Future analytics read it as in-progress. Call h-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 h-find-nodes results everywhere Likely no active memory bound, not "the topic isn't covered." Run h-set-active-memory first — most tree tools fall back to the active memory when memoryUrn is omitted.
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.