orca README

The project's README from github.com/VirtusLab/orca. As one markdown file: README.md.

Orca

Deterministic, AI-driven development flows.

Orca allows you to programmatically define software development workflows where AI agents perform the coding. If you want AI-generated code to always be reviewed by another agent, don't try to coerce the agents; just express that requirement in code. Don't waste tokens on formatting, committing, or creating PRs - all of this can be handled by an ordinary script.

Orca comes with an orca cli and a skill, which can be used interactively by humans, or headlessly by humans and agents alike. A number of built-in flows, implementing e.g. a plan-implement-review loop, allow you to start using Orca right away.

Orca flow scripts are written in Scala, and can be run with a single command through scala-cli, which is installed by the orca installer. No other dependencies are needed - everything is automatically bootstrapped. Scala 3 looks like Python, but with types - so you get quick feedback if your flow script has any problems.

Orca's development flows are resumable, so that if work is interrupted mid-flow for any reason, it can be continued from the last commit.

You can use Orca to orchestrate development in any language and ecosystem.

Orca assumes that it has configured, logged-in access to Claude, Codex, OpenCode, Pi or Gemini (depending which backend you use), as well as gh and git.

[!NOTE] Orca is designed to be run as part of a single-developer workflow. For a platform designed for teams, see Visdom: VirtusLab's AI-native SDLC platform.

Documentation

Is available here: orca.virtuslab.com

Install

The below installs scala-cli (via its official installer) if you don't have it already, and writes the orca executable to ~/.local/bin/orca:

curl -fsSL https://raw.githubusercontent.com/VirtusLab/orca/master/install.sh | bash

To let a coding agent delegate work to Orca, install the orca skill. In Claude Code:

/plugin marketplace add VirtusLab/orca
/plugin install orca@orca-skills

In Pi: pi install git:github.com/VirtusLab/orca. For OpenCode, Codex and per-project installs, see skills/orca/README.md.

Start using

Run orca in your repository. The first run asks which agent and model to use for planning, coding and review. Then pick a flow (implement.sc comes first) and enter your prompt.

The same can be run non-interactively:

orca run implement.sc "add a rate limiter to /login"

Orca creates a feature branch, plans the change into tasks, implements and reviews each one, reviews the whole change, and opens a PR when the repository is on GitHub. Each stage is committed as it finishes; if the run is interrupted, run the same command again and it will continue from the last commit.

A flow is a scala-cli script, so it also runs with no install:

scala-cli run --workspace "$(mktemp -d)" implement.sc -- "add a rate limiter to /login"

[!WARNING] Orca should be used in a sandboxed environment! Coding agent tool usage is auto-approved by default: write-capable turns let the agent edit files and run shell commands without prompting. Use a VPS or a local sandbox such as Sandcat or Docker Sandboxes, or narrow the agents' tools in the flow.

A flow

Flows are ordinary Scala scripts. For example, the below one plans, implements each task with a review, and opens a PR:

//> using scala 3.9.0
//> using dep "org.virtuslab::orca:0.2.1"
//> using jvm 21

import orca.{*, given}

flow(OrcaArgs(args)):
  val plan = stage("Plan"):
    Plan.autonomous.from(userPrompt, planningAgent).value

  for task <- plan.tasks do
    stage(s"Task: ${task.title}"):
      val session = codingAgent.session("implementer", seed = plan.brief)
      session.run(task.description)
      reviewThenFix(coderSession = session, reviewers = allReviewers(reviewAgent), task = task)

  val openFindings = stage("Final review"):
    val finalFixer = codingAgent.session("final-fixer", seed = plan.brief)
    reviewAndFixLoop(
      coderSession = finalFixer,
      reviewers = allReviewers(reviewAgent),
      task = Task(Title("The whole planned change"), plan.brief),
      diff = ReviewDiff.WholeRun
    )

  openPrIfGitHub(summarisingAgent = codingAgent, openFindings = openFindings)

Each stage commits on completion and is skipped on resume. The tutorial at orca.virtuslab.com explains every line; the shipped flows live in flows/.

Documentation

License

Apache 2.0 — see LICENSE.

Copyright (C) 2026 VirtusLab https://virtuslab.com.

orca (VirtusLab/orca)

sdlc
Searching Database…

199 ·GitHub
What is this?Orca is a CLI for defining software development workflows as code, where AI coding agents do the actual coding — you describe the process, the agents handle the implementation steps.
Is it a tool I just run, or a framework I write code against?Both: an 'orca' CLI ships built-in flows (like a plan-implement-review loop) that work out of the box, and you can write your own flow scripts in Scala 3, run with a single command through scala-cli.
How do I install it and start my first flow?One command: the installer installs scala-cli if missing and writes orca to ~/.local/bin/orca. Then run 'orca' and pick a flow (implement.sc is first in the list), or use 'orca run' — also headlessly from CI or another agent.
What do I need to have set up beforehand?A configured, logged-in coding agent backend — Claude, Codex, OpenCode, Pi, or Gemini — plus gh and git. Everything else, scala-cli included, is bootstrapped automatically; no other dependencies.
Is it safe to run on my machine as-is?Agent tool use is auto-approved by default: agents edit files and run shell commands without prompting. Orca is designed for a sandboxed environment — a VPS, Sandcat, or Docker sandbox — though flow options can change auto-approval.
My project isn't written in Scala and neither am I — does that matter?No — Orca orchestrates development in any language and ecosystem. Scala only appears if you write custom flow scripts, and even then Scala 3 'looks like Python, but with types'.
What does a flow actually do to my git repository?It creates a feature branch (auto-named by a cheap model, or you name it with --branch) and the runtime — not the agents — does the committing and pushing. On success it opens a PR via gh and returns you to your original branch; on failure you stay on the feature branch, ready to test or open a PR by hand.
If a run is interrupted, do I have to start over?No — rerun the same command and the flow resumes from the last committed set of changes, so only a small amount of work repeats. Completed stages are tracked in a progress file committed alongside the code, making commits the unit of atomicity.
Can I choose which agent or model plans, codes, and reviews?Yes — those roles are resolved from settings.properties, written by the first-run wizard or 'orca config'. In scripts you can also pin specific backends and tiers: claude.opus for the hardest steps, or cheap one-shot calls like claude.haiku, codex.mini, and gemini.flash.
Why call the flows deterministic if AI writes the code?Because the process around the AI is ordinary code: branching, committing, PR creation, and requirements like always having another agent review the work are expressed in the script instead of being coerced out of the model. Ordinary scripts handle the chores so tokens aren't wasted on formatting or committing.
Creator
VirtusLab
Size
7.5 MB
Stars
199
Age
6mo
Commits · 90 Days