Getting started

Orcaops gives your coding agent skills for capturing and reviewing its work. You keep talking to the agent in plain language; the skills call the Orcaops CLI and record a structured plan, checkpoints, decisions, verification, and a final summary underneath.

You do not need an Orcaops account to capture work, run evaluators, or use Orcaops Watch. Captures stay in local project history. Optional background knowledge processing uses a provider CLI and may send captured content to that provider after you enable and consent to it.

How Orcaops names the work

Orcaops builds a task record while your agent works: the plan and its revisions, checkpoints, decisions, verification, evaluator results, uncertainty, and final outcome. The CLI and lower-level reference pages call one captured task thread an artifact. A branch can therefore contain several artifacts that contribute to one body of work.

A completion check is the user-facing last look at that work before you accept it. Evaluators compare the captured record with its requirements, while Task Review independently examines the code and organizes the captured account for a human reviewer. Neither a clean evaluator result nor a generated Task Review is automatically a merge verdict.

The Glossary is the quick reference for these and other terms that appear in Orcaops Watch, the digest, and lower-level command output.

Prerequisites

• Node.js 22.14 or newer — check with node --version.
• macOS or Linux on x64 or arm64. On Windows, use WSL2.
• A git repository with at least one commit.

1. Install the CLI

npm i -g @orcaops/cli
orcaops --version

2. Initialize your repository

Run this once from the repository root:

orcaops init

init looks for evidence of installed coding agents — a file the agent itself wrote under your home directory — and installs the matching Orcaops skills. Interactive setup pre-ticks each agent it found and shows why (for example detected: ~/.cursor/cli-config.json); untick any you do not use. Editors that leave no footprint of their own, such as Copilot in JetBrains or Neovim, are not pre-ticked, so tick them yourself. Setup then asks:

• which agents should receive Orcaops skills;
• whether to add the recommended session-start reminder so those agents remember to capture non-trivial work;
• whether Orcaops should maintain an instruction-file section when that surface is supported and still needed.

A repository that was initialized earlier keeps its agent list. To drop an agent that was ticked by the older directory-only detection, run orcaops configure and untick it (or orcaops init --force --reset-config to start over).

What init changes

The default personal setup is designed for one developer to try Orcaops without changing the repository for anyone else.

Surface	What happens	Why
Agent skills	Installs skills in the repository or in each selected agent's global skill location, depending on install scope. The default personal setup uses global locations, so no skill files enter the repository.	Your agent can run the capture and review workflows without committing generated files.
Configuration	Personal configuration lives in the Git common directory and is shared by worktrees. Project-scope configuration uses .orcaops/.	Captured history does not depend on checkout-local files.
Repository identity	Creates a durable registration in the Git common directory naming the project database and its expected instance.	A missing registered database is reported as missing history, never replaced silently.
Workflow guidance	Offers a recommended session-start hook and, where supported, a managed instruction-file section. Hooks emit only in initialized repositories; managed instructions stay within the selected install scope.	The agent remembers to run the lifecycle when you give it an ordinary development task.
Project history	Creates the project database in the selected per-user data root. Captures and mutable review state are stored there; retained evidence and Git snapshots have separate immutable storage.	History survives deletion of a worktree.
LLM tool	Selects an available local coding-agent CLI automatically when an Orcaops workflow needs a model; it reuses that tool's login rather than asking Orcaops for an API key.	You keep using the coding-agent subscription already configured on the machine.
Tracked repository	No tracked files, .gitignore edits, tracked instruction-file edits, git hooks, or background services are added by the default personal setup.	You can evaluate Orcaops without affecting teammates or the project diff.

Keep either the recommended session reminder or managed instruction section enabled to get the automatic workflow described below. Skills are installed even if you decline both, but skills alone provide capabilities rather than a session-wide reminder to capture every non-trivial task; in that deliberately manual setup, you may need an explicit skill request.

At the end, init prints the directories and agent support it created, whether session reminders are enabled, the selected LLM tool, and the command for adopting Orcaops as a team later:

orcaops update --scope project

That command materializes the shared files for review and commit; it is not part of the personal setup. For unattended setup, orcaops init --yes uses personal scope and does not install session hooks or edit agent instruction files. That unattended mode installs the skills but intentionally leaves proactive workflow guidance off. Use interactive orcaops configure afterward and follow any machine-registration instruction it prints when you want to enable that guidance with consent.

Example interactive initialization

$ npm i -g @orcaops/cli
$ orcaops init

◇ Which AI coding agents do you use in this repo?
│ ● claude-code (detected)
│
◇ Session-start hooks put a short Orcaops reminder into your agent's
│ context at the start of every session, so it remembers to capture
│ its work. What should the reminder say?
│ ● On — fixed reminder (recommended)
│
◇ Keep a backup of captured session history in your home directory?
│ ● Yes

After those choices, init prints a summary like this. Paths are normalized and intermediate sections are omitted; your selected agent and install scope determine the exact paths and counts.

Orcaops initialized at <repo>

Created:
  <repo>/.git/orcaops/config.json

Installed 18 skills for claude-code → <agent-skills-dir>

…

Machine session hooks installed for:
  + claude-code

…

LLM tool: auto (piggybacks on your local subscription — no API key).

…

Invisible install: nothing touches git — `git status` stays clean, teammates
see nothing. To adopt orcaops as a team later: `orcaops update --scope project`,
then commit the files it materializes.

…

Next: have your agent capture plans + checkpoints via `orcaops capture …`.
Change settings: `orcaops configure` · Undo: `orcaops uninstall`

The installed count includes the default-enabled skills compatible with that agent and scope. The complete skill index also lists opt-in and capability-gated skills.

3. Set up project knowledge

Orcaops can connect decisions and requirements across captured tasks so your agent can find them later. This background processing is off by default and needs both a configuration choice and your consent.

First, find the configuration file this checkout actually uses:

orcaops knowledge status

The first line names the config file to edit. Open it in your editor, keep its existing keys, and choose one of these setups. Set schema_version to 8 when you add knowledge_processing.

For fast, lower-cost processing with Codex, use GPT-6 Luna at high effort:

{
  "schema_version": 8,
  "knowledge_processing": {
    "enabled": false,
    "provider": "codex",
    "model": "gpt-6-luna",
    "effort": "high",
    "tool_access": "codex_restricted",
    "max_cost_usd_per_call": "none"
  }
}

If you use Claude Code instead, start with Claude Sonnet 5 at high effort:

{
  "schema_version": 8,
  "knowledge_processing": {
    "enabled": false,
    "provider": "claude",
    "model": "claude-sonnet-5",
    "effort": "high"
  }
}

Merge the chosen keys into your existing JSON file rather than replacing it. Keep enabled false; the command below turns it on after you consent. See Project knowledge for model choices, cost guidance, and the full configuration options.

Then run this yourself in an interactive terminal:

orcaops knowledge enable
orcaops knowledge status

enable shows the provider, model, content sent, and effective limits before asking for typed consent. status confirms the settings, consent, queue, and coverage. If you already captured work while processing was off, use orcaops knowledge enable --include-backlog to include those waiting captures. Older Git commits require a separate Git-history import, which previews the selection before you approve it. Imported commits become searchable history; they do not get knowledge-processing jobs.

4. Give your agent a normal task

Open your coding agent in the repository and describe the task normally:

Add pagination to the activity feed and update its tests.

With the recommended session reminder or managed instructions enabled, the installed guidance tells the agent to capture a plan before editing, checkpoint coherent units of work, and finish with the review, summary, and digest in one workflow. You do not add Orcaops instructions to each task or prompt for those phases individually. The skills own their CLI arguments, ordering, evaluator responses, and recovery behavior.

Explicit skill requests are available when you want to override the normal flow or recover from a missed trigger. Learn those controls—and the everyday on-demand requests—in Working with your agent.

5. Generate and inspect the branch review

One branch or worktree can contain several captured task artifacts, so you decide when the combined work is ready for review. Then ask your agent:

Generate a Task Review for this branch.

The skill assembles the branch-level review. From the repository, open it in Orcaops Watch:

orcaops watch

Orcaops Watch is the local terminal interface over captured artifacts and branch changes. Use it to inspect the captured reasoning alongside the diff and read the generated Task Review. Ask the agent to regenerate it after material branch changes.

Capture and Task Review stay local unless you deliberately enable a Cloud workflow. Knowledge processing sends prepared captures to the provider you consented to; model-backed evaluators can also contact their configured provider.

Where to go next

• Want more ways to use the installed skills? Browse the skill catalog.
• Need to change agents, install scope, hooks, or generated files? Use orcaops configure or open Configuration.
• Adopting Orcaops across a team? Follow Team adoption to standardize the developer setup, then connect Cloud collaboration for shared history, plan approval, and web review.

Updating

npm i -g @orcaops/cli@latest    # or @<version> to pin

Maintain or remove the installation

After updating the CLI, refresh generated support files with:

orcaops update

To inspect what an uninstall would remove, then uninstall safely:

orcaops uninstall --dry-run
orcaops uninstall
npm rm -g @orcaops/cli

The worktree .orcaops/ directory is kept by default. --purge-data also removes it. Neither form deletes canonical project history, which lives in the orcaops data directory; see local data.