macroclaw 0.1.0 → 0.3.0

package/README.md

@@ -63,21 +63,44 @@ the bot.
 - [Bun](https://bun.sh/) runtime
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and logged in
 
-## Install
+## Setup
 
 ```bash
 # Run directly (no install needed)
-TELEGRAM_BOT_TOKEN=xxx AUTHORIZED_CHAT_ID=123 bunx macroclaw
+bunx macroclaw
 
 # Or install globally
 bun install -g macroclaw
-export TELEGRAM_BOT_TOKEN=xxx
-export AUTHORIZED_CHAT_ID=123
 macroclaw
 ```
 
-On first run, a workspace is created at `~/.macroclaw-workspace` with default config.
-Set `WORKSPACE` to use a different path. Set `MODEL` to override the Claude model.
+On first launch, an interactive setup wizard guides you through configuration.
+
+The setup wizard will:
+1. Ask for your **Telegram bot token** (from [@BotFather](https://t.me/BotFather))
+2. Start the bot temporarily so you can send `/chatid` to discover your chat ID
+3. Ask for your **chat ID**, **model** preference, **workspace path**, and optional **OpenAI API key**
+4. Save settings to `~/.macroclaw/settings.json`
+
+On subsequent runs, settings are loaded from the file. Environment variables override file settings (see `.env.example`).
+
+### Configuration
+
+Settings are stored in `~/.macroclaw/settings.json` and validated on startup.
+
+| Setting        | Env var override       | Default                    | Required |
+|----------------|------------------------|----------------------------|----------|
+| `botToken`     | `TELEGRAM_BOT_TOKEN`   | —                          | Yes      |
+| `chatId`       | `AUTHORIZED_CHAT_ID`   | —                          | Yes      |
+| `model`        | `MODEL`                | `sonnet`                   | No       |
+| `workspace`    | `WORKSPACE`            | `~/.macroclaw-workspace`   | No       |
+| `openaiApiKey` | `OPENAI_API_KEY`       | —                          | No       |
+| `logLevel`     | `LOG_LEVEL`            | `debug`                    | No       |
+| `pinoramaUrl`  | `PINORAMA_URL`         | —                          | No       |
+
+Env vars take precedence over settings file values. On startup, a masked settings summary is printed showing which values were overridden by env vars.
+
+Session state (Claude session IDs) is stored separately in `~/.macroclaw/sessions.json`.
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/app.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
 import { existsSync, rmSync } from "node:fs";
 import { App, type AppConfig } from "./app";
 import type { Claude, ClaudeDeferredResult, ClaudeResult, ClaudeRunOptions } from "./claude";
-import { saveSettings } from "./settings";
+import { saveSessions } from "./sessions";
 
 const mockOpenAICreate = mock(async () => ({ text: "transcribed text" }));
 
@@ -64,7 +64,7 @@ const savedOpenAIKey = process.env.OPENAI_API_KEY;
 beforeEach(() => {
   process.env.OPENAI_API_KEY = "test-key";
   if (existsSync(tmpSettingsDir)) rmSync(tmpSettingsDir, { recursive: true });
-  saveSettings({ sessionId: "test-session" }, tmpSettingsDir);
+  saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
 });
 
 afterEach(() => {

package/src/index.ts

@@ -1,22 +1,38 @@
 import { cpSync, existsSync, readdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
 import { App, type AppConfig } from "./app";
 import { createLogger, initLogger } from "./logger";
+import { applyEnvOverrides, loadSettings, printSettings, saveSettings } from "./settings";
+import { runSetupWizard } from "./setup";
 
 await initLogger();
 const log = createLogger("index");
 
-function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) {
-    log.error({ name }, "Missing environment variable");
-    process.exit(1);
-  }
-  return value;
+const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
+
+let settings = loadSettings(defaultDir);
+
+if (!settings) {
+  log.info("No settings.json found, starting setup wizard");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const io = {
+    ask: (question: string): Promise<string> =>
+      new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim()))),
+    write: (msg: string) => process.stdout.write(msg),
+  };
+  settings = await runSetupWizard(io);
+  rl.close();
+  saveSettings(settings, defaultDir);
+  log.info("Settings saved");
 }
 
-const defaultWorkspace = resolve(process.env.HOME || "~", ".macroclaw-workspace");
-const workspace = process.env.WORKSPACE || defaultWorkspace;
+const { settings: resolved, overrides } = applyEnvOverrides(settings);
+settings = resolved;
+
+printSettings(settings, overrides);
+
+const workspace = resolve(settings.workspace.replace(/^~/, process.env.HOME || "~"));
 
 function initWorkspace(workspace: string) {
   const templateDir = join(dirname(import.meta.dir), "workspace-template");
@@ -33,10 +49,10 @@ function initWorkspace(workspace: string) {
 initWorkspace(workspace);
 
 const config: AppConfig = {
-  botToken: requireEnv("TELEGRAM_BOT_TOKEN"),
-  authorizedChatId: requireEnv("AUTHORIZED_CHAT_ID"),
+  botToken: settings.botToken,
+  authorizedChatId: settings.chatId,
   workspace,
-  model: process.env.MODEL,
+  model: settings.model,
 };
 
 new App(config).start();

package/src/logger.ts

@@ -6,12 +6,12 @@ const prettyStream = pretty({
 	messageFormat: "[{module}] {msg}",
 });
 
-const level = (process.env.LOG_LEVEL || "debug") as pino.Level;
+const level = (process.env.LOG_LEVEL || "info") as pino.Level;
 
 const streams: pino.StreamEntry[] = [{ level, stream: prettyStream }];
 
 const logger = pino(
-	{ level: process.env.LOG_LEVEL || "debug" },
+	{ level: process.env.LOG_LEVEL || "info" },
 	pino.multistream(streams),
 );
 

package/src/orchestrator.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
 import { existsSync, rmSync } from "node:fs";
 import { type Claude, type ClaudeDeferredResult, ClaudeParseError, ClaudeProcessError, type ClaudeResult, type ClaudeRunOptions } from "./claude";
 import { Orchestrator, type OrchestratorConfig, type OrchestratorResponse } from "./orchestrator";
-import { saveSettings } from "./settings";
+import { saveSessions } from "./sessions";
 
 const tmpSettingsDir = "/tmp/macroclaw-test-orchestrator-settings";
 const TEST_WORKSPACE = "/tmp/macroclaw-test-workspace";
@@ -231,7 +231,7 @@ describe("Orchestrator", () => {
 
   describe("session management", () => {
     it("uses --resume for existing session", async () => {
-      saveSettings({ sessionId: "existing-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "existing-session" }, tmpSettingsDir);
       const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }));
       const { orch } = makeOrchestrator(claude);
 
@@ -254,7 +254,7 @@ describe("Orchestrator", () => {
     });
 
     it("creates new session when resume fails", async () => {
-      saveSettings({ sessionId: "old-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "old-session" }, tmpSettingsDir);
       let callCount = 0;
       const claude = mockClaude(async (_opts: ClaudeRunOptions): Promise<ClaudeResult> => {
         callCount++;
@@ -286,7 +286,7 @@ describe("Orchestrator", () => {
     });
 
     it("handleSessionCommand sends session via onResponse", async () => {
-      saveSettings({ sessionId: "test-id" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "test-id" }, tmpSettingsDir);
       const claude = mockClaude(successResult({ action: "send", message: "", actionReason: "" }));
       const { orch, responses } = makeOrchestrator(claude);
 
@@ -298,7 +298,7 @@ describe("Orchestrator", () => {
     });
 
     it("background-agent forks from main session without affecting it", async () => {
-      saveSettings({ sessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
       const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }, "main-session"));
       const { orch } = makeOrchestrator(claude);
 
@@ -319,7 +319,7 @@ describe("Orchestrator", () => {
     });
 
     it("updates session ID after forked call", async () => {
-      saveSettings({ sessionId: "old-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "old-session" }, tmpSettingsDir);
       const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }, "new-forked-session"));
       const { orch } = makeOrchestrator(claude);
 
@@ -436,7 +436,7 @@ describe("Orchestrator", () => {
     });
 
     it("deferred → sends 'taking longer' via onResponse, feeds result back when resolved", async () => {
-      saveSettings({ sessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
       let resolveCompletion: (r: ClaudeResult) => void;
       const completion = new Promise<ClaudeResult>((r) => { resolveCompletion = r; });
       const claude = mockClaude(async (): Promise<ClaudeResult | ClaudeDeferredResult> =>
@@ -458,7 +458,7 @@ describe("Orchestrator", () => {
     });
 
     it("session fork when background agent running on main session", async () => {
-      saveSettings({ sessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
       let resolveCompletion: (r: ClaudeResult) => void;
       const completion = new Promise<ClaudeResult>((r) => { resolveCompletion = r; });
       let callCount = 0;
@@ -485,7 +485,7 @@ describe("Orchestrator", () => {
     });
 
     it("background result with matching session: applied directly (no extra Claude call)", async () => {
-      saveSettings({ sessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
       // Use a deferred claude to simulate the scenario where a task is backgrounded
       let resolveCompletion: (r: ClaudeResult) => void;
       const completion = new Promise<ClaudeResult>((r) => { resolveCompletion = r; });
@@ -587,7 +587,7 @@ describe("Orchestrator", () => {
     });
 
     it("adopt feeds result back when deferred resolves", async () => {
-      saveSettings({ sessionId: "adopted-session" }, tmpSettingsDir);
+      saveSessions({ mainSessionId: "adopted-session" }, tmpSettingsDir);
       let resolveCompletion: (r: ClaudeResult) => void;
       const completion = new Promise<ClaudeResult>((r) => { resolveCompletion = r; });
       const claude = mockClaude(async (): Promise<ClaudeResult | ClaudeDeferredResult> =>

package/src/orchestrator.ts

@@ -4,7 +4,7 @@ import { logPrompt, logResult } from "./history";
 import { createLogger } from "./logger";
 import { BG_TIMEOUT, CRON_TIMEOUT, MAIN_TIMEOUT, SYSTEM_PROMPT } from "./prompts";
 import { Queue } from "./queue";
-import { loadSettings, newSessionId, type Settings, saveSettings } from "./settings";
+import { loadSessions, newSessionId, type Sessions, saveSessions } from "./sessions";
 
 const log = createLogger("orchestrator");
 
@@ -84,7 +84,7 @@ interface CallResult {
 
 export class Orchestrator {
   #claude: Claude;
-  #settings: Settings;
+  #sessions: Sessions;
   #sessionId: string;
   #sessionFlag: "--resume" | "--session-id";
   #sessionResolved = false;
@@ -95,17 +95,17 @@ export class Orchestrator {
   constructor(config: OrchestratorConfig) {
     this.#config = config;
     this.#claude = config.claude ?? new Claude({ workspace: config.workspace, jsonSchema });
-    this.#settings = loadSettings(config.settingsDir);
+    this.#sessions = loadSessions(config.settingsDir);
     this.#queue = new Queue<OrchestratorRequest>();
     this.#queue.setHandler((request) => this.#handleRequest(request));
 
-    if (this.#settings.sessionId) {
-      this.#sessionId = this.#settings.sessionId;
+    if (this.#sessions.mainSessionId) {
+      this.#sessionId = this.#sessions.mainSessionId;
       this.#sessionFlag = "--resume";
     } else {
       this.#sessionId = newSessionId();
       this.#sessionFlag = "--session-id";
-      saveSettings({ sessionId: this.#sessionId }, config.settingsDir);
+      saveSessions({ mainSessionId: this.#sessionId }, config.settingsDir);
       log.info({ sessionId: this.#sessionId }, "Created new session");
     }
   }
@@ -272,7 +272,7 @@ export class Orchestrator {
         this.#sessionId = newSessionId();
         log.info({ sessionId: this.#sessionId }, "Resume failed, created new session");
         this.#sessionFlag = "--session-id";
-        saveSettings({ sessionId: this.#sessionId }, this.#config.settingsDir);
+        saveSessions({ mainSessionId: this.#sessionId }, this.#config.settingsDir);
         result = await this.#callClaude(built, this.#sessionFlag, this.#sessionId);
       }
 
@@ -282,7 +282,7 @@ export class Orchestrator {
       if (result.sessionId && result.sessionId !== this.#sessionId) {
         log.info({ oldSessionId: this.#sessionId, newSessionId: result.sessionId }, "Session forked, updating session ID");
         this.#sessionId = result.sessionId;
-        saveSettings({ sessionId: this.#sessionId }, this.#config.settingsDir);
+        saveSessions({ mainSessionId: this.#sessionId }, this.#config.settingsDir);
       }
 
       // Mark resolved on first success

package/src/sessions.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadSessions, newSessionId, saveSessions } from "./sessions";
+
+const tmpDir = "/tmp/macroclaw-sessions-test";
+
+afterEach(() => {
+  if (existsSync(tmpDir)) rmSync(tmpDir, { recursive: true });
+});
+
+describe("loadSessions", () => {
+  it("returns empty object when dir does not exist", () => {
+    expect(loadSessions(tmpDir)).toEqual({});
+  });
+
+  it("returns empty object when file does not exist", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    expect(loadSessions(tmpDir)).toEqual({});
+  });
+
+  it("reads sessions from file", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({ mainSessionId: "abc-123" }));
+    expect(loadSessions(tmpDir)).toEqual({ mainSessionId: "abc-123" });
+  });
+
+  it("returns empty object when file is corrupt", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "sessions.json"), "not json");
+    expect(loadSessions(tmpDir)).toEqual({});
+  });
+
+  it("strips unknown fields via schema", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({ mainSessionId: "abc", extra: true }));
+    const result = loadSessions(tmpDir);
+    expect(result).toEqual({ mainSessionId: "abc" });
+  });
+});
+
+describe("saveSessions", () => {
+  it("creates directory and writes file", () => {
+    saveSessions({ mainSessionId: "new-id" }, tmpDir);
+    const saved = loadSessions(tmpDir);
+    expect(saved).toEqual({ mainSessionId: "new-id" });
+  });
+
+  it("overwrites existing file", () => {
+    saveSessions({ mainSessionId: "first" }, tmpDir);
+    saveSessions({ mainSessionId: "second" }, tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({ mainSessionId: "second" });
+  });
+});
+
+describe("newSessionId", () => {
+  it("returns a valid UUID", () => {
+    const id = newSessionId();
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    expect(newSessionId()).not.toBe(id);
+  });
+});

package/src/sessions.ts

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod/v4";
+import { createLogger } from "./logger";
+
+const log = createLogger("sessions");
+
+const sessionsSchema = z.object({
+  mainSessionId: z.string().optional(),
+});
+
+export type Sessions = z.infer<typeof sessionsSchema>;
+
+const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
+
+export function loadSessions(dir: string = defaultDir): Sessions {
+  try {
+    const path = join(dir, "sessions.json");
+    if (!existsSync(path)) return {};
+    const raw = readFileSync(path, "utf-8");
+    return sessionsSchema.parse(JSON.parse(raw));
+  } catch (err) {
+    log.warn({ err }, "Failed to load sessions.json, resetting to empty");
+    return {};
+  }
+}
+
+export function saveSessions(sessions: Sessions, dir: string = defaultDir): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "sessions.json"), `${JSON.stringify(sessions, null, 2)}\n`);
+}
+
+export function newSessionId(): string {
+  return randomUUID();
+}

package/src/settings.test.ts

@@ -1,55 +1,220 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { loadSettings, newSessionId, saveSettings } from "./settings";
+import { applyEnvOverrides, loadSettings, printSettings, type Settings, saveSettings } from "./settings";
 
 const tmpDir = "/tmp/macroclaw-settings-test";
 
+const validSettings: Settings = {
+  botToken: "123:ABC",
+  chatId: "12345678",
+  model: "sonnet",
+  workspace: "~/.macroclaw-workspace",
+  logLevel: "debug",
+};
+
 afterEach(() => {
   if (existsSync(tmpDir)) rmSync(tmpDir, { recursive: true });
 });
 
 describe("loadSettings", () => {
-  it("returns empty object when dir does not exist", () => {
-    expect(loadSettings(tmpDir)).toEqual({});
+  it("returns null when file does not exist", () => {
+    expect(loadSettings(tmpDir)).toBeNull();
   });
 
-  it("returns empty object when file does not exist", () => {
+  it("reads and validates settings from file", () => {
     mkdirSync(tmpDir, { recursive: true });
-    expect(loadSettings(tmpDir)).toEqual({});
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
+      botToken: "123:ABC",
+      chatId: "12345678",
+    }));
+    const settings = loadSettings(tmpDir);
+    expect(settings).toEqual({
+      botToken: "123:ABC",
+      chatId: "12345678",
+      model: "sonnet",
+      workspace: "~/.macroclaw-workspace",
+      logLevel: "info",
+    });
   });
 
-  it("reads settings from file", () => {
+  it("applies defaults for optional fields", () => {
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ sessionId: "abc-123" }));
-    expect(loadSettings(tmpDir)).toEqual({ sessionId: "abc-123" });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
+      botToken: "tok",
+      chatId: "123",
+      model: "opus",
+      workspace: "/custom",
+      openaiApiKey: "sk-test",
+      logLevel: "info",
+      pinoramaUrl: "http://localhost:6200",
+    }));
+    const settings = loadSettings(tmpDir);
+    expect(settings).toEqual({
+      botToken: "tok",
+      chatId: "123",
+      model: "opus",
+      workspace: "/custom",
+      openaiApiKey: "sk-test",
+      logLevel: "info",
+      pinoramaUrl: "http://localhost:6200",
+    });
   });
 
-  it("returns empty object when file is corrupt", () => {
+  it("exits with code 1 when file is not valid JSON", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), "not json");
-    expect(loadSettings(tmpDir)).toEqual({});
+
+    const mockExit = mock(() => { throw new Error("exit"); });
+    const origExit = process.exit;
+    process.exit = mockExit as any;
+
+    try {
+      loadSettings(tmpDir);
+    } catch {
+      // expected
+    }
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    process.exit = origExit;
+  });
+
+  it("exits with code 1 when validation fails (missing required field)", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ chatId: "123" }));
+
+    const mockExit = mock(() => { throw new Error("exit"); });
+    const origExit = process.exit;
+    process.exit = mockExit as any;
+
+    try {
+      loadSettings(tmpDir);
+    } catch {
+      // expected
+    }
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    process.exit = origExit;
+  });
+
+  it("exits with code 1 when validation fails (invalid logLevel)", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
+      botToken: "tok",
+      chatId: "123",
+      logLevel: "verbose",
+    }));
+
+    const mockExit = mock(() => { throw new Error("exit"); });
+    const origExit = process.exit;
+    process.exit = mockExit as any;
+
+    try {
+      loadSettings(tmpDir);
+    } catch {
+      // expected
+    }
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    process.exit = origExit;
   });
 });
 
 describe("saveSettings", () => {
   it("creates directory and writes file", () => {
-    saveSettings({ sessionId: "new-id" }, tmpDir);
+    saveSettings(validSettings, tmpDir);
     const saved = loadSettings(tmpDir);
-    expect(saved).toEqual({ sessionId: "new-id" });
+    expect(saved).toEqual(validSettings);
   });
 
   it("overwrites existing file", () => {
-    saveSettings({ sessionId: "first" }, tmpDir);
-    saveSettings({ sessionId: "second" }, tmpDir);
-    expect(loadSettings(tmpDir)).toEqual({ sessionId: "second" });
+    saveSettings(validSettings, tmpDir);
+    const updated = { ...validSettings, model: "opus" };
+    saveSettings(updated, tmpDir);
+    expect(loadSettings(tmpDir)).toEqual(updated);
+  });
+});
+
+describe("applyEnvOverrides", () => {
+  const envVars = [
+    "TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL",
+    "WORKSPACE", "OPENAI_API_KEY", "LOG_LEVEL", "PINORAMA_URL",
+  ];
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const v of envVars) {
+      savedEnv[v] = process.env[v];
+      delete process.env[v];
+    }
+  });
+
+  afterEach(() => {
+    for (const v of envVars) {
+      if (savedEnv[v] !== undefined) process.env[v] = savedEnv[v];
+      else delete process.env[v];
+    }
+  });
+
+  it("returns original settings when no env vars set", () => {
+    const { settings, overrides } = applyEnvOverrides(validSettings);
+    expect(settings).toEqual(validSettings);
+    expect(overrides.size).toBe(0);
+  });
+
+  it("overrides model from MODEL env var", () => {
+    process.env.MODEL = "opus";
+    const { settings, overrides } = applyEnvOverrides(validSettings);
+    expect(settings.model).toBe("opus");
+    expect(overrides.has("model")).toBe(true);
+  });
+
+  it("overrides multiple fields and tracks them", () => {
+    process.env.TELEGRAM_BOT_TOKEN = "override-token";
+    process.env.AUTHORIZED_CHAT_ID = "99999";
+    process.env.OPENAI_API_KEY = "sk-override";
+    const { settings, overrides } = applyEnvOverrides(validSettings);
+    expect(settings.botToken).toBe("override-token");
+    expect(settings.chatId).toBe("99999");
+    expect(settings.openaiApiKey).toBe("sk-override");
+    expect(overrides.size).toBe(3);
+  });
+
+  it("overrides workspace and log-related fields", () => {
+    process.env.WORKSPACE = "/override/path";
+    process.env.LOG_LEVEL = "error";
+    process.env.PINORAMA_URL = "http://override:6200";
+    const { settings, overrides } = applyEnvOverrides(validSettings);
+    expect(settings.workspace).toBe("/override/path");
+    expect(settings.logLevel).toBe("error");
+    expect(settings.pinoramaUrl).toBe("http://override:6200");
+    expect(overrides.has("workspace")).toBe(true);
+    expect(overrides.has("logLevel")).toBe(true);
+    expect(overrides.has("pinoramaUrl")).toBe(true);
   });
 });
 
-describe("newSessionId", () => {
-  it("returns a valid UUID", () => {
-    const id = newSessionId();
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-    expect(newSessionId()).not.toBe(id);
+describe("printSettings", () => {
+  it("does not throw", () => {
+    expect(() => printSettings(validSettings, new Set())).not.toThrow();
+  });
+
+  it("does not throw with overrides", () => {
+    expect(() => printSettings(validSettings, new Set(["model"]))).not.toThrow();
+  });
+
+  it("does not throw with optional fields set", () => {
+    const full: Settings = {
+      ...validSettings,
+      openaiApiKey: "sk-1234567890",
+      pinoramaUrl: "http://localhost:6200",
+    };
+    expect(() => printSettings(full, new Set(["model", "openaiApiKey"]))).not.toThrow();
+  });
+
+  it("masks botToken showing only last 4 chars", () => {
+    // We test the masking indirectly — printSettings shouldn't throw
+    // and the function exists primarily for the startup log
+    expect(() => printSettings({ ...validSettings, botToken: "ab" }, new Set())).not.toThrow();
   });
 });

package/src/settings.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { z } from "zod/v4";
@@ -6,8 +5,14 @@ import { createLogger } from "./logger";
 
 const log = createLogger("settings");
 
-const settingsSchema = z.object({
-  sessionId: z.string().optional(),
+export const settingsSchema = z.object({
+  botToken: z.string(),
+  chatId: z.string(),
+  model: z.string().default("sonnet"),
+  workspace: z.string().default("~/.macroclaw-workspace"),
+  openaiApiKey: z.string().optional(),
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  pinoramaUrl: z.string().optional(),
 });
 
 export type Settings = z.infer<typeof settingsSchema>;
@@ -15,15 +20,24 @@ export type Settings = z.infer<typeof settingsSchema>;
 const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
 
 export function loadSettings(dir: string = defaultDir): Settings {
+  const path = join(dir, "settings.json");
+  if (!existsSync(path)) return null as unknown as Settings;
+
+  let raw: unknown;
   try {
-    const path = join(dir, "settings.json");
-    if (!existsSync(path)) return {};
-    const raw = readFileSync(path, "utf-8");
-    return settingsSchema.parse(JSON.parse(raw));
+    raw = JSON.parse(readFileSync(path, "utf-8"));
   } catch (err) {
-    log.warn({ err }, "Failed to load settings.json");
-    return {};
+    log.error({ err }, "settings.json is not valid JSON");
+    process.exit(1);
+  }
+
+  const result = settingsSchema.safeParse(raw);
+  if (!result.success) {
+    log.error({ issues: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) }, "settings.json validation failed");
+    process.exit(1);
   }
+
+  return result.data;
 }
 
 export function saveSettings(settings: Settings, dir: string = defaultDir): void {
@@ -31,6 +45,50 @@ export function saveSettings(settings: Settings, dir: string = defaultDir): void
   writeFileSync(join(dir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
 }
 
-export function newSessionId(): string {
-  return randomUUID();
+// --- Env var overrides ---
+
+const envMapping: Record<keyof Settings, string> = {
+  botToken: "TELEGRAM_BOT_TOKEN",
+  chatId: "AUTHORIZED_CHAT_ID",
+  model: "MODEL",
+  workspace: "WORKSPACE",
+  openaiApiKey: "OPENAI_API_KEY",
+  logLevel: "LOG_LEVEL",
+  pinoramaUrl: "PINORAMA_URL",
+};
+
+export function applyEnvOverrides(settings: Settings): { settings: Settings; overrides: Set<string> } {
+  const merged = { ...settings };
+  const overrides = new Set<string>();
+
+  for (const [key, envVar] of Object.entries(envMapping)) {
+    const value = process.env[envVar];
+    if (value !== undefined) {
+      (merged as Record<string, unknown>)[key] = value;
+      overrides.add(key);
+    }
+  }
+
+  return { settings: merged, overrides };
+}
+
+// --- Startup log ---
+
+export function maskValue(key: string, value: string | undefined): string {
+  if (value === undefined) return "(not set)";
+  if (key === "botToken" || key === "openaiApiKey") {
+    return value.length > 4 ? `****${value.slice(-4)}` : "****";
+  }
+  return value;
+}
+
+export function printSettings(settings: Settings, overrides: Set<string>): void {
+  const lines = ["Settings:"];
+  for (const key of Object.keys(envMapping) as (keyof Settings)[]) {
+    const value = settings[key];
+    const masked = maskValue(key, value);
+    const suffix = overrides.has(key) ? " (env)" : "";
+    lines.push(`  ${key}: ${masked}${suffix}`);
+  }
+  log.info(lines.join("\n"));
 }

package/src/setup.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import type { SetupIO } from "./setup";
+
+// Mock Grammy Bot
+const mockBotInit = mock(async () => {});
+const mockBotStart = mock(() => {});
+const mockBotStop = mock(async () => {});
+const mockSetMyCommands = mock(async () => {});
+let mockBotCatchHandler: Function | null = null;
+let mockBotCommandHandler: Function | null = null;
+
+mock.module("grammy", () => ({
+  Bot: class MockBot {
+    token: string;
+    botInfo = { username: "test_bot" };
+
+    api = { setMyCommands: mockSetMyCommands };
+
+    constructor(token: string) {
+      this.token = token;
+    }
+
+    command(_name: string, handler: Function) {
+      mockBotCommandHandler = handler;
+    }
+
+    catch(handler: Function) {
+      mockBotCatchHandler = handler;
+    }
+
+    async init() {
+      await mockBotInit();
+    }
+
+    start() {
+      mockBotStart();
+    }
+
+    async stop() {
+      await mockBotStop();
+    }
+  },
+}));
+
+const { runSetupWizard } = await import("./setup");
+
+function createMockIO(inputs: string[]): SetupIO {
+  let index = 0;
+  const written: string[] = [];
+  return {
+    ask: async () => inputs[index++] ?? "",
+    write: (msg: string) => { written.push(msg); },
+  };
+}
+
+// Save/restore env vars
+const envVars = ["TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL", "WORKSPACE", "OPENAI_API_KEY"];
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  for (const v of envVars) {
+    savedEnv[v] = process.env[v];
+    delete process.env[v];
+  }
+  mockBotInit.mockImplementation(async () => {});
+  mockBotStart.mockClear();
+  mockBotStop.mockClear();
+  mockSetMyCommands.mockClear();
+  mockBotCatchHandler = null;
+  mockBotCommandHandler = null;
+});
+
+afterEach(() => {
+  for (const v of envVars) {
+    if (savedEnv[v] !== undefined) process.env[v] = savedEnv[v];
+    else delete process.env[v];
+  }
+});
+
+describe("runSetupWizard", () => {
+  it("collects all required fields via prompts", async () => {
+    const io = createMockIO([
+      "123:ABC",   // bot token
+      "12345678",  // chat ID
+      "opus",      // model
+      "/my/ws",    // workspace
+      "sk-test",   // openai key
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.botToken).toBe("123:ABC");
+    expect(settings.chatId).toBe("12345678");
+    expect(settings.model).toBe("opus");
+    expect(settings.workspace).toBe("/my/ws");
+    expect(settings.openaiApiKey).toBe("sk-test");
+    expect(settings.logLevel).toBe("debug");
+  });
+
+  it("uses defaults from env vars when user presses enter", async () => {
+    process.env.TELEGRAM_BOT_TOKEN = "env-token";
+    process.env.AUTHORIZED_CHAT_ID = "env-chat";
+    process.env.MODEL = "haiku";
+    process.env.WORKSPACE = "/env/ws";
+    process.env.OPENAI_API_KEY = "sk-env";
+
+    const io = createMockIO([
+      "",  // accept default token
+      "",  // accept default chat ID
+      "",  // accept default model
+      "",  // accept default workspace
+      "",  // accept default openai key
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.botToken).toBe("env-token");
+    expect(settings.chatId).toBe("env-chat");
+    expect(settings.model).toBe("haiku");
+    expect(settings.workspace).toBe("/env/ws");
+    expect(settings.openaiApiKey).toBe("sk-env");
+  });
+
+  it("uses sonnet as default model when no env var", async () => {
+    const io = createMockIO([
+      "tok",
+      "123",
+      "",       // press enter for default model
+      "",       // press enter for default workspace
+      "",       // press enter for no openai key
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.model).toBe("sonnet");
+    expect(settings.workspace).toBe("~/.macroclaw-workspace");
+    expect(settings.openaiApiKey).toBeUndefined();
+  });
+
+  it("starts and stops the setup bot", async () => {
+    const io = createMockIO([
+      "tok",
+      "123",
+      "",
+      "",
+      "",
+    ]);
+
+    await runSetupWizard(io);
+
+    expect(mockBotInit).toHaveBeenCalled();
+    expect(mockBotStart).toHaveBeenCalled();
+    expect(mockBotStop).toHaveBeenCalled();
+  });
+
+  it("re-prompts on invalid bot token", async () => {
+    let callCount = 0;
+    mockBotInit.mockImplementation(async () => {
+      callCount++;
+      if (callCount === 1) throw new Error("Invalid token");
+    });
+
+    const io = createMockIO([
+      "bad-token",   // first attempt — fails
+      "good-token",  // second attempt — succeeds
+      "123",
+      "",
+      "",
+      "",
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.botToken).toBe("good-token");
+    expect(callCount).toBe(2);
+  });
+
+  it("re-prompts when bot token is empty", async () => {
+    const io = createMockIO([
+      "",            // empty — re-prompt
+      "actual-token",
+      "123",
+      "",
+      "",
+      "",
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.botToken).toBe("actual-token");
+  });
+
+  it("re-prompts when chat ID is empty", async () => {
+    const io = createMockIO([
+      "tok",
+      "",        // empty — re-prompt
+      "456",
+      "",
+      "",
+      "",
+    ]);
+
+    const settings = await runSetupWizard(io);
+
+    expect(settings.chatId).toBe("456");
+  });
+
+  it("registers and uses catch handler on setup bot", async () => {
+    const io = createMockIO([
+      "tok",
+      "123",
+      "",
+      "",
+      "",
+    ]);
+
+    await runSetupWizard(io);
+
+    // The catch handler was registered
+    expect(mockBotCatchHandler).not.toBeNull();
+    // Calling it should not throw (it logs internally)
+    expect(() => mockBotCatchHandler!(new Error("test error"))).not.toThrow();
+  });
+
+  it("registers /chatid command handler on setup bot", async () => {
+    const io = createMockIO([
+      "tok",
+      "123",
+      "",
+      "",
+      "",
+    ]);
+
+    await runSetupWizard(io);
+
+    expect(mockBotCommandHandler).not.toBeNull();
+    const mockReply = mock(() => {});
+    mockBotCommandHandler!({ chat: { id: 12345 }, reply: mockReply });
+    expect(mockReply).toHaveBeenCalledWith("12345");
+  });
+});

package/src/setup.ts

@@ -0,0 +1,94 @@
+import { Bot } from "grammy";
+import { createLogger } from "./logger";
+import { maskValue, type Settings, settingsSchema } from "./settings";
+
+const log = createLogger("setup");
+
+export interface SetupIO {
+  ask: (question: string) => Promise<string>;
+  write: (msg: string) => void;
+}
+
+async function startSetupBot(token: string): Promise<Bot> {
+  const bot = new Bot(token);
+  bot.command("chatid", (ctx) => {
+    ctx.reply(ctx.chat.id.toString());
+  });
+  bot.catch((err) => {
+    log.debug({ err }, "Setup bot error");
+  });
+
+  await bot.init();
+  await bot.api.setMyCommands([{ command: "chatid", description: "Get your chat ID" }]);
+  log.info({ username: bot.botInfo.username }, "Setup bot started");
+
+  bot.start();
+  return bot;
+}
+
+export async function runSetupWizard(io: SetupIO): Promise<Settings> {
+  const { ask, write } = io;
+
+  write("\n=== Macroclaw Setup ===\n\n");
+
+  // Bot token
+  const defaultToken = process.env.TELEGRAM_BOT_TOKEN || "";
+  const tokenPrompt = defaultToken ? `Bot token [${maskValue("botToken", defaultToken)}]: ` : "Bot token: ";
+  let botToken = await ask(tokenPrompt) || defaultToken;
+
+  // Validate token by starting a temporary bot
+  let setupBot: Bot | null = null;
+  while (true) {
+    if (!botToken) {
+      botToken = await ask("Bot token (required): ");
+      continue;
+    }
+    try {
+      setupBot = await startSetupBot(botToken);
+      write(`Bot @${setupBot.botInfo.username} connected. Send /chatid to the bot to get your chat ID.\n`);
+      break;
+    } catch {
+      write("Invalid bot token. Please try again.\n");
+      botToken = await ask("Bot token: ");
+    }
+  }
+
+  // Chat ID
+  const defaultChatId = process.env.AUTHORIZED_CHAT_ID || "";
+  const chatIdPrompt = defaultChatId ? `Chat ID [${defaultChatId}]: ` : "Chat ID: ";
+  let chatId = await ask(chatIdPrompt) || defaultChatId;
+  while (!chatId) {
+    chatId = await ask("Chat ID (required): ");
+  }
+
+  // Stop setup bot
+  if (setupBot) {
+    await setupBot.stop();
+  }
+
+  // Model
+  const defaultModel = process.env.MODEL || "sonnet";
+  const model = await ask(`Model [${defaultModel}]: `) || defaultModel;
+
+  // Workspace
+  const defaultWorkspace = process.env.WORKSPACE || "~/.macroclaw-workspace";
+  const workspace = await ask(`Workspace [${defaultWorkspace}]: `) || defaultWorkspace;
+
+  // OpenAI API key
+  const defaultOpenai = process.env.OPENAI_API_KEY || "";
+  const openaiPrompt = defaultOpenai ? `OpenAI API key [${maskValue("openaiApiKey", defaultOpenai)}] (optional): ` : "OpenAI API key (optional): ";
+  const openaiApiKey = await ask(openaiPrompt) || defaultOpenai || undefined;
+
+  const settings: Settings = settingsSchema.parse({
+    botToken,
+    chatId,
+    model,
+    workspace,
+    openaiApiKey,
+    logLevel: "debug",
+  });
+
+  write("\nSetup complete!\n\n");
+
+  return settings;
+}