owlcode 0.1.0

package/.env.example

@@ -0,0 +1,17 @@
+# Telegram Bot Token (from @BotFather)
+TELEGRAM_BOT_TOKEN=
+
+# Allowed Telegram user IDs (comma-separated)
+ALLOWED_USERS=
+
+# Default project directory
+DEFAULT_PROJECT_DIR=
+
+# Claude Code CLI path (optional, defaults to 'claude')
+CLAUDE_CLI_PATH=claude
+
+# Session idle timeout in minutes (default: 30)
+SESSION_TIMEOUT_MIN=30
+
+# Log level: debug | info | warn | error
+LOG_LEVEL=info

package/README.md

@@ -0,0 +1,137 @@
+# owlcode
+
+Remote Claude Code access via Telegram. Send a message, get Claude Code's response — right from your phone.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+
+### Claude Code authentication
+
+Make sure Claude Code is logged in before starting the bot:
+
+```bash
+claude /login
+```
+
+Verify it works:
+
+```bash
+claude --print "say hello"
+```
+
+## Install
+
+```bash
+npm install -g owlcode
+```
+
+Or clone the repo:
+
+```bash
+git clone https://github.com/cr8rcho/owlcode.git
+cd owlcode
+npm install
+npm run build
+```
+
+## Setup
+
+### 1. Create a Telegram bot
+
+1. Open [@BotFather](https://t.me/botfather) on Telegram
+2. Send `/newbot` and follow the steps
+3. Copy the bot token
+
+### 2. Get your Telegram user ID
+
+1. Open [@userinfobot](https://t.me/userinfobot) on Telegram
+2. It will show your user ID
+
+### 3. Run the setup wizard
+
+```bash
+owlcode init
+```
+
+This will ask for:
+- Telegram bot token
+- Your Telegram user ID (only authorized users can use the bot)
+- Default project directory
+- Claude Code CLI path (defaults to `claude`)
+- Session idle timeout in minutes (defaults to 30)
+
+A `.env` file is created with your settings.
+
+### 4. Start the bot
+
+```bash
+owlcode start
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ls [path]` | Browse directories with inline buttons |
+| `/status` | Session info — current directory, Claude status, verbose level |
+| `/session_reset` | End current Claude Code conversation and start fresh |
+| `/verbose <0\|1\|2>` | Set output detail: 0 = result only, 1 = tools + result (default), 2 = full |
+| `/help` | Show available commands |
+
+Any other message is forwarded to Claude Code as a prompt. Claude Code runs in `--print` (non-interactive) mode with the current project directory as its working directory.
+
+### Directory browsing
+
+Use `/ls` to browse directories with tappable inline buttons. Git repos are sorted first and marked with `[git]`. Tap a folder to navigate into it, or tap "Select this directory" to set it as the current project.
+
+You can also pass a path directly: `/ls ~/projects`
+
+## How it works
+
+### Session lifecycle
+
+1. Your first message creates a session with the default project directory.
+2. Each message spawns a Claude Code CLI process (`claude --print`) and passes your message via stdin.
+3. After the first successful response, subsequent messages use `--continue` to maintain conversation context.
+4. If no messages are sent for the configured timeout (default 30 min), the CLI process is released to free memory — but the conversation state is preserved. Your next message will resume with `--continue`.
+5. `/session_reset` fully ends the conversation. The next message starts a new one.
+
+### Session persistence
+
+Session state (directory, verbose level) is saved to `.owlcode-sessions.json`. When the bot restarts, sessions are restored — so your project directory and settings survive reboots.
+
+### Architecture
+
+```
+Telegram → TelegramBot (grammY) → SessionManager → ClaudeRunner (CLI subprocess)
+```
+
+- **TelegramBot**: Thin grammY wrapper. All Telegram-specific code isolated here for easy replacement.
+- **SessionManager**: Per-user session with project directory tracking, idle cleanup, and disk persistence.
+- **ClaudeRunner**: Spawns `claude --print` as subprocess. Messages passed via stdin (supports CJK). Supports text and stream-json output modes.
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `owlcode init` | Interactive setup wizard |
+| `owlcode start` | Start the bot |
+| `owlcode version` | Show version |
+| `owlcode help` | Show help |
+
+## Development
+
+```bash
+git clone https://github.com/cr8rcho/owlcode.git
+cd owlcode
+npm install
+cp .env.example .env
+# Edit .env with your settings
+npm run dev
+```
+
+## License
+
+MIT

package/dist/claude/runner.d.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from "events";
+export interface ClaudeRunnerOptions {
+    cliPath: string;
+    cwd: string;
+    sessionId?: string;
+}
+export interface ClaudeResponse {
+    text: string;
+    toolUse?: string[];
+}
+export declare class ClaudeRunner extends EventEmitter {
+    private options;
+    private process;
+    constructor(options: ClaudeRunnerOptions, hasExistingSession?: boolean);
+    get isRunning(): boolean;
+    get cwd(): string;
+    private hasSession;
+    private buildArgs;
+    /**
+     * Send a message to Claude Code and get the response.
+     * Uses --print flag with --continue for session continuity.
+     * Message is passed via stdin to avoid encoding issues with CJK characters.
+     */
+    send(message: string): Promise<ClaudeResponse>;
+    /**
+     * Send a message using streaming mode with JSON output.
+     * Message is passed via stdin to avoid encoding issues.
+     */
+    sendStreaming(message: string, onChunk: (text: string) => void): Promise<ClaudeResponse>;
+    kill(): void;
+}

package/dist/claude/runner.js

@@ -0,0 +1,160 @@
+/**
+ * Claude Code CLI runner.
+ * Spawns and communicates with Claude Code as a subprocess.
+ */
+import { spawn } from "child_process";
+import { EventEmitter } from "events";
+export class ClaudeRunner extends EventEmitter {
+    options;
+    process = null;
+    constructor(options, hasExistingSession = false) {
+        super();
+        this.options = options;
+        this.hasSession = hasExistingSession;
+    }
+    get isRunning() {
+        return this.process !== null && this.process.exitCode === null;
+    }
+    get cwd() {
+        return this.options.cwd;
+    }
+    hasSession = false;
+    buildArgs(outputFormat) {
+        const args = ["--print", "--output-format", outputFormat];
+        if (outputFormat === "stream-json") {
+            args.push("--verbose");
+        }
+        // Continue previous conversation if one exists
+        if (this.hasSession) {
+            args.push("--continue");
+        }
+        return args;
+    }
+    /**
+     * Send a message to Claude Code and get the response.
+     * Uses --print flag with --continue for session continuity.
+     * Message is passed via stdin to avoid encoding issues with CJK characters.
+     */
+    async send(message) {
+        return new Promise((resolve, reject) => {
+            const args = this.buildArgs("text");
+            const proc = spawn(this.options.cliPath, args, {
+                cwd: this.options.cwd,
+                env: {
+                    ...process.env,
+                    LANG: "en_US.UTF-8",
+                    CLAUDE_CODE_DISABLE_NONINTERACTIVE_HINT: "1",
+                },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            this.process = proc;
+            let stdout = "";
+            let stderr = "";
+            proc.stdout?.on("data", (data) => {
+                const chunk = data.toString("utf-8");
+                stdout += chunk;
+                this.emit("chunk", chunk);
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString("utf-8");
+            });
+            proc.on("close", (code) => {
+                this.process = null;
+                if (code === 0) {
+                    this.hasSession = true;
+                    resolve({
+                        text: stdout.trim(),
+                    });
+                }
+                else {
+                    reject(new Error(`Claude Code exited with code ${code}: ${stderr.trim()}`));
+                }
+            });
+            proc.on("error", (err) => {
+                this.process = null;
+                reject(err);
+            });
+            // Write message via stdin then close
+            proc.stdin?.write(message, "utf-8");
+            proc.stdin?.end();
+        });
+    }
+    /**
+     * Send a message using streaming mode with JSON output.
+     * Message is passed via stdin to avoid encoding issues.
+     */
+    async sendStreaming(message, onChunk) {
+        return new Promise((resolve, reject) => {
+            const args = this.buildArgs("stream-json");
+            const proc = spawn(this.options.cliPath, args, {
+                cwd: this.options.cwd,
+                env: {
+                    ...process.env,
+                    LANG: "en_US.UTF-8",
+                    CLAUDE_CODE_DISABLE_NONINTERACTIVE_HINT: "1",
+                },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            this.process = proc;
+            let fullText = "";
+            let resultText = "";
+            let stderr = "";
+            const toolUse = [];
+            proc.stdout?.on("data", (data) => {
+                const lines = data.toString("utf-8").split("\n").filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.type === "assistant" && event.message?.content) {
+                            for (const block of event.message.content) {
+                                if (block.type === "text") {
+                                    fullText += block.text;
+                                    onChunk(block.text);
+                                }
+                                else if (block.type === "tool_use") {
+                                    toolUse.push(block.name);
+                                }
+                            }
+                        }
+                        else if (event.type === "result") {
+                            resultText = event.result ?? "";
+                        }
+                        // Ignore other event types (system, user, etc.)
+                    }
+                    catch {
+                        // Non-JSON line — skip to avoid prompt echo
+                    }
+                }
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString("utf-8");
+            });
+            proc.on("close", (code) => {
+                this.process = null;
+                if (code === 0) {
+                    this.hasSession = true;
+                    // Prefer streamed assistant text; fall back to result text only if empty
+                    const finalText = fullText.trim() || resultText.trim();
+                    resolve({ text: finalText, toolUse });
+                }
+                else {
+                    reject(new Error(`Claude Code exited with code ${code}: ${stderr.trim()}`));
+                }
+            });
+            proc.on("error", (err) => {
+                this.process = null;
+                reject(err);
+            });
+            // Write message via stdin then close
+            proc.stdin?.write(message, "utf-8");
+            proc.stdin?.end();
+        });
+    }
+    kill() {
+        if (this.process) {
+            this.process.kill("SIGTERM");
+            this.process = null;
+        }
+        this.hasSession = false;
+    }
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { existsSync, writeFileSync, readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { createInterface } from "readline";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function ask(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : "";
+    return new Promise((resolve) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            resolve(answer.trim() || defaultValue || "");
+        });
+    });
+}
+async function init() {
+    console.log("\n🦉 owlcode setup\n");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log("1. Create a Telegram bot:");
+    console.log("   → Open @BotFather on Telegram");
+    console.log("   → Send /newbot and follow the steps");
+    console.log("   → Copy the bot token\n");
+    const botToken = await ask(rl, "Telegram bot token");
+    if (!botToken) {
+        console.error("Bot token is required.");
+        rl.close();
+        process.exit(1);
+    }
+    console.log("\n2. Get your Telegram user ID:");
+    console.log("   → Open @userinfobot on Telegram");
+    console.log("   → It will show your user ID\n");
+    const allowedUsers = await ask(rl, "Your Telegram user ID");
+    if (!allowedUsers) {
+        console.error("User ID is required.");
+        rl.close();
+        process.exit(1);
+    }
+    const defaultDir = await ask(rl, "Default project directory", process.env.HOME || "~");
+    const claudePath = await ask(rl, "Claude Code CLI path", "claude");
+    const sessionTimeout = await ask(rl, "Session idle timeout (minutes)", "30");
+    rl.close();
+    const envContent = [
+        `TELEGRAM_BOT_TOKEN=${botToken}`,
+        `ALLOWED_USERS=${allowedUsers}`,
+        `DEFAULT_PROJECT_DIR=${defaultDir}`,
+        `CLAUDE_CLI_PATH=${claudePath}`,
+        `SESSION_TIMEOUT_MIN=${sessionTimeout}`,
+        `LOG_LEVEL=info`,
+    ].join("\n");
+    const envPath = resolve(process.cwd(), ".env");
+    if (existsSync(envPath)) {
+        const overwrite = await new Promise((resolve) => {
+            const rl2 = createInterface({ input: process.stdin, output: process.stdout });
+            rl2.question(".env already exists. Overwrite? (y/N): ", (answer) => {
+                rl2.close();
+                resolve(answer.trim().toLowerCase() === "y");
+            });
+        });
+        if (!overwrite) {
+            console.log("Skipped .env creation.");
+            return;
+        }
+    }
+    writeFileSync(envPath, envContent + "\n");
+    console.log("\n✓ .env created");
+    console.log("\nRun 'owlcode start' to launch the bot.");
+}
+async function start() {
+    const envPath = resolve(process.cwd(), ".env");
+    if (!existsSync(envPath)) {
+        console.error("No .env found. Run 'owlcode init' first.");
+        process.exit(1);
+    }
+    console.log("🦉 Starting owlcode...\n");
+    // Resolve the actual index.js path
+    const indexPath = resolve(__dirname, "index.js");
+    if (!existsSync(indexPath)) {
+        console.error(`Entry point not found: ${indexPath}`);
+        process.exit(1);
+    }
+    const child = spawn("node", [indexPath], {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        env: process.env,
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+}
+function version() {
+    try {
+        const pkgPath = resolve(__dirname, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        console.log(`owlcode v${pkg.version}`);
+    }
+    catch {
+        console.log("owlcode (unknown version)");
+    }
+}
+function help() {
+    console.log(`
+🦉 owlcode — Remote Claude Code via Telegram
+
+Commands:
+  init      Interactive setup (creates .env)
+  start     Start the bot
+  version   Show version
+  help      Show this help
+
+Usage:
+  owlcode init
+  owlcode start
+`);
+}
+// --- CLI Router ---
+const command = process.argv[2];
+switch (command) {
+    case "init":
+        init();
+        break;
+    case "start":
+        start();
+        break;
+    case "version":
+    case "--version":
+    case "-v":
+        version();
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+        help();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        help();
+        process.exit(1);
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface Config {
+    telegram: {
+        botToken: string;
+        allowedUsers: number[];
+    };
+    claude: {
+        cliPath: string;
+        sessionTimeoutMin: number;
+    };
+    defaultProjectDir: string;
+    logLevel: "debug" | "info" | "warn" | "error";
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+export function loadConfig() {
+    // Load .env file if exists
+    const envPath = resolve(process.cwd(), ".env");
+    if (existsSync(envPath)) {
+        const envContent = readFileSync(envPath, "utf-8");
+        for (const line of envContent.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx === -1)
+                continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            if (!process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+    }
+    const botToken = process.env.TELEGRAM_BOT_TOKEN;
+    if (!botToken) {
+        throw new Error("TELEGRAM_BOT_TOKEN is required");
+    }
+    const allowedUsers = (process.env.ALLOWED_USERS ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map(Number);
+    if (allowedUsers.length === 0) {
+        throw new Error("ALLOWED_USERS is required (comma-separated Telegram user IDs)");
+    }
+    return {
+        telegram: {
+            botToken,
+            allowedUsers,
+        },
+        claude: {
+            cliPath: process.env.CLAUDE_CLI_PATH ?? "claude",
+            sessionTimeoutMin: Number(process.env.SESSION_TIMEOUT_MIN ?? "30"),
+        },
+        defaultProjectDir: process.env.DEFAULT_PROJECT_DIR ?? process.env.HOME ?? "/tmp",
+        logLevel: process.env.LOG_LEVEL ?? "info",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,190 @@
+import { existsSync, readdirSync } from "fs";
+import { resolve, basename } from "path";
+import { loadConfig } from "./config.js";
+import { TelegramBot } from "./telegram/bot.js";
+import { SessionManager } from "./session/manager.js";
+const config = loadConfig();
+const bot = new TelegramBot(config);
+const sessions = new SessionManager(config.claude.cliPath, config.defaultProjectDir, config.claude.sessionTimeoutMin);
+// --- Path cache for short callback data ---
+// Telegram callback_data has a 64-byte limit, so we use short IDs
+const pathCache = new Map();
+let pathCounter = 0;
+function pathToId(fullPath) {
+    // Check if already cached
+    for (const [id, path] of pathCache) {
+        if (path === fullPath)
+            return id;
+    }
+    const id = `p${pathCounter++}`;
+    pathCache.set(id, fullPath);
+    return id;
+}
+function idToPath(id) {
+    return pathCache.get(id);
+}
+// --- Helper: list directories ---
+function listDirs(dirPath) {
+    try {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+            .map((e) => {
+            const fullPath = resolve(dirPath, e.name);
+            const isGit = existsSync(resolve(fullPath, ".git"));
+            return { name: e.name, path: fullPath, isGit };
+        })
+            .sort((a, b) => {
+            // Git repos first, then alphabetical
+            if (a.isGit !== b.isGit)
+                return a.isGit ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+    }
+    catch {
+        return [];
+    }
+}
+const MAX_BUTTONS = 30;
+function buildDirButtons(dirPath) {
+    const dirs = listDirs(dirPath);
+    const buttons = [];
+    // Parent directory
+    const parent = resolve(dirPath, "..");
+    if (parent !== dirPath) {
+        buttons.push({ text: ".. (up)", data: `ls:${pathToId(parent)}` });
+    }
+    // Subdirectories (limit to avoid Telegram errors)
+    const limited = dirs.slice(0, MAX_BUTTONS);
+    for (const dir of limited) {
+        const label = dir.isGit ? `[git] ${dir.name}` : dir.name;
+        buttons.push({ text: label, data: `ls:${pathToId(dir.path)}` });
+    }
+    if (dirs.length > MAX_BUTTONS) {
+        buttons.push({ text: `... +${dirs.length - MAX_BUTTONS} more`, data: `noop:0` });
+    }
+    // Select current directory button
+    buttons.push({ text: ">> Select this directory", data: `cd:${pathToId(dirPath)}` });
+    return buttons;
+}
+// --- Commands ---
+bot.onCommand("ls", async (msg) => {
+    const session = sessions.getOrCreate(msg.userId, msg.chatId);
+    const arg = msg.text.replace(/^\/ls\s*/, "").trim();
+    const targetDir = arg
+        ? resolve(arg.replace("~", process.env.HOME ?? ""))
+        : session.cwd;
+    if (!existsSync(targetDir)) {
+        return `Directory not found: ${targetDir}`;
+    }
+    const buttons = buildDirButtons(targetDir);
+    if (buttons.length <= 1) {
+        return `No subdirectories in: ${targetDir}`;
+    }
+    await bot.sendWithButtons(msg.chatId, targetDir, buttons, 1);
+});
+bot.onCommand("status", async (msg) => {
+    const session = sessions.get(msg.userId);
+    if (!session)
+        return "No active session.";
+    return [
+        `Project: ${session.cwd}`,
+        `Claude: ${session.runner?.isRunning ? "running" : "idle"}`,
+        `Verbose: ${session.verbose}`,
+    ].join("\n");
+});
+bot.onCommand("session_reset", async (msg) => {
+    sessions.stopSession(msg.userId);
+    return "Session reset.";
+});
+bot.onCommand("verbose", async (msg) => {
+    const level = parseInt(msg.text.replace(/^\/verbose\s*/, "").trim(), 10);
+    if (![0, 1, 2].includes(level)) {
+        return "Usage: /verbose <0|1|2>";
+    }
+    sessions.setVerbose(msg.userId, level);
+    return `Verbose set to ${level}.`;
+});
+// --- Callback handlers ---
+// ls: browse directories
+bot.onCallback("ls", async (query) => {
+    const pathId = query.data.replace("ls:", "");
+    const dirPath = idToPath(pathId);
+    if (!dirPath || !existsSync(dirPath))
+        return "Directory not found";
+    const buttons = buildDirButtons(dirPath);
+    await bot.editWithButtons(query.chatId, query.messageId, dirPath, buttons, 1);
+});
+// cd: select directory from browse
+bot.onCallback("cd", async (query) => {
+    const pathId = query.data.replace("cd:", "");
+    const dirPath = idToPath(pathId);
+    if (!dirPath || !existsSync(dirPath))
+        return "Directory not found";
+    sessions.setCwd(query.userId, dirPath);
+    await bot.editWithButtons(query.chatId, query.messageId, `Changed to: ${dirPath}`, [], 1);
+    return `Changed to ${basename(dirPath)}`;
+});
+// --- Message handler: forward to Claude Code ---
+bot.onMessage(async (msg) => {
+    const session = sessions.getOrCreate(msg.userId, msg.chatId);
+    const runner = sessions.getRunner(session);
+    // Send typing indicator
+    await bot.sendTyping(msg.chatId);
+    // Set up periodic typing indicator
+    const typingInterval = setInterval(() => {
+        bot.sendTyping(msg.chatId).catch(() => { });
+    }, 4000);
+    try {
+        if (session.verbose === 0) {
+            const response = await runner.send(msg.text);
+            sessions.setHasConversation(msg.userId, true);
+            await bot.sendMessage(msg.chatId, response.text);
+        }
+        else {
+            // Streaming mode: show progress
+            let buffer = "";
+            let lastSent = Date.now();
+            const response = await runner.sendStreaming(msg.text, (chunk) => {
+                buffer += chunk;
+                const now = Date.now();
+                if (now - lastSent > 2000 && buffer.length > 0) {
+                    lastSent = now;
+                }
+            });
+            let reply = response.text;
+            if (session.verbose >= 1 && response.toolUse && response.toolUse.length > 0) {
+                const tools = response.toolUse.map((t) => `• ${t}`).join("\n");
+                reply = `${tools}\n\n${reply}`;
+            }
+            sessions.setHasConversation(msg.userId, true);
+            await bot.sendMessage(msg.chatId, reply);
+        }
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        await bot.sendMessage(msg.chatId, `Error: ${errorMsg}`);
+    }
+    finally {
+        clearInterval(typingInterval);
+    }
+});
+// --- Finalize: register catch-all handlers AFTER commands ---
+bot.finalize();
+// --- Start ---
+sessions.startCleanup();
+bot.start().then(() => {
+    console.log("[owlcode] Bot is running");
+});
+// Graceful shutdown
+process.on("SIGINT", async () => {
+    console.log("[owlcode] Shutting down...");
+    sessions.stopCleanup();
+    await bot.stop();
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    sessions.stopCleanup();
+    await bot.stop();
+    process.exit(0);
+});

package/dist/session/manager.d.ts

@@ -0,0 +1,38 @@
+import { ClaudeRunner } from "../claude/runner.js";
+export interface Session {
+    userId: number;
+    chatId: number;
+    cwd: string;
+    runner: ClaudeRunner | null;
+    lastActive: number;
+    verbose: 0 | 1 | 2;
+    hasConversation: boolean;
+}
+export declare class SessionManager {
+    private sessions;
+    private cliPath;
+    private defaultCwd;
+    private timeoutMin;
+    private cleanupInterval;
+    private statePath;
+    constructor(cliPath: string, defaultCwd: string, timeoutMin: number);
+    private loadState;
+    private saveState;
+    getOrCreate(userId: number, chatId: number): Session;
+    get(userId: number): Session | undefined;
+    setCwd(userId: number, cwd: string): void;
+    getRunner(session: Session): ClaudeRunner;
+    /** Mark that a conversation exists for this session */
+    setHasConversation(userId: number, value: boolean): void;
+    setVerbose(userId: number, level: 0 | 1 | 2): void;
+    stopSession(userId: number): void;
+    /** Start periodic cleanup — only cleans up runner objects, preserves session continuity */
+    startCleanup(): void;
+    stopCleanup(): void;
+    /** Get all active sessions info */
+    listSessions(): Array<{
+        userId: number;
+        cwd: string;
+        active: boolean;
+    }>;
+}

package/dist/session/manager.js

@@ -0,0 +1,156 @@
+/**
+ * Session manager — one session per user, tracks current project directory.
+ * Persists session state (cwd, verbose) to disk for restart recovery.
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { ClaudeRunner } from "../claude/runner.js";
+export class SessionManager {
+    sessions = new Map();
+    cliPath;
+    defaultCwd;
+    timeoutMin;
+    cleanupInterval = null;
+    statePath;
+    constructor(cliPath, defaultCwd, timeoutMin) {
+        this.cliPath = cliPath;
+        this.defaultCwd = defaultCwd;
+        this.timeoutMin = timeoutMin;
+        this.statePath = resolve(process.cwd(), ".owlcode-sessions.json");
+        this.loadState();
+    }
+    loadState() {
+        try {
+            if (existsSync(this.statePath)) {
+                const data = JSON.parse(readFileSync(this.statePath, "utf-8"));
+                for (const ps of data) {
+                    if (existsSync(ps.cwd)) {
+                        this.sessions.set(ps.userId, {
+                            userId: ps.userId,
+                            chatId: ps.chatId,
+                            cwd: ps.cwd,
+                            runner: null,
+                            lastActive: Date.now(),
+                            verbose: ps.verbose ?? 1,
+                            hasConversation: true,
+                        });
+                    }
+                }
+                console.log(`[session] Restored ${this.sessions.size} session(s)`);
+            }
+        }
+        catch {
+            // Ignore corrupt state file
+        }
+    }
+    saveState() {
+        const data = Array.from(this.sessions.values()).map((s) => ({
+            userId: s.userId,
+            chatId: s.chatId,
+            cwd: s.cwd,
+            verbose: s.verbose,
+        }));
+        try {
+            writeFileSync(this.statePath, JSON.stringify(data, null, 2));
+        }
+        catch {
+            // Ignore write errors
+        }
+    }
+    getOrCreate(userId, chatId) {
+        let session = this.sessions.get(userId);
+        if (!session) {
+            session = {
+                userId,
+                chatId,
+                cwd: this.defaultCwd,
+                runner: null,
+                lastActive: Date.now(),
+                verbose: 1,
+                hasConversation: false,
+            };
+            this.sessions.set(userId, session);
+            this.saveState();
+        }
+        session.lastActive = Date.now();
+        return session;
+    }
+    get(userId) {
+        return this.sessions.get(userId);
+    }
+    setCwd(userId, cwd) {
+        const session = this.sessions.get(userId);
+        if (session) {
+            if (session.cwd !== cwd) {
+                if (session.runner) {
+                    session.runner.kill();
+                    session.runner = null;
+                }
+                session.hasConversation = false;
+            }
+            session.cwd = cwd;
+            this.saveState();
+        }
+    }
+    getRunner(session) {
+        if (!session.runner) {
+            session.runner = new ClaudeRunner({
+                cliPath: this.cliPath,
+                cwd: session.cwd,
+            }, session.hasConversation);
+        }
+        return session.runner;
+    }
+    /** Mark that a conversation exists for this session */
+    setHasConversation(userId, value) {
+        const session = this.sessions.get(userId);
+        if (session) {
+            session.hasConversation = value;
+        }
+    }
+    setVerbose(userId, level) {
+        const session = this.sessions.get(userId);
+        if (session) {
+            session.verbose = level;
+            this.saveState();
+        }
+    }
+    stopSession(userId) {
+        const session = this.sessions.get(userId);
+        if (session) {
+            if (session.runner) {
+                session.runner.kill();
+                session.runner = null;
+            }
+            session.hasConversation = false;
+        }
+    }
+    /** Start periodic cleanup — only cleans up runner objects, preserves session continuity */
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            const timeoutMs = this.timeoutMin * 60 * 1000;
+            for (const [userId, session] of this.sessions) {
+                if (now - session.lastActive > timeoutMs && session.runner) {
+                    console.log(`[session] Releasing idle runner for user ${userId}`);
+                    // Only null out the runner object, don't kill (preserves hasSession for --continue)
+                    session.runner = null;
+                }
+            }
+        }, 60_000);
+    }
+    stopCleanup() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /** Get all active sessions info */
+    listSessions() {
+        return Array.from(this.sessions.values()).map((s) => ({
+            userId: s.userId,
+            cwd: s.cwd,
+            active: s.runner?.isRunning ?? false,
+        }));
+    }
+}

package/dist/telegram/bot.d.ts

@@ -0,0 +1,47 @@
+import type { Config } from "../config.js";
+export interface IncomingMessage {
+    chatId: number;
+    userId: number;
+    text: string;
+    messageId: number;
+}
+export interface CallbackQuery {
+    chatId: number;
+    userId: number;
+    data: string;
+    messageId: number;
+}
+export type MessageHandler = (msg: IncomingMessage) => Promise<void>;
+export type CallbackHandler = (query: CallbackQuery) => Promise<string | void>;
+export declare class TelegramBot {
+    private bot;
+    private config;
+    private handler;
+    private callbackHandlers;
+    constructor(config: Config);
+    onMessage(handler: MessageHandler): void;
+    /** Register a command handler (abstracted from grammY) */
+    onCommand(command: string, handler: (msg: IncomingMessage) => Promise<string | void>): void;
+    /** Register a callback query handler by prefix */
+    onCallback(prefix: string, handler: CallbackHandler): void;
+    /**
+     * Finalize bot setup — registers catch-all handlers.
+     * Must be called AFTER all onCommand/onCallback registrations.
+     */
+    finalize(): void;
+    sendMessage(chatId: number, text: string): Promise<void>;
+    /** Send a message with inline keyboard buttons */
+    sendWithButtons(chatId: number, text: string, buttons: Array<{
+        text: string;
+        data: string;
+    }>, columns?: number): Promise<void>;
+    /** Edit an existing message with new buttons */
+    editWithButtons(chatId: number, messageId: number, text: string, buttons: Array<{
+        text: string;
+        data: string;
+    }>, columns?: number): Promise<void>;
+    sendTyping(chatId: number): Promise<void>;
+    private splitMessage;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/telegram/bot.js

@@ -0,0 +1,184 @@
+/**
+ * Telegram layer — thin wrapper around grammY.
+ * All grammY-specific code stays in this directory.
+ * The rest of the app communicates through MessageHandler interface.
+ */
+import { Bot, InlineKeyboard } from "grammy";
+export class TelegramBot {
+    bot;
+    config;
+    handler = null;
+    callbackHandlers = new Map();
+    constructor(config) {
+        this.config = config;
+        this.bot = new Bot(config.telegram.botToken);
+        // Auth middleware — must be first
+        this.bot.use(async (ctx, next) => {
+            const userId = ctx.from?.id;
+            if (!userId || !this.config.telegram.allowedUsers.includes(userId)) {
+                await ctx.reply("Unauthorized.");
+                return;
+            }
+            await next();
+        });
+        // Built-in commands
+        this.bot.command("start", (ctx) => ctx.reply("owlcode ready. Send a message to start coding."));
+        this.bot.command("help", (ctx) => ctx.reply([
+            "/projects — List registered projects",
+            "/ls — Browse directories (with buttons)",
+            "/status — Current session status",
+            "/session_reset — Reset Claude Code session",
+            "/verbose <0|1|2> — Output detail level",
+            "",
+            "Any other message is sent to Claude Code.",
+        ].join("\n")));
+    }
+    onMessage(handler) {
+        this.handler = handler;
+    }
+    /** Register a command handler (abstracted from grammY) */
+    onCommand(command, handler) {
+        this.bot.command(command, async (ctx) => {
+            try {
+                const result = await handler({
+                    chatId: ctx.chat.id,
+                    userId: ctx.from.id,
+                    text: ctx.message?.text ?? "",
+                    messageId: ctx.message?.message_id ?? 0,
+                });
+                if (result) {
+                    await ctx.reply(result);
+                }
+            }
+            catch (err) {
+                console.error(`[command:${command}]`, err);
+                await ctx.reply(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+    }
+    /** Register a callback query handler by prefix */
+    onCallback(prefix, handler) {
+        this.callbackHandlers.set(prefix, handler);
+    }
+    /**
+     * Finalize bot setup — registers catch-all handlers.
+     * Must be called AFTER all onCommand/onCallback registrations.
+     */
+    finalize() {
+        // Callback query handler (inline buttons)
+        this.bot.on("callback_query:data", async (ctx) => {
+            const data = ctx.callbackQuery.data;
+            const prefix = data.split(":")[0];
+            const handler = this.callbackHandlers.get(prefix);
+            if (handler) {
+                try {
+                    const result = await handler({
+                        chatId: ctx.chat?.id ?? 0,
+                        userId: ctx.from.id,
+                        data,
+                        messageId: ctx.callbackQuery.message?.message_id ?? 0,
+                    });
+                    if (result) {
+                        await ctx.answerCallbackQuery({ text: result });
+                    }
+                    else {
+                        await ctx.answerCallbackQuery();
+                    }
+                }
+                catch (err) {
+                    console.error(`[callback:${prefix}]`, err);
+                    await ctx.answerCallbackQuery({ text: "Error occurred" });
+                }
+            }
+            else {
+                await ctx.answerCallbackQuery();
+            }
+        });
+        // Catch-all: forward non-command text messages to handler
+        this.bot.on("message:text", async (ctx) => {
+            if (!this.handler)
+                return;
+            const text = ctx.message.text;
+            if (text.startsWith("/"))
+                return;
+            await this.handler({
+                chatId: ctx.chat.id,
+                userId: ctx.from.id,
+                text,
+                messageId: ctx.message.message_id,
+            });
+        });
+    }
+    async sendMessage(chatId, text) {
+        const chunks = this.splitMessage(text);
+        for (const chunk of chunks) {
+            await this.bot.api.sendMessage(chatId, chunk, {
+                parse_mode: "Markdown",
+            });
+        }
+    }
+    /** Send a message with inline keyboard buttons */
+    async sendWithButtons(chatId, text, buttons, columns = 2) {
+        const keyboard = new InlineKeyboard();
+        buttons.forEach((btn, i) => {
+            keyboard.text(btn.text, btn.data);
+            if ((i + 1) % columns === 0)
+                keyboard.row();
+        });
+        await this.bot.api.sendMessage(chatId, text, {
+            reply_markup: keyboard,
+        });
+    }
+    /** Edit an existing message with new buttons */
+    async editWithButtons(chatId, messageId, text, buttons, columns = 2) {
+        const keyboard = new InlineKeyboard();
+        buttons.forEach((btn, i) => {
+            keyboard.text(btn.text, btn.data);
+            if ((i + 1) % columns === 0)
+                keyboard.row();
+        });
+        await this.bot.api.editMessageText(chatId, messageId, text, {
+            reply_markup: keyboard,
+        });
+    }
+    async sendTyping(chatId) {
+        await this.bot.api.sendChatAction(chatId, "typing");
+    }
+    splitMessage(text, maxLen = 4096) {
+        if (text.length <= maxLen)
+            return [text];
+        const chunks = [];
+        let remaining = text;
+        while (remaining.length > 0) {
+            if (remaining.length <= maxLen) {
+                chunks.push(remaining);
+                break;
+            }
+            let splitIdx = remaining.lastIndexOf("\n", maxLen);
+            if (splitIdx === -1 || splitIdx < maxLen / 2) {
+                splitIdx = maxLen;
+            }
+            chunks.push(remaining.slice(0, splitIdx));
+            remaining = remaining.slice(splitIdx);
+        }
+        return chunks;
+    }
+    async start() {
+        console.log("[telegram] Starting bot...");
+        // Register command menu (shows when user types /)
+        await this.bot.api.setMyCommands([
+            { command: "ls", description: "Browse directories" },
+            { command: "status", description: "Session status" },
+            { command: "session_reset", description: "Reset Claude Code session" },
+            { command: "verbose", description: "Output detail level (0/1/2)" },
+            { command: "help", description: "Show available commands" },
+        ]);
+        this.bot.catch((err) => {
+            console.error("[bot] Error:", err.message ?? err);
+        });
+        this.bot.start();
+    }
+    async stop() {
+        await this.bot.stop();
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "owlcode",
+  "version": "0.1.0",
+  "description": "Telegram bot for remote Claude Code access — your owl delivers code commands and brings back results",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "owlcode": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "telegram",
+    "claude-code",
+    "ai",
+    "coding-agent",
+    "cli"
+  ],
+  "author": "John Cho <cr8rcho@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cr8rcho/owlcode.git"
+  },
+  "homepage": "https://github.com/cr8rcho/owlcode",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "grammy": "^1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}