Spectrum Claude Agent SDK

Run one persistent Claude Agent SDK session per messaging conversation through Photon Spectrum.

Zero-Code Start

npx @zmerchant/spectrum-claude-agent-sdk

The command reads .env from the current directory. Without Photon credentials it opens Spectrum's terminal provider. To use iMessage:

PROJECT_ID=your-photon-project-id
PROJECT_SECRET=your-photon-project-secret
ALLOWED_SENDERS=+15551234567

Remote iMessage mode fails closed when ALLOWED_SENDERS is empty or malformed.

Claude Agent SDK uses your existing Claude Code authentication or the provider credentials supported by the SDK. Set CLAUDE_CWD to the workspace Claude should operate in.

Install As A Library

npm install @zmerchant/spectrum-claude-agent-sdk

import { runClaudeSpectrumAgent } from "@zmerchant/spectrum-claude-agent-sdk";

await runClaudeSpectrumAgent({
  claude: {
    maxTurns: 8,
    queryOptions: {
      cwd: "/path/to/project",
      model: "sonnet",
      allowedTools: ["Read", "Grep", "Glob"],
    },
  },
});

allowedTools are tools Claude can run without an interactive permission prompt. Only allow tools appropriate for the machine and sender allowlist.

Custom Agent Behavior

import {
  createClaudeTurn,
  runSpectrumLoop,
} from "@zmerchant/spectrum-claude-agent-sdk";

const turn = createClaudeTurn({
  maxTurns: 6,
  buildPrompt: ({ text, senderId, platform }) => [
    "You are a concise project operator reached over messaging.",
    `Sender: ${senderId}`,
    `Platform: ${platform}`,
    "",
    text,
  ].join("\n"),
  queryOptions: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"],
  },
});

await runSpectrumLoop(turn);

You can also pass an existing Spectrum application through runSpectrumLoop(turn, { app }) to use Slack, Telegram, WhatsApp, a custom platform, or multiple providers in one process.

Use toTurnInput to translate replies, attachments, grouped content, voice metadata, or other provider-specific messages into the prompt Claude receives. Use formatResponse to return several message parts instead of one long block. createClaudeTurn also accepts onSdkMessage when the host application needs Claude Agent SDK stream events for real progress updates or custom telemetry.

Environment

| Variable | Purpose | |---|---| | PROJECT_ID, PROJECT_SECRET | Enable Photon iMessage mode | | ALLOWED_SENDERS | Comma-separated phone numbers or emails allowed to invoke the agent | | CLAUDE_CWD | Claude working directory | | CLAUDE_MODEL | Optional Claude model override | | CLAUDE_MAX_TURNS | Maximum Agent SDK turns per message, default 3 | | CLAUDE_ALLOWED_TOOLS | Comma-separated tools allowed without a prompt | | CLAUDE_DISALLOWED_TOOLS | Comma-separated tools removed from Claude | | CLAUDE_SYSTEM_PROMPT | Optional Claude system prompt | | CLAUDE_SESSION_STATE | Persistent conversation-to-session mapping file |

Session state is written atomically with owner-only permissions. Messages from the same Spectrum conversation are serialized so simultaneous texts cannot race the Claude resume ID.

Messaging Commands

The bridge handles these commands before the model sees them:

• /help or /commands lists the messaging commands.
• /status reports whether the conversation has a resumable Claude session.
• /new starts a fresh Claude session for the conversation.
• /clear is an alias for /new.
• /compact asks Claude Code to compact the current resumed session.

Other slash commands are passed directly to Claude Code, including project commands and skills. Set interceptCommands: false in ClaudeTurnOptions to pass every slash command through unchanged.

Public API

• runClaudeSpectrumAgent(options) starts the complete Claude and Spectrum loop.
• createClaudeTurn(options) creates a persistent Claude turn handler.
• runSpectrumLoop(turn, options) attaches any compatible turn handler to Spectrum.
• createSpectrumApp(options) creates terminal or iMessage Spectrum providers.
• ClaudeSessionStore persists Spectrum conversation IDs to Claude session IDs.
• parseAllowedSenders and normalizeSender expose the sender validation rules.

Requires Node.js 22.19 or newer.