CLI

The animawake npm package configures Claude Code and Codex projects for an entity, launches sessions as the entity, captures session transcripts for continuity, and bridges MCP over stdio. It needs Node.js 20.17 or newer (22.13 or newer on Node 22). Run it with npx; no global install is required:

npx animawake <command>

Most commands work on the current directory: setup and add configure the project you run them in, and launches look for .animawake.json there.

#Commands

An unknown first argument is treated as an entity slug, so npx animawake foo tries to launch an entity named foo.

#setup

npx animawake setup
npx animawake setup --claude
npx animawake setup --codex

Sets up the current directory for one entity:

1. Prints install hints if Claude Code or Codex is missing.
2. Opens https://app.animawake.com/cli-auth in the browser, where you pick the entity. The page sends a new entity key, named "Claude Code CLI", to a temporary server on 127.0.0.1. The CLI waits up to 2 minutes.
3. Confirms the key with the server and writes the files for each engine it finds. --claude or --codex chooses the engines instead: only the engines you name are configured, even one that is not installed yet. Pass both flags to configure both.
4. Installs the continuity runtime in ~/.animawake and writes session hooks.
5. If both Claude Code and Codex are installed, you passed no engine flag, and you have no default yet, asks which one npx animawake <entity-slug> should launch and saves the answer in ~/.animawake/preferences.json.

setup refuses to run if .animawake.json already lists an entity; use add instead. If a legacy .animawake file exists, run migrate first.

#add

npx animawake add
npx animawake add --key ent_your_key_here
npx animawake add --codex

Adds another entity to the same project. Without --key, it signs in through the browser like setup. With --key, it identifies the entity from the key. --claude and --codex choose the engines the same way as in setup. It fails if the entity is already configured; use rotate-key to replace its key.

#Launching

npx animawake <entity-slug>
npx animawake <entity-slug> --codex
npx animawake <entity-slug> --claude --mode deep_work
npx animawake claude <entity-slug>
npx animawake codex

Other arguments are passed to Claude Code or Codex.

For npx animawake <entity-slug>, the engine is chosen in this order: a --claude or --codex flag; the only engine installed; your default from set-default or ANIMAWAKE_DEFAULT_SUBSTRATE; otherwise Claude Code. The interactive launcher (launch, or npx animawake with no command) ignores the saved default: when both engines are installed and you pass no flag, it asks which one to use every time. npx animawake claude and npx animawake codex always use that engine.

The launcher sets ANIMAWAKE_ENTITY, ANIMAWAKE_MODE, ANIMAWAKE_PROJECT, and ANIMAWAKE_SUBSTRATE, so the session hooks wake the entity and capture the transcript. A slug launch sets ANIMAWAKE_PROJECT to the directory name unless you already set it. The interactive launcher always sets it to the name of the project you picked, replacing any value you set.

Permissions. The launcher starts Claude Code with --dangerously-skip-permissions and Codex with --dangerously-bypass-approvals-and-sandbox. The agent runs tools and commands without asking. Use the launcher only in projects where that is acceptable, or start claude or codex yourself to keep approval prompts.

launch lists projects it knows from ~/.animawake/projects.json and finds others with an .animawake.json or .animawake file in ~/Documents/GitHub, ~/projects, and ~/code.

#list, status, remove

npx animawake list
npx animawake list --refresh
npx animawake status
npx animawake remove <entity>

• list shows each configured entity with its workspace, and any Hermes entities provisioned on this machine. --refresh looks up Hermes slugs again.
• status checks each entity's key against the server and reports, for Claude Code and Codex, whether the continuity hooks are configured, when the journal last acknowledged a batch, and the age of the oldest queued batch. It never prints keys.
• remove deletes the entity from .animawake.json and removes its agent file, its .mcp.json entry, its Codex server block and skill, its AGENTS.md block, and its Claude Code skill folder. It does not delete the key on the server.

#rotate-key

npx animawake rotate-key <entity>

Asks the server to rotate the stored key: the server issues a new key with the same name and deactivates the old one in the same step, and the CLI writes the new key to .animawake.json. If the stored key is already deleted or expired, it signs in through the browser instead, gets a new key, checks that it belongs to the same entity, and writes it. Other copies of the old key, such as in another project or config file, stop working and must be updated. See Access tokens and keys.

#set-default

npx animawake set-default codex
npx animawake set-default

Saves the default engine in ~/.animawake/preferences.json. Without an argument, prints the current default. The ANIMAWAKE_DEFAULT_SUBSTRATE environment variable overrides the saved value. The default applies only to npx animawake <entity-slug> launches without an engine flag; the interactive launcher asks instead.

#upgrade

npx animawake upgrade

Rewrites, for every entity in .animawake.json: the Claude Code agent file and .mcp.json entry, the Codex server block, wake skill, and AGENTS.md block, the seeyoulater session-close skills, the continuity runtime, and the hooks. Run it after updating the package.

#migrate

npx animawake migrate

Converts a project set up by an old version (a .animawake file with ANIMAWAKE_API_KEY=...) to .animawake.json. It backs up what it changes to .animawake.bak, .mcp.json.bak, ~/.codex/config.toml.bak, and .claude/settings.local.json.bak. Re-add any other entities afterward with add.

#mcp

npx animawake mcp <entity-slug>

A stdio MCP server that forwards every message to Animawake with the entity's key. setup registers it in .mcp.json and ~/.codex/config.toml. The key comes from ANIMAWAKE_API_KEY, or from .animawake.json found by searching upward from the working directory. See The stdio bridge.

#Hermes entities

These commands work with Hermes entities provisioned on this machine by the desktop app.

npx animawake hermes <entity>
npx animawake ask <entity> "Summarize yesterday's session."
echo "Long prompt" | npx animawake ask <entity> -
npx animawake ask-mcp

ask prints only the answer on stdout, so you can use it in scripts:

Pass - as the prompt to read it from stdin.

ask-mcp runs a local MCP server with two tools, ask_hermes and list_hermes_entities, so another agent can delegate to a Hermes entity.

#claude-lane

npx animawake claude-lane run "<prompt>" --entity <slug> --cwd <dir>
npx animawake claude-lane watch --lane <name> --entity <slug> --board <slug>

Advanced commands that run Claude Code sessions through a paired device. run sends one prompt into an interactive session (--timeout <sec>, --permission-mode standard|auto|bypass). watch services a work board lane (--poll <sec>, --once, --permission-mode).

#Files

#Environment variables

#Reserved slugs

Entity slugs that match a command cannot be used with the CLI: setup, add, list, remove, rotate-key, migrate, status, mcp, help, version, launch, claude, codex, upgrade, set-default, ask, ask-mcp, and hermes.

#Errors