State Management

Perstack automatically saves execution state, enabling continuation and replay.

Checkpoints

Every step creates a checkpoint — a complete snapshot of execution state:

• Message history
• Token usage and cost
• Step number
• Expert info

Checkpoints are stored in perstack/runs/{runId}/. See Runtime for details.

Continuing execution

Use --continue to resume from the latest checkpoint:

npx perstack run my-expert "Initial query"
npx perstack run my-expert "Follow-up query" --continue

The Expert retains message history and processes the new query as a continuation.

Continue a specific run:

npx perstack run my-expert "Follow-up" --continue-run <runId>

Resuming from a checkpoint

Resume from a specific checkpoint to branch execution:

npx perstack run my-expert "query" --resume-from <checkpointId>

Useful for:

• Re-running from a past step
• Trying different approaches
• Debugging

Interactive tool calls

When an interactive skill’s tool is called, execution pauses for user input. Respond with --continue and -i:

npx perstack run my-expert "Initial query"
# Execution pauses at interactive tool call
 
npx perstack run my-expert "User response" --continue -i

The -i flag (or --interactive-tool-call-result) treats the query as the tool call result.

Events

Every state change is recorded as an event in perstack/runs/{runId}/.

Event types:

• startRun / finishRun — run lifecycle
• startGeneration / finishGeneration — LLM calls
• finishStep — step completion
• errorRun — errors

Events enable debugging, monitoring, and analysis. See Runtime for the event notification system.

What’s next

• Error Handling — handling failures gracefully
• Runtime — how state management works