Integrations

Add Orca Support to Your Agent

For agent makers - how your coding agent runs in Orca today, and what first-class support takes

Overview

A terminal coding agent already runs in Orca: users can add any command as a custom agent, and it gets its own workspace, Git worktree, and terminal. First-class support adds status indicators, notifications, session resume, and usage tracking. This page lists what each needs from your agent.

Works Today: Custom Agents

Users add your agent in Settings → Agents → Add agent → Custom agent… with:

  • Command - how to launch your agent
  • Prompt-only args and Prompt transport - how Orca passes a prompt: as an argument or on stdin
  • Resume args and Fork args - how to reopen or clone a session by its id, if your agent supports it

Document one command that starts your agent, a way to pass the first prompt as an argument or on stdin, and, if you have them, resume and fork flags that take a session id.

Inside a Orca terminal, your agent can read these environment variables:

VariableDescription
ORCA_WORKSPACE_IDThe workspace the terminal belongs to
ORCA_WORKSPACE_PATHPath to the workspace's worktree
ORCA_ROOT_PATHPath to the main checkout of the repository
ORCA_TERMINAL_IDThe terminal the agent runs in

First-Class Support

Built-in agents get more than a terminal. Each feature has a requirement:

FeatureWhat your agent needs
Status (working, needs input, done) and notificationsLifecycle hooks that run a command on session start, prompt submit, tool use, permission request, stop, and session end. Hooks shaped like Claude Code's (hook_event_name, session_id in a JSON payload) are the easiest to support.
Resume after restartA stable session id reported in those hooks, and a flag that reopens a session by id.
Fork sessionA flag that clones a session by id.
Usage historySession logs on disk that record tokens per model, in a documented location and format.
Quota meterA documented way to read the subscription's usage windows.
Model and effort pickersFlags or environment variables that select a model and reasoning effort.

Built-in agent support lives in the Orca repository on GitHub. To request it, open an issue with your agent's install command, its hook and session-id documentation, and where it writes session logs. We review pull requests that add an agent too.

See Supported Agents for where each built-in agent stands today.

On this page