openthrottle

The Node.js 22 CLI for OpenThrottle, a self-hosted pipeline that turns approved plans into reviewed GitHub pull requests with Claude Code, Codex, or OpenCode.

OpenThrottle is pre-production software. Use it for controlled pilots and register only repositories you trust to execute inside the sandbox.

Start here

Install the Fly and Daytona CLIs, authenticate them, then run guided setup:

npx openthrottle setup

Initialize a target repository:

cd your-repository
npx openthrottle init

init installs user-global authoring/operator skills for detected local agents, writes .openthrottle.yml, registers a Linear-team or GitHub-Issue control route, creates the GitHub webhook, and verifies the Daytona snapshot. New Claude and Codex configurations enable automatic implementation admission by default. OpenCode configurations omit that mode and use direct default-graph routing until their structured execution path is supported. Set intents.implement.admission_mode: legacy for direct routing on every engine.

For Linear control, prepare and delegate a plan:

npx openthrottle plan prepare docs/plans/my-change.md
npx openthrottle ship docs/plans/my-change.md
npx openthrottle status

For GitHub-Issue control, an authorized collaborator starts work by applying the exact openthrottle label to an open Issue.

Commands

openthrottle setup [--profile <name>] [--check] [--yes] [--legacy-checklist]
openthrottle init [--profile <name>] [--dry-run]
openthrottle plan validate <file.md>
openthrottle plan prepare <file.md> [--graph <id>]
openthrottle validate <file.md>
openthrottle ship <file.md>
openthrottle status [<ticket>] [--admission]
openthrottle stop <ticket>
openthrottle logs <ticket>
openthrottle analysis [filters]
openthrottle operator-skill <install|status|refresh|remove> [--json]
openthrottle planning-skill <install|status|refresh|remove> [--json]

Key workflows:

• setup provisions and verifies the pinned supervisor and sandbox release. --check is read-only; --profile keeps multiple environments separate.
• init is idempotent. Re-run it to change control provider, base branch, or repository commands. It scaffolds repository-owned implement-plan, admission-plan, and review-admission-plan packages. The planner and reviewer may be edited independently; provenance refreshes include their metadata and references and refuse to overwrite local edits. --dry-run reports refresh classifications without writing or registering. A partial OT_SUPERVISOR_URL/OT_STATUS_TOKEN pair fails closed. Test, lint, and build commands are required because the generated simple graph executes all three.
• plan prepare uses the configured local engine and canonical planning skill; plan validate checks the embedded execution-plan contract.
• status, stop, logs, and analysis call authenticated supervisor endpoints.
• status <ticket> --admission prints the exact accepted automatic plan and reviewer receipt from the same provider-neutral, status-token-protected data used by the list view. Init enables automatic admission by default.

Run npx openthrottle --help for full flag descriptions.

Credentials and local state

Setup profiles live under ~/.openthrottle/profiles/. Generated supervisor secrets and repository setup access are stored separately with owner-only permissions. Operator-owned GitHub, Daytona, Linear, and model credentials are not persisted by the CLI; configure them as Fly secrets.

Common environment variables:

• OT_SUPERVISOR_URL and OT_STATUS_TOKEN for explicit supervisor access;
• DAYTONA_API_KEY for setup;
• LINEAR_API_KEY, LINEAR_TEAM_ID, and OT_AGENT_APP_ID for Linear delegation; and
• OT_FLY_APP, OT_FLY_ORG, and OT_FLY_REGION for resource overrides.

Do not commit local skills, provider credentials, user-global agent configuration, or .env files.

Learn more

Read the project README, security policy, and normative specification.

License

MIT