# oonacode (npm wrapper)

OonaCode is a Windows-first, multi-provider coding agent: the genuine Claude Code engine (driven
through the official Claude Agent SDK) in an isolated profile, sessions in SQLite, any model
provider, and personal remote access to your own machines.

This package is the **npm/pnpm/bun/yarn entry point**. It contains no binaries itself; the native
build is pulled in through a per-platform optional dependency and linked into `bin/` by a
postinstall step (the same model as esbuild / opencode).

```
npm  install -g oonacode
pnpm add -g oonacode        # then: pnpm approve-builds   (allow the trusted postinstall)
bun  add -g oonacode        # then: bun pm trust oonacode
yarn global add oonacode
```

Then:

```
oona --help        # CLI (mirrors Claude Code flags: -p, --model, --output-format text|json|stream-json, --resume, ...)
oona serve         # start the host service (headless) + local web UI
oona web           # open the local web UI
```

## Platform packages

| Platform      | Package               | Status                                                  |
| ------------- | --------------------- | ------------------------------------------------------- |
| Windows x64   | `@oonacode/win32-x64` | shipped                                                 |
| Windows arm64 | —                     | later (x64 build runs under emulation)                  |
| Linux x64     | `@oonacode/linux-x64` | shipped with every release that carries Linux           |
| Linux arm64   | —                     | later                                                   |
| macOS         | —                     | not on npm (the terminal installer, `install.sh`)       |

Each platform package carries `oona.exe` (the single-binary host + CLI; `oona` on Linux), the local
web UI assets (`web-ui/`), the provider registry and native addons (`build/`, `prebuilds/`). The
pinned Claude Code engine sidecar, `oonaclaude.exe`, is in it only when the release bundled it;
otherwise the PC downloads it once into its own store on the first message (`docs/engine-once.md`).

`oonaclaude.exe` is a byte-for-byte copy of the pinned, **unmodified** engine binary from the Claude
Agent SDK platform package. OonaCode does not fork or patch Claude Code; the file is renamed only so
it can never be confused with, or collide with, your own `claude` on PATH.

## How `oona` resolves the binary

`bin/oona.js` looks for, in order: `bin/oona.exe` (linked by postinstall) → `@oonacode/win32-x64/oona.exe`
in place → the JS CLI `@oonacode/cli/dist/main.js` when that package is a dependency (developer
installs; slower start, needs an engine reachable via `OONACODE_CLAUDE_BIN`). The binary runs with
inherited stdio and its exit code is forwarded verbatim. If nothing is found it prints how to fix
it, including the Windows one-liner:

```
irm https://oonacode.oonak.ai/install.ps1 | iex
```

## Notes

- **pnpm / bun block lifecycle scripts by default.** Without the postinstall the wrapper still
  works (it resolves the platform package in place); linking only removes one resolution step.
- Set `OONACODE_SKIP_POSTINSTALL=1` to skip the link step entirely.
- Your own subscriptions and your own API keys always run direct from your PC to the provider
  (OonaCode translates on your PC where a provider needs it); only OonaCode's own pool goes through
  the OonaCode gateway. No credential is ever shared between users.
- In the monorepo `optionalDependencies` use `workspace:<version>` so pnpm links the sibling
  platform package. npm does not understand the workspace protocol, so what `packaging/release.ps1`
  publishes is a copy staged outside the repo by `packaging/scripts/stage-npm.mjs`, whose
  `optionalDependencies` are concrete versions and name only the platforms that release built
  (until 0.3.131 this directory was published as it was, and `npm i -g oonacode` failed with
  `EUNSUPPORTEDPROTOCOL` — review C18/C26, 2026-09-23).