orca-agent

Orca is a terminal-oriented DeepSeek-native coding agent, built with Rust, running locally, and licensed under MIT. After the user assigns a task to Orca, it reads code, edits files, runs commands, verifies results, and keeps working until the task is complete or user intervention is needed.

Main capabilities

• Code operations: reads, searches, edits, and writes code, runs shell commands, and can verify results with user-specified commands. bash is the only command entry point; each command belongs to a task rather than a tool call, and long builds, CI monitoring, or interactive PTY sessions continue running after the call returns.
• Interactive TUI: run orca in a project directory to start it. On first run it asks whether to trust the folder; after trusting, Orca can load project configuration, instructions, skills, agents, and workflows, but does not enable or bypass the operating system sandbox. Supports @ mentions of files, skills, plugins, and MCP resources, $ to insert skills, / to open the command menu, ? to list all keybindings, and Ctrl+V to attach clipboard images.
• Task control: Esc to interrupt, Enter to queue the next follow-up, Ctrl+Enter to send a follow-up to the running turn, and Ctrl+B to move the turn to the background. When tool calls require approval, an approval panel appears with options to allow once, allow this exact call, allow that tool for this session, or deny. Shift+Tab cycles between suggest → auto-edit → full-auto → plan modes.
• Background work: /tasks shows the task dock, /agents opens the Agent workspace, and /workflows keeps the workflow run tree. Background agents complete when the user is idle, and Orca continues processing their results.
• MCP servers: servers in the configuration connect in the background when the TUI opens, /mcp shows status, tools, and prompts, and supports reconnect, login, or logout. Each MCP prompt can be run as a slash command.
• Plans, goals, and recaps: /plan is read-only investigation and ends with a plan, /goal sets a persistent goal, /recap summarizes the session, and /side opens a side conversation.
• Session management: commands such as /new, /resume, /fork, /rename, /model, /config, and /copy. Model and reasoning effort selections are savedto the user config.toml.
• Project memory: recorded sessions automatically enable project memory, and /remember is used to explicitly record user or project facts.
• Subagents and workflows: supports synchronous subagents, asynchronous subagents, and workflow subagents, with continuation IDs owned by the runtime, allowing new prompts to be appended to the same persistent subconversation via resume_from.
• Persistent goal mode: runs persistent goals with no fixed turn limit, with optional [budget] limits (--max-turns, --max-tool-calls, --max-cost-usd, --max-wall-time-secs).
• Interface contracts: provides stable JSONL, app-server, and Agent Client Protocol (ACP) contracts for use by editors, testing frameworks, and CI.

Usage Installation: can be installed via npm; the npm package supports ARM64 and x64 on macOS, Linux, and Windows; prebuilt archives can also be obtained from GitHub Releases, or the native binary can be installed directly. On Windows PowerShell, you can set $env:DEEPSEEK_API_KEY = "sk-...".

Run orca from the project directory to launch the TUI, or use orca exec for scripts and CI. Configuration precedence is environment variables, CLI arguments, configuration file, defaults. User configuration is located at ~/.orca/config.toml; trusted projects can also provide .orca/config.toml, AGENTS.md, rules, skills, and workflows.

Models: if unset or set to auto, the model uses deepseek-flash (DeepSeek-V4.1-Flash). You can select deepseek-v4-pro via /model, --model, or model = "deepseek-v4-pro" in config.toml. 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 are still accepted and normalized to deepseek-flash. DeepSeek thinking must be explicitly enabled: set reasoning_effort to low, high, or max (default) in config.toml, or use ORCA_REASONING_EFFORT.

Image input: accepts JPEG, PNG, GIF, and WebP from ACP clients and the TUI. Flash consumes images directly; Pro uses Flash for task-aware visual analysis before continuing. In the TUI, you can use Ctrl+V to attach a clipboard image, or drag/paste image paths and file:// URLs, or select images via @file. Inline attachments share a 5 MiB total limit.

Use cases

• Interactive programming tasks within the terminal.
• Automated programming tasks in scripts and CI (orca exec).
• Work that requires long-running, background execution or parallel subtasks.
• Integration with editors or browsers that support ACP (such as Pilion Browser).

Limitations

• Requires a DeepSeek API key.
• On minimal Linux systems (such as slim container images), the ca-certificates package is required, otherwise no network requests can be made, including plain HTTP.
• On Windows, PowerShell 7 is preferred; restricted sessions fall back to cmd.exe when PowerShell 7 is unavailable; Windows PowerShell 5.1 is available only as an explicit option in modes that do not require AppContainer isolation.
• Computer Use features are available only on macOS 14 or later.
• Shared ACP sessions (orca daemon, orca attach, orca acp-bridge) are available only on Unix.
• Continuation recovery uses a fail-closed policy and restores only conversation checkpoints that have passed summary verification, not Rust futures or process stacks.
• Other features, charges, prices, platforms, or effects not clearly stated in the materials are not yet provided.