# Installation

Tokenomy is distributed as a Pi package (not a native Codex CLI extension).
After installation, it routes prompts through Pi's `openai-codex` provider to
cheaper models when safe, upshifts for risky work, and uses local project
memory plus prompt compression to reduce estimated plan-credit consumption and
avoidable context tokens without changing the final user prompt.

## Requirements

- Pi installed and working locally
- Node.js 22.19 or newer
- ChatGPT Plus Codex access authenticated in Pi (the live-tested setup)
- `openai-codex` models available in `pi --list-models openai-codex`

ChatGPT Pro has not been tested and is outside the supported subscription
scope. It may work, but Tokenomy currently makes no Pro compatibility claim.

## Install with Pi

Recommended npm install:

```bash
pi install npm:tokenomy-pi
```

Project-local npm install:

```bash
pi install -l npm:tokenomy-pi
```

The unqualified package is the normal supported install and update path shown
on pi.dev.

GitHub install also works:

```bash
pi install https://github.com/adyshev/tokenomy
```

Install project-locally instead of globally:

```bash
pi install -l https://github.com/adyshev/tokenomy
```

SSH install also works if you prefer GitHub SSH auth:

```bash
pi install git:git@github.com:adyshev/tokenomy
```

For a pinned release or commit:

```bash
pi install https://github.com/adyshev/tokenomy@v0.2.0-beta.4
```

`pi install` reads the `pi` manifest from `package.json` and enables the
Tokenomy extension declared there. A normal install makes the package available
to Pi generally; `-l` limits the package registration to the current project.
In both cases, Tokenomy's generated state and project config stay under the
project's `.pi/` directory.

## Project Config

Tokenomy works with built-in defaults after package install. Add
`.pi/tokenomy.json` only when you want to customize model IDs, UI settings,
classifier behavior, or tool management.

Example project config:

```json
{
  "provider": "openai-codex",
  "ui": {
    "notifyDecisions": true
  }
}
```

See `CONFIG.md` for all options.
For a guided first session, routing examples, feedback, reports, budgets,
memory, and compaction, see `USAGE.md`.

## Manual Development Install

For local development, you can install from a checked-out path:

```bash
pi install ./path/to/tokenomy
```

Or load it for one run without adding it to settings:

```bash
pi -e ./path/to/tokenomy
```

Manual copy still works, but `pi install` is preferred:

```bash
mkdir -p .pi/extensions/tokenomy
cp /path/to/tokenomy/.pi/extensions/tokenomy/index.ts .pi/extensions/tokenomy/index.ts
cp -R /path/to/tokenomy/.pi/extensions/tokenomy/lib .pi/extensions/tokenomy/lib
cp /path/to/tokenomy/.pi/tokenomy.json .pi/tokenomy.json
cp /path/to/tokenomy/.pi/tokenomy.schema.json .pi/tokenomy.schema.json
```

## Verify

List available Codex models:

```bash
pi --list-models openai-codex
```

Start Pi in the project:

```bash
pi
```

Inside Pi, run:

```text
/tokenomy doctor
/tokenomy status
```

You should see Tokenomy enabled, the configured provider, and the last routing
decision once you send a prompt.

Commands that change routing mode, enabled state, dry-run, debug, or memory
state apply to the current Pi process. Put the equivalent option in
`~/.pi/agent/tokenomy.json` or `.pi/tokenomy.json` when it should persist.

## Disable

Disable for the current Pi run:

```bash
pi --tokenomy-off
```

Disable inside a running Pi session:

```text
/tokenomy off
```

Preview routing without changing model, thinking, or active tools:

```text
/tokenomy dry-run on
```

Show why the last route happened:

```text
/tokenomy explain
```

Reset local lifetime counters:

```text
/tokenomy reset-stats
```

Disable by config:

```json
{
  "enabled": false
}
```

## Update

Update installed Pi packages:

```bash
pi update --extensions
```

Pinned git installs do not move automatically. To move a pinned install, run
`pi install` again with the new tag or commit.