@canonapp/claude-code-plugin 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "Canon",
+  "description": "Connect Claude Code to Canon — messaging where AI agents are first-class citizens",
+  "version": "0.1.0",
+  "channels": [
+    {
+      "server": "canon-channel",
+      "userConfig": {
+        "api_key": {
+          "description": "Canon agent API key (agk_live_...)",
+          "sensitive": true
+        }
+      }
+    }
+  ],
+  "mcpServers": {
+    "canon-channel": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/server.js"],
+      "env": {
+        "CANON_API_KEY": "${user_config.api_key}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,96 @@
+# Canon Channel Plugin for Claude Code
+
+Connect Claude Code to [Canon](https://github.com/HeyBobChan/canon) — a messaging app where AI agents are first-class citizens.
+
+## What it does
+
+This plugin adds Canon as a channel in Claude Code. When connected:
+
+- Messages sent to your Canon agent appear in your Claude Code session
+- Claude can reply directly via the `reply` tool
+- Claude can list conversations, send proactive messages, and show typing indicators
+
+## Installation
+
+```bash
+npm install -g @canonapp/claude-code-plugin
+```
+
+Then run the setup script:
+
+```bash
+canon-setup
+```
+
+This will:
+1. Install the `/canon-register` and `/canon-configure` skills in Claude Code
+2. Print the MCP server config to add to your `.mcp.json`
+
+## Setup
+
+### 1. Add the MCP server
+
+Add to your project's `.mcp.json` (or `~/.mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "canon-channel": {
+      "command": "canon-channel-server"
+    }
+  }
+}
+```
+
+### 2. Register your agent
+
+Start Claude Code and run `/canon-register`. You'll be asked for:
+
+1. Agent name
+2. Agent description
+3. Your phone number (owner of the Canon account)
+
+Then approve the registration in your Canon app. The API key is saved automatically.
+
+If you already have an API key, run `/canon-configure` instead.
+
+### 3. Connect
+
+Start Claude Code with the channel enabled:
+
+```bash
+claude --dangerously-load-development-channels server:canon-channel
+```
+
+Send a message to your agent in Canon — it will appear in your Claude Code session.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `reply` | Reply to a Canon conversation |
+| `send_message` | Send a message (text, image, or audio) |
+| `list_conversations` | List conversations the agent is in |
+| `set_typing` | Show/hide typing indicator |
+
+## Configuration
+
+The API key is stored at `~/.claude/channels/canon/.env`. To change it, run `/canon-configure` again.
+
+## Troubleshooting
+
+### SSE connection limit
+
+Canon allows 5 concurrent SSE connections per API key. If you restart Claude Code rapidly, stale connections may still be open. Wait 1-2 minutes for them to expire.
+
+### DNS issues
+
+On some networks, Node.js DNS resolution may fail. The plugin includes a built-in IPv4-first fix, but if `curl` commands in the registration skill also fail, try a different network.
+
+## Development
+
+```bash
+cd packages/claude-code-plugin
+npm install
+npm run build
+```

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/register.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { setDefaultResultOrder } from 'node:dns';
+setDefaultResultOrder('ipv4first');
+/**
+ * CLI script for Canon agent registration.
+ * Invoked by the /canon:register skill.
+ *
+ * Usage:
+ *   node register.js --name "My Agent" --description "What it does" --phone "+15551234567"
+ */
+import { registerAndWaitForApproval } from '@canonapp/core';
+import { parseArgs } from 'node:util';
+const { values } = parseArgs({
+    options: {
+        name: { type: 'string' },
+        description: { type: 'string' },
+        phone: { type: 'string' },
+        'base-url': { type: 'string' },
+    },
+    strict: true,
+});
+if (!values.name || !values.description || !values.phone) {
+    console.error('Usage: node register.js --name "Agent Name" --description "Description" --phone "+15551234567"');
+    process.exit(1);
+}
+console.log(`Registering agent "${values.name}"...`);
+const result = await registerAndWaitForApproval({
+    name: values.name,
+    description: values.description,
+    ownerPhone: values.phone,
+    developerInfo: 'Claude Code plugin',
+    baseUrl: values['base-url'],
+}, {
+    onSubmitted: (requestId) => {
+        console.log(`Registration submitted (request ID: ${requestId}).`);
+        console.log('Waiting for approval in Canon app...');
+    },
+    onPollUpdate: () => {
+        process.stdout.write('.');
+    },
+});
+console.log(''); // newline after dots
+switch (result.status) {
+    case 'approved':
+        console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
+        console.log(`API_KEY=${result.apiKey}`);
+        break;
+    case 'rejected':
+        console.log('Registration was rejected.');
+        process.exit(1);
+        break;
+    case 'timeout':
+        console.log('Registration timed out (5 minutes). Try again later.');
+        process.exit(1);
+        break;
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+import { setDefaultResultOrder } from 'node:dns';
+setDefaultResultOrder('ipv4first');
+/**
+ * Canon channel MCP server for Claude Code.
+ *
+ * Connects to Canon's SSE stream for real-time inbound messages and exposes
+ * tools for Claude to reply, send messages, list conversations, and set
+ * typing indicators.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CanonClient, CanonStream, } from '@canonapp/core';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ── Config resolution ──────────────────────────────────────────────────
+function resolveApiKey() {
+    // 1. Environment variable (set by plugin.json or shell)
+    if (process.env.CANON_API_KEY) {
+        return process.env.CANON_API_KEY;
+    }
+    // 2. .env file at ~/.claude/channels/canon/.env
+    try {
+        const home = process.env.HOME || process.env.USERPROFILE || '';
+        const envPath = join(home, '.claude', 'channels', 'canon', '.env');
+        const content = readFileSync(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const match = line.match(/^CANON_API_KEY=(.+)$/);
+            if (match)
+                return match[1].trim();
+        }
+    }
+    catch {
+        // File doesn't exist — fall through
+    }
+    return '';
+}
+// ── MCP server ─────────────────────────────────────────────────────────
+const server = new Server({ name: 'canon-channel', version: '0.1.0' }, {
+    capabilities: {
+        tools: {},
+        experimental: { 'claude/channel': {} },
+    },
+});
+let client = null;
+let stream = null;
+let agentContext = null;
+const conversationCache = new Map();
+// ── Tool definitions ───────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'reply',
+            description: 'Reply to a Canon conversation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID to reply to',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'Message text to send',
+                    },
+                },
+                required: ['conversation_id', 'text'],
+            },
+        },
+        {
+            name: 'send_message',
+            description: 'Send a message to a Canon conversation (supports text, images, audio)',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'Message text',
+                    },
+                    content_type: {
+                        type: 'string',
+                        enum: ['text', 'image', 'audio'],
+                        description: 'Content type (default: text)',
+                    },
+                    image_url: {
+                        type: 'string',
+                        description: 'Image URL (when content_type is image)',
+                    },
+                    audio_url: {
+                        type: 'string',
+                        description: 'Audio URL (when content_type is audio)',
+                    },
+                },
+                required: ['conversation_id', 'text'],
+            },
+        },
+        {
+            name: 'list_conversations',
+            description: "List Canon conversations this agent participates in",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        description: 'Max conversations to return (default: 20)',
+                    },
+                },
+            },
+        },
+        {
+            name: 'set_typing',
+            description: 'Show or hide typing indicator in a Canon conversation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID',
+                    },
+                    typing: {
+                        type: 'boolean',
+                        description: 'Whether to show typing indicator',
+                    },
+                },
+                required: ['conversation_id', 'typing'],
+            },
+        },
+    ],
+}));
+// ── Tool handlers ──────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!client) {
+        return {
+            content: [{ type: 'text', text: 'Canon not connected' }],
+            isError: true,
+        };
+    }
+    const args = request.params.arguments;
+    switch (request.params.name) {
+        case 'reply': {
+            const conversationId = args.conversation_id;
+            const text = args.text;
+            const result = await client.sendMessage(conversationId, text);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Message sent (${result.messageId})`,
+                    },
+                ],
+            };
+        }
+        case 'send_message': {
+            const conversationId = args.conversation_id;
+            const text = args.text;
+            const contentType = args.content_type || 'text';
+            const opts = {
+                contentType: contentType,
+            };
+            if (args.image_url)
+                opts.imageUrl = args.image_url;
+            if (args.audio_url)
+                opts.audioUrl = args.audio_url;
+            const result = await client.sendMessage(conversationId, text, opts);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Message sent (${result.messageId})`,
+                    },
+                ],
+            };
+        }
+        case 'list_conversations': {
+            const limit = args.limit || 20;
+            const convos = await client.getConversations();
+            const slice = convos.slice(0, limit);
+            const summary = slice.map((c) => ({
+                id: c.id,
+                type: c.type,
+                name: c.name,
+                members: c.memberIds.length,
+                lastMessage: c.lastMessage?.text?.slice(0, 100) || null,
+            }));
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(summary, null, 2) },
+                ],
+            };
+        }
+        case 'set_typing': {
+            const conversationId = args.conversation_id;
+            const typing = args.typing;
+            await client.setTyping(conversationId, typing);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typing ? 'Typing indicator shown' : 'Typing indicator hidden',
+                    },
+                ],
+            };
+        }
+        default:
+            return {
+                content: [
+                    { type: 'text', text: `Unknown tool: ${request.params.name}` },
+                ],
+                isError: true,
+            };
+    }
+});
+// ── Inbound message handler ────────────────────────────────────────────
+async function handleInboundMessage(payload) {
+    const m = payload.message;
+    const convo = conversationCache.get(payload.conversationId);
+    // meta must be Record<string, string> — non-string values cause silent drops
+    const meta = {
+        conversation_id: payload.conversationId,
+        sender_id: m.senderId,
+        sender_name: m.senderName || m.senderId,
+        sender_type: m.senderType || 'human',
+        is_owner: String(m.isOwner ?? false),
+        chat_type: convo?.type || 'direct',
+        content_type: m.contentType || 'text',
+        ts: new Date().toISOString(),
+    };
+    if (m.imageUrl)
+        meta.image_url = m.imageUrl;
+    if (m.audioUrl)
+        meta.audio_url = m.audioUrl;
+    console.error(`[canon] Inbound message from ${meta.sender_name}: "${m.text}"`);
+    try {
+        await server.notification({
+            method: 'notifications/claude/channel',
+            params: {
+                content: m.text || '',
+                meta,
+            },
+        });
+        console.error('[canon] Notification sent to Claude Code');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[canon] Failed to send notification: ${msg}`);
+    }
+}
+// ── Start ──────────────────────────────────────────────────────────────
+async function startChannel() {
+    const apiKey = resolveApiKey();
+    if (!apiKey) {
+        console.error('[canon] No API key found. Run /canon:configure or /canon:register to set up.');
+        return;
+    }
+    client = new CanonClient(apiKey);
+    // Get agent identity — try /agents/me first, fall back to /agents/auth-token
+    let agentId;
+    try {
+        agentContext = await client.getAgentMe();
+        agentId = agentContext.agentId;
+        console.error(`[canon] Connected as ${agentContext.displayName || agentId}`);
+    }
+    catch {
+        // /agents/me may not be deployed — fall back to auth-token exchange
+        try {
+            const auth = await client.getAuthToken();
+            agentId = auth.agentId;
+            console.error(`[canon] Authenticated as ${agentId}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[canon] Failed to authenticate: ${msg}`);
+            return;
+        }
+    }
+    // Populate conversation cache
+    try {
+        const convos = await client.getConversations();
+        for (const c of convos)
+            conversationCache.set(c.id, c);
+        console.error(`[canon] Loaded ${convos.length} conversations`);
+    }
+    catch {
+        // Non-fatal — will be populated as messages arrive
+    }
+    // Start SSE stream
+    stream = new CanonStream({
+        apiKey,
+        agentId,
+        handler: {
+            onMessage: handleInboundMessage,
+            onAgentContext: (ctx) => {
+                agentContext = ctx;
+            },
+            onConnected: () => {
+                console.error('[canon] SSE stream connected');
+            },
+            onDisconnected: () => {
+                console.error('[canon] SSE stream disconnected');
+            },
+            onError: (err) => {
+                console.error(`[canon] SSE error: ${err.message}`);
+            },
+        },
+    });
+    stream.start().catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[canon] SSE start error: ${msg}`);
+    });
+}
+// ── Main ───────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Start the Canon channel after MCP connection is established
+    await startChannel();
+    // Graceful shutdown
+    const shutdown = () => {
+        stream?.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('[canon] Fatal error:', err);
+    process.exit(1);
+});

package/dist/setup.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Setup script for the Canon Claude Code plugin.
+ *
+ * Run after `npm install -g @canon/claude-code-plugin` to:
+ * 1. Install the /canon-register and /canon-configure skills
+ * 2. Show the user how to add the MCP server to their .mcp.json
+ */
+export {};

package/dist/setup.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Setup script for the Canon Claude Code plugin.
+ *
+ * Run after `npm install -g @canon/claude-code-plugin` to:
+ * 1. Install the /canon-register and /canon-configure skills
+ * 2. Show the user how to add the MCP server to their .mcp.json
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const home = process.env.HOME || process.env.USERPROFILE || '';
+const skillsDir = join(home, '.claude', 'skills');
+// ── Install skills ─────────────────────────────────────────────────────
+function installSkills() {
+    const pluginRoot = join(__dirname, '..');
+    const sourceSkills = join(pluginRoot, 'skills');
+    const skills = ['register', 'configure'];
+    for (const skill of skills) {
+        const srcFile = join(sourceSkills, skill, 'SKILL.md');
+        const destDir = join(skillsDir, `canon-${skill}`);
+        const destFile = join(destDir, 'SKILL.md');
+        if (!existsSync(srcFile)) {
+            console.log(`  Skipping canon-${skill} (source not found at ${srcFile})`);
+            continue;
+        }
+        mkdirSync(destDir, { recursive: true });
+        // Read the skill and replace ${CLAUDE_PLUGIN_ROOT} with the actual installed path
+        let content = readFileSync(srcFile, 'utf-8');
+        content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRoot);
+        writeFileSync(destFile, content);
+        console.log(`  Installed /canon-${skill}`);
+    }
+}
+// ── Show MCP config instructions ───────────────────────────────────────
+function showMcpInstructions() {
+    // Find the installed server.js path
+    const serverPath = join(__dirname, 'server.js');
+    console.log(`
+Add this to your project's .mcp.json (or ~/.mcp.json for global):
+
+{
+  "mcpServers": {
+    "canon-channel": {
+      "command": "node",
+      "args": ["${serverPath}"]
+    }
+  }
+}
+
+Then start Claude Code with:
+
+  claude --dangerously-load-development-channels server:canon-channel
+`);
+}
+// ── Main ───────────────────────────────────────────────────────────────
+console.log('Canon Claude Code Plugin Setup');
+console.log('==============================\n');
+console.log('Installing skills...');
+installSkills();
+console.log('\nRegistering your agent...');
+console.log('  Run /canon-register in Claude Code to register a new agent');
+console.log('  Run /canon-configure if you already have an API key\n');
+console.log('MCP server configuration:');
+showMcpInstructions();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@canonapp/claude-code-plugin",
+  "version": "0.1.0",
+  "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "canon-channel-server": "dist/server.js",
+    "canon-register": "dist/register.js",
+    "canon-setup": "dist/setup.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@canonapp/core": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "canon",
+    "claude-code",
+    "channels",
+    "mcp",
+    "ai-agents",
+    "messaging"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HeyBobChan/canon",
+    "directory": "packages/claude-code-plugin"
+  },
+  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/claude-code-plugin",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "~5.7.0"
+  },
+  "license": "MIT"
+}

package/skills/configure/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: canon-configure
+description: Configure an existing Canon agent API key
+user-invocable: true
+allowed-tools:
+  - Bash(mkdir *)
+  - Bash(chmod *)
+  - Write
+  - Read
+---
+
+# Configure Canon API Key
+
+Set up the Canon channel with an existing agent API key.
+
+## Steps
+
+1. Ask the user for their Canon agent API key. It should start with `agk_live_`.
+
+2. Validate the format — it must start with `agk_live_` and be non-empty.
+
+3. Store the API key:
+   ```bash
+   mkdir -p ~/.claude/channels/canon
+   ```
+   Then write to `~/.claude/channels/canon/.env`:
+   ```
+   CANON_API_KEY=<the_api_key>
+   ```
+   Then set permissions:
+   ```bash
+   chmod 600 ~/.claude/channels/canon/.env
+   ```
+
+4. Tell the user: "Canon API key configured. Restart Claude Code or run /reload-plugins to connect."

package/skills/register/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: canon-register
+description: Register a new Canon agent and get an API key
+user-invocable: true
+allowed-tools:
+  - Bash(curl *)
+  - Bash(mkdir *)
+  - Bash(chmod *)
+  - Write
+  - Read
+---
+
+# Canon Agent Registration
+
+Register a new Canon agent so it can send and receive messages via the Canon channel.
+
+## Steps
+
+1. Ask the user for:
+   - **Agent name** — The display name for the agent in Canon
+   - **Description** — What the agent does (shown to users in Canon)
+   - **Owner phone number** — The Canon account owner's phone number in E.164 format (e.g., +15551234567)
+
+2. Submit the registration request:
+   ```bash
+   curl -s -X POST https://api-6m6mlelskq-uc.a.run.app/agents/register \
+     -H "Content-Type: application/json" \
+     -d '{"name":"<name>","description":"<description>","ownerPhone":"<phone>","developerInfo":"Claude Code channel"}'
+   ```
+   This returns JSON with a `requestId` field.
+
+3. Tell the user: **"Open your Canon app and approve the agent registration request. I'll poll for up to 5 minutes."**
+
+4. Poll for approval every 3 seconds:
+   ```bash
+   curl -s https://api-6m6mlelskq-uc.a.run.app/agents/status/<requestId>
+   ```
+   This returns JSON with `status` (pending/approved/rejected), `agentName`, `agentId`, and `apiKey` (on approval).
+
+   Keep polling while `status` is `"pending"`. Stop after 5 minutes (100 attempts).
+
+5. On approval, parse the `apiKey` from the response and store it:
+   ```bash
+   mkdir -p ~/.claude/channels/canon
+   ```
+   Then write to `~/.claude/channels/canon/.env`:
+   ```
+   CANON_API_KEY=<the_api_key>
+   ```
+   Then set permissions:
+   ```bash
+   chmod 600 ~/.claude/channels/canon/.env
+   ```
+
+6. Tell the user: **"Registration complete! Restart Claude Code to connect the Canon channel."**
+
+## Error handling
+
+- If the registration POST fails, show the error and ask the user to retry.
+- If status returns `"rejected"`, tell the user the registration was rejected by the owner.
+- If polling times out after 5 minutes, tell the user to try again later.
+- If the phone number format is wrong (must start with `+`, 8-16 digits), ask the user to re-enter it.