.sinatrarc

.sinatrarc is a JSON file you commit to the root of a target repo. You can also name it .sinatrarc.json — handy because editors apply $schema autocomplete to .json files; if both exist, .sinatrarc.json wins. 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"]
    }
  },
  "ci": {
    "max_rework": 2
  },
  "planning": {
    "enabled": true
  },
  "brainstorm": {
    "enabled": true
  }
}

Top level

Field	Type	Default	Description
`$schema`	string	none	URL of the JSON Schema, for editor autocomplete.
`engine`	`claude-code` \| `opencode` \| `oh-my-pi`	`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` and `oh-my-pi`.
`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`	Reserved — no effect today. Runs are capped at 120 minutes.
`max_turns`	integer 1 to 100	`20`	Reserved — no effect today. The agent is not turn-limited.

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, or engine: oh-my-pi with an openai-codex/* model, and a connected Codex subscription.

`hooks`

Shell commands run inside the sandbox. All are optional.

Field	Type	When it runs
`before_run`	string	Reserved — no effect today. Use `sandbox.setup_commands.post_clone` instead.
`after_run`	string	Reserved — no effect today.
`test_command`	string	After the agent succeeds, before the PR opens. Sinatra re-runs the agent to fix failures up to twice; if tests still fail it opens the PR anyway and notes the failure on the ticket.

`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	Not yet enabled on hosted workspaces. Opts into an auto-built per-repo snapshot that bakes your dependency cache.
`snapshot.build_commands`	string[]	none	Not yet enabled on hosted workspaces. Overrides the commands used to warm that snapshot's cache.
`snapshot.base_image`	string	none	Not yet enabled on hosted workspaces. Overrides the base image the snapshot builds from.

The snapshot.* fields configure the auto-built per-repo dependency cache. That feature is not turned on for hosted workspaces yet, so these fields have no effect today. To start from a pre-built image now, set snapshot_name; to speed up the initial clone on a large repo, set clone_strategy to blobless.

`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