Get started

openvibe-codes runs a coding task on whichever agent fits it, hands it to the next one when an agent fails, hits its limit or goes quiet, and keeps the whole run. It runs on your machine with the agents and keys you already have: nothing goes through OpenVibe, and it needs no account.

Install

Node.js 22 or newer, then:

npm install -g https://codeload.github.com/OpenVibers/OpenVibe.Codes/tar.gz/refs/tags/v0.2.0

Or from a clone: git clone https://github.com/OpenVibers/OpenVibe.Codes, npm ci, then node bin/openvibe-codes.js. Check what it found with openvibe-codes agents.

The agents it can use

Install any of them; the harness uses what is there and says why the rest are not.

Agent	What it needs
Claude Code	`claude` on PATH, signed in
Codex	`codex` on PATH, signed in
OpenCode	`opencode` on PATH
Command Code	`cmd` on PATH
Aider	`aider` on PATH
DeepSeek	`DEEPSEEK_API_KEY`; the harness runs its own agent loop against the API
Your own model	`OPENVIBE_CODES_BASE_URL` (an OpenAI-compatible server: llama.cpp, vLLM, Ollama, LM Studio…), `OPENVIBE_CODES_MODEL`, and `OPENVIBE_CODES_API_KEY` if it wants one

Use it

$ openvibe-codes agents
✔ claude-code        Claude Code      ~/.local/bin/claude
✔ codex              Codex            ~/.local/bin/codex
· aider              Aider            `aider` is not on PATH (install Aider)
· deepseek           DeepSeek         set DEEPSEEK_API_KEY

$ cd my-project
$ openvibe-codes run "rename getUser to findUser everywhere"
$ openvibe-codes run --permission read "where is the session cookie set?"
$ openvibe-codes runs
$ openvibe-codes resume run_… "now add a test"

Command	What it does
`agents`	Which agents this machine can run, and why not the others.
`route [--task edit] [--need harness:resume]`	Which agent a task would go to, with the reason for every candidate.
`run [options] "task"`	Run a task. `--agent` skips routing, `--model` picks the first agent's model, `--cwd` sets where it works, `--attempts` caps the hand-offs (default 3), `--no-handoff` stops at the first result, `--json` prints the events. A task of `-` is read from stdin.
`runs`	The latest runs on this machine.
`show <run id> [--json]`	One run: each attempt, its session and the result; every event with --json.
`resume <run id> "follow-up"`	Continue the run's last session with the same agent.

The exit code follows the result: 0 when the last agent finished, 1 when it did not.

Permission levels

Level	What the agent may do
`read`	Look and answer. Claude Code runs in plan mode, Codex in its read-only sandbox, the API agents get only list, read and search tools.
`edit` (default)	Change files in the working directory. Claude Code accepts edits and is refused `git push`; Codex runs in its workspace-write sandbox; the API agents can write and edit files but not run commands.
`full`	Anything, unattended, including running commands. Use it in a container, a VM or a throwaway checkout.

The built-in API agent never leaves the working directory, never reads a .env file and never writes under .git, at any level.

Hand-offs

When an attempt fails, hits a usage limit, crashes or prints nothing for a while, the harness stops it and gives the task to the next agent the router picks, leaving out the ones already tried. The next agent gets a note: the original task, which agent tried and why it stopped, the tools it used, the files it changed, its last message and git status. Every attempt is in the run.

One event format

Every agent's output becomes the same events: one JSON object per line with --json, the same shape as Claude Code's stream-json, ending with exactly one result. Keys and tokens in an agent's output are redacted before an event is printed or kept.

{"type":"system","subtype":"init","agent":"codex","session_id":"0199…","run_id":"run_…"}
{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Bash","input":{"command":"npm test"}}]}}
{"type":"user","message":{"content":[{"type":"tool_result","content":"…","is_error":false}]}}
{"type":"system","subtype":"handoff","from":"codex","reason":"You have hit your usage limit."}
{"type":"result","subtype":"success","is_error":false,"result":"…","total_cost_usd":0.04,"usage":{…}}

Where runs are kept

In $OPENVIBE_CODES_HOME, else $XDG_STATE_HOME/openvibe-codes, else ~/.local/state/openvibe-codes: one directory per run with its attempts and events, readable only by you.

From your own code

const { createHarness } = require('openvibe-codes');

const harness = createHarness();          // your PATH, your keys
for await (const event of harness.run({ prompt: 'fix the failing test', cwd: '.' })) {
    if (event.type === 'result') console.log(event.is_error ? 'failed' : 'done', event.result);
}

harness.agents(), harness.route({ task }) and harness.run({ prompt, cwd, agent, permission, handoff }) are what the command line uses. The router is the same one behind /api/v1/harnesses/route.

What comes next

A hosted runner on OpenVibe.Run workers for people who would rather not run agents themselves, with budgets; OpenVibe.Actor using Codes for its coding work; and Improve OpenVibe as a guided run: pick a repository, describe the change, get a pull request.