# Install One Code

[← One Code user guide](README.md)

One Code ships as two npm packages from one repository. Choose the one that
fits how you already work.

| You | Install | What you get |
|---|---|---|
| New to this, or you want the simplest setup | `npm install -g @one-ai/one-code` | The bundled app: its own `onecode` command, a pinned version of the pi coding agent inside it, and its state kept in `~/.onecode`. It coexists with any `pi` you already have. |
| On Windows without Node.js | `powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 \| iex"` | The bundled app, with Node.js fetched for you when the machine has none. See [Install on Windows](#install-on-windows). |
| Already running [pi](https://github.com/earendil-works/pi) | `pi install npm:one-code-extension` | The extensions only. They run on your existing pi. One Code's own state still goes to `~/.onecode`; pi's own files stay under your pi agent directory (`~/.pi/agent`). |

## Requirements

- Node.js 22.19 or later. The app refuses to start on older versions,
  because pi crashes at import time there.
- macOS, Linux, or Windows. Windows Subsystem for Linux (WSL) works like
  Linux. On native Windows, One Code takes Claude Code's shape: Git for
  Windows is recommended but optional, and PowerShell is the primary shell
  tool. See [Windows](windows.md) for what is verified and what isn't.
- `git`. Optional: `rg` (ripgrep) for faster search, the GitHub CLI for the
  pull-request marker in the footer, and a language server for your
  language (see
  [Language-server diagnostics](configuration.md#language-server-diagnostics)).

## Install the app with npm

```bash
npm install -g @one-ai/one-code
cd your-project
onecode
```

On the first run there's no provider yet: the banner shows `model none`.
Run `/login` inside One Code to connect a provider, or set a provider key
in your environment before launching. For a free option, see
[Providers and models](providers-and-models.md).

The first run also seeds pi's settings under `~/.onecode/agent/` with the
`onecode` theme, quiet startup, and full-screen mode. It never overrides a
value you change later.

## Install on Windows

Open Windows Terminal or PowerShell and run:

```powershell
powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
```

The script looks for Node.js 22.19 or later on your PATH. When there is
none, it downloads the current Node LTS for your CPU from nodejs.org as a
zip, checks it against nodejs.org's published checksums, unpacks it under
`%LOCALAPPDATA%\onecode\node`, and adds that folder to your user PATH.
Nothing is installed system-wide and no Windows installer runs. It then
runs `npm install -g @one-ai/one-code` and makes sure the `onecode` command
is on your PATH. Open a new terminal afterwards so it sees the PATH change.

The script also tells you when `git` is missing. One Code runs without it,
but Git for Windows gives you the branch in the footer, `/init`, worktrees,
and a bash tool for the model next to PowerShell. Install it with
`winget install --id Git.Git -e`, or set `ONECODE_INSTALL_GIT=1` before
running the script to have it do that for you.

If you already have Node.js 22.19 or later, the plain npm command works the
same on Windows as anywhere else:

```powershell
npm install -g @one-ai/one-code
```

The script's knobs are environment variables, because a piped script
cannot take parameters: `ONECODE_INSTALL_NODE=1` downloads the standalone
Node even when one exists, `ONECODE_NODE_VERSION` pins the version it
downloads, and `ONECODE_NO_PATH_UPDATE=1` leaves your PATH alone and prints
what to add. Read the script before running it if you like; it is the
`install.ps1` at the root of the repository.

Windows Subsystem for Linux (WSL) is Linux: use the npm or Homebrew route
inside the distribution. For what works on native Windows, see
[Windows](windows.md).

## Install with Homebrew

Homebrew installs Node for you, so this route has no separate Node step:

```bash
brew install isurumaduranga/one-ai/onecode
```

The formula and the command it installs are both named `onecode`.
Homebrew refuses npm packages published less than a day ago, so a release
becomes installable this way about a day after it appears on npm.

## Install the extension on your own pi

If you already run pi, add One Code as an extension:

```bash
pi install npm:one-code-extension
```

Use `pi` in place of `onecode` for every command in this guide. The
extension is tested against pi 0.83 through 0.86 and warns at startup when
your pi is outside that range. Full-screen mode is opt-in on your own pi;
see [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).

A few interface refinements are applied only by the bundled app, because
they patch pi internals the extension API can't reach: a clean exit that
erases the screen in regular mode, and suppression of pi's "Operation
aborted" line when you interrupt a reply. Everything else is identical.

## Install from source

```bash
git clone https://github.com/IsuruMaduranga/one-code
cd one-code
npm install
cd ..
pi install ./one-code
pi list
```

Run `npm install` before the path install so the dependencies are present.
`pi list` confirms the package registered.

## Check the installation

```bash
onecode --version    # prints the app version and the pi version inside it
onecode doctor       # prints the setup report; exits 1 when no provider is ready
```

Inside a session, `/doctor` runs the full checkup. See
[Check your setup with doctor](doctor.md).

## Update

The bundled app checks npm once a day when a session starts and shows a
notice with the matching upgrade command when a newer version exists:

```bash
npm install -g @one-ai/one-code      # npm installs
brew upgrade onecode                 # Homebrew installs
```

A Homebrew install sees the notice a day after the npm release, because
Homebrew refuses packages younger than that and `brew upgrade` would find
nothing sooner. Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check;
`--offline` skips it too.
On your own pi, update with `pi update --extensions`.

Both packages are released together with the same version number.

## Uninstall

```bash
npm uninstall -g @one-ai/one-code    # or: brew uninstall onecode
rm -rf ~/.onecode                    # One Code's state, including pi's under the app
```

If the Windows script fetched Node.js for you, delete `%LOCALAPPDATA%\onecode`
too and remove that folder from your user PATH. On your own pi, run
`pi remove one-code-extension` (or remove the package entry from pi's
settings). Removing `~/.onecode` deletes One Code's
settings, approvals, plan files, and, under the bundled app, pi's sessions
and credentials. Memory files stay in `~/.claude/projects/`, because they
are shared with Claude Code.

## Next step

Connect a provider and choose a model in
[Providers and models](providers-and-models.md).