opencode-claw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opencode-claw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# opencode-claw
+
+Transform [OpenCode](https://opencode.ai) into a personal AI assistant accessible via messaging platforms, with persistent memory and automated task processing.
+
+## What is this?
+
+opencode-claw wraps the `@opencode-ai/sdk` to add three capabilities that OpenCode doesn't have out of the box:
+
+1. **Pluggable Memory** -- Persistent knowledge across projects and sessions. Ships with a simple text-file backend (Markdown files, zero dependencies) and an optional [OpenViking](https://github.com/volcengine/OpenViking) backend for semantic search.
+
+2. **Paired Channels** -- Chat with your AI assistant from Slack, Telegram, or WhatsApp. Each conversation maps to an OpenCode session. Users can create new sessions, switch between them, and fork existing ones -- all from within the chat interface.
+
+3. **Cron Jobs** -- Schedule periodic tasks that create OpenCode sessions and run prompts automatically. Pull Linear issues every morning, generate standup summaries from Jira, or run any recurring workflow. Results are delivered to your preferred channel.
+
+## Architecture
+
+```
+[Slack] [Telegram] [WhatsApp]
+    \       |        /
+     Channel Adapters
+           |
+     Message Router
+      /    |     \
+  Session  Memory  Cron
+  Manager  System  Scheduler
+      \    |     /
+     OpenCode SDK
+     (agent runtime)
+```
+
+OpenCode handles the hard parts: LLM routing, tool execution, session state, file editing, MCP servers. opencode-claw adds the "glue" layer for channels, memory, and scheduling.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) >= 20
+- [OpenCode](https://opencode.ai) installed and configured (`opencode` binary in `PATH`)
+- At least one channel configured (Telegram bot token, Slack app token, or WhatsApp)
+
+## Installation
+
+```bash
+# Run directly (no install)
+npx opencode-claw
+
+# Or install globally
+npm install -g opencode-claw
+opencode-claw
+```
+
+## Quick Start
+
+```bash
+# 1. Create a config file in your project directory
+curl -O https://raw.githubusercontent.com/jinkoso/opencode-claw/main/opencode-claw.example.json
+mv opencode-claw.example.json opencode-claw.json
+
+# 2. Edit opencode-claw.json with your tokens and preferences
+#    (see Configuration section below)
+
+# 3. Run
+npx opencode-claw
+```
+
+The service starts an OpenCode server, connects your configured channels, initializes the memory system, and begins listening for messages.
+
+## Configuration
+
+All configuration lives in `opencode-claw.json` in the current working directory. Environment variables can be referenced with `${VAR_NAME}` syntax and will be expanded at load time.
+
+### OpenCode
+
+```json
+{
+  "opencode": {
+    "port": 0,
+    "directory": "/path/to/your/project"
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | number | `0` (random) | Port for the OpenCode server |
+| `directory` | string | cwd | Working directory for OpenCode |
+| `configPath` | string | — | Path to a custom OpenCode config file |
+
+### Memory
+
+```json
+{
+  "memory": {
+    "backend": "txt",
+    "txt": {
+      "directory": "./data/memory"
+    }
+  }
+}
+```
+
+**Text backend** (`txt`): Stores knowledge in Markdown files organized by category (`general.md`, `project.md`, `experience.md`, `architecture.md`). Supports keyword-based search. Zero external dependencies.
+
+**OpenViking backend** (`openviking`): Connects to a running OpenViking instance for semantic vector search. Falls back to txt backend if OpenViking is unreachable (when `fallback: true`).
+
+```json
+{
+  "memory": {
+    "backend": "openviking",
+    "openviking": {
+      "url": "http://localhost:8100",
+      "fallback": true
+    }
+  }
+}
+```
+
+Memory is injected into OpenCode sessions via a plugin. The agent can call `memory_search`, `memory_store`, and `memory_delete` tools during any conversation.
+
+### Channels
+
+#### Telegram
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "allowlist": ["your_telegram_username"],
+      "mode": "polling",
+      "rejectionBehavior": "ignore"
+    }
+  }
+}
+```
+
+Create a bot via [@BotFather](https://t.me/BotFather) and set the token. The `allowlist` restricts access to specific Telegram usernames. `rejectionBehavior` controls what happens when an unlisted user messages the bot: `"ignore"` silently drops the message, `"reject"` sends a "This assistant is private" reply.
+
+#### Slack
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "botToken": "${SLACK_BOT_TOKEN}",
+      "appToken": "${SLACK_APP_TOKEN}",
+      "mode": "socket"
+    }
+  }
+}
+```
+
+Requires a Slack app with Socket Mode enabled. The `appToken` is an app-level token (starts with `xapp-`), and `botToken` is the bot user OAuth token (starts with `xoxb-`). Optionally set `mode: "http"` with a `signingSecret` for HTTP-based event delivery.
+
+#### WhatsApp
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "allowlist": ["5511999887766"],
+      "authDir": "./data/whatsapp/auth",
+      "debounceMs": 1000
+    }
+  }
+}
+```
+
+Uses the [Baileys](https://github.com/WhiskeySockets/Baileys) library for a multi-device WhatsApp Web connection. On first start, a QR code is printed to the terminal for authentication. The `allowlist` uses full phone numbers (with country code, no `+` prefix). `debounceMs` batches rapid messages into a single prompt.
+
+### Cron Jobs
+
+```json
+{
+  "cron": {
+    "enabled": true,
+    "defaultTimeoutMs": 300000,
+    "jobs": [
+      {
+        "id": "daily-standup",
+        "schedule": "0 9 * * 1-5",
+        "description": "Morning standup briefing",
+        "prompt": "Check my Linear board for P1 and P2 issues assigned to me. Summarize what needs attention today.",
+        "reportTo": {
+          "channel": "telegram",
+          "peerId": "your_telegram_username"
+        },
+        "enabled": true,
+        "timeoutMs": 300000
+      }
+    ]
+  }
+}
+```
+
+Jobs use standard [cron expressions](https://crontab.guru/). Each job creates a fresh OpenCode session, sends the `prompt`, waits for completion (with timeout), and optionally delivers the result to a channel via the outbox. Jobs run one at a time to avoid overwhelming the agent.
+
+### Router
+
+```json
+{
+  "router": {
+    "timeoutMs": 300000
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `timeoutMs` | number | `300000` (5 min) | Max time to wait for an agent response before timing out |
+
+### Health Server
+
+```json
+{
+  "health": {
+    "enabled": true,
+    "port": 9090
+  }
+}
+```
+
+When enabled, exposes HTTP endpoints for monitoring:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Overall status (`up`, `degraded`, `down`) + uptime |
+| `GET /channels` | Connection status for each channel adapter |
+| `GET /memory` | Memory backend status and stats |
+| `GET /outbox` | Pending and dead-letter message counts |
+
+### Outbox
+
+```json
+{
+  "outbox": {
+    "directory": "./data/outbox",
+    "pollIntervalMs": 500,
+    "maxAttempts": 3
+  }
+}
+```
+
+The outbox is a file-based async delivery queue for cron job results. Messages are written as JSON files, a drainer polls the directory and delivers via the appropriate channel adapter. Failed deliveries are retried up to `maxAttempts` times before being moved to a dead-letter directory.
+
+## Chat Commands
+
+These commands are available in any connected channel:
+
+| Command | Description |
+|---------|-------------|
+| `/new [title]` | Create a new OpenCode session |
+| `/switch <id>` | Switch to an existing session |
+| `/sessions` | List all your sessions |
+| `/current` | Show the active session ID |
+| `/fork` | Fork the current session into a new one |
+| `/help` | Show available commands |
+
+Any non-command message is routed to the active OpenCode session as a prompt.
+
+## Programmatic API
+
+Use opencode-claw as a library in your own Node.js application:
+
+```typescript
+import { main, createMemoryBackend } from "opencode-claw"
+
+// Run the full service programmatically
+await main()
+```
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `main()` | Start the full opencode-claw service |
+| `createMemoryBackend(config)` | Create a memory backend (txt or openviking) from config |
+| `createOutboxWriter(config)` | Create an outbox writer for queuing messages |
+| `createOutboxDrainer(config, channels)` | Create an outbox drainer for delivering queued messages |
+
+### Types
+
+All configuration and domain types are exported for TypeScript consumers:
+
+```typescript
+import type {
+  Config,
+  MemoryConfig,
+  MemoryBackend,
+  MemoryEntry,
+  ChannelAdapter,
+  ChannelId,
+  InboundMessage,
+  OutboundMessage,
+} from "opencode-claw"
+```
+
+### Standalone Memory Plugin
+
+Use the memory plugin with a vanilla OpenCode installation (without the rest of opencode-claw):
+
+```typescript
+import { memoryPlugin } from "opencode-claw/plugin"
+```
+
+This registers `memory_search`, `memory_store`, and `memory_delete` tools, and injects relevant memories into the system prompt via a chat transform hook. Configure it by placing an `opencode-claw.json` with a `memory` section in your OpenCode project directory.
+
+## Inspiration
+
+- **[OpenClaw](https://github.com/nichochar/openclaw)** -- Channel plugin architecture, session key routing, memory system design.
+- **[MonClaw](https://cefboud.com/posts/monclaw-a-light-openclaw-with-opencode-sdk/)** -- Outbox pattern, plugin-based memory injection, wrapping OpenCode SDK.
+
+## License
+
+[MIT](LICENSE)

package/dist/channels/router.d.ts

@@ -0,0 +1,18 @@
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { Config } from "../config/types.js";
+import type { SessionManager } from "../sessions/manager.js";
+import type { Logger } from "../utils/logger.js";
+import type { ChannelAdapter, ChannelId, InboundMessage } from "./types.js";
+type RouterDeps = {
+    client: OpencodeClient;
+    sessions: SessionManager;
+    adapters: Map<ChannelId, ChannelAdapter>;
+    config: Config;
+    logger: Logger;
+    timeoutMs: number;
+};
+export declare function createRouter(deps: RouterDeps): {
+    handler: (msg: InboundMessage) => Promise<void>;
+};
+export type Router = ReturnType<typeof createRouter>;
+export {};

package/dist/channels/router.js

@@ -0,0 +1,188 @@
+import { buildSessionKey } from "../sessions/manager.js";
+function allowlist(config, channel) {
+    const ch = config.channels[channel];
+    if (!ch)
+        return undefined;
+    if ("allowlist" in ch && Array.isArray(ch.allowlist))
+        return ch.allowlist;
+    return undefined;
+}
+function rejection(config, channel) {
+    const ch = config.channels[channel];
+    if (!ch)
+        return "ignore";
+    if ("rejectionBehavior" in ch && ch.rejectionBehavior)
+        return ch.rejectionBehavior;
+    return "ignore";
+}
+function checkAllowlist(config, msg) {
+    const list = allowlist(config, msg.channel);
+    if (!list)
+        return true;
+    return list.includes(msg.peerId);
+}
+function extractText(parts) {
+    return parts
+        .filter((p) => p.type === "text" && typeof p.text === "string")
+        .map((p) => p.text)
+        .join("\n\n");
+}
+function parseCommand(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("/"))
+        return undefined;
+    const space = trimmed.indexOf(" ");
+    if (space === -1)
+        return { name: trimmed.slice(1).toLowerCase(), args: "" };
+    return { name: trimmed.slice(1, space).toLowerCase(), args: trimmed.slice(space + 1).trim() };
+}
+const HELP_TEXT = `Available commands:
+/new [title] — Create a new session
+/switch <id> — Switch to an existing session
+/sessions — List your sessions
+/current — Show current session
+/fork — Fork current session into a new one
+/help — Show this help`;
+async function handleCommand(cmd, msg, deps) {
+    const key = buildSessionKey(msg.channel, msg.peerId, msg.threadId);
+    const prefix = `${msg.channel}:${msg.peerId}`;
+    switch (cmd.name) {
+        case "new": {
+            const id = await deps.sessions.newSession(key, cmd.args || undefined);
+            return `Created new session: ${id}`;
+        }
+        case "switch": {
+            if (!cmd.args)
+                return "Usage: /switch <session-id>";
+            await deps.sessions.switchSession(key, cmd.args);
+            return `Switched to session: ${cmd.args}`;
+        }
+        case "sessions": {
+            const list = await deps.sessions.listSessions(prefix);
+            if (list.length === 0)
+                return "No sessions found.";
+            return list
+                .map((s) => {
+                const marker = s.active ? " (active)" : "";
+                return `• ${s.id} — ${s.title}${marker}`;
+            })
+                .join("\n");
+        }
+        case "current": {
+            const id = deps.sessions.currentSession(key);
+            if (!id)
+                return "No active session. Send a message to create one.";
+            return `Current session: ${id}`;
+        }
+        case "fork": {
+            const current = deps.sessions.currentSession(key);
+            if (!current)
+                return "No active session to fork.";
+            const result = await deps.client.session.fork({
+                path: { id: current },
+                body: {},
+            });
+            if (!result.data)
+                return "Fork failed: no data returned.";
+            const forked = result.data.id;
+            await deps.sessions.switchSession(key, forked);
+            return `Forked into new session: ${forked}`;
+        }
+        case "help": {
+            return HELP_TEXT;
+        }
+        default: {
+            return `Unknown command: /${cmd.name}\n\n${HELP_TEXT}`;
+        }
+    }
+}
+async function routeMessage(msg, deps) {
+    const adapter = deps.adapters.get(msg.channel);
+    if (!adapter) {
+        deps.logger.warn("router: no adapter for channel", { channel: msg.channel });
+        return;
+    }
+    // Allowlist check
+    if (!checkAllowlist(deps.config, msg)) {
+        const behavior = rejection(deps.config, msg.channel);
+        if (behavior === "reject") {
+            await adapter.send(msg.peerId, { text: "This assistant is private." });
+        }
+        deps.logger.debug("router: message dropped (not in allowlist)", {
+            channel: msg.channel,
+            peerId: msg.peerId,
+        });
+        return;
+    }
+    // Command interception
+    const cmd = parseCommand(msg.text);
+    if (cmd) {
+        const reply = await handleCommand(cmd, msg, deps);
+        await adapter.send(msg.peerId, { text: reply, replyToId: msg.replyToId });
+        return;
+    }
+    // Resolve or create session
+    const key = buildSessionKey(msg.channel, msg.peerId, msg.threadId);
+    const sessionId = await deps.sessions.resolveSession(key);
+    deps.logger.debug("router: prompting session", { sessionId, channel: msg.channel });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs);
+    let result;
+    try {
+        result = await deps.client.session.prompt({
+            path: { id: sessionId },
+            body: { parts: [{ type: "text", text: msg.text }] },
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (controller.signal.aborted) {
+            deps.logger.warn("router: session prompt timed out", {
+                sessionId,
+                timeoutMs: deps.timeoutMs,
+            });
+            await adapter.send(msg.peerId, {
+                text: "Request timed out. The agent took too long to respond.",
+                replyToId: msg.replyToId,
+            });
+            return;
+        }
+        throw err;
+    }
+    clearTimeout(timer);
+    if (!result.data) {
+        deps.logger.error("router: prompt returned no data", { sessionId });
+        await adapter.send(msg.peerId, { text: "Error: no response from agent." });
+        return;
+    }
+    // Extract text parts from response
+    const reply = extractText(result.data.parts);
+    if (!reply) {
+        deps.logger.warn("router: empty response from agent", { sessionId });
+        await adapter.send(msg.peerId, { text: "(empty response)" });
+        return;
+    }
+    await adapter.send(msg.peerId, { text: reply, replyToId: msg.replyToId });
+}
+export function createRouter(deps) {
+    async function handler(msg) {
+        try {
+            await routeMessage(msg, deps);
+        }
+        catch (err) {
+            deps.logger.error("router: unhandled error", {
+                channel: msg.channel,
+                peerId: msg.peerId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // Best-effort error reply
+            const adapter = deps.adapters.get(msg.channel);
+            if (adapter) {
+                await adapter
+                    .send(msg.peerId, { text: "An internal error occurred. Please try again." })
+                    .catch(() => { });
+            }
+        }
+    }
+    return { handler };
+}

package/dist/channels/slack.d.ts

@@ -0,0 +1,4 @@
+import type { SlackConfig } from "../config/types.js";
+import type { Logger } from "../utils/logger.js";
+import type { ChannelAdapter } from "./types.js";
+export declare function createSlackAdapter(config: SlackConfig, logger: Logger): ChannelAdapter;

package/dist/channels/slack.js

@@ -0,0 +1,87 @@
+import { App } from "@slack/bolt";
+import { createReconnector } from "../utils/reconnect.js";
+export function createSlackAdapter(config, logger) {
+    const app = new App({
+        token: config.botToken,
+        appToken: config.appToken,
+        socketMode: config.mode === "socket",
+        signingSecret: config.mode === "http" ? config.signingSecret : undefined,
+    });
+    let state = "disconnected";
+    let handler;
+    const reconnector = createReconnector({
+        name: "slack",
+        logger,
+        connect: async () => {
+            state = "connecting";
+            await app.start();
+            state = "connected";
+            reconnector.reset();
+            logger.info("slack: reconnected");
+        },
+    });
+    app.message(async ({ message, say }) => {
+        if (!handler)
+            return;
+        if (!("text" in message) || !message.text)
+            return;
+        if ("bot_id" in message && message.bot_id)
+            return;
+        if (!("user" in message) || !message.user)
+            return;
+        const peerId = message.user;
+        const channel = "channel" in message ? message.channel : undefined;
+        if (config.allowlist && config.allowlist.length > 0 && !config.allowlist.includes(peerId)) {
+            if (config.rejectionBehavior === "reject") {
+                await say("This assistant is private.");
+            }
+            logger.debug("slack: message dropped (not in allowlist)", { peerId });
+            return;
+        }
+        const threadTs = "thread_ts" in message ? message.thread_ts : undefined;
+        const msg = {
+            channel: "slack",
+            peerId,
+            groupId: channel,
+            threadId: threadTs,
+            text: message.text,
+            raw: message,
+        };
+        await handler(msg);
+    });
+    app.error(async (error) => {
+        logger.error("slack: app error", {
+            error: error.message,
+        });
+        state = "error";
+        reconnector.attempt();
+    });
+    return {
+        id: "slack",
+        name: "Slack",
+        async start(h) {
+            handler = h;
+            state = "connecting";
+            logger.info("slack: starting app", { mode: config.mode });
+            await app.start();
+            state = "connected";
+            logger.info("slack: app connected");
+        },
+        async stop() {
+            reconnector.stop();
+            state = "disconnected";
+            await app.stop();
+            logger.info("slack: app stopped");
+        },
+        async send(peerId, message) {
+            await app.client.chat.postMessage({
+                channel: peerId,
+                text: message.text,
+                thread_ts: message.threadId,
+            });
+        },
+        status() {
+            return state;
+        },
+    };
+}

package/dist/channels/telegram.d.ts

@@ -0,0 +1,4 @@
+import type { TelegramConfig } from "../config/types.js";
+import type { Logger } from "../utils/logger.js";
+import type { ChannelAdapter } from "./types.js";
+export declare function createTelegramAdapter(config: TelegramConfig, logger: Logger): ChannelAdapter;