Install Tokenade

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.

npm install -g @tokenade/cli
tokenade install

After that, link the machine to your account with tokenade login (see Log in and activate a machine).

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

A free tokenade.net account, used at the login step. No card is needed for the free plan; see pricing for what each plan includes.

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 listed in the release manifest on downloads.tokenade.net, checks its SHA-256 against the 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:

tokenade --version

tokenade 1.2.2

What `tokenade install` does

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

Detects the coding agents installed on the machine (Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Kilo Code, and the others listed in compatibility).
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.
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.
Routes your third-party MCP servers through tokenade mcp-wrap, so their large results are folded. See Wrap MCP servers.
Sets up the local 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.
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, Codex, Cursor, 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:

✗ 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

For a deliberate root install, set TOKENADE_ALLOW_ROOT=1.

Preview before writing

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
`--ref <code>`	Record a referral code

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.

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:

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.