Multi-Runtime Support

Perstack supports running Experts through third-party coding agent runtimes. Instead of using the default runtime, you can leverage Cursor, Claude Code, or Gemini CLI as the execution engine.

Why use non-default runtimes?

Your Expert definitions are your assets

In the agent-first era, Expert definitions are the single source of truth — not the runtime, not the app, not the vendor platform. Your carefully crafted instructions, delegation patterns, and skill configurations represent accumulated domain knowledge. They should be:

• Portable — run on any compatible runtime
• Comparable — test the same definition across different runtimes to measure cost vs. performance
• Shareable — publish to the registry and let others run your Experts on their preferred runtime

No vendor lock-in

Agent definitions should not be trapped in vendor silos. With multi-runtime support:

Practical benefits

Supported runtimes

Basic usage

npx perstack run my-expert "query" --runtime cursor
npx perstack run my-expert "query" --runtime claude-code
npx perstack run my-expert "query" --runtime gemini

Runtime selection

How the runtime is determined depends on whether you’re running an Expert directly or delegating to one.

Direct execution (Coordinator Expert)

When running an Expert via CLI, use --runtime to explicitly specify the runtime:

npx perstack run my-expert "query" --runtime cursor

If --runtime is not specified, the Perstack runtime is used by default.

Delegation (Delegate Expert)

When a Coordinator Expert delegates to another Expert, the Coordinator decides which runtime(s) to use by passing the runtime parameter to the delegation tool:

# Coordinator calls delegation tool with:
delegate("code-reviewer", query: "Review this code", runtime: ["cursor", "claude-code"])

The Coordinator should choose from the runtimes declared in the delegate’s runtime field (compatibility declaration). If runtime is not specified, Perstack runtime is used by default.

Example: Meta code review

This example demonstrates running the same Expert across multiple runtimes by specifying the runtime parameter in the delegation call.

Use case: Get code review feedback from both Cursor and Claude Code using identical instructions. Each runtime brings unique capabilities (Cursor’s codebase indexing vs Claude Code’s deep reasoning), producing different insights from the same prompt.

Expert definition

# perstack.toml
 
[experts."code-reviewer"]
runtime = ["cursor", "claude-code"]  # Compatible with both runtimes
description = "Reviews code for quality, security, and best practices"
instruction = """
You are a senior code reviewer. Analyze the codebase and provide feedback on:
- Code quality and maintainability
- Security vulnerabilities
- Performance issues
- Best practices violations
 
Write your review to `{reviewer}-review.md` where {reviewer} is your name
(e.g., cursor, claude).
"""
 
[experts."meta-reviewer"]
# runtime defaults to "perstack"
description = "Aggregates and synthesizes multiple code reviews"
instruction = """
You are a meta-reviewer that orchestrates parallel code reviews.
 
When asked to review code:
1. Delegate to code-reviewer with runtime: ["cursor", "claude-code"] to run on both runtimes in parallel
2. Read all *-review.md files in the workspace
3. Identify common issues raised by multiple reviewers
4. Highlight unique insights from each review
5. Prioritize findings by severity
6. Create a unified action plan in `meta-review.md`
"""
delegates = ["code-reviewer"]

Running the workflow

A single command triggers the entire multi-runtime workflow:

npx perstack run meta-reviewer "Review the src/ directory"

How parallel delegation works

When the meta-reviewer calls the delegation tool with runtime: ["cursor", "claude-code"]:

meta-reviewer (perstack)
        │
        └─► delegate code-reviewer (runtime: ["cursor", "claude-code"])
                    │
                    ├─► cursor-agent --print ──► cursor-review.md
                    │   (same instruction)
                    │
                    └─► claude -p ──► claude-review.md
                        (same instruction)
                    │
                    ▼
            Both reviews collected
                    │
                    ▼
   meta-reviewer reads both files
   and creates unified meta-review.md

The delegation tool accepts an optional runtime parameter:

• Single runtime: runtime: "cursor" — runs on Cursor only
• Multiple runtimes: runtime: ["cursor", "claude-code"] — runs in parallel on both
• Not specified: defaults to "perstack" (built-in runtime)

Why this works

The key insight is that identical instructions produce different results depending on the runtime’s capabilities:

How it works

When you specify a non-default runtime, Perstack:

1. Converts the Expert definition into the runtime’s native format
2. Executes the runtime CLI in headless mode
3. Captures the output and converts events to Perstack format
4. Stores checkpoints in the standard perstack/jobs/ directory

perstack run --runtime <runtime>
        │
        ▼
┌─────────────────────────┐
│   Runtime Adapter       │
│   (converts Expert      │
│    to CLI arguments)    │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Runtime CLI           │
│   (headless mode)       │
│                         │
│   cursor-agent --print  │
│   claude -p "..." --append-system-prompt "..."
│   gemini -p "..."       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Event Normalization   │
│   → Perstack format     │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   perstack/jobs/        │
│   (Job/Run/Checkpoint)  │
└─────────────────────────┘

Runtime-specific setup

Cursor

Prerequisites:

• Cursor CLI installed (curl https://cursor.com/install -fsS | bash)
• CURSOR_API_KEY environment variable set

How Expert definitions are mapped:

• instruction → Passed via cursor-agent --print "..." prompt argument
• skills → ⚠️ Not supported (headless mode has no MCP)
• delegates → Included in prompt as context

Claude Code

Prerequisites:

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Authenticated via claude command

How Expert definitions are mapped:

• instruction → Passed via --append-system-prompt flag
• skills → ⚠️ Not injectable (runtime uses its own MCP config)
• delegates → Included in system prompt as context

Gemini CLI

Prerequisites:

• Gemini CLI installed
• GEMINI_API_KEY environment variable set

How Expert definitions are mapped:

• instruction → Passed via gemini -p "..." prompt argument
• skills → ⚠️ Not supported (MCP unavailable)
• delegates → Included in prompt as context

Limitations

Delegation

Non-default runtimes do not natively support Expert-to-Expert delegation. When using --runtime, delegation behavior depends on the adapter:

With instruction-based delegation, the delegate Expert’s description is included in the system prompt, and the LLM is instructed to “think as” the delegate when appropriate. This is less reliable than native delegation.

Interactive skills

Interactive tools (interactiveSkill) are handled differently:

Checkpoint compatibility

Checkpoints created with non-default runtimes use a normalized format. You can:

• ✅ View checkpoints with perstack start --continue-job
• ✅ Query job history
• ⚠️ Resume may have limitations (runtime-specific state not preserved)

Best practices

1. Start with the default runtime during development for full skill control
2. Design skill-free Experts when targeting non-default runtimes (skill definitions in perstack.toml are ignored)
3. Configure tools in each runtime — set up MCP servers via claude mcp, Cursor settings, etc.
4. Keep delegation simple — non-default runtimes emulate delegation via instruction
5. Leverage built-in capabilities — non-default runtimes have their own file/shell tools

What’s next

• Running Experts — basic CLI usage
• CLI Reference — all options including --runtime
• Skills — MCP tool configuration