MCP Tools Reference
SnapBack gives your AI assistant four tools that form a complete session lifecycle. All communication is local — nothing leaves your machine.
| Tool | When to Call | Writes State |
|---|---|---|
snap_begin | Start of every task — before anything else | ✓ Opens session |
snap_pulse | Mid-task health check | ✗ Read-only |
snap_learn | When you discover something worth remembering | ✓ Writes rule |
snap_end | Task complete | ✓ Closes session |
Workflow: snap_begin → [work] → snap_pulse (optional) → snap_learn (as needed) → snap_end
snap_begin — Session Start
Opens a session and loads codebase intelligence your AI doesn’t have yet: fragile files, co-change patterns, past learnings. Safe to call multiple times — resumes an existing session instead of creating a duplicate.
Call this before any other tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
task | string | No | What you’re about to do |
files | string[] | No | Files you plan to modify |
Returns: Session ID, relevant past learnings, fragile file warnings, co-change alerts, risk assessment.
Example:
{
"name": "snap_begin",
"input": {
"task": "Refactor authentication middleware",
"files": ["src/middleware/auth.ts", "src/lib/session.ts"]
}
}First session in a new codebase returns sparse output — that’s normal. Intelligence accumulates with each session.
snap_pulse — Mid-Session Check
Read-only health check. Returns current session vitals, warnings, and co-change gaps. Doesn’t write, learn, or create snapshots.
When to call: After 3+ file changes, before a destructive operation, when you’re uncertain about approach, or before asking the user a clarifying question.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
focus | "risk" | "cochanges" | "vitals" | No | Narrow the response to a specific aspect |
task | string | No | Get a topology-enhanced briefing scoped to this task |
query | string | No | Search past learnings from the knowledge base |
Returns: Session vitals (pulse, pressure, trajectory), active warnings, fragile files touched, co-change gaps.
Example:
{
"name": "snap_pulse",
"input": { "query": "What should I know about the auth middleware?" }
}Use query to retrieve past learnings without calling snap_learn. Read-only — searching never stores anything.
snap_learn — Capture a Rule
Encodes an IF/THEN rule into the workspace knowledge base. Not for general observations — for rules that should surface in future sessions.
Call immediately when: the user corrects an assumption, you find unexpected codebase behavior, or an error reveals an unknown constraint.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
trigger | string | ✓ | The condition. Starts with “when” |
action | string | ✓ | What to do when the trigger fires. Starts with a verb |
files | string[] | No | Files this rule applies to |
type | "pattern" | "pitfall" | "constraint" | "preference" | No | Controls how this surfaces in future briefings |
severity | "info" | "warning" | "critical" | No | critical surfaces in snap_begin even on cold start |
Returns: Confirmation and related learnings already in the knowledge base.
Example:
{
"name": "snap_learn",
"input": {
"trigger": "when modifying token refresh logic in auth.ts",
"action": "snapshot first — this file has 3 rollbacks across 2 sessions",
"type": "pitfall",
"severity": "warning",
"files": ["src/auth/auth.ts"]
}
}Rules start cold. After appearing in 3+ sessions they auto-promote and surface more prominently in briefings.
snap_end — Closing Ceremony
Closes the session and returns a full summary: files modified, snapshots created, learnings captured, coherence score, and carry-forward context for next time.
Call this before your final message to the user.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
outcome | string | ✓ | What you accomplished, what’s incomplete, and decisions made. One paragraph minimum — this becomes the opening context for your next session |
Returns: Session summary with metrics, coherence score, carry-forward items, and AI synthesis (Pro).
Example:
{
"name": "snap_end",
"input": {
"outcome": "Refactored auth middleware to support OAuth2 PKCE. Token refresh is now in src/auth/refresh.ts. Left incomplete: revoke-token endpoint still uses the old pattern. Decided to keep session cookies HTTP-only after security review."
}
}A vague outcome ("done", "completed") produces a sparse briefing next session. Be specific — future sessions start from this context.
Full Session Flow
Start task
→ snap_begin({ task: "...", files: [...] })
→ Read the briefing. Note fragile files and co-change alerts.
During work
→ snap_learn({ trigger: "when...", action: "...", type: "pitfall" }) // when you discover something
→ snap_pulse({ focus: "risk" }) // optional mid-task check
Finish task
→ snap_end({ outcome: "What you did, what's left, decisions made." })
→ Carry-forward items appear in your next snap_begin briefing.Privacy
All MCP communication is local. Your AI assistant talks to snapbackd on your machine via Unix socket (macOS/Linux) or named pipe (Windows). No code is transmitted — only intelligence metadata: patterns, risk scores, warnings, learning IDs.