orca-agent

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

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 rewind --at MID --dry-run            # preview a file/conversation rollback
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.
• Rewind. /rewind (alias /checkpoint, or orca rewind --at MID) lists the session's user turns and can restore files to their state before a chosen turn, rewind only the conversation, do both, or replace one side of the boundary with a model-written summary. Before each edit / write_file Orca stores the file's pre-image in a content-addressed checkpoint; the most recent 100 stay file-restorable, edits made by bash or other processes are reported as untracked and never restored, and an interrupted restore can be rolled back from its journal.

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:

• Documentation and the Terminal UI guide
• Persistent Goal Mode
• Memory
• Harness and app-server contract
• Dynamic workflow design
• Production roadmap

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.

• Report a bug
• Request a feature
• Ask for help
• Report a vulnerability

License

MIT