Sessions

Sessions Skill

Use this skill when the task is about how the Synapse plugin itself behaves inside Claude Code: which hooks fire, what they inject into context, how sub-agent sessions are managed, and how to dispatch multiple experiments in parallel to Task sub-agents.

Prompt Boundary

Stay inside this skill when the work is about:

• understanding why Synapse context appeared in the session (which hook injected it)
• debugging a sub-agent that is not behaving as expected (session, heartbeat, or teardown issue)
• deciding how a main agent should dispatch parallel experiment work across sub-agents
• deciding when to call synapse_create_session / synapse_close_session directly instead of relying on hooks

Hand off to:

• experiments for the actual work inside one experiment
• autonomy for the CC-client autonomous loop

Core Rule

For sub-agents spawned through the Task tool, sessions are fully automatic. Do not manually call synapse_create_session or synapse_close_session for a sub-agent unless you are debugging the lifecycle itself. The SubagentStart and SubagentStop hooks already do it.

Plugin Hooks At A Glance

The plugin ships ten hooks wired up in hooks/hooks.json. Each reads/writes local state under .synapse/ in the project and, when needed, calls Synapse MCP tools via the bundled synapse-api.sh wrapper.

Local State Layout

The plugin keeps per-project state under .synapse/ in the project working directory:

• state.json — flock-guarded key/value store. Holds owner info cached from synapse_checkin, agent roles, the primary project UUID, and the session_{…} / agent_for_session_{…} / name_for_agent_{…} mappings used by the start/stop hooks.
• pending/{name} — written by on-pre-spawn-agent.sh, atomically claimed by on-subagent-start.sh via mv.
• claimed/{agent_id} — marker file showing which pending entry was claimed.
• sessions/{name}.json — per-sub-agent session metadata: sessionUuid, agentId, agentName, agentType, sessionAction, createdAt. Other hooks (idle, stop, user-prompt) read from here to locate the session.

on-session-end.sh removes .synapse/ only when it is safe; otherwise state is preserved across sessions so resumed work reconnects to the same Synapse sessions.

MCP Connection Session vs Synapse Agent Session

These are two different things — do not confuse them.

• MCP connection session — the HTTP-streamable session on /api/mcp. Identified by the mcp-session-id header, auto-renewed on every request, expires after 30 minutes of inactivity. The plugin handles this transparently.
• Synapse agent session — a durable record in Synapse of which agent is working on what (the green / yellow / grey indicators on the Settings page). Created/closed by the plugin hooks above, or explicitly by synapse_create_session / synapse_close_session.

Session Status Lifecycle

active ——(no heartbeat 1h)——> inactive ——(heartbeat)——> active
  \                                 \
   \—— close ——> closed ——(reopen)——> active

Session Tools

Running Multiple Experiments In Parallel

When the main agent needs to execute several pending_start experiments concurrently, it should orchestrate, not execute. The plugin does the heavy lifting for session bookkeeping; the main agent only needs to spawn sub-agents and monitor.

Main agent: dispatch

# 1. Refresh and list what needs to run
synapse_checkin()
synapse_get_assigned_experiments({ researchProjectUuid, statuses: ["pending_start"] })

# 2. Inspect each candidate
synapse_get_experiment({ experimentUuid })

# 3. For each experiment, spawn a Task sub-agent with the experiment UUID in the prompt.
#    The SubagentStart hook auto-creates/reuses a Synapse session and injects the
#    execution workflow. The main agent does not need to call synapse_create_session.
Task({
  subagent_type: "general-purpose",
  name: "training-worker-<short>",
  prompt: "Your Synapse experiment UUID: <experiment-uuid>. Run the experiment end to end."
})

Sub-agent: execute

Each sub-agent follows the full execution checklist in experiments: synapse_start_experiment({ sessionUuid }) → synapse_list_compute_nodes / synapse_reserve_gpus → synapse_get_node_access_bundle → run remotely (tmux + unbuffered) → synapse_report_experiment_progress at milestones → synapse_submit_experiment_results({ sessionUuid }) → optional synapse_save_experiment_report.

Main agent: monitor

The main agent does not block on any one sub-agent. After dispatching all sub-agents, it schedules a single Claude Code CronCreate heartbeat that polls Synapse on a cadence — see "Monitoring Long Runs With CronCreate" in the experiments skill for the full pattern. The heartbeat prompt should look like:

CronCreate({
  cron: "*/10 * * * *",
  prompt: "Check Synapse for project <projectUuid>: synapse_get_assigned_experiments({ researchProjectUuid: '<projectUuid>', statuses: ['in_progress', 'completed'] }). For each still-in-progress experiment, synapse_get_experiment + synapse_report_experiment_progress with the latest tmux/log line. Once all have completed, CronDelete this job.",
  recurring: true,
  durable: true,
})

Within each fire of the heartbeat, the iteration looks like:

synapse_get_assigned_experiments({
  researchProjectUuid,
  statuses: ["in_progress", "completed"]
})

# For any experiment still in_progress, read its latest state
synapse_get_experiment({ experimentUuid })

# Once all have completed, synthesize. If this is the assigned autonomous-loop
# agent, propose follow-ups; otherwise use synapse_create_experiment for
# user-directed terminal work.
synapse_propose_experiment({ researchProjectUuid, title, description })

durable: true keeps the heartbeat alive across CC restarts so cards do not go stale just because the user closed their laptop. Always CronDelete once every experiment is completed and synthesis has been written.

Sequential multi-experiment sub-agent

A single sub-agent can also handle multiple experiments in order when dependencies matter:

Task({
  subagent_type: "general-purpose",
  name: "sequential-worker",
  prompt: """
    Synapse experiments, in order (each depends on the previous):
      1. <experiment-uuid-1> — baseline evaluation
      2. <experiment-uuid-2> — ablation built on #1's results

    For each: start_experiment → run → report_progress → submit_results.
  """
})

Project-Level MCP For Sub-Agents

Sub-agents only inherit Synapse MCP access if the MCP server is configured at the project level. Put the config in .mcp.json at the project root (the plugin bundle ships the template at public/synapse-plugin/.mcp.json). User-level-only MCP configs will not reach sub-agents.

Troubleshooting

Reference

• Session and sub-agent reference
• Experiments skill
• Autonomy skill
• Common tools