MCP Tools Reference

Vreko 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"]
  }
}

---

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?" }
}

---

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"]
  }
}

---

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."
  }
}

---

Coming Soon: Real-Time Intelligence Channel

What It Does

The Channel Server creates a second MCP connection that pushes Vreko intelligence alerts in real-time to your AI coding assistant, rather than requiring manual snap_pulse checks.

Planned Capabilities

• Proactive Risk Warnings: Inline alerts when modifying fragile files (e.g., “⚠️ This file has 85% fragility - previous edits caused 3 violations”)
• Live Session Monitoring: Automatic push notifications for risk detection, snapshot creation, and learning discoveries
• Inline Acknowledgments: New vreko_acknowledge tool to respond to alerts:
  • "acknowledged" - I see the risk
  • "creating_snapshot" - Creating a snapshot before proceeding
  • "proceeding_anyway" - Accept the risk and continue
• Zero Configuration: Runs alongside your existing MCP server with no additional setup

How It Works

Vreko Daemon (vrekod)
         ↓ broadcasts events
Channel Server (vreko mcp --channel)
         ↓ pushes via MCP
Your AI Assistant Session
         ↓ shows inline
Real-time intelligence alerts

Usage Example

Once released, you’ll enable it via .mcp.json:

{
  "mcpServers": {
    "vreko": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@vreko/cli", "mcp", "--stdio", "\${workspacePath}"],
      "instructions": "Use snap_begin, snap_pulse, snap_learn, snap_end for session management."
    },
    "vreko-channel": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@vreko/cli", "mcp", "--channel", "\${workspacePath}"]
    }
  }
}

Or launch Claude Code with:

claude --channels vreko-channel

---

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 vrekod 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.