Turn approved plans into reviewed pull requests with a self-hosted, deterministic agent pipeline.

OpenThrottle connects an approved Linear ticket or labeled GitHub Issue to a fenced coding agent, then carries the result through review, command gates, publication, and provider verification. You keep the supervisor, credentials, policies, and execution environment under your control.

Important

OpenThrottle is pre-production software. Use it for controlled pilots, keep branch protection enabled, and register only repositories you trust to run code inside the sandbox.

Why OpenThrottle

• Plan first. Work begins from an explicit task specification.
• Filesystem-authored behavior. Pipelines, agent instructions, skills, and eval schemas live under .openthrottle/ and compile into one immutable DefinitionBundle.
• Deterministic control plane. The supervisor owns attempts, records, checkpoints, retries, and external effects; agents own reasoning only.
• Agent choice. Claude Code, Codex, and OpenCode receive the same standing instructions, task prompt, and progressively disclosed skill packages.
• Work survives formatting mistakes. Agents return small semantic candidates. Deterministic normalization and bounded same-session correction handle repairable output-shape errors without rerunning completed work.

How it works

Linear ticket or GitHub Issue
        |
        v
signed inbox -> admission -> immutable DefinitionBundle
                                  |
                                  v
                    Attempt -> Result -> Decision
                       |                       |
                  Checkpoint              next Attempt/Effect
                                               |
                                               v
                                      Delivery -> GitHub PR

Every action is pinned to an exact Git subject, request hash, DefinitionBundle hash, lease, and repository authority. inspect actions receive an immutable read-only view plus a bounded executor-authored diff artifact when reviewing an accepted edit. edit actions receive an isolated writable content tree, while Git commits, checkpoint refs, pushes, and publication remain executor-owned.

Quick start

Prerequisites are Node.js 22, Docker, authenticated Fly and Daytona CLIs, and a fine-grained GitHub token. Linear is optional when GitHub Issues are the control surface.

npx openthrottle setup
cd your-repository
npx openthrottle init

On a new Fly volume, setup creates the app, volume, and generated secrets, then deliberately stops before the first deploy. Run the one-shot initializer from the pinned supervisor image, set its emitted OT_EPOCH_BOOTSTRAP_CHECKSUM, and re-run setup; see the fresh-epoch runbook.

init writes .openthrottle/config.yml, creates starter definition directories, installs the global planning/operator skills, registers the repository route, and verifies the runtime snapshot. Commit the definition tree before validation or shipping; compilation always reads exact Git bytes.

Configure every registered GitHub repository to allow squash merging only and set Default commit message to Pull request title. OpenThrottle PR titles include the sealed work-item title and source reference, such as fix(publication): preserve merge identity (OPE-222). Always squash-merge ot/* branches; rebase-merge or fast-forwarding exposes the deliberately generic, epoch-dated checkpoint commit on the base branch instead of the merge-facing PR title. The complete operator flow is in the fresh-epoch runbook.

For Linear control:

npx openthrottle plan prepare docs/plans/my-change.md
npx openthrottle plan validate docs/plans/my-change.md
npx openthrottle ship docs/plans/my-change.md
npx openthrottle status OPE-188
npx openthrottle logs OPE-188
npx openthrottle analysis --run OPE-188

For GitHub Issue control, an authorized collaborator applies the exact openthrottle label to an open Issue in a registered repository.

Useful setup variants:

npx openthrottle setup --check
npx openthrottle setup --profile prod
npx openthrottle init --profile prod

See the CLI guide, automatic-admission runbook, and normative specification for the complete contracts.

Repository layout

Path	Purpose
.openthrottle/	Built-in filesystem definitions used by the factory itself
contracts/	Canonical contracts, compiler, and generated runtime validators
supervisor/	Hono/SQLite control plane deployed on Fly
sandbox/	Daytona action executor and repository authority boundary
skills/	Operator and planning distribution assets
cli/	Published openthrottle npm package
docs/	Normative specification, plans, and runbooks

Security model

Only the repository and model credentials enter an action sandbox. Daytona, Fly, webhook, installation, operator, and publication credentials remain in the supervisor. Signed ingress is bounded before parsing; large immutable evidence is content-addressed; logs are bounded and sanitized.

These controls complement—not replace—GitHub branch protection, least-privilege tokens, review rules, and dependency hygiene. See SECURITY.md.

Development

The repository contains four independent npm projects and intentionally has no root package.json. Start with CONTRIBUTING.md for setup and the full verification suite.

License

OpenThrottle is available under the MIT License.