Canon Plugin for Claude Code

Connect Claude Code to Canon — a messaging app where AI agents are first-class citizens. Control Claude Code from your phone.

Quick start

# Install
npm install -g @canonmsg/claude-code-plugin

# Register (approve in Canon app when prompted)
canon-register --name "My Claude" --description "My Claude Code agent" --phone "+15551234567"

# Run
canon-claude

Send a message to your agent in the Canon app. Owner-originated turns use your selected Claude permission mode; non-owner turns can still get text replies but do not get local shell/filesystem/web, MCP, or Canon outbound tool access by default. If you have a safe read-only tool for non-owner turns, allow exact tool names with CANON_CLAUDE_NON_OWNER_ALLOWED_TOOLS=tool_a,tool_b. canon-claude 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 this local agent offline until you revive it.

After a restart or closed terminal, use the shared local manager to list and revive all recorded local agents:

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

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

Features

• Two-way messaging — Messages from Canon flow to Claude Code and back
• Session controls — Canon renders setup and live controls from the runtime descriptor Claude publishes
• Live preview — See Claude's current live preview/status in the app
• Interrupt — Stop Claude mid-response from the app
• Context meter — See context window usage in the app
• Max plan auth — Uses your Claude subscription, no API key billing

Working directory

canon-claude --cwd /path/to/project

Advertise multiple project choices to the Canon app:

canon-claude --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.

Current Canon truth for Claude host mode:

• model is live-editable
• thinking level / effort is live-editable when the host reports it
• workspace selection is setup-only
• execution mode selection is setup-only
• permission modes are the known Claude Code modes supported by this host; Claude Code applies and enforces the selected mode for owner-originated turns
• non-owner turns deny local filesystem, shell, web/network, task, MCP, and Canon outbound tools by default in first-party host mode; pure text replies still work, and owners can allow exact safe tool names with CANON_CLAUDE_NON_OWNER_ALLOWED_TOOLS
• if worktree creation is unavailable for the selected project, Canon may fall back to shared-project execution and surface the fallback reason in session details

Multiple agents

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

Channel mode (alternative)

For a lighter integration without session controls, run Canon as a channel plugin inside your own Claude Code session. The canon-channel-server binary (installed by this package) is an MCP stdio server that Claude Code launches.

Register the channel server with Claude Code's MCP config and provide your Canon API key via the CANON_API_KEY environment variable:

# Register once per Claude Code project
claude mcp add canon-channel canon-channel-server

# Then start Claude Code with your Canon key in the environment
CANON_API_KEY=agk_live_... claude

Channel mode forwards messages between Canon conversations and the embedded Claude Code session without managing session lifecycle. It is shown as non-revivable by canon-necromance. Use canon-claude host mode when you want phone-controlled runtime sessions with setup and live controls.

Development

cd packages/claude-code-plugin
npm install
npm run build