# Install Tokenade

> Install Tokenade with npm on Linux, macOS or Windows, then run tokenade install to wire it into every coding agent it detects.

Source: https://tokenade.net/en/docs/install · Updated: 2026-10-16

To install Tokenade, install the npm package globally, then run `tokenade install` once as your normal user. The first command puts the binary on your machine; the second connects it to the coding agents it finds.

```bash
npm install -g @tokenade/cli
tokenade install
```

That's all: there is nothing to activate. Tokenade is free and open source (MIT/Apache-2.0); the code is on [GitHub](https://github.com/pi-infected/tokenade).

Prefer to let your agent do it? Paste this into your coding agent: "Install Tokenade for me: read https://tokenade.net/install.md and follow the instructions."

## Requirements

- Node.js 18 or later (only for the npm installer; Tokenade itself is a native binary).
- One of the supported platforms:

| OS | Architectures |
|---|---|
| Linux | x64 (glibc and musl), arm64 (musl) |
| macOS | Apple Silicon (arm64), Intel (x64) |
| Windows | x64, arm64 |

## What the npm package does

`@tokenade/cli` ships one optional dependency per platform. npm installs the one matching your machine, and the `postinstall` step uses it directly (`tokenade provided by @tokenade/cli-... — no download needed`).

If that platform package is missing, `postinstall` falls back to downloading the binary from the matching [GitHub Release](https://github.com/pi-infected/tokenade/releases), verifies the release manifest against its Ed25519 signature, checks the archive's SHA-256 against that signed manifest, and checks that the file really is an executable for your OS before keeping it.

The download honours your proxy settings and has a timeout:

| Variable | Effect |
|---|---|
| `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` (and lowercase forms) | Route the download through your proxy |
| `NO_PROXY` / `no_proxy` | Hosts that bypass the proxy |
| `TOKENADE_HTTP_TIMEOUT_MS` | Per-request timeout in milliseconds (default `30000`) |

Network errors are retried; a 4xx response (other than 429) or a checksum mismatch is not.

Check the binary:

```bash
tokenade --version
```

```text
tokenade 2.0.1
```

## Upgrading from 1.x

If auto-update is on (the default), your 1.x install moves to 2.0 by itself. Otherwise, run:

```bash
npm i -g @tokenade/cli@latest
```

The licence and account files left by 1.x are cleaned up during the upgrade.

## What `tokenade install` does

`tokenade install` is zero-config. In one run it:

1. Detects the coding agents installed on the machine (Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Kilo Code, and the others listed in [compatibility](https://tokenade.net/en/docs/compatibility)).
2. Wires Tokenade into each one through that agent's own mechanism: hooks for Claude Code, Codex, Cursor, Copilot CLI, Qwen Code, Grok, Droid and the Antigravity CLI; a plugin or extension for OpenCode, Kilo Code, Cline, Hermes, Pi and OpenClaw.
3. Writes a short Tokenade rules section into the global rules file each agent loads (for example `~/.claude/CLAUDE.md` or `~/.codex/AGENTS.md`), and scaffolds project rules in the current folder.
4. Routes your third-party MCP servers through `tokenade mcp-wrap`, so their large results are folded. See [Wrap MCP servers](https://tokenade.net/en/docs/mcp-wrap).
5. Sets up the local [LLM proxy](https://tokenade.net/en/docs/llm-proxy) for an agent only where it adds a feature the agent's hooks cannot provide (for example Codex while its hooks are not approved). It binds `127.0.0.1` and prints how to undo it.
6. Enables `~/.tokenade/debug.log`, which `tokenade hooks tail` reads.

Every config file it edits is merged, not replaced: your own hooks, MCP servers and rules stay as they are. Each agent page lists the exact files: [Claude Code](https://tokenade.net/en/docs/claude-code), [Codex](https://tokenade.net/en/docs/codex), [Cursor](https://tokenade.net/en/docs/cursor), [Copilot](https://tokenade.net/en/docs/copilot).

### Do not use sudo

Run `tokenade install` as yourself. Under `sudo` it refuses, because it would write into `/root` and your agent would never see the hooks:

```text
✗ running under sudo: this would install into /root, not your own HOME —
  your AI agent would never see the hooks (and everything would LOOK fine).
  Re-run WITHOUT sudo: tokenade install
  (intentional root install: TOKENADE_ALLOW_ROOT=1 tokenade install)
```

For a deliberate root install, set `TOKENADE_ALLOW_ROOT=1`.

### Preview before writing

```bash
tokenade install --dry-run
```

`--dry-run` prints every file it would change, including the Codex `config.toml` trust entries, and writes nothing.

## Install flags

| Flag | Effect |
|---|---|
| `--yes`, `-y` | Assume yes for destructive cleanup prompts |
| `--dry-run` | Print what would be done, change nothing |
| `--only <agent>` | Restrict the install to one agent |
| `--per-project` | Install into `./.<agent>/` instead of your home directory |
| `--profile <name>` | Use a domain-tailored CLAUDE.md template |
| `--no-cleanup` | Skip the incompatible-tools fix-up pass |
| `--no-debug-log` | Do not enable `~/.tokenade/debug.log` |
| `--debug-log <path>` | Custom debug log location |
| `--autocompact-pct <N>` | Ask the agent to auto-compact at N% of its context window (10-95, default 70) |
| `--no-autocompact` | Remove the auto-compact threshold Tokenade set (a hand-set value is left alone) |
| `--no-hook` | Skip the Claude Code PostToolUse and Edit/Write auto-index hooks |
| `--no-wrap-mcps` | Do not route third-party MCP servers through `tokenade mcp-wrap` |
| `--with-claude-md` | Add a framework-aware CLAUDE.md (Next.js, FastAPI, Rust…) |
| `--with-brevity-skill` | Add a terse-response style hint to CLAUDE.md (can degrade reasoning on complex tasks) |
| `--defaults` | Forget the choices remembered from earlier installs |

Agent names accepted by `--only`: `claude-code`, `codex`, `cursor`, `copilot`, `kilo-code`, `opencode`, `cline`, `hermes`, `pi`, `openclaw`, `qwen-code`, `antigravity`, `grok`, `droid`, `aider`, `t3-code`, `devin-desktop` (`windsurf` is a deprecated alias of `devin-desktop`). `--only` narrows the detected agents to one: if that agent is not found on the machine, install stops and suggests the closest detected name.

```bash
tokenade install --only claude-code    # just Claude Code
tokenade install --per-project         # ./.claude/ instead of ~/.claude/
```

### Remembered choices

Install remembers the opt-outs and choices you pass (`--no-hook`, `--only`, `--per-project`, `--no-debug-log`, `--debug-log`, `--no-autocompact`, `--no-wrap-mcps`, `--profile`, `--with-*`). Every later install, upgrade and self-repair reuses them. To start again from the defaults:

```bash
tokenade install --defaults
```

### Other token tools

Install also looks for other token-saving tools that conflict with Tokenade and proposes fixes. Run the check on its own with `tokenade incompatibilities`, or skip the fix-up pass with `--no-cleanup`.

## Re-running install

`tokenade install` is idempotent. Re-run it after installing a new agent, or when `tokenade healthcheck` reports something missing. Updates refresh the hooks and plugins on their own; see [Upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall).

## Related

- [Check it works: your first session](https://tokenade.net/en/docs/first-session)
- [Supported agents and compatibility](https://tokenade.net/en/docs/compatibility)
- [Upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall)
- [Environment variables](https://tokenade.net/en/docs/environment-variables)