kimaki 0.4.28 → 0.4.30

package/dist/cli.js

@@ -4,7 +4,7 @@
 // project channel creation, and launching the bot with opencode integration.
 import { cac } from 'cac';
 import { intro, outro, text, password, note, cancel, isCancel, confirm, log, multiselect, spinner, } from '@clack/prompts';
-import { deduplicateByKey, generateBotInstallUrl } from './utils.js';
+import { deduplicateByKey, generateBotInstallUrl, abbreviatePath } from './utils.js';
 import { getChannelsWithDescriptions, createDiscordClient, getDatabase, startDiscordBot, initializeOpencodeForDirectory, ensureKimakiCategory, createProjectChannels, } from './discord-bot.js';
 import { Events, ChannelType, REST, Routes, SlashCommandBuilder, AttachmentBuilder, } from 'discord.js';
 import path from 'node:path';
@@ -12,10 +12,11 @@ import fs from 'node:fs';
 import { createLogger } from './logger.js';
 import { spawn, spawnSync, execSync } from 'node:child_process';
 import http from 'node:http';
+import { setDataDir, getDataDir, getLockPort } from './config.js';
+import { extractTagsArrays } from './xml.js';
 const cliLogger = createLogger('CLI');
 const cli = cac('kimaki');
 process.title = 'kimaki';
-const LOCK_PORT = 29988;
 async function killProcessOnPort(port) {
     const isWindows = process.platform === 'win32';
     const myPid = process.pid;
@@ -58,13 +59,14 @@ async function killProcessOnPort(port) {
     return false;
 }
 async function checkSingleInstance() {
+    const lockPort = getLockPort();
     try {
-        const response = await fetch(`http://127.0.0.1:${LOCK_PORT}`, {
+        const response = await fetch(`http://127.0.0.1:${lockPort}`, {
             signal: AbortSignal.timeout(1000),
         });
         if (response.ok) {
-            cliLogger.log('Another kimaki instance detected');
-            await killProcessOnPort(LOCK_PORT);
+            cliLogger.log(`Another kimaki instance detected for data dir: ${getDataDir()}`);
+            await killProcessOnPort(lockPort);
             // Wait a moment for port to be released
             await new Promise((resolve) => { setTimeout(resolve, 500); });
         }
@@ -74,22 +76,24 @@ async function checkSingleInstance() {
     }
 }
 async function startLockServer() {
+    const lockPort = getLockPort();
     return new Promise((resolve, reject) => {
         const server = http.createServer((req, res) => {
             res.writeHead(200);
             res.end('kimaki');
         });
-        server.listen(LOCK_PORT, '127.0.0.1');
+        server.listen(lockPort, '127.0.0.1');
         server.once('listening', () => {
+            cliLogger.debug(`Lock server started on port ${lockPort}`);
             resolve();
         });
         server.on('error', async (err) => {
             if (err.code === 'EADDRINUSE') {
                 cliLogger.log('Port still in use, retrying...');
-                await killProcessOnPort(LOCK_PORT);
+                await killProcessOnPort(lockPort);
                 await new Promise((r) => { setTimeout(r, 500); });
                 // Retry once
-                server.listen(LOCK_PORT, '127.0.0.1');
+                server.listen(lockPort, '127.0.0.1');
             }
             else {
                 reject(err);
@@ -461,7 +465,15 @@ async function run({ restart, addChannels }) {
         .filter((ch) => ch.kimakiDirectory && ch.kimakiApp === appId)
         .map((ch) => ch.kimakiDirectory)
         .filter(Boolean));
-    const availableProjects = deduplicateByKey(projects.filter((project) => !existingDirs.includes(project.worktree)), (x) => x.worktree);
+    const availableProjects = deduplicateByKey(projects.filter((project) => {
+        if (existingDirs.includes(project.worktree)) {
+            return false;
+        }
+        if (path.basename(project.worktree).startsWith('opencode-test-')) {
+            return false;
+        }
+        return true;
+    }), (x) => x.worktree);
     if (availableProjects.length === 0) {
         note('All OpenCode projects already have Discord channels', 'No New Projects');
     }
@@ -471,7 +483,7 @@ async function run({ restart, addChannels }) {
             message: 'Select projects to create Discord channels for:',
             options: availableProjects.map((project) => ({
                 value: project.id,
-                label: `${path.basename(project.worktree)} (${project.worktree})`,
+                label: `${path.basename(project.worktree)} (${abbreviatePath(project.worktree)})`,
             })),
             required: false,
         });
@@ -585,13 +597,20 @@ cli
     .command('', 'Set up and run the Kimaki Discord bot')
     .option('--restart', 'Prompt for new credentials even if saved')
     .option('--add-channels', 'Select OpenCode projects to create Discord channels before starting')
+    .option('--data-dir <path>', 'Data directory for config and database (default: ~/.kimaki)')
     .action(async (options) => {
     try {
+        // Set data directory early, before any database access
+        if (options.dataDir) {
+            setDataDir(options.dataDir);
+            cliLogger.log(`Using data directory: ${getDataDir()}`);
+        }
         await checkSingleInstance();
         await startLockServer();
         await run({
             restart: options.restart,
             addChannels: options.addChannels,
+            dataDir: options.dataDir,
         });
     }
     catch (error) {
@@ -665,5 +684,149 @@ cli
         process.exit(EXIT_NO_RESTART);
     }
 });
+// Magic prefix used to identify bot-initiated sessions.
+// The running bot will recognize this prefix and start a session.
+const BOT_SESSION_PREFIX = '🤖 **Bot-initiated session**';
+cli
+    .command('start-session', 'Start a new session in a Discord channel (creates thread, bot handles the rest)')
+    .option('-c, --channel <channelId>', 'Discord channel ID')
+    .option('-p, --prompt <prompt>', 'Initial prompt for the session')
+    .option('-n, --name [name]', 'Thread name (optional, defaults to prompt preview)')
+    .option('-a, --app-id [appId]', 'Bot application ID (required if no local database)')
+    .action(async (options) => {
+    try {
+        const { channel: channelId, prompt, name, appId: optionAppId } = options;
+        if (!channelId) {
+            cliLogger.error('Channel ID is required. Use --channel <channelId>');
+            process.exit(EXIT_NO_RESTART);
+        }
+        if (!prompt) {
+            cliLogger.error('Prompt is required. Use --prompt <prompt>');
+            process.exit(EXIT_NO_RESTART);
+        }
+        // Get bot token from env var or database
+        const envToken = process.env.KIMAKI_BOT_TOKEN;
+        let botToken;
+        let appId = optionAppId;
+        if (envToken) {
+            botToken = envToken;
+            if (!appId) {
+                // Try to get app_id from database if available (optional in CI)
+                try {
+                    const db = getDatabase();
+                    const botRow = db
+                        .prepare('SELECT app_id FROM bot_tokens ORDER BY created_at DESC LIMIT 1')
+                        .get();
+                    appId = botRow?.app_id;
+                }
+                catch {
+                    // Database might not exist in CI, that's ok
+                }
+            }
+        }
+        else {
+            // Fall back to database
+            try {
+                const db = getDatabase();
+                const botRow = db
+                    .prepare('SELECT app_id, token FROM bot_tokens ORDER BY created_at DESC LIMIT 1')
+                    .get();
+                if (botRow) {
+                    botToken = botRow.token;
+                    appId = appId || botRow.app_id;
+                }
+            }
+            catch (e) {
+                // Database error - will fall through to the check below
+                cliLogger.error('Database error:', e instanceof Error ? e.message : String(e));
+            }
+        }
+        if (!botToken) {
+            cliLogger.error('No bot token found. Set KIMAKI_BOT_TOKEN env var or run `kimaki` first to set up.');
+            process.exit(EXIT_NO_RESTART);
+        }
+        const s = spinner();
+        s.start('Fetching channel info...');
+        // Get channel info to extract directory from topic
+        const channelResponse = await fetch(`https://discord.com/api/v10/channels/${channelId}`, {
+            headers: {
+                'Authorization': `Bot ${botToken}`,
+            },
+        });
+        if (!channelResponse.ok) {
+            const error = await channelResponse.text();
+            s.stop('Failed to fetch channel');
+            throw new Error(`Discord API error: ${channelResponse.status} - ${error}`);
+        }
+        const channelData = await channelResponse.json();
+        if (!channelData.topic) {
+            s.stop('Channel has no topic');
+            throw new Error(`Channel #${channelData.name} has no topic. It must have a <kimaki.directory> tag.`);
+        }
+        const extracted = extractTagsArrays({
+            xml: channelData.topic,
+            tags: ['kimaki.directory', 'kimaki.app'],
+        });
+        const projectDirectory = extracted['kimaki.directory']?.[0]?.trim();
+        const channelAppId = extracted['kimaki.app']?.[0]?.trim();
+        if (!projectDirectory) {
+            s.stop('No kimaki.directory tag found');
+            throw new Error(`Channel #${channelData.name} has no <kimaki.directory> tag in topic.`);
+        }
+        // Verify app ID matches if both are present
+        if (channelAppId && appId && channelAppId !== appId) {
+            s.stop('Channel belongs to different bot');
+            throw new Error(`Channel belongs to a different bot (expected: ${appId}, got: ${channelAppId})`);
+        }
+        s.message('Creating starter message...');
+        // Create starter message with magic prefix
+        // The full prompt goes in the message so the bot can read it
+        const starterMessageResponse = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bot ${botToken}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                content: `${BOT_SESSION_PREFIX}\n${prompt}`,
+            }),
+        });
+        if (!starterMessageResponse.ok) {
+            const error = await starterMessageResponse.text();
+            s.stop('Failed to create message');
+            throw new Error(`Discord API error: ${starterMessageResponse.status} - ${error}`);
+        }
+        const starterMessage = await starterMessageResponse.json();
+        s.message('Creating thread...');
+        // Create thread from the message
+        const threadName = name || (prompt.length > 80 ? prompt.slice(0, 77) + '...' : prompt);
+        const threadResponse = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages/${starterMessage.id}/threads`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bot ${botToken}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                name: threadName.slice(0, 100),
+                auto_archive_duration: 1440, // 1 day
+            }),
+        });
+        if (!threadResponse.ok) {
+            const error = await threadResponse.text();
+            s.stop('Failed to create thread');
+            throw new Error(`Discord API error: ${threadResponse.status} - ${error}`);
+        }
+        const threadData = await threadResponse.json();
+        s.stop('Thread created!');
+        const threadUrl = `https://discord.com/channels/${channelData.guild_id}/${threadData.id}`;
+        note(`Thread: ${threadData.name}\nDirectory: ${projectDirectory}\n\nThe running bot will pick this up and start the session.\n\nURL: ${threadUrl}`, '✅ Thread Created');
+        console.log(threadUrl);
+        process.exit(0);
+    }
+    catch (error) {
+        cliLogger.error('Error:', error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_NO_RESTART);
+    }
+});
 cli.help();
 cli.parse();

package/dist/commands/add-project.js

@@ -5,6 +5,7 @@ import { getDatabase } from '../database.js';
 import { initializeOpencodeForDirectory } from '../opencode.js';
 import { createProjectChannels } from '../channel-management.js';
 import { createLogger } from '../logger.js';
+import { abbreviatePath } from '../utils.js';
 const logger = createLogger('ADD-PROJECT');
 export async function handleAddProjectCommand({ command, appId, }) {
     await command.deferReply({ ephemeral: false });
@@ -69,7 +70,15 @@ export async function handleAddProjectAutocomplete({ interaction, appId, }) {
             .prepare('SELECT DISTINCT directory FROM channel_directories WHERE channel_type = ?')
             .all('text');
         const existingDirSet = new Set(existingDirs.map((row) => row.directory));
-        const availableProjects = projectsResponse.data.filter((project) => !existingDirSet.has(project.worktree));
+        const availableProjects = projectsResponse.data.filter((project) => {
+            if (existingDirSet.has(project.worktree)) {
+                return false;
+            }
+            if (path.basename(project.worktree).startsWith('opencode-test-')) {
+                return false;
+            }
+            return true;
+        });
         const projects = availableProjects
             .filter((project) => {
             const baseName = path.basename(project.worktree);
@@ -83,7 +92,7 @@ export async function handleAddProjectAutocomplete({ interaction, appId, }) {
         })
             .slice(0, 25)
             .map((project) => {
-            const name = `${path.basename(project.worktree)} (${project.worktree})`;
+            const name = `${path.basename(project.worktree)} (${abbreviatePath(project.worktree)})`;
             return {
                 name: name.length > 100 ? name.slice(0, 99) + '…' : name,
                 value: project.id,

package/dist/commands/create-new-project.js

@@ -1,8 +1,8 @@
 // /create-new-project command - Create a new project folder, initialize git, and start a session.
 import { ChannelType } from 'discord.js';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { getProjectsDir } from '../config.js';
 import { createProjectChannels } from '../channel-management.js';
 import { handleOpencodeSession } from '../session-handler.js';
 import { SILENT_MESSAGE_FLAGS } from '../discord-utils.js';
@@ -31,12 +31,12 @@ export async function handleCreateNewProjectCommand({ command, appId, }) {
         await command.editReply('Invalid project name');
         return;
     }
-    const kimakiDir = path.join(os.homedir(), 'kimaki');
-    const projectDirectory = path.join(kimakiDir, sanitizedName);
+    const projectsDir = getProjectsDir();
+    const projectDirectory = path.join(projectsDir, sanitizedName);
     try {
-        if (!fs.existsSync(kimakiDir)) {
-            fs.mkdirSync(kimakiDir, { recursive: true });
-            logger.log(`Created kimaki directory: ${kimakiDir}`);
+        if (!fs.existsSync(projectsDir)) {
+            fs.mkdirSync(projectsDir, { recursive: true });
+            logger.log(`Created projects directory: ${projectsDir}`);
         }
         if (fs.existsSync(projectDirectory)) {
             await command.editReply(`Project directory already exists: ${projectDirectory}`);

package/dist/config.js

@@ -0,0 +1,59 @@
+// Runtime configuration for Kimaki bot.
+// Stores data directory path and provides accessors for other modules.
+// Must be initialized before database or other path-dependent modules are used.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const DEFAULT_DATA_DIR = path.join(os.homedir(), '.kimaki');
+let dataDir = null;
+/**
+ * Get the data directory path.
+ * Falls back to ~/.kimaki if not explicitly set.
+ */
+export function getDataDir() {
+    if (!dataDir) {
+        dataDir = DEFAULT_DATA_DIR;
+    }
+    return dataDir;
+}
+/**
+ * Set the data directory path.
+ * Creates the directory if it doesn't exist.
+ * Must be called before any database or path-dependent operations.
+ */
+export function setDataDir(dir) {
+    const resolvedDir = path.resolve(dir);
+    if (!fs.existsSync(resolvedDir)) {
+        fs.mkdirSync(resolvedDir, { recursive: true });
+    }
+    dataDir = resolvedDir;
+}
+/**
+ * Get the projects directory path (for /create-new-project command).
+ * Returns <dataDir>/projects
+ */
+export function getProjectsDir() {
+    return path.join(getDataDir(), 'projects');
+}
+const DEFAULT_LOCK_PORT = 29988;
+/**
+ * Derive a lock port from the data directory path.
+ * Returns 29988 for the default ~/.kimaki directory (backwards compatible).
+ * For custom data dirs, uses a hash to generate a port in the range 30000-39999.
+ */
+export function getLockPort() {
+    const dir = getDataDir();
+    // Use original port for default data dir (backwards compatible)
+    if (dir === DEFAULT_DATA_DIR) {
+        return DEFAULT_LOCK_PORT;
+    }
+    // Hash-based port for custom data dirs
+    let hash = 0;
+    for (let i = 0; i < dir.length; i++) {
+        const char = dir.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    // Map to port range 30000-39999
+    return 30000 + (Math.abs(hash) % 10000);
+}

package/dist/database.js

@@ -1,23 +1,23 @@
 // SQLite database manager for persistent bot state.
 // Stores thread-session mappings, bot tokens, channel directories,
-// API keys, and model preferences in ~/.kimaki/discord-sessions.db.
+// API keys, and model preferences in <dataDir>/discord-sessions.db.
 import Database from 'better-sqlite3';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { createLogger } from './logger.js';
+import { getDataDir } from './config.js';
 const dbLogger = createLogger('DB');
 let db = null;
 export function getDatabase() {
     if (!db) {
-        const kimakiDir = path.join(os.homedir(), '.kimaki');
+        const dataDir = getDataDir();
         try {
-            fs.mkdirSync(kimakiDir, { recursive: true });
+            fs.mkdirSync(dataDir, { recursive: true });
         }
         catch (error) {
-            dbLogger.error('Failed to create ~/.kimaki directory:', error);
+            dbLogger.error(`Failed to create data directory ${dataDir}:`, error);
         }
-        const dbPath = path.join(kimakiDir, 'discord-sessions.db');
+        const dbPath = path.join(dataDir, 'discord-sessions.db');
         dbLogger.log(`Opening database at: ${dbPath}`);
         db = new Database(dbPath);
         db.exec(`

package/dist/discord-bot.js

@@ -296,6 +296,85 @@ export async function startDiscordBot({ token, appId, discordClient, }) {
             }
         }
     });
+    // Magic prefix used by `kimaki start-session` CLI command to initiate sessions
+    const BOT_SESSION_PREFIX = '🤖 **Bot-initiated session**';
+    // Handle bot-initiated threads created by `kimaki start-session`
+    discordClient.on(Events.ThreadCreate, async (thread, newlyCreated) => {
+        try {
+            if (!newlyCreated) {
+                return;
+            }
+            // Only handle threads in text channels
+            const parent = thread.parent;
+            if (!parent || parent.type !== ChannelType.GuildText) {
+                return;
+            }
+            // Get the starter message to check for magic prefix
+            const starterMessage = await thread.fetchStarterMessage().catch(() => null);
+            if (!starterMessage) {
+                discordLogger.log(`[THREAD_CREATE] Could not fetch starter message for thread ${thread.id}`);
+                return;
+            }
+            // Only handle messages from this bot with the magic prefix
+            if (starterMessage.author.id !== discordClient.user?.id) {
+                return;
+            }
+            if (!starterMessage.content.startsWith(BOT_SESSION_PREFIX)) {
+                return;
+            }
+            discordLogger.log(`[BOT_SESSION] Detected bot-initiated thread: ${thread.name}`);
+            // Extract the prompt (everything after the prefix)
+            const prompt = starterMessage.content.slice(BOT_SESSION_PREFIX.length).trim();
+            if (!prompt) {
+                discordLogger.log(`[BOT_SESSION] No prompt found in starter message`);
+                return;
+            }
+            // Extract directory from parent channel topic
+            if (!parent.topic) {
+                discordLogger.log(`[BOT_SESSION] Parent channel has no topic`);
+                return;
+            }
+            const extracted = extractTagsArrays({
+                xml: parent.topic,
+                tags: ['kimaki.directory', 'kimaki.app'],
+            });
+            const projectDirectory = extracted['kimaki.directory']?.[0]?.trim();
+            const channelAppId = extracted['kimaki.app']?.[0]?.trim();
+            if (!projectDirectory) {
+                discordLogger.log(`[BOT_SESSION] No kimaki.directory in parent channel topic`);
+                return;
+            }
+            if (channelAppId && channelAppId !== currentAppId) {
+                discordLogger.log(`[BOT_SESSION] Channel belongs to different bot app`);
+                return;
+            }
+            if (!fs.existsSync(projectDirectory)) {
+                discordLogger.error(`[BOT_SESSION] Directory does not exist: ${projectDirectory}`);
+                await thread.send({
+                    content: `✗ Directory does not exist: ${JSON.stringify(projectDirectory)}`,
+                    flags: SILENT_MESSAGE_FLAGS,
+                });
+                return;
+            }
+            discordLogger.log(`[BOT_SESSION] Starting session for thread ${thread.id} with prompt: "${prompt.slice(0, 50)}..."`);
+            await handleOpencodeSession({
+                prompt,
+                thread,
+                projectDirectory,
+                channelId: parent.id,
+            });
+        }
+        catch (error) {
+            voiceLogger.error('[BOT_SESSION] Error handling bot-initiated thread:', error);
+            try {
+                const errMsg = error instanceof Error ? error.message : String(error);
+                await thread.send({ content: `Error: ${errMsg}`, flags: SILENT_MESSAGE_FLAGS });
+            }
+            catch {
+                // Ignore send errors
+            }
+        }
+    });
     await discordClient.login(token);
     const handleShutdown = async (signal, { skipExit = false } = {}) => {
         discordLogger.log(`Received ${signal}, cleaning up...`);

package/dist/session-handler.js

@@ -525,7 +525,7 @@ export async function handleOpencodeSession({ prompt, thread, projectDirectory,
                 path: { id: session.id },
                 body: {
                     parts,
-                    system: getOpencodeSystemMessage({ sessionId: session.id }),
+                    system: getOpencodeSystemMessage({ sessionId: session.id, channelId }),
                     model: modelParam,
                     agent: agentPreference,
                 },

package/dist/system-message.js

@@ -1,13 +1,13 @@
 // OpenCode system prompt generator.
 // Creates the system message injected into every OpenCode session,
 // including Discord-specific formatting rules, diff commands, and permissions info.
-export function getOpencodeSystemMessage({ sessionId }) {
+export function getOpencodeSystemMessage({ sessionId, channelId }) {
     return `
 The user is reading your messages from inside Discord, via kimaki.xyz
 
 The user cannot see bash tool outputs. If there is important information in bash output, include it in your text response.
 
-Your current OpenCode session ID is: ${sessionId}
+Your current OpenCode session ID is: ${sessionId}${channelId ? `\nYour current Discord channel ID is: ${channelId}` : ''}
 
 ## permissions
 
@@ -22,7 +22,15 @@ Only users with these Discord permissions can send messages to the bot:
 To upload files to the Discord thread (images, screenshots, long files that would clutter the chat), run:
 
 npx -y kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
+${channelId ? `
+## starting new sessions from CLI
 
+To start a new thread/session in this channel programmatically, run:
+
+npx -y kimaki start-session --channel ${channelId} --prompt "your prompt here"
+
+This is useful for automation (cron jobs, GitHub webhooks, n8n, etc.)
+` : ''}
 ## showing diffs
 
 IMPORTANT: After editing any files, you MUST execute the critique command using the Bash tool to get a diff URL, then share that URL with the user.

package/dist/utils.js

@@ -1,6 +1,7 @@
 // General utility functions for the bot.
 // Includes Discord OAuth URL generation, array deduplication,
 // abort error detection, and date/time formatting helpers.
+import os from 'node:os';
 import { PermissionsBitField } from 'discord.js';
 export function generateBotInstallUrl({ clientId, permissions = [
     PermissionsBitField.Flags.ViewChannel,
@@ -83,3 +84,10 @@ const dtf = new Intl.DateTimeFormat('en-US', {
 export function formatDateTime(date) {
     return dtf.format(date);
 }
+export function abbreviatePath(fullPath) {
+    const home = os.homedir();
+    if (fullPath.startsWith(home)) {
+        return '~' + fullPath.slice(home.length);
+    }
+    return fullPath;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "kimaki",
   "module": "index.ts",
   "type": "module",
-  "version": "0.4.28",
+  "version": "0.4.30",
   "scripts": {
     "dev": "tsx --env-file .env src/cli.ts",
     "prepublishOnly": "pnpm tsc",

package/src/cli.ts

@@ -16,7 +16,7 @@ import {
   multiselect,
   spinner,
 } from '@clack/prompts'
-import { deduplicateByKey, generateBotInstallUrl } from './utils.js'
+import { deduplicateByKey, generateBotInstallUrl, abbreviatePath } from './utils.js'
 import {
   getChannelsWithDescriptions,
   createDiscordClient,
@@ -45,14 +45,14 @@ import fs from 'node:fs'
 import { createLogger } from './logger.js'
 import { spawn, spawnSync, execSync, type ExecSyncOptions } from 'node:child_process'
 import http from 'node:http'
+import { setDataDir, getDataDir, getLockPort } from './config.js'
+import { extractTagsArrays } from './xml.js'
 
 const cliLogger = createLogger('CLI')
 const cli = cac('kimaki')
 
 process.title = 'kimaki'
 
-const LOCK_PORT = 29988
-
 async function killProcessOnPort(port: number): Promise<boolean> {
   const isWindows = process.platform === 'win32'
   const myPid = process.pid
@@ -95,13 +95,14 @@ async function killProcessOnPort(port: number): Promise<boolean> {
 }
 
 async function checkSingleInstance(): Promise<void> {
+  const lockPort = getLockPort()
   try {
-    const response = await fetch(`http://127.0.0.1:${LOCK_PORT}`, {
+    const response = await fetch(`http://127.0.0.1:${lockPort}`, {
       signal: AbortSignal.timeout(1000),
     })
     if (response.ok) {
-      cliLogger.log('Another kimaki instance detected')
-      await killProcessOnPort(LOCK_PORT)
+      cliLogger.log(`Another kimaki instance detected for data dir: ${getDataDir()}`)
+      await killProcessOnPort(lockPort)
       // Wait a moment for port to be released
       await new Promise((resolve) => { setTimeout(resolve, 500) })
     }
@@ -111,22 +112,24 @@ async function checkSingleInstance(): Promise<void> {
 }
 
 async function startLockServer(): Promise<void> {
+  const lockPort = getLockPort()
   return new Promise((resolve, reject) => {
     const server = http.createServer((req, res) => {
       res.writeHead(200)
       res.end('kimaki')
     })
-    server.listen(LOCK_PORT, '127.0.0.1')
+    server.listen(lockPort, '127.0.0.1')
     server.once('listening', () => {
+      cliLogger.debug(`Lock server started on port ${lockPort}`)
       resolve()
     })
     server.on('error', async (err: NodeJS.ErrnoException) => {
       if (err.code === 'EADDRINUSE') {
         cliLogger.log('Port still in use, retrying...')
-        await killProcessOnPort(LOCK_PORT)
+        await killProcessOnPort(lockPort)
         await new Promise((r) => { setTimeout(r, 500) })
         // Retry once
-        server.listen(LOCK_PORT, '127.0.0.1')
+        server.listen(lockPort, '127.0.0.1')
       } else {
         reject(err)
       }
@@ -151,6 +154,7 @@ type Project = {
 type CliOptions = {
   restart?: boolean
   addChannels?: boolean
+  dataDir?: string
 }
 
 // Commands to skip when registering user commands (reserved names)
@@ -644,7 +648,15 @@ async function run({ restart, addChannels }: CliOptions) {
   )
 
   const availableProjects = deduplicateByKey(
-    projects.filter((project) => !existingDirs.includes(project.worktree)),
+    projects.filter((project) => {
+      if (existingDirs.includes(project.worktree)) {
+        return false
+      }
+      if (path.basename(project.worktree).startsWith('opencode-test-')) {
+        return false
+      }
+      return true
+    }),
     (x) => x.worktree,
   )
 
@@ -663,7 +675,7 @@ async function run({ restart, addChannels }: CliOptions) {
       message: 'Select projects to create Discord channels for:',
       options: availableProjects.map((project) => ({
         value: project.id,
-        label: `${path.basename(project.worktree)} (${project.worktree})`,
+        label: `${path.basename(project.worktree)} (${abbreviatePath(project.worktree)})`,
       })),
       required: false,
     })
@@ -823,13 +835,24 @@ cli
     '--add-channels',
     'Select OpenCode projects to create Discord channels before starting',
   )
-  .action(async (options: { restart?: boolean; addChannels?: boolean }) => {
+  .option(
+    '--data-dir <path>',
+    'Data directory for config and database (default: ~/.kimaki)',
+  )
+  .action(async (options: { restart?: boolean; addChannels?: boolean; dataDir?: string }) => {
     try {
+      // Set data directory early, before any database access
+      if (options.dataDir) {
+        setDataDir(options.dataDir)
+        cliLogger.log(`Using data directory: ${getDataDir()}`)
+      }
+      
       await checkSingleInstance()
       await startLockServer()
       await run({
         restart: options.restart,
         addChannels: options.addChannels,
+        dataDir: options.dataDir,
       })
     } catch (error) {
       cliLogger.error(
@@ -936,6 +959,196 @@ cli
   })
 
 
+// Magic prefix used to identify bot-initiated sessions.
+// The running bot will recognize this prefix and start a session.
+const BOT_SESSION_PREFIX = '🤖 **Bot-initiated session**'
+
+cli
+  .command('start-session', 'Start a new session in a Discord channel (creates thread, bot handles the rest)')
+  .option('-c, --channel <channelId>', 'Discord channel ID')
+  .option('-p, --prompt <prompt>', 'Initial prompt for the session')
+  .option('-n, --name [name]', 'Thread name (optional, defaults to prompt preview)')
+  .option('-a, --app-id [appId]', 'Bot application ID (required if no local database)')
+  .action(async (options: { channel?: string; prompt?: string; name?: string; appId?: string }) => {
+    try {
+      const { channel: channelId, prompt, name, appId: optionAppId } = options
+
+      if (!channelId) {
+        cliLogger.error('Channel ID is required. Use --channel <channelId>')
+        process.exit(EXIT_NO_RESTART)
+      }
+
+      if (!prompt) {
+        cliLogger.error('Prompt is required. Use --prompt <prompt>')
+        process.exit(EXIT_NO_RESTART)
+      }
+
+      // Get bot token from env var or database
+      const envToken = process.env.KIMAKI_BOT_TOKEN
+      let botToken: string | undefined
+      let appId: string | undefined = optionAppId
+
+      if (envToken) {
+        botToken = envToken
+        if (!appId) {
+          // Try to get app_id from database if available (optional in CI)
+          try {
+            const db = getDatabase()
+            const botRow = db
+              .prepare('SELECT app_id FROM bot_tokens ORDER BY created_at DESC LIMIT 1')
+              .get() as { app_id: string } | undefined
+            appId = botRow?.app_id
+          } catch {
+            // Database might not exist in CI, that's ok
+          }
+        }
+      } else {
+        // Fall back to database
+        try {
+          const db = getDatabase()
+          const botRow = db
+            .prepare('SELECT app_id, token FROM bot_tokens ORDER BY created_at DESC LIMIT 1')
+            .get() as { app_id: string; token: string } | undefined
+
+          if (botRow) {
+            botToken = botRow.token
+            appId = appId || botRow.app_id
+          }
+        } catch (e) {
+          // Database error - will fall through to the check below
+          cliLogger.error('Database error:', e instanceof Error ? e.message : String(e))
+        }
+      }
+
+      if (!botToken) {
+        cliLogger.error('No bot token found. Set KIMAKI_BOT_TOKEN env var or run `kimaki` first to set up.')
+        process.exit(EXIT_NO_RESTART)
+      }
+
+      const s = spinner()
+      s.start('Fetching channel info...')
+
+      // Get channel info to extract directory from topic
+      const channelResponse = await fetch(
+        `https://discord.com/api/v10/channels/${channelId}`,
+        {
+          headers: {
+            'Authorization': `Bot ${botToken}`,
+          },
+        }
+      )
+
+      if (!channelResponse.ok) {
+        const error = await channelResponse.text()
+        s.stop('Failed to fetch channel')
+        throw new Error(`Discord API error: ${channelResponse.status} - ${error}`)
+      }
+
+      const channelData = await channelResponse.json() as {
+        id: string
+        name: string
+        topic?: string
+        guild_id: string
+      }
+
+      if (!channelData.topic) {
+        s.stop('Channel has no topic')
+        throw new Error(`Channel #${channelData.name} has no topic. It must have a <kimaki.directory> tag.`)
+      }
+
+      const extracted = extractTagsArrays({
+        xml: channelData.topic,
+        tags: ['kimaki.directory', 'kimaki.app'],
+      })
+
+      const projectDirectory = extracted['kimaki.directory']?.[0]?.trim()
+      const channelAppId = extracted['kimaki.app']?.[0]?.trim()
+
+      if (!projectDirectory) {
+        s.stop('No kimaki.directory tag found')
+        throw new Error(`Channel #${channelData.name} has no <kimaki.directory> tag in topic.`)
+      }
+
+      // Verify app ID matches if both are present
+      if (channelAppId && appId && channelAppId !== appId) {
+        s.stop('Channel belongs to different bot')
+        throw new Error(`Channel belongs to a different bot (expected: ${appId}, got: ${channelAppId})`)
+      }
+
+      s.message('Creating starter message...')
+
+      // Create starter message with magic prefix
+      // The full prompt goes in the message so the bot can read it
+      const starterMessageResponse = await fetch(
+        `https://discord.com/api/v10/channels/${channelId}/messages`,
+        {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bot ${botToken}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            content: `${BOT_SESSION_PREFIX}\n${prompt}`,
+          }),
+        }
+      )
+
+      if (!starterMessageResponse.ok) {
+        const error = await starterMessageResponse.text()
+        s.stop('Failed to create message')
+        throw new Error(`Discord API error: ${starterMessageResponse.status} - ${error}`)
+      }
+
+      const starterMessage = await starterMessageResponse.json() as { id: string }
+
+      s.message('Creating thread...')
+
+      // Create thread from the message
+      const threadName = name || (prompt.length > 80 ? prompt.slice(0, 77) + '...' : prompt)
+      const threadResponse = await fetch(
+        `https://discord.com/api/v10/channels/${channelId}/messages/${starterMessage.id}/threads`,
+        {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bot ${botToken}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            name: threadName.slice(0, 100),
+            auto_archive_duration: 1440, // 1 day
+          }),
+        }
+      )
+
+      if (!threadResponse.ok) {
+        const error = await threadResponse.text()
+        s.stop('Failed to create thread')
+        throw new Error(`Discord API error: ${threadResponse.status} - ${error}`)
+      }
+
+      const threadData = await threadResponse.json() as { id: string; name: string }
+
+      s.stop('Thread created!')
+
+      const threadUrl = `https://discord.com/channels/${channelData.guild_id}/${threadData.id}`
+
+      note(
+        `Thread: ${threadData.name}\nDirectory: ${projectDirectory}\n\nThe running bot will pick this up and start the session.\n\nURL: ${threadUrl}`,
+        '✅ Thread Created',
+      )
+
+      console.log(threadUrl)
+
+      process.exit(0)
+    } catch (error) {
+      cliLogger.error(
+        'Error:',
+        error instanceof Error ? error.message : String(error),
+      )
+      process.exit(EXIT_NO_RESTART)
+    }
+  })
+
 
 cli.help()
 cli.parse()

package/src/commands/add-project.ts

@@ -7,6 +7,7 @@ import { getDatabase } from '../database.js'
 import { initializeOpencodeForDirectory } from '../opencode.js'
 import { createProjectChannels } from '../channel-management.js'
 import { createLogger } from '../logger.js'
+import { abbreviatePath } from '../utils.js'
 
 const logger = createLogger('ADD-PROJECT')
 
@@ -107,9 +108,15 @@ export async function handleAddProjectAutocomplete({
       .all('text') as { directory: string }[]
     const existingDirSet = new Set(existingDirs.map((row) => row.directory))
 
-    const availableProjects = projectsResponse.data.filter(
-      (project) => !existingDirSet.has(project.worktree),
-    )
+    const availableProjects = projectsResponse.data.filter((project) => {
+      if (existingDirSet.has(project.worktree)) {
+        return false
+      }
+      if (path.basename(project.worktree).startsWith('opencode-test-')) {
+        return false
+      }
+      return true
+    })
 
     const projects = availableProjects
       .filter((project) => {
@@ -124,7 +131,7 @@ export async function handleAddProjectAutocomplete({
       })
       .slice(0, 25)
       .map((project) => {
-        const name = `${path.basename(project.worktree)} (${project.worktree})`
+        const name = `${path.basename(project.worktree)} (${abbreviatePath(project.worktree)})`
         return {
           name: name.length > 100 ? name.slice(0, 99) + '…' : name,
           value: project.id,

package/src/commands/create-new-project.ts

@@ -2,9 +2,9 @@
 
 import { ChannelType, type TextChannel } from 'discord.js'
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import type { CommandContext } from './types.js'
+import { getProjectsDir } from '../config.js'
 import { createProjectChannels } from '../channel-management.js'
 import { handleOpencodeSession } from '../session-handler.js'
 import { SILENT_MESSAGE_FLAGS } from '../discord-utils.js'
@@ -44,13 +44,13 @@ export async function handleCreateNewProjectCommand({
     return
   }
 
-  const kimakiDir = path.join(os.homedir(), 'kimaki')
-  const projectDirectory = path.join(kimakiDir, sanitizedName)
+  const projectsDir = getProjectsDir()
+  const projectDirectory = path.join(projectsDir, sanitizedName)
 
   try {
-    if (!fs.existsSync(kimakiDir)) {
-      fs.mkdirSync(kimakiDir, { recursive: true })
-      logger.log(`Created kimaki directory: ${kimakiDir}`)
+    if (!fs.existsSync(projectsDir)) {
+      fs.mkdirSync(projectsDir, { recursive: true })
+      logger.log(`Created projects directory: ${projectsDir}`)
     }
 
     if (fs.existsSync(projectDirectory)) {

package/src/config.ts

@@ -0,0 +1,71 @@
+// Runtime configuration for Kimaki bot.
+// Stores data directory path and provides accessors for other modules.
+// Must be initialized before database or other path-dependent modules are used.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DEFAULT_DATA_DIR = path.join(os.homedir(), '.kimaki')
+
+let dataDir: string | null = null
+
+/**
+ * Get the data directory path.
+ * Falls back to ~/.kimaki if not explicitly set.
+ */
+export function getDataDir(): string {
+  if (!dataDir) {
+    dataDir = DEFAULT_DATA_DIR
+  }
+  return dataDir
+}
+
+/**
+ * Set the data directory path.
+ * Creates the directory if it doesn't exist.
+ * Must be called before any database or path-dependent operations.
+ */
+export function setDataDir(dir: string): void {
+  const resolvedDir = path.resolve(dir)
+  
+  if (!fs.existsSync(resolvedDir)) {
+    fs.mkdirSync(resolvedDir, { recursive: true })
+  }
+  
+  dataDir = resolvedDir
+}
+
+/**
+ * Get the projects directory path (for /create-new-project command).
+ * Returns <dataDir>/projects
+ */
+export function getProjectsDir(): string {
+  return path.join(getDataDir(), 'projects')
+}
+
+const DEFAULT_LOCK_PORT = 29988
+
+/**
+ * Derive a lock port from the data directory path.
+ * Returns 29988 for the default ~/.kimaki directory (backwards compatible).
+ * For custom data dirs, uses a hash to generate a port in the range 30000-39999.
+ */
+export function getLockPort(): number {
+  const dir = getDataDir()
+  
+  // Use original port for default data dir (backwards compatible)
+  if (dir === DEFAULT_DATA_DIR) {
+    return DEFAULT_LOCK_PORT
+  }
+  
+  // Hash-based port for custom data dirs
+  let hash = 0
+  for (let i = 0; i < dir.length; i++) {
+    const char = dir.charCodeAt(i)
+    hash = ((hash << 5) - hash) + char
+    hash = hash & hash // Convert to 32bit integer
+  }
+  // Map to port range 30000-39999
+  return 30000 + (Math.abs(hash) % 10000)
+}

package/src/database.ts

@@ -1,12 +1,12 @@
 // SQLite database manager for persistent bot state.
 // Stores thread-session mappings, bot tokens, channel directories,
-// API keys, and model preferences in ~/.kimaki/discord-sessions.db.
+// API keys, and model preferences in <dataDir>/discord-sessions.db.
 
 import Database from 'better-sqlite3'
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import { createLogger } from './logger.js'
+import { getDataDir } from './config.js'
 
 const dbLogger = createLogger('DB')
 
@@ -14,15 +14,15 @@ let db: Database.Database | null = null
 
 export function getDatabase(): Database.Database {
   if (!db) {
-    const kimakiDir = path.join(os.homedir(), '.kimaki')
+    const dataDir = getDataDir()
 
     try {
-      fs.mkdirSync(kimakiDir, { recursive: true })
+      fs.mkdirSync(dataDir, { recursive: true })
     } catch (error) {
-      dbLogger.error('Failed to create ~/.kimaki directory:', error)
+      dbLogger.error(`Failed to create data directory ${dataDir}:`, error)
     }
 
-    const dbPath = path.join(kimakiDir, 'discord-sessions.db')
+    const dbPath = path.join(dataDir, 'discord-sessions.db')
 
     dbLogger.log(`Opening database at: ${dbPath}`)
     db = new Database(dbPath)

package/src/discord-bot.ts

@@ -412,6 +412,99 @@ export async function startDiscordBot({
     }
   })
 
+  // Magic prefix used by `kimaki start-session` CLI command to initiate sessions
+  const BOT_SESSION_PREFIX = '🤖 **Bot-initiated session**'
+
+  // Handle bot-initiated threads created by `kimaki start-session`
+  discordClient.on(Events.ThreadCreate, async (thread, newlyCreated) => {
+    try {
+      if (!newlyCreated) {
+        return
+      }
+
+      // Only handle threads in text channels
+      const parent = thread.parent as TextChannel | null
+      if (!parent || parent.type !== ChannelType.GuildText) {
+        return
+      }
+
+      // Get the starter message to check for magic prefix
+      const starterMessage = await thread.fetchStarterMessage().catch(() => null)
+      if (!starterMessage) {
+        discordLogger.log(`[THREAD_CREATE] Could not fetch starter message for thread ${thread.id}`)
+        return
+      }
+
+      // Only handle messages from this bot with the magic prefix
+      if (starterMessage.author.id !== discordClient.user?.id) {
+        return
+      }
+
+      if (!starterMessage.content.startsWith(BOT_SESSION_PREFIX)) {
+        return
+      }
+
+      discordLogger.log(`[BOT_SESSION] Detected bot-initiated thread: ${thread.name}`)
+
+      // Extract the prompt (everything after the prefix)
+      const prompt = starterMessage.content.slice(BOT_SESSION_PREFIX.length).trim()
+      if (!prompt) {
+        discordLogger.log(`[BOT_SESSION] No prompt found in starter message`)
+        return
+      }
+
+      // Extract directory from parent channel topic
+      if (!parent.topic) {
+        discordLogger.log(`[BOT_SESSION] Parent channel has no topic`)
+        return
+      }
+
+      const extracted = extractTagsArrays({
+        xml: parent.topic,
+        tags: ['kimaki.directory', 'kimaki.app'],
+      })
+
+      const projectDirectory = extracted['kimaki.directory']?.[0]?.trim()
+      const channelAppId = extracted['kimaki.app']?.[0]?.trim()
+
+      if (!projectDirectory) {
+        discordLogger.log(`[BOT_SESSION] No kimaki.directory in parent channel topic`)
+        return
+      }
+
+      if (channelAppId && channelAppId !== currentAppId) {
+        discordLogger.log(`[BOT_SESSION] Channel belongs to different bot app`)
+        return
+      }
+
+      if (!fs.existsSync(projectDirectory)) {
+        discordLogger.error(`[BOT_SESSION] Directory does not exist: ${projectDirectory}`)
+        await thread.send({
+          content: `✗ Directory does not exist: ${JSON.stringify(projectDirectory)}`,
+          flags: SILENT_MESSAGE_FLAGS,
+        })
+        return
+      }
+
+      discordLogger.log(`[BOT_SESSION] Starting session for thread ${thread.id} with prompt: "${prompt.slice(0, 50)}..."`)
+
+      await handleOpencodeSession({
+        prompt,
+        thread,
+        projectDirectory,
+        channelId: parent.id,
+      })
+    } catch (error) {
+      voiceLogger.error('[BOT_SESSION] Error handling bot-initiated thread:', error)
+      try {
+        const errMsg = error instanceof Error ? error.message : String(error)
+        await thread.send({ content: `Error: ${errMsg}`, flags: SILENT_MESSAGE_FLAGS })
+      } catch {
+        // Ignore send errors
+      }
+    }
+  })
+
   await discordClient.login(token)
 
   const handleShutdown = async (signal: string, { skipExit = false } = {}) => {

package/src/session-handler.ts

@@ -690,7 +690,7 @@ export async function handleOpencodeSession({
           path: { id: session.id },
           body: {
             parts,
-            system: getOpencodeSystemMessage({ sessionId: session.id }),
+            system: getOpencodeSystemMessage({ sessionId: session.id, channelId }),
             model: modelParam,
             agent: agentPreference,
           },

package/src/system-message.ts

@@ -2,13 +2,13 @@
 // Creates the system message injected into every OpenCode session,
 // including Discord-specific formatting rules, diff commands, and permissions info.
 
-export function getOpencodeSystemMessage({ sessionId }: { sessionId: string }) {
+export function getOpencodeSystemMessage({ sessionId, channelId }: { sessionId: string; channelId?: string }) {
   return `
 The user is reading your messages from inside Discord, via kimaki.xyz
 
 The user cannot see bash tool outputs. If there is important information in bash output, include it in your text response.
 
-Your current OpenCode session ID is: ${sessionId}
+Your current OpenCode session ID is: ${sessionId}${channelId ? `\nYour current Discord channel ID is: ${channelId}` : ''}
 
 ## permissions
 
@@ -23,7 +23,15 @@ Only users with these Discord permissions can send messages to the bot:
 To upload files to the Discord thread (images, screenshots, long files that would clutter the chat), run:
 
 npx -y kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
+${channelId ? `
+## starting new sessions from CLI
 
+To start a new thread/session in this channel programmatically, run:
+
+npx -y kimaki start-session --channel ${channelId} --prompt "your prompt here"
+
+This is useful for automation (cron jobs, GitHub webhooks, n8n, etc.)
+` : ''}
 ## showing diffs
 
 IMPORTANT: After editing any files, you MUST execute the critique command using the Bash tool to get a diff URL, then share that URL with the user.

package/src/utils.ts

@@ -2,6 +2,7 @@
 // Includes Discord OAuth URL generation, array deduplication,
 // abort error detection, and date/time formatting helpers.
 
+import os from 'node:os'
 import { PermissionsBitField } from 'discord.js'
 
 type GenerateInstallUrlOptions = {
@@ -116,3 +117,11 @@ const dtf = new Intl.DateTimeFormat('en-US', {
 export function formatDateTime(date: Date): string {
   return dtf.format(date)
 }
+
+export function abbreviatePath(fullPath: string): string {
+  const home = os.homedir()
+  if (fullPath.startsWith(home)) {
+    return '~' + fullPath.slice(home.length)
+  }
+  return fullPath
+}