How it works
Orcacode connects a model to a small set of workspace-aware tools: files, shell, background processes, skills, subagents and MCP servers. The model proposes calls; the host applies policy, approvals, limits and session recording. This page walks it in three steps, each ending with something done. Every command runs as written on orcacode 0.7.0. Orcacode is open source under the Apache License 2.0. The source, issues and releases are on GitHub. 01A prompt
Install one binary, point it at a model, ask it about the repo you are standing in.Your workflow
Standing instructions, skills, MCP servers and sessions you can resume, fork and rewind.Your product
Headless runs for scripts and CI, hooks and plugins around the loop, or the kernel embedded in Rust.The boundary: Orcacode is a terminal host, not a hosted control plane. It runs in your workspace with the permissions of the process you started.
1. A prompt
01. Install
macOS and Linux, one command. It verifies the checksum and writes a single executable to~/.local/bin; Windows, pinning a version and other install locations are on Install & run.
02. Point it at a model
Any one of these works. Flags and environment variables always win over saved settings./models lists the endpoint’s catalog and /settings saves provider, model and key to ~/.config/orcacode/config.json. Details on Providers & models.
03. Ask about the repo you are in
Run it from the repository you want the tools rooted in.--plan makes the first session read-only, so it can explore and propose but not edit or run shell.
--plan and shell, write and edit calls ask first. At the prompt, y allows once, a for the rest of the session, A saves the grant for this workspace (revoke in /settings), n denies. /mode switches between plan, normal, auto and yolo live. Approvals and Plan mode cover the policy behind each.
Check before you act:
--yolo runs every gated tool without asking for the whole session. Start in plan or normal mode unless you intend unattended local actions.2. Your workflow
The second session is where Orcacode stops being a demo. Give it the rules of the repo, the procedures it should follow, and the tools it should reach for. Each of these is one file or one command, and each has its own page.04. Plan on one provider, delegate to others
The parent and its workers do not have to share a provider. One setup: sign in with ChatGPT for the parent, add an OpenRouter key for workers, give each worker tier a model, then start in orchestrate mode so the parent plans and delegates the heavy work.3. Your product
01. Run it unattended
-p runs one prompt and exits. This is a real run in a two-file project, output as printed:
2>/dev/null keeps only the answer. A model that streams its reasoning prints that to stderr as well.
--bare strips instructions, skills, memory, MCP and subagents and limits the tools to read_file,grep,glob, which is what a CI check usually wants. --json emits one NDJSON event per line instead of the transcript: an opening metadata, streaming assistant_delta and reasoning_delta, tool_call, tool_started, tool_finished, tool_result, assistant, usage, result and a closing summary with status, steps and duration. --auto-approve lets shell, write and edit run without a prompt. Headless runs has the scripting rules.
02. Put your own code around the loop
A plugin packages skills, an MCP server and lifecycle hooks in Python or TypeScript. Hooks seebefore_tool, after_tool, before_model and after_model, can deny or rewrite a call, and fail closed: a hook that errors stops the run.
PLUGIN_DATA directory and the handle pattern for stateful runtimes are on Plugins.
03. Embed the kernel
To run the loop inside your own program,orca-harness-sdk composes models, tools, sessions, memory, skills and MCP in Rust; four calls run a session. See Rust SDK.