animawake docs

Connect

Connect Codex

Connect an entity to the Codex CLI and Codex desktop app with the animawake CLI, or as a remote MCP server.

Codex reads MCP servers from ~/.codex/config.toml, and the Codex CLI and desktop app share that file. The simplest setup is the animawake CLI, which writes the server entry, a wake skill, and session hooks for you.

#With the animawake CLI

You need Node.js 20.17 or newer (22.13 or newer on Node 22) and Codex installed.

  1. In your project directory, run:

    Terminal
    npx animawake setup --codex

    Without --codex, setup configures every engine it finds: Claude Code, Codex, or both.

  2. Your browser opens the portal's CLI sign-in page. Pick the entity. The CLI receives a new entity key and writes:

    File Purpose
    ~/.codex/config.toml A [mcp_servers.<entity-slug>] block that runs the stdio bridge.
    ~/.codex/skills/<entity-slug>/SKILL.md A wake skill that loads the entity.
    AGENTS.md A block, between animawake:<entity-slug> markers, telling Codex to wake as the entity on the first turn.
    .codex/hooks.json Session hooks that capture transcripts for continuity.
    .animawake.json The entity slug, workspace slug, and key. Owner-only permissions, added to .gitignore.

    The server block looks like this:

    TOML
    [mcp_servers.<entity-slug>]
command = "npx"
args = ["-y", "animawake", "mcp", "<entity-slug>"]

  3. Launch Codex as the entity:

    Terminal
    npx animawake <entity-slug> --codex

    If you use Codex more than Claude Code, make it the default with npx animawake set-default codex.

The launcher starts Codex with --dangerously-bypass-approvals-and-sandbox, so commands run without approval prompts or sandboxing. To keep Codex's approvals, run codex yourself in the project; the MCP tools and the AGENTS.md wake instructions still apply.

#Where the key comes from

The server entry in ~/.codex/config.toml is global, but the bridge looks up the key in .animawake.json, starting in the current directory and walking up. Run Codex inside the project (or a subdirectory) where you ran setup. To use the entity anywhere, set ANIMAWAKE_API_KEY to an ent_ key in your environment; the bridge checks it first.

#Session hooks in Codex

Continuity capture uses Codex hooks. If your ~/.codex/config.toml has hooks = false under [features], the hooks do not run; npx animawake status reports this.

#As a remote MCP server

Recent Codex versions can connect to streamable HTTP servers directly. Check codex mcp --help for the commands your version supports.

With OAuth:

Terminal
codex mcp add <entity-slug> --url https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/
codex mcp login <entity-slug>

Codex opens the browser and receives the token on a loopback address, which Animawake allows.

With an entity key, add the server to ~/.codex/config.toml and keep the key in an environment variable:

TOML
[mcp_servers.<entity-slug>]
url = "https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/"
bearer_token_env_var = "ANIMAWAKE_API_KEY"
Terminal
export ANIMAWAKE_API_KEY=ent_your_key_here

#Check the connection

In Codex, ask:

Text
Call get_startup and tell me who you are.

Run /mcp in the Codex CLI to list connected servers and their tools.

#Troubleshooting

  • no key configured for entity '<slug>': Codex was started outside the project that holds .animawake.json. Start it in the project, set ANIMAWAKE_API_KEY, or run npx animawake add in the new directory.
  • API key for '<slug>' rejected: the key was deleted or expired. Run npx animawake rotate-key <entity-slug>.
  • The entity does not wake on the first turn: make sure AGENTS.md contains the animawake:<entity-slug> block, or invoke the wake skill by name.

For more, see Connection troubleshooting.