ratchetai-runner
v0.5.0
Published
Local runner for ratchetAI — drives your own Claude Code / Codex CLI in non-interactive, streamed sessions. Your vendor credentials never leave your machine.
Maintainers
Readme
ratchetai-runner
The local runner for ratchetAI — schedule non-interactive, streamed Claude Code / Codex CLI sessions on the subscriptions you already pay for, and let an orchestrator run the loop within a budget cap while you observe and steer from one inbox.
The runner drives a CLI you have already authenticated on your own machine. Your vendor credentials never leave your computer — ratchetAI never sees your Claude or OpenAI login. The runner only sends session output (and the prompts you choose to run) to your ratchetAI control plane over an authenticated channel.
Requirements
- Node.js >= 20
- An installed, logged-in CLI:
claude(Claude Code) and/orcodex(OpenAI Codex CLI) - A ratchetAI account and a device token (created in the app under Connect a runner)
Connect (daemon mode)
Polls ratchetAI for scheduled / dispatched tasks and executes each one, streaming it back live:
npx ratchetai-runner connect --url https://<your-control-plane> --token rt_...Or set the connection once via environment variables and omit the flags:
export RATCHET_URL=https://<your-control-plane>
export RATCHET_DEVICE_TOKEN=rt_...
npx ratchetai-runner connectRun a single session now
npx ratchetai-runner run --prompt "tidy the changelog and open a PR" --model claude| Command | What it does |
| --- | --- |
| connect | Daemon mode — polls for dispatched/scheduled tasks and streams each session up. --interval <ms> controls the poll cadence. |
| run --prompt <text> | Execute one non-interactive session now and stream it. --model claude\|codex, --title, --cwd. |
Shared options: --url (or RATCHET_URL), --token (or RATCHET_DEVICE_TOKEN), --cwd.
How it works
The runner spawns your CLI in non-interactive mode (claude -p --output-format stream-json /
codex exec --json), parses the streamed events, and posts them to your control plane. Execution and
all file access happen locally, in the working directory you choose. ratchetAI schedules and
observes; your machine does the work.
Disclosure
ratchetAI runs AI agents autonomously within the budget and rules you set. It assists and flags — you decide on anything it escalates.
MIT © SprawlTo
