opencode-claw 0.2.3 → 0.3.0

package/README.md

@@ -47,6 +47,8 @@ npm install -g opencode-claw
 opencode-claw
 ```
 
+No git clone needed. The package is published to npm and runs anywhere Node.js is available.
+
 ## Quick Start
 
 ```bash
@@ -60,13 +62,65 @@ npx opencode-claw --init
 npx opencode-claw
 ```
 
-Or create `opencode-claw.json` manually — see the [example config](https://github.com/jinkoso/opencode-claw/blob/main/opencode-claw.example.json) for all available options.
+`--init` launches an interactive wizard that asks which channels to enable, prompts for bot tokens and allowlists, and writes an `opencode-claw.json` in the current directory. You can also copy the bundled example config directly:
+
+```bash
+# After global install
+cp $(npm root -g)/opencode-claw/opencode-claw.example.json ./opencode-claw.json
+
+# After npx run (example config also on GitHub)
+# https://github.com/jinkoso/opencode-claw/blob/main/opencode-claw.example.json
+```
+
+## How It Works
 
-The service starts an OpenCode server, connects your configured channels, initializes the memory system, and begins listening for messages.
+When you run `opencode-claw`, it:
+
+1. Reads `opencode-claw.json` from the current directory (or the path in `OPENCODE_CLAW_CONFIG`)
+2. Starts an OpenCode server, **automatically registering the memory plugin** — no changes to `opencode.json` or any OpenCode config required
+3. Connects your configured channel adapters (Telegram, Slack, WhatsApp)
+4. Routes inbound messages to OpenCode sessions and streams responses back
+
+### Automatic Memory Plugin Registration
+
+The memory plugin is wired automatically. You do **not** need to modify OpenCode's own config files. Internally, opencode-claw resolves the plugin path relative to its own installed location and passes it to the OpenCode SDK:
+
+```
+opencode-claw starts
+  → resolves plugin path from its own dist/ directory
+  → passes plugin: ["file:///...path.../dist/memory/plugin-entry.js"] to createOpencode()
+  → OpenCode server starts with the plugin loaded
+  → memory_search, memory_store, memory_delete tools available in every session
+```
+
+This path resolution uses `import.meta.url` and works correctly whether you installed via `npm install -g`, `npx`, or as a local dependency — no hardcoded paths, no manual setup.
+
+### Session Persistence
+
+opencode-claw maps each channel peer (Telegram username, Slack user ID, phone number) to an OpenCode session ID, persisted in `./data/sessions.json` (relative to the config file). When you restart the service, existing sessions resume automatically.
+
+### Config File Location
+
+The config file is discovered in this order:
+
+1. `OPENCODE_CLAW_CONFIG` environment variable (absolute path to the config file)
+2. `./opencode-claw.json` in the current working directory
+3. `../opencode-claw.json` in the parent directory
+
+All relative paths inside `opencode-claw.json` (memory directory, session file, outbox, WhatsApp auth) are resolved relative to the **config file's directory**, not the current working directory. This means the service creates consistent data paths regardless of where you invoke it from.
+
+**Data files created by default (relative to config file):**
+
+| Path | Purpose |
+|------|---------|
+| `./data/memory/` | Memory files (txt backend) |
+| `./data/sessions.json` | Session ID persistence |
+| `./data/outbox/` | Async delivery queue for cron results |
+| `./data/whatsapp/auth/` | WhatsApp multi-device credentials |
 
 ## 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.
+All configuration lives in `opencode-claw.json`. Environment variables can be referenced with `${VAR_NAME}` syntax and are expanded at load time.
 
 ### OpenCode
 
@@ -114,7 +168,7 @@ All configuration lives in `opencode-claw.json` in the current working directory
 }
 ```
 
-Memory is injected into OpenCode sessions via a plugin. The agent can call `memory_search`, `memory_store`, and `memory_delete` tools during any conversation.
+Memory is injected into OpenCode sessions automatically via the memory plugin. The agent can call `memory_search`, `memory_store`, and `memory_delete` tools during any conversation.
 
 ### Channels
 
@@ -202,7 +256,12 @@ Jobs use standard [cron expressions](https://crontab.guru/). Each job creates a
 ```json
 {
   "router": {
-    "timeoutMs": 300000
+    "timeoutMs": 300000,
+    "progress": {
+      "enabled": true,
+      "toolThrottleMs": 5000,
+      "heartbeatMs": 30000
+    }
   }
 }
 ```
@@ -210,6 +269,11 @@ Jobs use standard [cron expressions](https://crontab.guru/). Each job creates a
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `timeoutMs` | number | `300000` (5 min) | Max time to wait for an agent response before timing out |
+| `progress.enabled` | boolean | `true` | Forward tool-use notifications and heartbeats to the channel while the agent is working |
+| `progress.toolThrottleMs` | number | `5000` | Minimum ms between tool-use progress messages (prevents flooding) |
+| `progress.heartbeatMs` | number | `30000` | Interval for "still working…" heartbeat messages during long-running tasks |
+
+When `progress.enabled` is true, the router sends intermediate updates to the channel while the agent is processing — tool call notifications (e.g. "Running: read_file"), todo list updates when the agent calls `TodoWrite`, and periodic heartbeats so you know it hasn't stalled.
 
 ### Health Server
 
@@ -263,11 +327,8 @@ 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
+import { main, createMemoryBackend } from "opencode-claw/lib"
 await main()
 ```
 
@@ -294,18 +355,49 @@ import type {
   ChannelId,
   InboundMessage,
   OutboundMessage,
-} from "opencode-claw"
+} from "opencode-claw/lib"
 ```
 
 ### Standalone Memory Plugin
 
-Use the memory plugin with a vanilla OpenCode installation (without the rest of opencode-claw):
+The memory plugin can be used with a vanilla OpenCode installation (without the rest of opencode-claw). Add the package name to the `plugin` array in your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-claw"]
+}
+```
+
+OpenCode will install the package automatically on next startup and load the memory plugin.
+
+Or wire it programmatically via the SDK:
 
 ```typescript
-import { memoryPlugin } from "opencode-claw/plugin"
+import { createOpencode } from "@opencode-ai/sdk"
+import { resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { dirname } from "node:path"
+const dir = dirname(fileURLToPath(import.meta.url))
+const pluginPath = `file://${resolve(dir, "node_modules/opencode-claw/dist/memory/plugin-entry.js")}`
+const { client, server } = await createOpencode({
+  config: { plugin: [pluginPath] },
+})
+```
+
+The plugin registers `memory_search`, `memory_store`, and `memory_delete` tools, and injects relevant memories into the system prompt via a chat transform hook. It reads its config from `opencode-claw.json` in the working directory — only the `memory` section is required:
+
+```json
+{
+  "memory": {
+    "backend": "txt",
+    "txt": {
+      "directory": "./data/memory"
+    }
+  }
+}
 ```
 
-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.
+> **Note**: You do not need the standalone plugin wiring when using `opencode-claw` directly — it is registered automatically on startup.
 
 ## Inspiration
 

package/dist/channels/router.js

@@ -31,11 +31,13 @@ function parseCommand(text) {
         return { name: trimmed.slice(1).toLowerCase(), args: "" };
     return { name: trimmed.slice(1, space).toLowerCase(), args: trimmed.slice(space + 1).trim() };
 }
+const PAGE_SIZE = 10;
 const HELP_TEXT = `Available commands:
 /new [title] — Create a new session
 /switch <id> — Switch to an existing session
-/sessions — List your sessions
+/sessions [page] — List your sessions (paginated)
 /current — Show current session
+/status — Show current agent run status
 /fork — Fork current session into a new one
 /cancel — Abort the currently running agent
 /help — Show this help`;
@@ -43,7 +45,7 @@ const HELP_TEXT = `Available commands:
 function peerKey(channel, peerId) {
     return `${channel}:${peerId}`;
 }
-async function handleCommand(cmd, msg, deps, activeStreams) {
+async function handleCommand(cmd, msg, deps, activeStreams, activeStreamsMeta) {
     const key = buildSessionKey(msg.channel, msg.peerId, msg.threadId);
     switch (cmd.name) {
         case "new": {
@@ -60,12 +62,18 @@ async function handleCommand(cmd, msg, deps, activeStreams) {
             const list = await deps.sessions.listSessions(key);
             if (list.length === 0)
                 return "No sessions found.";
-            return list
-                .map((s) => {
+            const page = Math.max(1, Number.parseInt(cmd.args) || 1);
+            const totalPages = Math.ceil(list.length / PAGE_SIZE);
+            const clamped = Math.min(page, totalPages);
+            const slice = list.slice((clamped - 1) * PAGE_SIZE, clamped * PAGE_SIZE);
+            const lines = slice.map((s) => {
                 const marker = s.active ? " (active)" : "";
                 return `• ${s.id} — ${s.title}${marker}`;
-            })
-                .join("\n");
+            });
+            if (totalPages > 1) {
+                lines.push(`\nPage ${clamped}/${totalPages}${clamped < totalPages ? ` — use /sessions ${clamped + 1} for next` : ""}`);
+            }
+            return lines.join("\n");
         }
         case "current": {
             const id = deps.sessions.currentSession(key);
@@ -96,6 +104,19 @@ async function handleCommand(cmd, msg, deps, activeStreams) {
             deps.logger.info("router: session aborted by user", { sessionId, aborted });
             return aborted ? "Agent aborted." : "Abort request sent (agent may already be done).";
         }
+        case "status": {
+            const pk = peerKey(msg.channel, msg.peerId);
+            const sessionId = activeStreams.get(pk);
+            if (!sessionId)
+                return "No agent is currently running.";
+            const meta = activeStreamsMeta.get(pk);
+            const elapsedSec = meta ? Math.floor((Date.now() - meta.startedAt) / 1000) : 0;
+            const mins = Math.floor(elapsedSec / 60);
+            const secs = elapsedSec % 60;
+            const elapsed = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+            const tool = meta?.lastTool ? ` — last tool: ${humanizeToolName(meta.lastTool)}` : "";
+            return `⏳ Agent is running (${elapsed} elapsed${tool})`;
+        }
         case "help": {
             return HELP_TEXT;
         }
@@ -110,7 +131,22 @@ function humanizeToolName(raw) {
         return raw;
     return raw.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
-async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
+function formatTodoList(todos) {
+    if (todos.length === 0)
+        return "📋 Todo list cleared.";
+    const icons = {
+        completed: "✅",
+        in_progress: "🔄",
+        pending: "⬜",
+        cancelled: "❌",
+    };
+    const lines = todos.map((t) => {
+        const icon = icons[t.status] ?? "•";
+        return `${icon} [${t.priority}] ${t.content}`;
+    });
+    return `📋 **Todos**\n${lines.join("\n")}`;
+}
+async function routeMessage(msg, deps, activeStreams, activeStreamsMeta, pendingQuestions) {
     const adapter = deps.adapters.get(msg.channel);
     if (!adapter) {
         deps.logger.warn("router: no adapter for channel", { channel: msg.channel });
@@ -131,7 +167,7 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
     // Command interception
     const cmd = parseCommand(msg.text);
     if (cmd) {
-        const reply = await handleCommand(cmd, msg, deps, activeStreams);
+        const reply = await handleCommand(cmd, msg, deps, activeStreams, activeStreamsMeta);
         await adapter.send(msg.peerId, { text: reply, replyToId: msg.replyToId });
         return;
     }
@@ -141,6 +177,7 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
     deps.logger.debug("router: prompting session", { sessionId, channel: msg.channel });
     const pk = peerKey(msg.channel, msg.peerId);
     activeStreams.set(pk, sessionId);
+    activeStreamsMeta.set(pk, { startedAt: Date.now(), lastTool: undefined });
     // Start typing indicator
     if (adapter.sendTyping) {
         await adapter.sendTyping(msg.peerId).catch(() => { });
@@ -179,10 +216,15 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
     }
     const progress = progressEnabled
         ? {
-            onToolRunning: (_tool, title) => adapter.send(msg.peerId, {
-                text: `🔧 ${humanizeToolName(title)}...`,
-                replyToId: msg.replyToId,
-            }),
+            onToolRunning: (_tool, title) => {
+                const meta = activeStreamsMeta.get(pk);
+                if (meta)
+                    meta.lastTool = title;
+                return adapter.send(msg.peerId, {
+                    text: `🔧 ${humanizeToolName(title)}...`,
+                    replyToId: msg.replyToId,
+                });
+            },
             onHeartbeat: async () => {
                 if (adapter.sendTyping) {
                     await adapter.sendTyping(msg.peerId).catch(() => { });
@@ -197,6 +239,10 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
             },
             toolThrottleMs: deps.config.router.progress.toolThrottleMs,
             heartbeatMs: deps.config.router.progress.heartbeatMs,
+            onTodoUpdated: async (todos) => {
+                const text = formatTodoList(todos);
+                await adapter.send(msg.peerId, { text });
+            },
         }
         : undefined;
     let reply;
@@ -219,6 +265,7 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
     }
     finally {
         activeStreams.delete(pk);
+        activeStreamsMeta.delete(pk);
         pendingQuestions.delete(pk);
         if (adapter.stopTyping) {
             await adapter.stopTyping(msg.peerId).catch(() => { });
@@ -234,6 +281,8 @@ async function routeMessage(msg, deps, activeStreams, pendingQuestions) {
 export function createRouter(deps) {
     // Tracks which sessionId is currently streaming for each channel:peerId pair
     const activeStreams = new Map();
+    // Tracks timing + last tool for each active stream
+    const activeStreamsMeta = new Map();
     // Tracks pending question resolvers — when agent asks a question, user's next message resolves it
     const pendingQuestions = new Map();
     async function handler(msg) {
@@ -247,7 +296,7 @@ export function createRouter(deps) {
                 pending.resolve(msg.text);
                 return;
             }
-            await routeMessage(msg, deps, activeStreams, pendingQuestions);
+            await routeMessage(msg, deps, activeStreams, activeStreamsMeta, pendingQuestions);
         }
         catch (err) {
             deps.logger.error("router: unhandled error", {

package/dist/config/loader.js

@@ -1,3 +1,4 @@
+import { dirname, isAbsolute, resolve } from "node:path";
 import { fileExists, readJsonFile } from "../compat.js";
 import { configSchema } from "./schema.js";
 function expand(value) {
@@ -22,12 +23,12 @@ function expandDeep(obj) {
     }
     return obj;
 }
-const searchPaths = [
-    process.env.OPENCODE_CLAW_CONFIG,
-    "./opencode-claw.json",
-    `${process.env.HOME}/.config/opencode-claw/config.json`,
-].filter(Boolean);
 export async function loadConfig() {
+    const searchPaths = [
+        process.env.OPENCODE_CLAW_CONFIG,
+        "./opencode-claw.json",
+        `${process.env.HOME}/.config/opencode-claw/config.json`,
+    ].filter(Boolean);
     let raw = null;
     let found = "";
     for (const p of searchPaths) {
@@ -53,5 +54,16 @@ export async function loadConfig() {
             .join("\n");
         throw new Error(`Config validation failed (${found}):\n${errors}`);
     }
-    return result.data;
+    const data = result.data;
+    const base = dirname(resolve(found));
+    function resolvePath(p) {
+        return isAbsolute(p) ? p : resolve(base, p);
+    }
+    data.memory.txt.directory = resolvePath(data.memory.txt.directory);
+    data.sessions.persistPath = resolvePath(data.sessions.persistPath);
+    data.outbox.directory = resolvePath(data.outbox.directory);
+    if (data.channels.whatsapp) {
+        data.channels.whatsapp.authDir = resolvePath(data.channels.whatsapp.authDir);
+    }
+    return data;
 }

package/dist/memory/plugin.js

@@ -57,7 +57,12 @@ function createMemoryPlugin(backend) {
                 const block = memories.map((m) => `- [${m.category}] ${m.content}`).join("\n");
                 output.system.push(`\n\n## Relevant Context from Memory\n${block}`);
             }
-            output.system.push(`\n\n## Memory Instructions\nYou have access to persistent long-term memory across sessions via two tools:\n- **memory_search**: Look up stored facts about projects, workflows, and past experiences.\n- **memory_store**: Save important information so it persists across sessions.\n\n**When to search memory:**\n- At the start of any task involving a project — search for its location, build commands, test steps, and relationships to other projects.\n- When you are unsure about a project's structure or conventions.\n\n**When to store memory (do this proactively):**\n- Project facts: absolute path on disk, repo URL, language/stack, key entry points.\n- Dev workflows: how to build, run, lint, and format the project.\n- Test procedures: how to run tests locally, what test framework is used, any setup required.\n- Dependencies and relationships: which projects depend on each other, shared libraries, APIs consumed.\n- Architecture decisions: patterns used, notable design choices, known pitfalls.\n- Use category \`project\` for project-specific facts, \`knowledge\` for workflows and procedures, \`experience\` for lessons learned.\n\nStore facts at the granularity of one clear, self-contained statement per call.`);
+            output.system.push("\n\n## Memory — Mandatory Protocol", "\nYou have two persistent memory tools: **memory_search** and **memory_store**.", "\n\n**MANDATORY — you MUST follow this on every turn:**", "\n1. **BEFORE replying**: call `memory_search` with the user's topic. Always. No exceptions.", "\n2. **AFTER completing any task**: call `memory_store` for EVERY new fact you learned.", "\n\n**What to store (one fact per call):**", "\n- Project: absolute path, repo URL, language/stack, key entry points", "\n- Workflows: build, run, lint, test commands", "\n- Architecture: patterns, design decisions, known pitfalls", "\n- Preferences: user choices, style guidelines", "\n- Relationships: which projects depend on each other", "\n\n**Categories**: project | experience | preference | entity | event | knowledge", "\nStore one clear, self-contained statement per call. This is NOT optional.");
+        },
+        "experimental.session.compacting": async (_input, output) => {
+            output.context.push("MANDATORY: Before this session is compacted, call memory_store to preserve every important fact " +
+                "from this session. Store: project paths, build/run/test commands, architecture decisions, " +
+                "key file locations, lessons learned, user preferences. One fact per call. Do this first.");
         },
     });
 }

package/dist/plugin-root.d.ts

@@ -0,0 +1 @@
+export { memoryPlugin } from "./memory/plugin-entry.js";

package/dist/plugin-root.js

@@ -0,0 +1 @@
+export { memoryPlugin } from "./memory/plugin-entry.js";

package/dist/sessions/prompt.d.ts

@@ -1,12 +1,14 @@
-import type { OpencodeClient, QuestionRequest } from "@opencode-ai/sdk/v2";
+import type { OpencodeClient, QuestionRequest, Todo } from "@opencode-ai/sdk/v2";
 import type { Logger } from "../utils/logger.js";
 export type ToolProgressCallback = (tool: string, title: string) => Promise<void>;
 export type HeartbeatCallback = () => Promise<void>;
 export type QuestionCallback = (question: QuestionRequest) => Promise<Array<Array<string>>>;
+export type TodoUpdatedCallback = (todos: Todo[]) => Promise<void>;
 export type ProgressOptions = {
     onToolRunning?: ToolProgressCallback;
     onHeartbeat?: HeartbeatCallback;
     onQuestion?: QuestionCallback;
+    onTodoUpdated?: TodoUpdatedCallback;
     toolThrottleMs?: number;
     heartbeatMs?: number;
 };

package/dist/sessions/prompt.js

@@ -81,6 +81,16 @@ export async function promptStreaming(client, sessionId, promptText, timeoutMs,
                 }
                 continue;
             }
+            if (event.type === "todo.updated") {
+                const { sessionID, todos } = event.properties;
+                if (sessionID !== sessionId)
+                    continue;
+                if (progress?.onTodoUpdated) {
+                    await progress.onTodoUpdated(todos).catch(() => { });
+                    touchActivity();
+                }
+                continue;
+            }
             if (event.type === "session.error") {
                 const { sessionID, error } = event.properties;
                 if (sessionID && sessionID !== sessionId)

package/opencode-claw.example.json

@@ -59,7 +59,12 @@
     "maxAttempts": 3
   },
   "router": {
-    "timeoutMs": 300000
+    "timeoutMs": 300000,
+    "progress": {
+      "enabled": true,
+      "toolThrottleMs": 5000,
+      "heartbeatMs": 30000
+    }
   },
   "health": {
     "enabled": false,

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "opencode-claw",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Wrap OpenCode with persistent memory, messaging channels, and cron jobs",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/exports.js",
+  "main": "./dist/plugin-root.js",
   "types": "./dist/exports.d.ts",
   "bin": {
     "opencode-claw": "./dist/cli.js"
   },
   "exports": {
     ".": {
+      "import": "./dist/plugin-root.js",
+      "types": "./dist/plugin-root.d.ts"
+    },
+    "./lib": {
       "import": "./dist/exports.js",
       "types": "./dist/exports.d.ts"
     },