Agent quickstart

This page is written for coding agents such as Cursor, Claude Code and Codex, and for the people who supervise them. It covers what an agent must know to add Trigora to an existing project without breaking recovery: where checkpoints happen, which language forms compile, how to treat side effects, what recovery does not promise, and how to verify it with trigora verify.

The prompt

Paste this into your coding agent. Every docs page also has a Copy page for your agent button under its title.

Add Trigora durable execution to this codebase.

1. Read https://trigora.dev/docs/agent-quickstart/ and https://trigora.dev/llms.txt, then https://trigora.dev/docs/quickstart/ and https://trigora.dev/docs/authoring/supported-semantics/.
2. Inspect the project and choose the matching SDK: TypeScript (@trigora/sdk, Node.js 22 or 24), Python or Rust. Python-only and Rust-only projects do not require Node.js.
3. Write one small Program for an existing long-running task. Put every model, tool and network call inside effect("<literal name>", fn). Effect names and event names must be string literals.
4. Keep durable calls (effect, invoke, waitForEvent, sleep) in the program entry, not in helper functions or closures. Use Promise.all, gather or join only in the forms the structured concurrency docs allow.
5. effect() is not exactly-once for external systems: a crash before the outcome commits can run it again. Pass an idempotency key to any API that charges, sends or writes.
6. Run `trigora verify <program> --faults all --effects fixtures.json`, with a fixture result for every effect key. It crashes the Program after each committed boundary, resumes it, and exits non-zero if the result differs or an effect runs twice or goes missing. Fix any failure before moving on. Then run it with `trigora dev`, kill the process while the execution waits, restart it, and confirm that nothing before the wait runs again.
7. Ask me before choosing Trigora Cloud or Trigora Pulse, before creating a TRIGORA_TOKEN and before running `trigora deploy`. Pulse v1.0.0 is published as ghcr.io/trigora-dev/pulse:1.0.0. It runs the Node adapter on Node.js 22 or 24. `trigora pulse start` starts that host; `trigora start` does not. There is no Python or Rust Pulse adapter. Never print, log or commit secrets.
8. Follow this project's conventions, and tell me what configuration I need to provide.

Machine-readable sources: /llms.txt is the index, /llms-full.txt is the full documentation corpus, and /skills/trigora/SKILL.md is the same guidance as an agent skill file.

Checkpoint boundaries

A durable boundary is a durable operation: effect, waitForEvent / wait_for_event, sleep, or invoke, and in Rust also join and race. At each one the host can commit the Program’s control position and the values it needs to continue. Ordinary assignments between them do not create separate commits. See Durable boundaries.

Durable operations are explicit imports. A local function with the same name is not a durable operation.
Durable operations stay in the program entry. A helper or closure frame cannot perform one; a closure value may live across a wait.
Effect keys and event names are string literals. effect(fn) without a name is rejected.
Keep each effect name stable. A name built from data that changes across a retry creates a second effect instead of a reuse. See Effect identity.

Supported runtime behaviour

Each language is a declared subset. Ordinary computation between durable operations is supported; constructs outside the profile fail at compile time during trigora dev or deployment, and never run under another recovery model.

Read Supported language semantics and Unsupported constructs before restructuring code.
Promise.all, Promise.race, gather, race, and Rust join / race compile only in the forms on Structured concurrency. Promise.any, Promise.allSettled and stored promises do not.
Node.js 22 and 24 are supported for the npm CLI launcher and TypeScript adapter. Python-only and Rust-only projects do not require Node.js. See Install.

Side effects and idempotency

After an effect outcome commits, recovery returns the stored value and does not run the function again. If the process dies after the function started and before the outcome committed, it can run again, and the external system sees that.

Put every model, tool and network call inside a named effect.
For APIs that charge, send or write, pass an idempotency key and keep it in a system that survives retries. Trigora does not provide exactly-once delivery to external systems.
trigora cancel stops an Execution. It does not undo a committed effect; compensate in your own system if you need to.

See Production considerations.

Recovery limits

Recovery restores a continuation instead of replaying the completed prefix. It does not eliminate failures in the systems your effects call, and it is not a general latency guarantee.

Recovery cost scales with live state; see the research limitations.
Waiting Executions stay on the artifact they started with. Deploying a new version does not migrate them. See Artifact pinning.
Inputs, event payloads and results are stored as JSON on the Execution. Keep them small, and never put credentials in them.

Verify recovery

trigora verify is the fastest proof that a Program recovers. It records a healthy baseline run, then crashes the Program after committed boundaries, resumes it, and checks the result against the baseline. It runs in-process on a temporary SQLite host: it does not start trigora dev or contact Trigora Cloud or Pulse.

trigora verify <program> --faults all --effects fixtures.json
trigora verify <program> --faults all --effects fixtures.json --out verify.json

A pass means every tested fault point recovered, the terminal status and result matched the baseline, and no completed effect was repeated or dropped. The verdict is one line, ✔ Recovery verified at every checkpoint.
The command exits non-zero when a recovery fails, the result differs, an effect runs twice or an effect is missing, so it works as a CI gate.
--faults sample, the default, checks up to 8 boundaries. --faults all checks every committed boundary.
A Program with effects is refused without --effects. Prefer a fixtures file, a JSON object of effect key to result, so no real API is called. --effects live runs the real handlers during the baseline; ask before using it on calls that charge, send or write.
--events supplies event payloads; an awaited event with no queued payload receives "ok". Sleeps are fast-forwarded. --input is the same argument vector as trigora start.

trigora bench <program> profiles one healthy run: boundaries committed, checkpoint time, continuation size and restore latency. See Benchmark and verify.

Pulse

Pulse v1.0.0 is the published host, ghcr.io/trigora-dev/pulse:1.0.0, for Linux AMD64 and ARM64. You run the process. Trigora stores the checkpoint.

The Pulse adapter is Node.js 22 or 24. TypeScript authoring elsewhere does not add a Python or Rust Pulse adapter.
trigora pulse start compiles the project and starts the host and adapter. It requires TRIGORA_TOKEN on the host unless --ephemeral is set. It does not create an execution.
trigora start targets local trigora dev or, with --remote, Trigora Cloud. It is not the Pulse start path.
A waiting execution stays on the artifact hash it started with. Keep that artifact running until those executions finish. See Versions.

Prove it with trigora dev

trigora init
trigora dev

Leave trigora dev running and, from another shell, start the Program. While it waits, kill trigora dev, start it again, then send the event. The wait restores from local SQLite and nothing before it runs again.

trigora start <program>
trigora send <execution-id> <event>
trigora executions inspect <execution-id>

Next: Quickstart · Benchmark and verify · Durable operations · How recovery works