Orca Agent

Orca Agent is a DeepSeek-native coding agent for your terminal.

Give Orca Agent a task and it reads code, edits files, runs commands, verifies the
result, and keeps working until the task is done or it needs you. Use the TUI
for interactive work or orca exec for scripts and CI. Orca is built in Rust,
runs locally, and is MIT licensed.

English · 简体中文 · 日本語 · Tiếng Việt · 한국어 · Español · Português

Naming. Orca Agent is unrelated to other projects named "Orca", including the stablyai/orca desktop agent orchestrator, Plotly's orca package, and the GNOME Orca screen reader. This repository is the DeepSeek-native terminal coding agent at orcaagent.dev.

Website · Changelog · Releases · npm

Orca Agent's first run: trust the workspace, then enter a DeepSeek API key

Install

npm install -g @blade-ai/orca

Or install the native binary directly:

curl -fsSL https://orcaagent.dev/install.sh | sh

On Windows PowerShell:

irm https://orcaagent.dev/install.ps1 | iex

From a project directory, provision its restricted sandbox capability with:

& ([scriptblock]::Create((irm https://orcaagent.dev/install.ps1))) -SetupSandbox

The npm package supports macOS, Linux, and Windows on ARM64 and x64. Prebuilt
archives are also available from GitHub Releases.

Orca checks HTTPS certificates against the operating system's trust store, so a
company proxy's CA works once it is installed there. A minimal Linux system, such
as a slim container image, needs the ca-certificates package: with no CA
certificates at all, Orca cannot make any network request, plain HTTP included.
Configuration covers SSL_CERT_FILE
and SSL_CERT_DIR.

On Windows, Orca prefers PowerShell 7 and detects its standard installation
path even when it is absent from PATH. Restricted sessions fall back to
cmd.exe when PowerShell 7 is unavailable. Windows PowerShell 5.1 remains an
explicit option only for modes that do not require AppContainer isolation.
Protocol command arrays are launched as native Windows argv without shell
re-parsing; legacy string commands use the resolved shell dialect.

Use

export DEEPSEEK_API_KEY=sk-...

orca                                      # open the terminal UI (Full Access by default)
orca --yolo                               # start with Full Access (full-auto)
orca --yolo --continue                    # resume the latest session with Full Access
orca exec "fix the failing test"          # run headlessly
orca exec --yolo "finish the task"        # run headlessly with Full Access
printf '%s' "$INSTRUCTION" | orca exec   # keep arbitrary prompt text out of argv
orca exec --verifier "cargo test" "fix it" # verify before finishing
orca exec resume SESSION_ID "continue"    # resume a headless session
orca exec resume --last "continue"        # resume the most recent session
orca exec resume SID --resume-at MID "continue"  # resume up to a message boundary
orca --resume [SESSION_ID]                # resume a saved conversation
orca --fork SESSION_ID                    # fork a saved conversation
orca acp                                  # connect an ACP client
orca app-server                           # serve the JSON-RPC app protocol
orca --plan exec --json -C ./project "inspect it"  # read-only JSONL run
orca doctor                               # check the key, trust, and sandbox locally

On Windows PowerShell, set the key with $env:DEEPSEEK_API_KEY = "sk-...";
the orca commands are the same. The positional prompt form remains
supported. When the prompt may contain tokens that a task later searches for or
kills in the process table, pipe it on stdin so it is not exposed in orca's
command line.

Orca also offers opt-in shared ACP sessions on Unix
(orca daemon, orca attach, and orca acp-bridge),
file-defined subagents, and
persistent terminal output pages.

The terminal UI

Run orca in a project. The first run in a folder asks you to trust it or
continue untrusted: trust lets Orca load the project's configuration,
instructions, skills, agents, and workflows, and never enables or bypasses the
OS sandbox. Then type a task and press Enter.

New TUI sessions default to Full Access (full-auto, also called yolo) when no
mode is configured. An explicit --mode, ORCA_MODE, or user config mode takes
precedence. Resuming keeps the conversation’s saved mode; use --yolo to force
Full Access on resume. Headless exec and shared daemons default to auto-edit.

Mention and command. @ mentions files, skills, plugins, and MCP
resources; $ inserts a skill; / opens the command menu; ? lists every
key. Ctrl+V attaches a clipboard image.
Follow along. Replies are marked ●, reasoning collapses to one
⋯ thinking line, and each tool call shows its output under a │ rail.
Ctrl+O expands the latest collapsed output and Ctrl+Shift+O all of them.
The status bar shows the approval mode, the model and reasoning effort, the
context left, and usage.
Steer a running turn. Esc interrupts. Enter queues a follow-up for
the next turn, Ctrl+Enter sends it into the running turn (in terminals
with the kitty keyboard protocol), and Ctrl+B moves the turn to the
background.
Approve tool calls. A call that needs approval turns the input into an
approval panel: allow once, allow this exact call, allow the tool for the
session, or deny. Esc denies; once a computer call has run in the turn, it
stops the whole turn instead. On a window panel, press 4 to keep the
window and let Orca continue. An MCP tool can also be always
allowed, alone or with its whole server, as a rule saved to your config. Shift+Tab cycles
suggest → auto-edit → full-auto → plan. While waiting for approval,
Shift+Tab opens Full Access confirmation directly. Confirming applies
full-auto without waiting for the turn to finish; answer the original
pending request once to continue. The next tool call uses the new policy,
while tools already admitted and subagents already launched keep their
original policy. Mode changes are recorded in the current conversation and restored on resume;
they do not change the default mode in your config.
Background work. /tasks shows the tasks dock under the conversation,
where background turns, subagents, commands, monitors, and workflow children
appear. /agents opens the Agent Workspace with each task's live
conversation or transcript and the controls it can safely take: stop,
resume, retry, or a follow-up. When background agents finish while you are
idle, Orca continues with their results. /workflows keeps the workflow run
tree.
MCP servers. The servers in your config connect in the background as
soon as the TUI opens. /mcp shows how each stands, with its tools and
prompts, and reconnects, logs in, or logs out; each MCP prompt runs as a
slash command, /mcp__<server>__<prompt>.
Computer use on macOS. On macOS 14 or later, the main TUI session can
inspect and operate other apps to check a UI or work without a command-line
interface, or work in an app you name. App grants work for one call, the
session, or future sessions. Outside full-auto, windows you already had
open ask separately; app grants do not cover them. Press 4 to keep a
window and let Orca continue (Esc can stop the whole turn). Password entry
asks separately unless a qualifying whole-tool rule preapproves it. Window titles appear only for apps used
this session. See
Computer Use for system permissions
and foreground switching.
Plan, goals, and recap. /plan investigates read-only and ends with a
plan to approve; /goal sets a persistent objective; /recap summarizes the
session, and Orca writes one itself when you return after a quiet spell;
/side opens a side conversation for a quick question.
Sessions. /new, /resume (grouped by project, with fork, rename,
archive, delete, and copy ID), /fork [name], /rename [name], /model,
/config, and /copy [N]. Model and reasoning-effort choices are saved to
the user config.toml, so new sessions use them too. /status reports the effective execution profile,
shell sandbox, and permission profile. Ctrl+L clears the screen but keeps
the conversation, and on exit Orca prints the orca --resume <SESSION_ID>
command.

The Terminal UI guide walks through
the screen and every key.

Automatic project memory is on for recorded sessions; use /remember for
explicit user or project facts. See Memory for capture,
recall, storage, privacy, and deletion.

Use Orca from Pilion Browser

Pilion Browser is a desktop browser that works as an ACP client. Choose Orca in its Agent panel: Pilion launches orca --mode=acp, forwards DEEPSEEK_API_KEY, and exposes its own tabs to Orca as MCP tools (browser_snapshot, browser_screenshot, navigate, click, type) with approval-before-action and human takeover. Installers for macOS, Windows and Linux are on the Pilion releases page.

What it does

Uses DeepSeek's reasoning and tool-use semantics directly, with SSE streaming,
prefix-cache-friendly prompts, automatic context management, and retry logic.
Reads, searches, edits, and writes code; runs shell commands; and can verify
the result with a command you choose. bash is the only command entry point,
and every command it starts belongs to the task rather than to the tool call:
a long build, a CI watch, or an interactive PTY session keeps running after
the call returns. yield_time_ms bounds only how long the call waits, while
timeout_ms is the sole caller-side execution deadline. task_read_output,
task_send_input, task_wait, and task_stop continue, feed, wait for, and
stop a command by its task_id. A background supervisor settles exited or
stopped sessions without polling and injects one bounded completion
notification before the next model turn.
Asks one to four structured clarification questions in interactive TUI
sessions, including described choices, optional previews, and multi-select
answers.
Gates risky actions with suggest, sandboxed auto-edit, full-access
full-auto, and read-only plan modes, plus per-folder trust.
Saves local conversations with --resume for continuation and --fork for
branching; orca exec resume <SESSION_ID> restores a headless session with a
fresh budget scope, and headless exits print the exact resume command.
Gives synchronous subagents, async subagents, and workflow child agents a
runtime-owned continuation id. A later subagent call can pass
resume_from with that continuation id (or the originating task id) to append
a new prompt to the same durable child conversation. Task/status output on
TUI, ACP, JSONL, and headless surfaces includes the current attempt,
checkpoint, resumable, and indeterminate state.
Runs direct, nested, Workflow, hosted, continued, and recovered children
through one durable execution scope per root task tree. The default 32
execution leases are a capacity ceiling rather than a delegation target;
accepted overflow queues without creating a worker, and parents waiting for
children yield their lease before re-entering the fair queue.
Keeps up to four active child summaries visible in the conversation and up to
eight durable activity entries per child. /agents opens live conversations
and transcripts and exposes only controls the selected child can safely
perform: stop, resume, retry, or a revision-fenced follow-up.
Learns a bounded set of durable project facts after successfully committed
turns and retrieves only prompt-relevant facts on later turns.
Runs with no implicit turn ceiling; optional [budget] limits
(--max-turns, --max-tool-calls, --max-cost-usd,
--max-wall-time-secs) bound an operation explicitly, and budget stops
settle the current tool, create a checkpoint, and exit 4 with a typed
terminal in the JSONL stream.
Runs persistent goals without a fixed turn ceiling (a cumulative Goal token
budget disables automatic continuation when exhausted), plus subagents and
JavaScript workflows for longer tasks that need continuation or parallel work.
Loads project instructions, skills, plugins, custom tools, MCP tools, and MCP
resources after the workspace is trusted.
Manages MCP servers with orca mcp add, list, get, remove, login,
and logout: local stdio servers, and remote ones over streamable HTTP or
legacy SSE that sign in with OAuth or a bearer token from the environment.
Exposes stable JSONL, app-server, and Agent Client Protocol (ACP) contracts
for editors, harnesses, and CI.

Configuration priority is CLI arguments, environment variables, trusted project
configuration, user configuration, then defaults. Run orca --help or orca exec --help for the full command
surface. User configuration lives at ~/.orca/config.toml; trusted projects
can also provide .orca/config.toml, AGENTS.md, rules, skills, and workflows.

An unset or auto model uses deepseek-flash (DeepSeek-V4.1-Flash). Choose
deepseek-v4-pro with /model, --model, or model = "deepseek-v4-pro" in
config.toml; releases before 0.5.0 routed auto to Pro. Both models use a
1M-token context window and allow up to 384K output tokens. The retired
deepseek-v4-flash and deepseek-v4-flash-vision-exp names remain accepted
and normalize to deepseek-flash, including Flash pricing. DeepSeek thinking is
enabled explicitly: set reasoning_effort to low, high, or max (the
default) in config.toml, or use ORCA_REASONING_EFFORT.

Cost estimates follow DeepSeek's published prices, including the peak rate
that applies Monday to Friday from 01:00 to 04:00 and from 06:00 to 10:00 UTC
(Chinese public holidays are off-peak all day). Orca ships with the prices
current at release. At session startup, each process checks once whether cached
prices are missing or at least 24 hours old and, if needed, refreshes them from
models.dev in the background. Set refresh = false under
[pricing] in ~/.orca/config.toml to disable pricing refresh. To price a model
yourself, for example one served by another endpoint, set input_cache_miss,
input_cache_hit, and output (US dollars per million tokens) under
[models."<name>".pricing]; those prices apply at every hour. Both settings
are read only from the user configuration.

JPEG, PNG, GIF, and WebP inputs are accepted from ACP clients and the TUI with
every model selection. Flash consumes images directly; Pro uses Flash for
task-aware visual analysis before continuing with Pro. In the TUI, use Ctrl+V
to attach the current clipboard image (Alt+V is also available on Windows),
drag or paste image paths and file:// URLs, or select an image through
@file. Each attachment appears as an atomic [Image #N] item that can be
deleted, cleared, queued, edited, and restored after a rejected submission.
Cmd+V works when the terminal forwards it as Super+V; terminals that
consume Cmd+V should use Ctrl+V. Clipboard reads run in the background, and
pressing Enter while one is pending waits for the image before submitting.
Place the cursor on an image item and press Enter to open its preview;
submitted images also render in the message area and can be clicked. The viewer
supports +/- zoom, arrow-key panning, 0 to fit, and Esc to close. Kitty
and Ghostty use the Kitty graphics protocol for native-pixel previews; iTerm2
and WezTerm use the inline-image protocol. Terminals without an image protocol,
including Apple Terminal, fall back to low-resolution true-color cells. SSH
sessions without a graphical clipboard should paste or mention a path on the
remote host. Inline attachments share a 5 MiB total limit. Orca keeps the Chat
Completions transport and fully replays any returned reasoning_content across
tool turns as required by DeepSeek.

More detail:

Reliability

TUI, headless, ACP, and JSONL sessions use the same runtime host for turn
ownership, cancellation, persistence, and terminal results.
Goal and session storage run outside the async actor loop, so a slow disk or
busy SQLite database does not freeze unrelated controls such as cancel or
status.
Cancelling a foreground turn also stops the subagent task tree it owns;
unrelated detached work is left alone.
SIGINT, SIGTERM, and SIGHUP stop a run like an ordinary exit, in
orca exec from the moment it starts and in the TUI: running work and MCP
servers are stopped, the session records how it ended, and the exit code is
128 + the signal. Copies of one stop request that arrive together count
once. On Windows, orca exec takes the console's Ctrl+C as SIGINT, and
Ctrl+Break, a logoff or a shutdown as SIGTERM.
Escape-driven cancellation commits one terminal child state and ignores late
activity from the cancelled attempt, so a stopped subagent cannot flood the
terminal while its parent returns to an interactive prompt.
Continuation recovery is deliberately fail-closed. Orca restores only a
digest-verified conversation checkpoint, never a Rust future or process
stack. A tool admitted with unknown external side effects makes the
continuation indeterminate until a later safe checkpoint covers its
terminal result. Worktree continuations inherit the original path only while
it still exists; retryable resumable attempts retain that path, and Orca does
not silently recreate a missing worktree.
The durable prompt queue and checkpointable child-agent continuation model
project the same queued, resumable, indeterminate, and terminal state across
TUI, ACP, JSONL, and Headless. Large ordinary-chat pastes remain compact in
the composer but submit their complete text; Goal pastes are materialized
under ORCA_HOME/attachments/<uuid> with path validation and transactional
cleanup before the Goal mutation commits. Alt+Up queue editing commits a
revision-checked runtime delete, failed queue admission restores the prompt,
and queued previews remain bounded instead of copying the full body per frame.
Detached background workers never hold the terminal open, and they end once
their task is gone or their lease is lost.
Session switches start the replacement before closing the current runtime.
Rename, fork, archive, and delete commit through revision-checked and durable
paths, and stale events from a previous attachment are ignored.
Runtime surface and platform contracts run in CI before release artifacts are
built for macOS, Linux, and Windows.

Community

QQ group: 472309526
Telegram

Related projects

blade-code is a TypeScript coding
agent with a CLI, a web UI, and a headless mode.
boss-skill turns one coding agent
into an auditable team workflow, from PM through DevOps.
blade-agent-sdk is a
session-first TypeScript SDK for multi-turn agents, streaming tools, MCP,
and subagents.

Contributing

Read CONTRIBUTING.md before contributing. Open an issue first
for large or compatibility-sensitive changes.

License

MIT

orca-agent