GitHub - Sangkwun/sandy: Deterministic MCP scenario replay for AI agents — create once, replay without LLM inference

Sandy makes AI agents faster by letting them create and reuse MCP tool call sequences. Once a workflow is saved as a scenario, it replays without LLM inference—saving tokens and time.

What is Sandy?

Sandy is a workflow accelerator for AI agents. When an agent identifies a repeatable workflow, Sandy can:

1. Store the tool call sequence as a scenario
2. Parameterize variable parts (URLs, IDs, search terms)
3. Replay the exact sequence without LLM reasoning

How Agents Use Sandy

Create scenarios: When an agent completes a repeatable workflow, it writes the MCP tool sequence as a scenario JSON file.

Reuse scenarios: On similar requests, the agent finds existing scenarios and replays them instead of reasoning through the steps again.

Judgment: The agent decides when a workflow is worth saving and when to reuse existing scenarios.

Example Flow

User: "Scrape HN top stories and save to database"

Agent (first time):
  1. Executes workflow: navigate → scrape → insert
  2. Recognizes pattern as reusable
  3. Writes scenario to .sandy/scenarios/hn-scrape-to-db.json

User: "Scrape HN again"

Agent (subsequent):
  1. Finds matching scenario
  2. Replays via Sandy
  3. Done—no LLM inference needed

Demo

Watch what Sandy does and how it works:

Installation

As Claude Code Plugin

claude plugin marketplace add Sangkwun/sandy
claude plugin install sandy@sangkwun

That's it. Once installed:

• Use /sandy command to invoke the skill
• Agent can identify repeatable workflows
• Write them as scenario files
• Replay them without LLM inference

Update existing installation:

claude plugin marketplace update sangkwun
claude plugin update sandy@sangkwun

As Standalone CLI

pip install mcp jsonpath-ng python-dotenv
python sandy-skill/scripts/play.py scenario.json --json

Scenario Format

Scenarios are JSON files defining MCP tool sequences:

{
  "version": "2.1",
  "metadata": { "name": "Query Database" },
  "variables": { "LIMIT": "5" },
  "steps": [
    {
      "step": 1,
      "tool": "mcp__supabase__query",
      "params": { "sql": "SELECT * FROM users LIMIT {{LIMIT}}" }
    }
  ]
}

Full schema: See sandy-skill/references/schema.md

Supported Transports

Config Auto-Detection

Sandy finds MCP configuration from:

1. $SANDY_CONFIG environment variable
2. .sandy/config.json (project local)
3. Claude Desktop config
4. Cursor config (~/.cursor/mcp.json)
5. ~/.sandy/config.json (global)

python sandy-skill/scripts/play.py <scenario.json> [options]

Documentation

Cross-Platform Compatibility

Sandy follows the Agent Skills open standard:

Support

If you find Sandy useful, please consider supporting its development!

Your contributions help keep the project maintained and allow me to focus on building new features.

Contributing

Contributions are welcome! Feel free to open issues and pull requests.