@colinmollenhour/occtl 1.0.0

package/dist/client.js

@@ -0,0 +1,64 @@
+import { createOpencodeClient } from "@opencode-ai/sdk";
+import { execSync } from "child_process";
+let _client = null;
+let _baseUrl = null;
+/**
+ * Auto-detect the OpenCode server by looking at running processes.
+ * Falls back to env vars or defaults.
+ */
+function detectServer() {
+    // Check env vars first
+    if (process.env.OPENCODE_SERVER_HOST || process.env.OPENCODE_SERVER_PORT) {
+        return {
+            host: process.env.OPENCODE_SERVER_HOST || "127.0.0.1",
+            port: process.env.OPENCODE_SERVER_PORT || "4096",
+        };
+    }
+    // Try to detect from running opencode process
+    try {
+        const output = execSync("ps aux | grep 'opencode serve' | grep -v grep", { encoding: "utf-8", timeout: 2000 });
+        const lines = output.trim().split("\n");
+        for (const line of lines) {
+            const portMatch = line.match(/--port\s+(\d+)/);
+            const hostMatch = line.match(/--hostname\s+([\w.:]+)/);
+            if (portMatch) {
+                return {
+                    host: hostMatch?.[1] || "127.0.0.1",
+                    port: portMatch[1],
+                };
+            }
+        }
+    }
+    catch {
+        // Process detection failed, fall through
+    }
+    return { host: "127.0.0.1", port: "4096" };
+}
+export function getBaseUrl() {
+    if (!_baseUrl) {
+        const { host, port } = detectServer();
+        _baseUrl = `http://${host}:${port}`;
+    }
+    return _baseUrl;
+}
+export function getClient() {
+    if (!_client) {
+        _client = createOpencodeClient({
+            baseUrl: getBaseUrl(),
+        });
+    }
+    return _client;
+}
+export async function ensureServer() {
+    const client = getClient();
+    try {
+        // Try listing sessions as a health check
+        await client.session.list();
+    }
+    catch {
+        console.error("Error: Cannot connect to OpenCode server at " + getBaseUrl());
+        console.error("Make sure OpenCode is running, or set OPENCODE_SERVER_HOST/OPENCODE_SERVER_PORT");
+        process.exit(1);
+    }
+    return client;
+}

package/dist/commands/session-abort.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionAbortCommand(): Command;

package/dist/commands/session-abort.js

@@ -0,0 +1,16 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+export function sessionAbortCommand() {
+    return new Command("abort")
+        .description("Abort a running session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .action(async (sessionId) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        await client.session.abort({
+            path: { id: resolved },
+        });
+        console.log(`Aborted session: ${resolved}`);
+    });
+}

package/dist/commands/session-children.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionChildrenCommand(): Command;

package/dist/commands/session-children.js

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatSession, formatJSON } from "../format.js";
+export function sessionChildrenCommand() {
+    return new Command("children")
+        .description("List child sessions (sub-agents) of a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.children({
+            path: { id: resolved },
+        });
+        const children = result.data ?? [];
+        if (opts.json) {
+            console.log(formatJSON(children));
+            return;
+        }
+        if (children.length === 0) {
+            console.log("No child sessions.");
+            return;
+        }
+        console.log("ID\tTITLE\tUPDATED");
+        for (const s of children) {
+            console.log(formatSession(s));
+        }
+    });
+}

package/dist/commands/session-create.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionCreateCommand(): Command;

package/dist/commands/session-create.js

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatSessionDetailed, formatJSON } from "../format.js";
+export function sessionCreateCommand() {
+    return new Command("create")
+        .alias("new")
+        .description("Create a new session")
+        .option("-t, --title <title>", "Session title")
+        .option("-p, --parent <id>", "Parent session ID (creates a child/sub-agent session)")
+        .option("-d, --dir <path>", "Project directory for the session (defaults to cwd)")
+        .option("-j, --json", "Output as JSON")
+        .option("-q, --quiet", "Only output the session ID")
+        .action(async (opts) => {
+        const client = await ensureServer();
+        const directory = opts.dir
+            ? (await import("path")).resolve(opts.dir)
+            : process.cwd();
+        const result = await client.session.create({
+            body: {
+                ...(opts.title && { title: opts.title }),
+                ...(opts.parent && { parentID: opts.parent }),
+            },
+            query: { directory },
+        });
+        if (!result.data) {
+            console.error("Failed to create session.");
+            process.exit(1);
+        }
+        if (opts.quiet) {
+            console.log(result.data.id);
+            return;
+        }
+        if (opts.json) {
+            console.log(formatJSON(result.data));
+            return;
+        }
+        console.log(formatSessionDetailed(result.data));
+    });
+}

package/dist/commands/session-diff.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionDiffCommand(): Command;

package/dist/commands/session-diff.js

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatJSON } from "../format.js";
+export function sessionDiffCommand() {
+    return new Command("diff")
+        .description("Show the diff (file changes) for a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.diff({
+            path: { id: resolved },
+        });
+        const diffs = result.data ?? [];
+        if (opts.json) {
+            console.log(formatJSON(diffs));
+            return;
+        }
+        if (diffs.length === 0) {
+            console.log("No file changes in this session.");
+            return;
+        }
+        for (const d of diffs) {
+            console.log(`--- ${d.file}`);
+            console.log(`+${d.additions} -${d.deletions}`);
+            if (d.before !== d.after) {
+                console.log(`Before: ${d.before.slice(0, 100)}`);
+                console.log(`After:  ${d.after.slice(0, 100)}`);
+            }
+            console.log("");
+        }
+    });
+}

package/dist/commands/session-get.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionGetCommand(): Command;

package/dist/commands/session-get.js

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatSessionDetailed, formatJSON } from "../format.js";
+export function sessionGetCommand() {
+    return new Command("get")
+        .description("Get session details")
+        .argument("<session-id>", "Session ID")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const result = await client.session.get({
+            path: { id: sessionId },
+        });
+        if (!result.data) {
+            console.error(`Session not found: ${sessionId}`);
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(formatJSON(result.data));
+            return;
+        }
+        console.log(formatSessionDetailed(result.data));
+    });
+}

package/dist/commands/session-last.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionLastCommand(): Command;

package/dist/commands/session-last.js

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatMessage, formatJSON } from "../format.js";
+import { resolveSession } from "../resolve.js";
+export function sessionLastCommand() {
+    return new Command("last")
+        .description("Get the last message from a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .option("-v, --verbose", "Show tool calls and extra details")
+        .option("-t, --text-only", "Show only text content (default)")
+        .option("--role <role>", "Get last message of a specific role (user or assistant)")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.messages({
+            path: { id: resolved },
+        });
+        let messages = result.data ?? [];
+        if (opts.role) {
+            messages = messages.filter((m) => m.info.role === opts.role);
+        }
+        if (messages.length === 0) {
+            console.error("No messages in session.");
+            process.exit(1);
+        }
+        const last = messages[messages.length - 1];
+        if (opts.json) {
+            console.log(formatJSON(last));
+            return;
+        }
+        // Default to text-only for the 'last' command unless verbose
+        const textOnly = opts.verbose ? false : (opts.textOnly !== false);
+        console.log(formatMessage(last.info, last.parts, {
+            verbose: opts.verbose,
+            textOnly,
+        }));
+    });
+}

package/dist/commands/session-list.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionListCommand(): Command;

package/dist/commands/session-list.js

@@ -0,0 +1,91 @@
+import { Command } from "commander";
+import path from "path";
+import { ensureServer } from "../client.js";
+import { formatSession, formatSessionDetailed, formatJSON } from "../format.js";
+export function sessionListCommand() {
+    return new Command("list")
+        .alias("ls")
+        .description("List sessions. Default: current directory only. Pass a path to filter by directory, or --all for everything.")
+        .argument("[directory]", "Only show sessions for this directory")
+        .option("-j, --json", "Output as JSON")
+        .option("-d, --detailed", "Show detailed info for each session")
+        .option("-n, --limit <n>", "Limit number of results", parseInt)
+        .option("-a, --all", "Show sessions for all directories")
+        .option("-c, --children", "Include child sessions (sub-agents)")
+        .option("--sort <field>", "Sort by: updated (default), created, title", "updated")
+        .option("--asc", "Sort ascending instead of descending")
+        .action(async (directory, opts) => {
+        const client = await ensureServer();
+        // Determine which directory to filter by
+        let filterDir;
+        if (opts.all) {
+            filterDir = undefined;
+        }
+        else if (directory) {
+            filterDir = path.resolve(directory);
+        }
+        else {
+            filterDir = process.cwd();
+        }
+        const result = await client.session.list({
+            ...(filterDir && { query: { directory: filterDir } }),
+        });
+        let sessions = result.data ?? [];
+        // Client-side directory filtering as fallback
+        if (filterDir) {
+            sessions = sessions.filter((s) => s.directory === filterDir);
+        }
+        // Filter out child sessions unless --children
+        if (!opts.children) {
+            sessions = sessions.filter((s) => !s.parentID);
+        }
+        // Sort
+        const sortField = opts.sort;
+        const ascending = !!opts.asc;
+        sessions.sort((a, b) => {
+            let cmp = 0;
+            switch (sortField) {
+                case "created":
+                    cmp = b.time.created - a.time.created;
+                    break;
+                case "title":
+                    cmp = (a.title || "").localeCompare(b.title || "");
+                    break;
+                case "updated":
+                default:
+                    cmp = b.time.updated - a.time.updated;
+                    break;
+            }
+            return ascending ? -cmp : cmp;
+        });
+        // Apply limit
+        if (opts.limit && opts.limit > 0) {
+            sessions = sessions.slice(0, opts.limit);
+        }
+        if (opts.json) {
+            console.log(formatJSON(sessions));
+            return;
+        }
+        if (sessions.length === 0) {
+            if (filterDir) {
+                console.log(`No sessions found for ${filterDir}.`);
+            }
+            else {
+                console.log("No sessions found.");
+            }
+            return;
+        }
+        if (opts.detailed) {
+            for (const s of sessions) {
+                console.log(formatSessionDetailed(s));
+                console.log("");
+            }
+        }
+        else {
+            console.log("ID\tTITLE\tUPDATED");
+            for (const s of sessions) {
+                console.log(formatSession(s));
+            }
+        }
+    });
+}

package/dist/commands/session-messages.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionMessagesCommand(): Command;

package/dist/commands/session-messages.js

@@ -0,0 +1,44 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatMessage, formatJSON } from "../format.js";
+import { resolveSession } from "../resolve.js";
+export function sessionMessagesCommand() {
+    return new Command("messages")
+        .alias("msgs")
+        .description("List messages in a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .option("-v, --verbose", "Show tool calls and extra details")
+        .option("-t, --text-only", "Show only text content")
+        .option("-n, --limit <n>", "Limit number of messages", parseInt)
+        .option("--role <role>", "Filter by role (user or assistant)")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.messages({
+            path: { id: resolved },
+        });
+        let messages = result.data ?? [];
+        if (opts.role) {
+            messages = messages.filter((m) => m.info.role === opts.role);
+        }
+        if (opts.limit && opts.limit > 0) {
+            messages = messages.slice(-opts.limit);
+        }
+        if (opts.json) {
+            console.log(formatJSON(messages));
+            return;
+        }
+        if (messages.length === 0) {
+            console.log("No messages in session.");
+            return;
+        }
+        for (const m of messages) {
+            console.log(formatMessage(m.info, m.parts, {
+                verbose: opts.verbose,
+                textOnly: opts.textOnly,
+            }));
+            console.log("");
+        }
+    });
+}

package/dist/commands/session-respond.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionRespondCommand(): Command;

package/dist/commands/session-respond.js

@@ -0,0 +1,78 @@
+import { Command } from "commander";
+import { ensureServer, getClient } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatJSON } from "../format.js";
+import { streamEvents } from "../sse.js";
+export function sessionRespondCommand() {
+    return new Command("respond")
+        .description("Respond to a permission request in a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-r, --response <response>", "Response: once, always, or reject", "once")
+        .option("-j, --json", "Output as JSON")
+        .option("-p, --permission-id <id>", "Permission ID to respond to (auto-detects if omitted)")
+        .option("-w, --wait", "Wait for a permission request if none pending")
+        .option("--auto-approve", "Automatically approve all permission requests (implies --wait)")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const validResponses = ["once", "always", "reject"];
+        if (!validResponses.includes(opts.response)) {
+            console.error(`Invalid response: ${opts.response}. Must be one of: ${validResponses.join(", ")}`);
+            process.exit(1);
+        }
+        if (opts.permissionId) {
+            await respondToPermission(resolved, opts.permissionId, opts.response);
+            if (opts.json) {
+                console.log(formatJSON({ success: true, permissionId: opts.permissionId }));
+            }
+            else {
+                console.log(`Responded to permission ${opts.permissionId} with: ${opts.response}`);
+            }
+            return;
+        }
+        if (opts.wait || opts.autoApprove) {
+            await waitAndRespond(resolved, opts);
+            return;
+        }
+        console.error("No --permission-id specified. Use --wait to wait for permission requests.");
+        process.exit(1);
+    });
+}
+async function respondToPermission(sessionId, permissionId, response) {
+    const client = getClient();
+    await client.postSessionIdPermissionsPermissionId({
+        path: { id: sessionId, permissionID: permissionId },
+        body: { response },
+    });
+}
+async function waitAndRespond(sessionId, opts) {
+    console.error(`Waiting for permission requests on session ${sessionId}...`);
+    console.error("Press Ctrl+C to stop.\n");
+    const result = await streamEvents(sessionId, async (event) => {
+        if (event.type !== "permission.updated")
+            return;
+        const props = event.properties;
+        // Skip permissions that are not pending (already resolved)
+        if (props.status && props.status !== "pending")
+            return;
+        console.error(`Permission request: ${props.title} (type: ${props.type}, id: ${props.id})`);
+        try {
+            if (opts.autoApprove) {
+                await respondToPermission(sessionId, props.id, "once");
+                console.error(`Auto-approved: ${props.id}`);
+            }
+            else {
+                await respondToPermission(sessionId, props.id, opts.response);
+                console.error(`Responded with "${opts.response}": ${props.id}`);
+                return "stop";
+            }
+        }
+        catch (err) {
+            console.error(`Failed to respond to ${props.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    if (result === "disconnected") {
+        console.error("Error: lost connection to OpenCode server.");
+        process.exit(1);
+    }
+}

package/dist/commands/session-send.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionSendCommand(): Command;

package/dist/commands/session-send.js

@@ -0,0 +1,114 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatMessage, formatJSON } from "../format.js";
+import { resolveSession } from "../resolve.js";
+import { waitForIdle } from "../wait-util.js";
+export function sessionSendCommand() {
+    return new Command("send")
+        .alias("prompt")
+        .description("Send a message to a session")
+        .argument("<message...>", "Message text to send")
+        .option("-s, --session <id>", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output response as JSON")
+        .option("-v, --verbose", "Show tool calls and extra details")
+        .option("-t, --text-only", "Show only text content in response")
+        .option("--no-reply", "Send as context injection (no AI response)")
+        .option("--async", "Send async and return immediately")
+        .option("-w, --wait", "Send async, block until session is idle, then show the last message")
+        .option("--agent <agent>", "Agent to use")
+        .option("--model <model>", "Model to use (format: provider/model)")
+        .option("--stdin", "Read message from stdin instead of arguments")
+        .action(async (messageParts, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, opts.session);
+        let messageText;
+        if (opts.stdin) {
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            messageText = Buffer.concat(chunks).toString("utf-8").trim();
+        }
+        else {
+            messageText = messageParts.join(" ");
+        }
+        if (!messageText) {
+            console.error("No message provided.");
+            process.exit(1);
+        }
+        // Parse model if provided
+        let model;
+        if (opts.model) {
+            const parts = opts.model.split("/");
+            if (parts.length === 2 && parts[0] && parts[1]) {
+                model = { providerID: parts[0], modelID: parts[1] };
+            }
+        }
+        const body = {
+            parts: [{ type: "text", text: messageText }],
+            ...(model && { model }),
+            ...(opts.agent && { agent: opts.agent }),
+            ...(opts.reply === false && { noReply: true }),
+        };
+        // --async: fire and forget
+        if (opts.async) {
+            await client.session.promptAsync({
+                path: { id: resolved },
+                body,
+            });
+            console.log("Message sent (async).");
+            return;
+        }
+        // --wait: send async, then block until session.idle, then show result
+        if (opts.wait) {
+            await client.session.promptAsync({
+                path: { id: resolved },
+                body,
+            });
+            const result = await waitForIdle(client, resolved);
+            if (!result.idle) {
+                if (result.reason === "disconnected") {
+                    console.error("Error: lost connection to OpenCode server.");
+                }
+                process.exit(1);
+            }
+            // Fetch and display the last assistant message
+            const msgs = await client.session.messages({
+                path: { id: resolved },
+            });
+            const messages = msgs.data ?? [];
+            const last = messages.filter((m) => m.info.role === "assistant").pop();
+            if (!last) {
+                console.error("No assistant response found.");
+                process.exit(1);
+            }
+            if (opts.json) {
+                console.log(formatJSON(last));
+                return;
+            }
+            const textOnly = opts.verbose ? false : (opts.textOnly !== false);
+            console.log(formatMessage(last.info, last.parts, {
+                verbose: opts.verbose,
+                textOnly,
+            }));
+            return;
+        }
+        // Default: synchronous send (blocks until response)
+        const syncResult = await client.session.prompt({
+            path: { id: resolved },
+            body,
+        });
+        if (!syncResult.data) {
+            console.error("No response received.");
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(formatJSON(syncResult.data));
+            return;
+        }
+        console.log(formatMessage(syncResult.data.info, syncResult.data.parts, {
+            verbose: opts.verbose,
+            textOnly: opts.textOnly ?? true,
+        }));
+    });
+}

package/dist/commands/session-share.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function sessionShareCommand(): Command;
+export declare function sessionUnshareCommand(): Command;