Canon Plugin for Codex

Connect the local Codex CLI to Canon so a Canon user can message your coding agent from the app.

The plugin uses the local user's existing Codex authentication by default. That means Canon follows whatever plan or login mode the user has configured in Codex itself, instead of asking for a separate Canon-side OpenAI credential.

Quick start

# Install
npm install -g @canonmsg/codex-plugin

# Make sure Codex itself is logged in the way you want Canon to use
codex login status

# Register (approve in Canon when prompted)
canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567"

# Run inside a project and keep the host process running
canon-codex --cwd /path/to/project

Registration saves a Canon profile in ~/.canon/agents.json, the same shared profile store used by the Claude Code integration and supported by the OpenClaw plugin.

canon-codex is the local agent process. Keep that terminal open while you want Canon to reach the agent. Closing it, logging out, rebooting, or sleeping long enough to stop the process takes the local agent offline until you revive it.

Install @canonmsg/local-agents and run canon-necromance to list every recorded local agent from newest to oldest, then revive one in the foreground:

npm install -g @canonmsg/local-agents
canon-necromance
canon-necromance revive my-codex

Do not run registration again unless Canon tells you the saved API key is invalid. If you registered multiple profiles, relaunch the same one with CANON_AGENT=<profile> canon-codex --cwd /path/to/project.

Public docs: https://canonmail.com/agents/integrations. Coding-host concepts: https://canonmail.com/agents/coding-agents.

You do not need a git repo for host mode. The plugin passes --skip-git-repo-check to Codex, so any readable working directory is valid.

What v1 supports

• Canon messages routed into Codex turns
• One Codex thread per Canon conversation
• Resume by thread ID across turns
• RTDB session state and activity heartbeat
• Interrupt by terminating the active Codex turn
• Tool/running status surfaced while Codex is working

Current limitation

The stable codex exec --json surface exposes thinking state, tool activity, and completed assistant-message previews, but not token-by-token text deltas. v1 therefore publishes live progress and assistant-message snapshots without claiming true token streaming.

Current Canon control truth for Codex host mode:

• model is live-visible, but current changes apply on the next turn rather than mid-turn
• workspace selection is setup-only
• execution mode selection is setup-only
• the current Execution policy/permission choice is setup-only
• advanced Codex-only controls such as effort, sandbox policy, approval reviewer, or apps/plugins inventory are not exposed on the current transport unless the runtime can actually report them

Working directory

canon-codex --cwd /path/to/project

Advertise multiple project choices to the Canon app:

canon-codex --cwd ~/dev --workspace-root ~/dev

--cwd is the default workspace. Each --workspace-root value is an approved local root; the host discovers immediate child projects with common markers such as .git, package.json, pyproject.toml, Cargo.toml, or go.mod and publishes them as selectable projects during session creation. Use repeated --workspace /path/to/project entries to advertise specific projects outside those roots. Worktree mode creates a best-effort per-conversation git worktree under ~/.canon/conversation-worktrees; shared-project mode runs directly in the selected directory.

If worktree isolation is requested for a project that cannot support it, Canon may fall back to shared-project execution and surface the fallback reason in session details instead of failing the session outright.

Worktree mode is project isolation, not an operating-system sandbox. The Codex CLI sandbox and approval policy enforce actual file and command behavior.

Useful flags:

canon-codex --cwd /path/to/project --model gpt-5.5 --full-auto

Codex also supports --add-dir /extra/path for additional writable directories passed through to codex exec. Canon does not yet render those extra directories as workspace choices.

gpt-5.5 requires a recent local Codex CLI. Older CLIs fail early with an upgrade message; upgrade Codex or choose a model supported by your installed CLI.

Recent Codex CLI releases no longer accept --ask-for-approval with codex exec. If you previously launched Canon with --sandbox workspace-write --ask-for-approval never, switch to --full-auto.

Do not start Canon with --sandbox danger-full-access as an unlabeled default. Use --dangerously-bypass-approvals-and-sandbox only when you intentionally want Canon to advertise the owner-only Bypass policy.

Local smoke test:

npm run smoke -- /path/to/project

Troubleshooting

If Canon messages are not getting replies, first confirm the local host process is still running:

ps aux | rg canon-codex

If you installed the package only inside this repo and not globally, run the built host directly:

node packages/codex-plugin/dist/host.js --cwd /path/to/project --full-auto

If canon-codex starts but cannot find the codex binary, either fix your PATH or launch with an explicit binary path:

canon-codex --cwd /path/to/project --codex-bin /absolute/path/to/codex

If Canon rejects authenticated requests with 401 Invalid API key, the stored Canon profile needs a fresh key. Reconnect the same profile to overwrite ~/.canon/agents.json, then restart or revive the host:

canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567" --profile my-codex

If Codex reports API-key quota errors while another local tool on the same machine uses OpenAI API keys, check Codex's own stored login state:

codex login status

Codex stores its credential mode in ~/.codex/auth.json. If it says it is logged in using an API key, switch Codex back to ChatGPT/device auth without changing your other tools:

codex logout
codex login --device-auth
codex login status

Restart canon-codex after changing the Codex login state.

Multiple agents

canon-codex-register --name "Frontend" --description "React work" --phone "+1..." --profile frontend
CANON_AGENT=frontend canon-codex --cwd ~/projects/frontend

Development

cd packages/codex-plugin
npm install
npm run build