.sinatrarc

.sinatrarc is a JSON file you commit to the root of a target repo. It controls the engine, model, sandbox setup, hooks, and CI behavior for work Sinatra does in that repo. Every field is optional; the defaults below apply when you omit one.

The canonical JSON Schema is served at https://api.sinatra.dev/sinatrarc/schema. Set it as $schema for editor autocomplete.

Example

{
  "$schema": "https://api.sinatra.dev/sinatrarc/schema",
  "engine": "claude-code",
  "agent": {
    "model": "sonnet",
    "effort": "high",
    "timeout_minutes": 15,
    "max_turns": 20
  },
  "hooks": {
    "before_run": "pnpm install",
    "after_run": "pnpm typecheck",
    "test_command": "pnpm test"
  },
  "sandbox": {
    "snapshot_name": "sinatra-agent",
    "clone_strategy": "full",
    "env": { "FOO": "bar" },
    "setup_commands": {
      "pre_clone": [],
      "post_clone": ["pnpm install"]
    },
    "snapshot": {
      "enabled": false,
      "build_commands": ["pnpm install"],
      "base_image": "node:22"
    }
  },
  "ci": {
    "max_rework": 2
  },
  "planning": {
    "enabled": false
  },
  "brainstorm": {
    "enabled": false
  }
}

Top level

Field	Type	Default	Description
`$schema`	string	none	URL of the JSON Schema, for editor autocomplete.
`engine`	`claude-code` \| `opencode`	`claude-code`	The agent harness. Fixed for the life of a workstream. See Models.

`agent`

Field	Type	Default	Description
`model`	enum	per engine	The model to run. Must belong to the chosen engine. Defaults to `sonnet` on `claude-code` and `anthropic/claude-sonnet-4-6` on `opencode`.
`effort`	`low` \| `medium` \| `high` \| `xhigh` \| `max`	`high`	How hard the model thinks. Clamped to the levels the model supports.
`timeout_minutes`	integer 1 to 60	`15`	Maximum wall-clock time for a single agent turn.
`max_turns`	integer 1 to 100	`20`	Maximum agent iterations before the run stops.

See Models for the model list and per-model effort ranges. agent.model_provider was removed: the provider is now derived from the engine and model, so there is nothing to set. To run an OpenAI model, use engine: opencode with an openai/* model and a connected Codex subscription.

`hooks`

Shell commands run inside the sandbox. All are optional.

Field	Type	When it runs
`before_run`	string	Before the agent starts.
`after_run`	string	After the agent finishes, on success or failure.
`test_command`	string	After the agent succeeds, before the PR opens. It must pass for the PR to open, and Sinatra retries it up to twice.

`sandbox`

Field	Type	Default	Description
`snapshot_name`	string	none	A pre-built snapshot image to start the sandbox from.
`env`	object	none	Environment variables injected into the sandbox.
`setup_commands.pre_clone`	string[]	none	Commands run before the repo is cloned.
`setup_commands.post_clone`	string[]	none	Commands run after the repo is cloned.
`clone_strategy`	`full` \| `blobless`	`full`	`blobless` clones with `--filter=blob:none`, which speeds up the initial clone on large repos by fetching file contents lazily.
`sync_with_base`	boolean	`true`	Before each run, probe whether the working branch conflicts with the repo's default branch. Only a real conflict is handed to the agent to merge and resolve; a behind-but-conflict-free branch is left frozen (GitHub still merges a conflict-free PR). Set `false` to skip the probe entirely. Never rebases or force-pushes.
`snapshot.enabled`	boolean	none	Opt into an auto-built per-repo snapshot that bakes your dependency cache, so cold runs skip a full install.
`snapshot.build_commands`	string[]	none	Override the commands used to warm that snapshot's cache.
`snapshot.base_image`	string	none	Override the base image the snapshot builds from.

`ci`

Field	Type	Default	Description
`max_rework`	integer 0 to 10	`2`	How many times the agent retries a PR after a CI failure before it pauses for a human.

`planning` and `brainstorm`

Both phases are on by default. See How it works for what they do. Set enabled: false to opt out per phase.

Field	Type	Default	Description
`planning.enabled`	boolean	`true`	Turn on the planning phase.
`planning.model`	enum	`agent.model`	Use a different model for planning only. Must run on the chosen engine.
`brainstorm.enabled`	boolean	`true`	Turn on the brainstorming phase.
`brainstorm.model`	enum	`agent.model`	Use a different model for brainstorming only. Must run on the chosen engine.

Per-user overrides

A teammate can override some of the repo's .sinatrarc for their own runs, from their workspace settings, without changing the committed file. Overrides apply only to work that person triggers.

Overridable fields: engine, agent.model, agent.effort, agent.timeout_minutes, agent.max_turns, ci.max_rework, and the planning and brainstorm toggles and models.

Not overridable: hooks and sandbox. These control code execution and the image shape, so they stay with the committed file the whole team shares.

The effective config is the schema defaults, then the committed .sinatrarc, then the user's override, applied in that order.

On this page