Agent setup

Agent Setup Guide

Connect Attestack to your AI coding agent in a few minutes. Every integration follows the same pattern:

Install Attestack (attestack + attestack-mcp)
Initialize the repo (attestack init)
Connect the agent (MCP config or session wrapper)
Start a session before agent work (attestack start "…")
Stop and export when done (attestack stop && attestack bundle create)

Quick setup (automated)

From your project root (after cloning or installing Attestack):

# One agent
./scripts/setup-agent.sh cursor

# Several at once
./scripts/setup-agent.sh cursor claude-code windsurf

# MCP binary + repo init only (any agent)
./scripts/setup-agent.sh --init-only

The script will:

Build or locate attestack-mcp
Run attestack init if needed
Write the correct MCP config for each agent
Optionally install Cursor rules (see below)

Session workflow (all agents)

attestack start "fix auth bug"
# … agent work …
attestack stop
attestack bundle create
attestack verify .attestack/bundles/*.attestack.zip

Or use the helper:

./scripts/agent-session.sh start "fix auth bug"
# … agent work …
./scripts/agent-session.sh finish   # stop + bundle create

Cursor

Best for: MCP-native recording inside the editor.

Automated

./scripts/setup-agent.sh cursor

Manual

Build MCP: cargo build --release -p attestack-mcp
Copy examples/agents/cursor/mcp.json → .cursor/mcp.json
Replace /path/to/attestack-mcp with your binary path (or ~/.local/bin/attestack-mcp)
Restart Cursor (or reload MCP)
Optional: copy examples/agents/cursor/rules.mdc → .cursor/rules/attestack.mdc

Before agent work

attestack init
attestack start "feature work"

Ask the agent to use MCP tools: attestack_status, attestack_note, attestack_agent_tool_call, attestack_agent_decision, attestack_snapshot.

Claude Code

Best for: Terminal agent with project-local MCP.

Automated

./scripts/setup-agent.sh claude-code

Manual

Build MCP: cargo build --release -p attestack-mcp
Copy examples/agents/claude-code/mcp.json → .mcp.json in the project root
(or merge into ~/.claude/settings.json under mcpServers)
Add CLAUDE.md snippet from examples/agents/claude-code/CLAUDE.md.snippet
Restart Claude Code

CLI alternative (no MCP)

Wrap your session:

./scripts/agent-session.sh start "claude code session"
claude "implement the billing fix"
./scripts/agent-session.sh finish

Record decisions manually:

attestack agent decision --summary "Used existing JWT middleware"

Claude Desktop

Best for: Desktop app with global MCP.

Automated

./scripts/setup-agent.sh claude-desktop

Writes a config fragment to examples/agents/claude-desktop/generated-config.json and prints where to merge it.

Manual

Open Claude Desktop → Settings → Developer → Edit Config
Merge examples/agents/claude-desktop/mcp.json into mcpServers
Use an absolute path to attestack-mcp
Set ATTESTACK_REPO_ROOT to your project path (or open Claude from that directory)

Config file locations:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Windsurf

Best for: Codeium Windsurf (Cursor-like MCP).

Automated

./scripts/setup-agent.sh windsurf

Manual

Copy examples/agents/windsurf/mcp.json into Windsurf MCP settings
(global: ~/.codeium/windsurf/mcp_config.json, or project MCP UI)
Set absolute attestack-mcp path and ATTESTACK_REPO_ROOT

Same session workflow as Cursor.

VS Code + GitHub Copilot

Copilot does not expose MCP in all setups. Use the CLI wrapper pattern:

Automated

./scripts/setup-agent.sh copilot

Installs .github/copilot-instructions.md (optional) and prints wrapper commands.

Manual workflow

attestack init
attestack start "copilot session"

# Run tests/build through Attestack so commands are recorded
attestack run -- npm test
attestack note "Copilot: refactored auth module"

attestack stop
attestack bundle create

Add examples/agents/copilot/copilot-instructions.md to your repo as .github/copilot-instructions.md so Copilot knows to remind you to record evidence.

Cline (VS Code extension)

Best for: MCP in VS Code.

Automated

./scripts/setup-agent.sh cline

Manual

Open Cline → MCP Servers → Configure
Merge examples/agents/cline/mcp.json
Use absolute attestack-mcp path

Or paste the JSON from examples/agents/cline/mcp.json into Cline’s MCP settings UI.

OpenCode

Best for: Open-source terminal agents with MCP.

Automated

./scripts/setup-agent.sh opencode

Manual

Add examples/agents/opencode/mcp.json to OpenCode’s MCP config (see OpenCode docs for config path)
Set ATTESTACK_REPO_ROOT to the project root

Fallback: use ./scripts/agent-session.sh like Claude Code CLI.

Any agent (shell-only)

No MCP required. Works everywhere:

attestack init
attestack start "manual agent session"

attestack run -- make test          # records command + output metadata
attestack note "Agent reviewed diff"
attestack agent tool-call --tool apply_patch --summary "Updated auth.rs"
attestack snapshot

attestack stop
attestack bundle create

Verify MCP is working

attestack start "mcp test"
attestack status

In the agent, invoke attestack_status (or ask: “call attestack_status MCP tool”). You should see the open session ID.

If MCP fails:

Confirm attestack-mcp is on PATH or path in config is absolute
Confirm ATTESTACK_REPO_ROOT points at an initialized repo (attestack init)
Confirm an open session exists (attestack start "…")
Restart the editor/agent after config changes

What gets recorded

Method	Records
MCP `attestack_note`	Session notes
MCP `attestack_agent_tool_call`	Tool name + optional hashes
MCP `attestack_agent_decision`	Decision summary
MCP `attestack_snapshot`	Git snapshot
`attestack run -- …`	Shell commands + exit codes
`attestack agent …`	AI events from CLI

Raw prompts are not stored by default — only hashes if you use attestack agent prompt --content-hash ….

Next steps

Agent guide — MCP tools and CLI reference
CI integration — record CI runs
Scenarios — end-to-end workflows