# orangu llms-full.txt orangu 0.7.2. This file concatenates README.md, docs/USAGE.md, docs/DETERMINISM.md from the repository, verbatim, with relative links rewritten to https://github.com/NissanOhana/orangu/blob/main/. The short index is llms.txt. --- # README.md
orangu # orangu **Observe the run. Improve the next outcome.** Local, offline, deterministic observability for Claude Code, Cowork, and Desktop sessions, with optional Claude Code skills that turn the evidence into reviewable changes. [sample report](https://nissanohana.github.io/orangu/sample.html) · [repo sample](https://nissanohana.github.io/orangu/sample-repo.html) · [docs](https://github.com/NissanOhana/orangu/blob/main/docs/README.md) · [npm](https://www.npmjs.com/package/orangu) · `npx orangu report`
You run coding agents for hours. The transcript on disk is the only record of what they did, and nobody reads it. orangu does, and shows you: | What the session does not tell you | What orangu shows | |---|---| | "compacted" | which turns filled the context window, and with what | | a subagent's final answer | its full tree: tools, tokens, time, errors | | that a skill or MCP server is installed | whether it ever fired, and what it weighs in context | | nothing about repetition | the same file read again and again, and the same context re-read in every request | One real number, from one local session: 34.9M of the 37.0M tokens the model processed were cache reads, one 223k-token context read again 156 times over. Tokens are the only usage metric orangu has, because they are the only one the transcript records. ccusage counts your token usage. orangu tells you what to change. ## Quick start **Read-only.** orangu reads the session files already on your disk and writes one HTML file. No SDK, proxy, account, instrumentation, upload, or telemetry. Your whole history is analyzable the minute it is installed, not just sessions started after it. ```bash npx orangu # orange terminal dashboard -> repo, global, or open session reports npx orangu report # latest session -> self-contained HTML report, opened in your browser npx orangu pick # choose a session (running ones first), Enter opens its report npx orangu report current # the session Claude Code is running you in; or -s for any npx orangu serve # live loopback viewer over every local session npx orangu repo # recurring patterns across this repository's sessions npx orangu global # ... across every session on the machine npx orangu harness # what your config declares vs what your sessions used, in tokens ``` Use the arrow keys or `j`/`k` and Enter in the dashboard. In a pipe or CI, bare `orangu` keeps the compact latest-session summary instead of waiting for input. The repo and global choices open the same self-contained HTML report for a whole scope. From the command line, `orangu repo --html ` writes it where you say and `--open` writes it to the temp directory and hands it to your browser; `--json` stays a side-effect-free machine read. Node.js 20 or newer. Zero runtime dependencies. More commands, inputs, and limits are in the [usage guide](https://github.com/NissanOhana/orangu/blob/main/docs/USAGE.md). ## The improve loop 1. **Observe.** orangu parses, redacts, counts, reconciles, matches, and ranks locally against 44 deterministic rules. No model is involved. 2. **See.** The report shows what happened: quality, time, and tokens as separate axes, with the evidence behind each finding. 3. **Propose.** `/orangu:improve` explains one finding's bounded evidence and drafts a structured proposal. It never edits your project. 4. **Apply, with a receipt.** `/orangu:apply` applies one explicitly reviewed proposal and records what changed and which checks ran. Every proposal lands in one of nine change classes: instruction files, scripts and CLIs, hooks, skills to create, skills to discover, subagents and agents, MCP servers, plugins, or workflow and configuration ([data contracts](https://github.com/NissanOhana/orangu/blob/main/docs/DATA-CONTRACTS.md)). One run can be fixed and re-checked against a later session from the same workspace. Repo-wide changes are applied on request. Whole-harness (global) changes stay review-only. A proposal is not an application, and a later comparison is not causal proof; the full boundary is in [determinism and skill authority](https://github.com/NissanOhana/orangu/blob/main/docs/DETERMINISM.md). ## Skills ```text /plugin marketplace add NissanOhana/orangu /plugin install orangu ``` | Skill | What it does | |---|---| | `/orangu:analyze` | Explain what happened in one session, finished or still running, from local evidence; open the report for the session it runs in | | `/orangu:improve` | Draft one reviewable proposal from a finding (`/orangu:improve latest`) | | `/orangu:apply` | Apply one reviewed session or repo proposal and save the receipt | | `/orangu:harness` | Review the whole harness: CLAUDE.md, skills, agents, hooks, MCP, in tokens | | `/orangu:feedback` | Send reviewed beta feedback from a localhost form | Skills read `orangu ... --json` and `orangu evidence`, never the raw `.jsonl`, and every one shows a token estimate before reading more than it should. The shipped instructions live in [`plugin/skills/`](https://github.com/NissanOhana/orangu/blob/main/plugin/skills). Codex is also an improvement-skill host: `codex plugin marketplace add NissanOhana/orangu` then `codex plugin add orangu@orangu` installs `$orangu-improve`, `$orangu-apply`, and `$orangu-feedback`; orangu does not ingest Codex transcripts. ## Not a wrapper orangu is not a proxy, an SDK, a hook you install before the session, or a model that summarizes your transcript. It is a parser plus a rule set over the `.jsonl` files Claude Code already writes. Nothing runs during your session, nothing is sent anywhere, and the measurement never asks a model what it thinks. ## Design principles - **No model in the measurement path.** Counting, reconciling, and ranking are plain code; skills only interpret the result. - **Zero network from reports.** Every report ships `default-src 'none'` and makes no request. `serve` binds to `127.0.0.1` and places every route behind a fresh process capability in its launched URL. - **Redacted by default.** Secrets are scrubbed and prompt text is omitted unless you ask with `--include-text`. - **Same transcript in, byte-identical analysis out.** No clock, no randomness, no network in the analyzer. - **Components, never a composite score.** Quality, time, and tokens stay separate. Never a leaderboard of people. - **Tokens only.** Input, cache-read, cache-write, and output tokens; nothing converted into any other unit. ## Where it sits | | | |---|---| | Raw transcripts | Contain the record, but leave the reading and synthesis to you. | | Usage counters (ccusage and friends) | Sum tokens across time and sources. | | Instrumented trace platforms | Capture applications that have been wired to send traces and evaluations. | | orangu | Reads the transcript you already have, explains it, and turns findings into reviewed changes with receipts. | ## Privacy and support - Redaction is on by default; add `--strip-paths` before sharing a report, and review every export first. - Unknown transcript records are counted and shown in Coverage instead of crashing the analysis. - Feedback stays on localhost until you review the exact title and body and open GitHub's issue composer yourself. Read the [privacy model](https://github.com/NissanOhana/orangu/blob/main/docs/PRIVACY.md), [supported limits](https://github.com/NissanOhana/orangu/blob/main/docs/USAGE.md#supported-inputs-and-limits), and [security policy](https://github.com/NissanOhana/orangu/blob/main/SECURITY.md) before sharing a report or JSON export. Are you an LLM? Read [llms.txt](https://nissanohana.github.io/orangu/llms.txt). ## Documentation | Guide | Purpose | |---|---| | [Documentation index](https://github.com/NissanOhana/orangu/blob/main/docs/README.md) | All user, integration, design, and contributor references | | [Usage](https://github.com/NissanOhana/orangu/blob/main/docs/USAGE.md) | CLI commands, app surfaces, inputs, and limits | | [Determinism](https://github.com/NissanOhana/orangu/blob/main/docs/DETERMINISM.md) | Local evidence, AI-skill authority, and lifecycle rules | | [Architecture](https://github.com/NissanOhana/orangu/blob/main/docs/ARCHITECTURE.md) | Pipeline, modules, build, and correctness gates | | [Data contracts](https://github.com/NissanOhana/orangu/blob/main/docs/DATA-CONTRACTS.md) | Analysis, evidence, app, proposal, and receipt shapes | | [Beta feedback](https://github.com/NissanOhana/orangu/blob/main/docs/feedback.md) | Localhost intake, exact-review consent, and GitHub handoff | | [Contributing](https://github.com/NissanOhana/orangu/blob/main/CONTRIBUTING.md) | Development workflow and project layout | ## Develop ```bash git clone https://github.com/NissanOhana/orangu && cd orangu npm ci && npm run verify:release ``` ## License MIT © Nissan Ohana. The mascot is CC0.
orangu is not affiliated with Anthropic or OpenAI. Claude and Claude Code are trademarks of Anthropic. Codex is a product of OpenAI.
--- # docs/USAGE.md # Usage Orangu reads supported local session files and turns them into a self-contained report, a loopback app, or redacted JSON. ## Install Orangu requires Node.js 20 or newer. ```bash npx orangu report npm install --global orangu ``` To run from a source checkout: ```bash npm ci npm run build node dist/orangu.js report ``` ## Commands | Command | Purpose | |---|---| | `orangu` (no verb) | Open the terminal dashboard for repo, global, and session reports | | `orangu report [selector]` | Write and open one self-contained session report | | `orangu analyze [selector]` | Print a summary or redacted JSON | | `orangu list` | List discoverable supported sessions | | `orangu pick` | Choose a session from a list, running ones first, and open its report | | `orangu watch [selector]` | Refresh one report while its session grows | | `orangu serve` | Run the capability-protected local app on `127.0.0.1` | | `orangu feedback` | Open the isolated, capability-protected localhost beta-feedback form | | `orangu repo` | Aggregate supported sessions for the current repository (`--html`/`--open` for the report) | | `orangu global` | Aggregate supported sessions across configured roots (`--html`/`--open` for the report) | | `orangu evidence ` | Emit the bounded, always-redacted evidence a skill reads | | `orangu estimate [selector\|repo\|global\|harness]` | Size the bounded read before handing evidence to a skill | | `orangu harness` | Compare declared harness configuration with observed use | | `orangu suggest` | Inspect and transition validated suggestion records | A session selector can be `latest`, a session id or unique prefix, a supported `.jsonl` path, or `current`: the session Claude Code is running orangu from, resolved from the Claude Code environment and never guessed silently (a cwd-based guess says so; outside Claude Code it is an error). `report`, `analyze`, `watch`, and `estimate` also take the selector as `--session ` (`-s`); giving both the positional and the flag with different values is an error. On an interactive terminal, bare `orangu` draws the orange ASCII mascot and a keyboard dashboard. The first choices open the current-repository aggregate, the global aggregate, or the full session picker; currently open Claude Code sessions appear underneath as direct report shortcuts. Move with the arrow keys or `j`/`k`, choose with Enter, and cancel with `q`, Esc, or Ctrl-C. A pipe, CI, `--plain`, `--quiet`, or an explicit scope/session flag keeps the compact latest-session behavior and never waits for input. `orangu repo` and `orangu global` print their answer to stdout. `--html ` also writes that scope as one self-contained HTML report, and `--open` writes it into the temp directory as `orangu--.html` and hands it to your browser, so a re-run never overwrites a file a browser still has open. The dashboard's repository and global choices ask for that report; `--no-open` suppresses it. Both flags are refused with `--json`, which is a machine read with no side effect, and `--out ` still writes the aggregate JSON. The written file is private (mode `0600`), redacted by default, and passes the same zero-network gate as the session report. `orangu pick` lists sessions running first (title, project, age, size), moves with the arrow keys, `j`/`k`, or a digit, opens the chosen report on Enter, and cancels on `q`, Esc, or Ctrl-C with the terminal restored. Without a terminal, in CI, or with `--plain` it prints a numbered list and the `orangu report ` hint; `--json` prints the array (`[]` on an empty home, still exiting 1 because the chooser had nothing to choose). Use `orangu --help` for flags and output controls. ### Terminal output `orangu report` writes only the report path to stdout, so `orangu report | xargs open` works; its summary (the check line, the path, the top finding, and the next command) goes to stderr. `orangu analyze` prints the measurement block on stdout and the same footer on stderr. The bare interactive dashboard and the non-interactive latest-session brief both use stdout. The next command is the short `claude "/orangu:improve sg_..."`: the suggestion record is stored under `~/.orangu` at report time, and only when that store cannot be written does the long `--finding` form appear, with a line saying so. Colour appears only on an interactive terminal and is off under `--json`, `--quiet`, `--no-color`, `NO_COLOR`, `FORCE_COLOR=0`, `TERM=dumb`, or a pipe (`FORCE_COLOR=1|2|3` paints a pipe). The spinner needs the same terminal and is also off under `CI`, `NO_COLOR`, `FORCE_COLOR=0`, and `ORANGU_NO_ANIMATION=1` (the last one stops the spinner alone). `file://` hyperlinks (OSC 8) appear on terminals known to render them; `FORCE_HYPERLINK=0|1` overrides, and `NO_COLOR` leaves them alone. `--json` and `--quiet` output never carries an escape sequence. `--verbose` adds the cache diagnostic on stderr. `report`, `analyze`, and the non-interactive bare-session brief record the top finding's suggestion under `~/.orangu` so the printed `claude "/orangu:improve sg_…"` works; `--quiet` silences the trailing hint but still records it (re-runs add nothing), and `--json` records nothing. ## Report and app The file report and localhost app render the same session evidence: - Overview: outcome narrative, named signals, and relevant findings. - Timeline: turns, parent and subagent tool calls, actors, durations, and errors. - Tools: calls, latency, failure states, and recurring error shapes. - Agents: parent and subagent structure and activity. - Context and tokens: context changes, compaction, cache behavior, and token composition. - Coverage: parsed and unknown records plus usage reconciliation. - Repo and Global: recurring patterns across supported sessions. - Suggestions: matching known fixes, proposals, receipts, host hand-offs, and scope-aware verification state. The browser never starts an agent or marks a proposal applied. It only copies a command for explicit use in Claude Code or Codex. ## Beta feedback Run `orangu feedback --context session|repo|global|report|app` or use the **Beta feedback** launcher in the localhost app. The standalone command does not discover a session or attach report data. Feedback stays in the browser until you review the exact title, body, and generic diagnostics and explicitly open GitHub's issue composer. See [beta feedback](https://github.com/NissanOhana/orangu/blob/main/docs/feedback.md) for the privacy boundary, consent flow, and oversized-report fallback. ## Shareable output Reports and JSON scrub recognized secrets by default. Report, `analyze --json`, `evidence`, `repo`, and `global` output also omit arbitrary prompt and result text (session titles, previews, tool-error text, finding details built from commands) unless `--include-text` is requested. Home paths are shortened to `~`, but other absolute paths may remain useful evidence. Add `--strip-paths` to reduce them to basenames before sharing. `--no-redact` is intended only for explicitly requested local inspection. `orangu evidence` is always redacted and does not accept `--no-redact`. ## Supported inputs and limits Orangu currently parses supported Claude Code, Cowork, and Desktop session formats. It is not a generic JSONL reader and does not ingest Codex transcripts. Claude Code and Codex are both supported as hosts for the optional improvement skills. Disk-backed parsing is fail-closed: - Normal parse, cache, and live snapshots share a 256 MiB and 100,000-record session budget. - Evidence and later verification use a stricter 64 MiB whole-session budget. - One JSONL record may be at most 8 MiB. - Sidecar discovery is bounded by entry count, nesting depth, and metadata file size. - Symlinks, replacement races, partial verification inputs, and over-limit inputs are rejected. Current Analysis, SlimAnalysis, and Aggregate JSON inputs to `orangu evidence` are capped at 8 MiB. The projection validates at most 500 findings and 1,000 aggregate sessions, selects at most 50 findings, and emits at most 256 KiB. Unknown records appear in Coverage instead of being silently treated as supported. ## Improvement lifecycle The optional skills use `orangu evidence` as their only transcript boundary: ```text observe -> draft proposal -> explicit apply -> later session comparison ``` - Session scope supports proposal, explicit application, and later same-workspace comparison. - Repo scope supports proposal and explicit application; later verification for repo scope is not implemented yet. - Global scope is proposal-only. See [determinism and AI skills](https://github.com/NissanOhana/orangu/blob/main/docs/DETERMINISM.md) and [data contracts](https://github.com/NissanOhana/orangu/blob/main/docs/DATA-CONTRACTS.md) for the complete rules. --- # docs/DETERMINISM.md # What is deterministic and what uses an AI skill Orangu is one improvement system with a deliberate evidence boundary. Local code produces the measurements, finding identities, catalog matches, artifact validation, and lifecycle state. AI skills explain that bounded evidence, optionally research choices, draft a change, and, only in a separately invoked apply skill, edit reviewed project files. The boundary makes each claim inspectable without pretending that deterministic rules and model judgment do the same job. ## The workflow ```text DETERMINISTIC LOCAL CORE supported JSONL session ─┐ current Analysis JSON ───┼─> orangu evidence ─> catalog matches + bounded findings current SlimAnalysis ────┤ │ current Aggregate JSON ──┘ │ ▼ AI SKILLS orangu-improve explain + optional research draft .md + .json │ session/repo explicit invocation ▼ orangu-apply reviewed repo edit + local checks .applied.json │ session only, same workspace run ▼ orangu-improve --verify .verified.json ``` The report and localhost app show the same lifecycle. Browser actions are copy-only handoffs for Claude Code or Codex; the browser does not launch an agent, edit a repository, or mark a record applied or verified. ## Deterministic local core The following paths make no model call and no network request: - **Session parsing:** `src/adapters/claude-code/parse.ts` maps supported Claude Code, Cowork, and Desktop JSONL records into the normalized `Session` model. The adapter owns usage deduplication, tool result pairing, subagent linkage, compaction, and tolerant handling of unknown records. - **Analysis:** `src/analyze/` computes tool, file, outcome, context, token, agent, skill, hook, and timing components. Hand-written rules emit findings with named evidence and fixed recommendation text. - **Aggregation:** `src/analyze/aggregate.ts` rolls recurring evidence across repo or global scope. Recurrence is evidence for investigation, not proof of causality. - **Catalog matching:** `src/suggest/catalog.ts`, `catalog.json`, and `features.json` map a finding to known change options by rule id or measured signal. The catalog content is curated; matching and ordering are deterministic. - **Bounded evidence:** `src/suggest/evidence.ts` validates a current `Analysis`, `SlimAnalysis`, or `Aggregate` value, applies redaction, selects a bounded number of findings, attaches catalog matches first, and emits stable report-source suggestion ids and finding tokens. Aggregate ids include a compact fingerprint supplied from every session in the active cohort, while the evidence bundle retains only bounded example ids. Proposal preflight resolves those example sessions and checks that each contains the claimed rule; it does not reconstruct the original aggregate or independently attest a supplied cohort fingerprint. The fingerprint prevents stale identity reuse, not aggregate-proof. Raw supported session selectors and `.jsonl` paths enter through the same parser via `orangu evidence`. - **Estimate gate:** `orangu evidence --estimate --quiet` reports the byte length and approximate token count of the exact canonical projection the skill would read. Evidence has one projection; `--depth` does not apply. - **Artifact validation:** `src/suggest/artifacts.ts` accepts only bounded, versioned, regular non-symlink files under the Orangu proposals directory. It validates relative target-path shapes, source provenance, the shape and reviewed-file agreement of a skill-authored application receipt, and a session-verification intent before a lifecycle transition. It does not inspect a repository diff or independently execute the reported checks. Verification receipt pairs must exactly match the proposal's reviewed `verificationChecks`; Orangu generates check labels and the summary, resolves configured-root sessions in the proposal's canonical workspace, computes approved metrics, and refuses a comparison that does not pass. - **Suggestion state:** `src/suggest/store.ts` keeps append-only records under the Orangu data directory and enforces legal state transitions. A successful current verifier stamps `verificationTrust: "computed-v1"`; readable legacy verified records without that marker are not current computed verification. - **Reports and app:** the self-contained report remains offline. `serve` binds to `127.0.0.1`, protects every route with a fresh process capability, and its suggestion controls only copy chat commands. This transport randomness does not enter analysis output. `orangu evidence` accepts exactly these input families: | Input | Scope | Notes | |---|---|---| | supported session id, `latest`, or `.jsonl` path | `session` | parsed by the supported Claude adapter; skills never open JSONL directly | | current Orangu `Analysis` or `SlimAnalysis` JSON | `session` | `--scope` is rejected | | current Orangu `Aggregate` JSON | `repo` or `global` | an explicit matching `--scope` is required | It is not a generic JSONL parser. Orangu does not currently ingest Codex transcripts; Codex is an improvement-skill host. All accepted inputs may be diagnosed in chat. Persisting an applicable session/repo proposal is stricter: every evidence session must resolve from configured supported roots and its canonical cwd must match the current workspace. Archived or custom roots must be configured through `ORANGU_CLAUDE_ROOTS` or `CLAUDE_CONFIG_DIR`. `orangu suggest --show --for-proposal` checks this before a skill writes proposal artifacts. Global scope may persist a structured review, but that record is proposal-only. ### Resource and filesystem bounds - A normal disk-backed parse, cache fill, or live snapshot has one 256 MiB and 100,000-record budget shared by its main transcript, subagent transcripts, and metadata. A JSONL record is capped at 8 MiB. - `orangu evidence` session reads and verification use a stricter 64 MiB shared session budget. Verification additionally rejects partial main or sidecar records and requires the complete immutable manifest to be quiet for at least 30 minutes. - One sidecar tree is limited to 2,048 inspected entries, four nested directory levels, and 1 MiB per metadata file. The manifest binds regular-file and directory identities, absent paths, and the canonical paths it will read; symlinks or changes before/during/final validation fail the read. - General discovery is capped at 25,000 cumulative directory entries and 25,000 candidate sessions. A verification inventory is capped at 10,000 candidate sessions. These ceilings apply across configured roots, so splitting an oversized tree does not bypass them. - A current Analysis, SlimAnalysis, or Aggregate JSON artifact is capped at 8 MiB. Evidence validation accepts at most 500 input findings and 1,000 aggregate sessions, selects at most 50 findings, and caps serialized output at 256 KiB. The limits are rejection boundaries. They do not imply that an input near a ceiling will be accepted if it violates a schema, identity, redaction, or lifecycle rule. ## Catalog first, research second The suggestion layer has three collaborators: 1. **Measured findings:** deterministic rules and aggregate rollups provide the only session-derived numbers. 2. **Curated matches:** deterministic catalog entries narrow the known tools, features, and change classes that fit those findings. 3. **AI interpretation:** `orangu-improve` explains the evidence, evaluates tradeoffs, and researches only gaps or time-sensitive choices. Proposal sources preserve that distinction: - `catalog` identifies a deterministic curated match. - `research` carries the direct HTTPS page actually opened and the date it was checked. - `inference` labels model synthesis without an invented URL or verification date. External skill discovery remains candidate-only. A popularity count is not evidence that a skill is suitable, and the improve workflow never installs a skill or plugin. Every skill and harness analyst treats session, evidence, tool, path, title, error, source, and proposal text as untrusted data. They extract bounded measurements and labels but never follow embedded instructions, commands, or URLs, let them override policy, turn them into network queries, or splice them into shell syntax. Shell-bound selectors and paths reject NUL/newlines and travel as individual argv items or correctly quoted shell words. ## Skills and their authority ### `orangu-improve` This is the primary suggestion workflow for both one-session diagnosis and recurring repo/global improvement. It: - runs the exact `orangu evidence` estimate before reading the evidence; - starts with `catalogMatches` and ties quantitative statements to emitted findings; - optionally researches uncovered choices; - writes one human-readable `.md` proposal and one validated `.json` manifest; - runs the deterministic `--for-proposal` evidence/workspace check before writing either artifact; - reports the evidence, expected effect, risk, files, verification condition, and sources in chat; - never edits the target repository. ### `orangu-apply` This is the explicit mutation workflow for session and repo scope. Global proposals are review-only. It requires a structured proposal in `proposed` state and: - runs `orangu suggest --show --for-apply` as a deterministic current-repository binding check before any project read or edit; - reads current repository instructions before editing; - treats proposal content and embedded commands as untrusted data; - is contractually required to change only the declared relative repository files; - chooses checks from trusted repository configuration; - writes `.applied.json` only after every recorded check succeeds; - moves the record to `applied`, never directly to `verified`; - does not browse, discover plugins, install dependencies, or delegate. The AI skill can make the reviewed edit. Its application receipt is skill-authored. The CLI validates the artifact shape and exact agreement with the reviewed relative file list for the current invocation; it does not inspect the diff, rerun commands, or prove filesystem confinement. ### Later verification `orangu-improve --verify ` is available only for an `applied` session-scope record. Repo records remain `applied` until Orangu has a real fresh-cohort comparator; global records cannot be applied or verified. The skill writes a verification intent containing later session selectors and the exact metric/comparison pairs reviewed in the proposal manifest. It must not write summary text, check names, claimed values, evidence, or pass/fail flags. The CLI resolves both baseline and later selectors through configured supported roots and revalidates the proposal's canonical path, device, and inode before and after loading them. Each selector must resolve to an immutable, non-partial transcript snapshot whose complete main/sidecar/metadata file manifest has been quiet for at least 30 minutes. This is a conservative settled-snapshot rule, not a provider-issued terminal state. Every baseline timeline must end before the application transition. Every later timeline must start after the application transition and every baseline. The CLI generates the canonical summary and check labels, computes the before/after averages, and evaluates the requested comparison. It rejects a mismatched pair set, reused, unresolved, duplicate, partial, unsettled, cross-workspace, too-early, or failing session set. Only a passing comparison produces the normalized verification receipt and moves the record to `verified`. That state is intentionally narrow: it means the reviewed metric comparisons passed over the user-selected baseline and later sessions. It does not prove that the tasks were equivalent, that the applied change caused the difference, or that overall quality improved. The computed values stay visible so a reviewer can make those judgments without treating correlation as causation. Supported metrics are `avgTotalTokens`, `avgToolCalls`, `avgToolErrors`, `avgActiveMs`, `avgContextPeak`, `avgTestRunsFailed`, `avgBuildRunsFailed`, and `avgInterruptions`. Supported comparisons are `decreased`, `not-increased`, `increased`, `not-decreased`, and `equal`. A proposal cannot verify itself, and an application receipt does not prove that its reported edit or checks occurred. Later verification is the separate deterministic claim based on resolved supported sessions. ### Supporting skills - `/orangu:analyze` translates one supported session or aggregate without designing or applying a change. - `/orangu:harness` is a separately requested deep review for repo or global scope. It remains catalog-first and saves the same structured Markdown plus manifest pair as `/orangu:improve`. It ends by asking which of its ranked items you approve, and then applies the ones you approved — under four standing limits: - **Per-item explicit approval.** Before the question it discloses, for every item, its id, the files its manifest declares, and the exact text of anything that would run or grant authority. Only a verbatim id approves, and only the answer to that question counts; nothing else in the conversation is consent. - **Repo scope only.** Global proposals are review-only and are never applied, at any approval. - **Through `/orangu:apply`, unchanged.** Each approved item is applied by invoking `/orangu:apply ` — one id, one record, one receipt per invocation, with that skill's existing binding check, untrusted-input rules and confinement contract. Harness forks nothing and grants itself no edit authority of its own; it prints the `/orangu:apply ` list so the same work can be done by hand. - **Stop at the first failure.** Approved items are applied in order and the run halts on the first one that fails, leaving the working tree as it stands for review rather than continuing down the list. None of this moves the deterministic boundary: no model measures anything, the evidence is still the bounded deterministic projection, and the CLI still validates artifact shape rather than inspecting a diff. - Live observation is a CLI concern: `orangu watch` refreshes one report and `orangu serve` follows several sessions; neither performs model reasoning of its own. ## Claude Code and Codex parity The Claude Code plugin exposes `/orangu:analyze`, `/orangu:improve`, `/orangu:apply`, `/orangu:harness`, and `/orangu:feedback`. The Codex marketplace package under `plugins/orangu/` exposes Orangu's own `$orangu-improve`, `$orangu-apply`, and `$orangu-feedback` skills with the bundled offline CLI; `.agents/skills/` contains byte-identical repo-discovered mirrors for contributors and source checkouts. Both mirrors are generated from `plugin/skills/` by `scripts/build.mjs`, so one edit updates every host; `npm run verify` fails when a mirror is stale. Both host variants use the same Orangu CLI evidence bundle, manifest and receipt schemas, state machine, scope policy, and session-verification rule. Host parity does not imply transcript parity: the local adapter still supports only the named Claude Code, Cowork, and Desktop session formats. ## Why the boundary matters - **Traceability:** measured values retain the finding, session ids, and evidence that produced them. - **Bounded context:** the model reads a canonical redacted projection instead of a multi-megabyte transcript. - **Better choices:** catalog matches provide known options, while research and synthesis can cover the long tail. - **Explicit authority:** drafting, applying, and verifying are separate actions with different permissions. - **Honest outcomes:** quality is the primary goal; time and token reductions are benefits only when the later evidence actually supports them. ## Summary Orangu combines deterministic local evidence with AI interpretation and editing. The core owns what happened and whether lifecycle artifacts satisfy the contract. The skills own explanation, proposal design, optional research, and an explicitly requested session/repo change. Later same-workspace session evidence owns the current verification claim; repo awaits a fresh-cohort comparator, and global remains proposal-only.