Orchvia

Orchvia runs Claude Code and Codex agents as a team from your own application: one local engine, with TypeScript and Python SDKs.

• Agents stay warm. Each agent is a long-lived session that keeps its history, so follow-up work reuses it instead of starting over, or forks it to try another direction.
• Nothing is lost or silently repeated. Tasks, messages, approvals and token usage are stored in SQLite before anything runs. After a crash, work whose outcome is unknown waits for you instead of being retried.
• You stay in charge. Your code and the limits you configure decide what runs next, not a manager model. A result counts as done only after a person or a check you registered accepts it.

Quickstart

You need Node.js 22.18 or later, on macOS or Linux. Orchvia uses Node's built-in SQLite, which prints an experimental warning.

git clone https://github.com/masonlee39/orchvia.git
cd orchvia
npm ci --ignore-scripts
node examples/typescript/quickstart.ts

The example uses a fake runtime, so it needs no account and calls no model. It runs two tasks, accepts each result, and the second task reuses the first agent's session:

1. "Draft the release notes": completed, session <id>
2. "Tighten the draft you just wrote": completed, session <id>
The second task reused the first agent's session: true

With real Claude, the same two tasks run on one Claude Code session. You need Claude Code signed in (claude auth login); the example makes two small model calls:

node examples/typescript/quickstart-claude.ts

From Python, the same kind of task runs through a Node host that Python starts:

PYTHONPATH=python/src python3 examples/python/fake_roundtrip.py

To use Orchvia in your own project, install it from npm (Node.js 22.18 or later):

npm install @orchvia/sdk @orchvia/engine @orchvia/adapter-claude

Use @orchvia/adapter-codex for Codex and add @orchvia/cli for a separate host. The Python package orchvia is not on PyPI yet; until it is, build it from source. To let agents edit files, run Codex, or wire the engine into your application, follow the integration guide.

How it compares

Orchvia runs coding agents. It is not a framework for building agents out of model calls, and it can sit next to one.

What it does

• Sessions: open, reuse, fork, compact, pause, resume and stop agents; each keeps its native history.
• Scheduling: dependencies between tasks, queues for busy agents, limits on how many run at once, and no two writers on the same files.
• Messages and handoffs: a durable mailbox between agents; delegation and handoffs that your host approves.
• Acceptance: human review of each result, or verification commands you register.
• Accounting: token usage recorded per task, with cost estimates from prices you register.
• Recovery: after a crash, nothing is resent or marked done by guesswork; you settle unknown outcomes explicitly.
• Routing (optional): a judge you choose, a model or plain rules, proposes which agent takes a request; nothing is submitted without you.

Status

Orchvia is alpha software.

• Tested offline on macOS and Linux, with Node 22 and 24 and Python 3.11 and 3.14.
• The real Claude Code and Codex programs are tested in CI against a scripted local gateway, with no model calls.
• Not verified yet: runs with real models, operating-system sandbox enforcement, Windows, and speed or cost compared with other approaches. Measurements will be published with their raw data.

Status lists what each check covered, the specifications and their evidence.

Documentation

• Integration guide: wire the engine into your application, step by step.
• Reference: installation, the CLI, configuration and handling failures.
• Concepts: the terms these documents use, in plain words.
• Design: why the engine works the way it does.
• Status: what is verified, specifications and evidence.
• Python SDK and contributing.

License

MIT. Third-party SDKs and native runtimes keep their own licenses.