zozul-cli 0.1.0

package/dist/sync/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/sync/transform.ts"],"names":[],"mappings":"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"}

package/dist/sync/transform.js

@@ -0,0 +1,90 @@
+// ── Safe JSON parse ──
+function safeJsonParse(value) {
+    if (value == null)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+// ── Transform functions ──
+export function transformSession(row) {
+    return {
+        id: row.id,
+        project_path: row.project_path,
+        started_at: row.started_at,
+        ended_at: row.ended_at,
+        total_input_tokens: row.total_input_tokens,
+        total_output_tokens: row.total_output_tokens,
+        total_cache_read_tokens: row.total_cache_read_tokens,
+        total_cache_creation_tokens: row.total_cache_creation_tokens,
+        total_cost_usd: row.total_cost_usd,
+        total_turns: row.total_turns,
+        total_duration_ms: row.total_duration_ms,
+        model: row.model,
+    };
+}
+export function transformTurn(row) {
+    return {
+        turn_index: row.turn_index,
+        role: row.role,
+        timestamp: row.timestamp,
+        input_tokens: row.input_tokens,
+        output_tokens: row.output_tokens,
+        cache_read_tokens: row.cache_read_tokens,
+        cache_creation_tokens: row.cache_creation_tokens,
+        cost_usd: row.cost_usd,
+        duration_ms: row.duration_ms,
+        model: row.model,
+        content_text: row.content_text,
+        tool_calls: safeJsonParse(row.tool_calls),
+        is_real_user: row.is_real_user === 1,
+    };
+}
+export function transformToolUse(row, turnLookup) {
+    return {
+        turn_index: row.turn_id != null ? (turnLookup.get(row.turn_id) ?? null) : null,
+        tool_name: row.tool_name,
+        tool_input: safeJsonParse(row.tool_input),
+        tool_result: row.tool_result,
+        success: row.success == null ? null : row.success === 1,
+        duration_ms: row.duration_ms,
+        timestamp: row.timestamp,
+    };
+}
+export function transformHookEvent(row) {
+    return {
+        event_name: row.event_name,
+        timestamp: row.timestamp,
+        payload: safeJsonParse(row.payload) ?? row.payload,
+    };
+}
+export function transformTaskTag(row, turnLookup) {
+    return {
+        turn_index: turnLookup.get(row.turn_id) ?? null,
+        task: row.task,
+        tagged_at: row.tagged_at,
+    };
+}
+export function transformOtelMetric(row) {
+    return {
+        name: row.name,
+        value: row.value,
+        attributes: safeJsonParse(row.attributes),
+        session_id: row.session_id,
+        model: row.model,
+        timestamp: row.timestamp,
+    };
+}
+export function transformOtelEvent(row) {
+    return {
+        event_name: row.event_name,
+        attributes: safeJsonParse(row.attributes),
+        session_id: row.session_id,
+        prompt_id: row.prompt_id,
+        timestamp: row.timestamp,
+    };
+}
+//# sourceMappingURL=transform.js.map

package/dist/sync/transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../src/sync/transform.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "zozul-cli",
+  "version": "0.1.0",
+  "description": "Observability for Claude Code — track token usage, costs, turns, and conversation history",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "zozul": "dist/index.js"
+  },
+  "scripts": {
+    "build": "./node_modules/.bin/tsc && cp src/dashboard/index.html dist/dashboard/index.html",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuesday-coder/zozul-cli.git"
+  },
+  "keywords": [
+    "claude-code",
+    "observability",
+    "telemetry",
+    "opentelemetry"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/tuesday-coder/zozul-cli/issues"
+  },
+  "homepage": "https://github.com/tuesday-coder/zozul-cli#readme",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-prometheus": "^0.213.0",
+    "@opentelemetry/otlp-grpc-exporter-base": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-logs": "^0.213.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.0",
+    "better-sqlite3": "^12.8.0",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli/commands.ts

@@ -0,0 +1,332 @@
+import { Command } from "commander";
+import { getDb } from "../storage/db.js";
+import { SessionRepo } from "../storage/repo.js";
+import { createHookServer } from "../hooks/server.js";
+import { installHooksToSettings, uninstallHooksFromSettings, generateHooksConfig } from "../hooks/config.js";
+import { installOtelToSettings, uninstallOtelFromSettings, generateOtelShellExports } from "../otel/config.js";
+import { ingestAllSessions } from "../parser/ingest.js";
+import { watchSessionFiles } from "../parser/watcher.js";
+import { installService, uninstallService, serviceStatus, restartService } from "../service/index.js";
+import { getActiveContext, setActiveContext, clearActiveContext } from "../context/index.js";
+import { installGitHook, uninstallGitHook } from "../hooks/git.js";
+import { runSync } from "../sync/index.js";
+import { ZozulApiClient } from "../sync/client.js";
+
+function envPort(): string {
+  return process.env.ZOZUL_PORT ?? "7890";
+}
+function envOtelEndpoint(): string {
+  return process.env.OTEL_ENDPOINT ?? "http://localhost:7890";
+}
+function envOtelProtocol(): string {
+  return process.env.OTEL_PROTOCOL ?? "http/json";
+}
+function envVerbose(): boolean {
+  return process.env.ZOZUL_VERBOSE === "true" || process.env.ZOZUL_VERBOSE === "1";
+}
+function envDbPath(): string | undefined {
+  return process.env.ZOZUL_DB_PATH || undefined;
+}
+
+export function buildCli(): Command {
+  const program = new Command();
+
+  program
+    .name("zozul")
+    .description("Observability for Claude Code — track tokens, costs, turns, and conversations")
+    .version("0.1.0");
+
+  program
+    .command("serve")
+    .description("Start the hooks HTTP server to receive real-time events from Claude Code")
+    .option("-p, --port <port>", "Port to listen on", envPort())
+    .option("-v, --verbose", "Print events to stderr as they arrive")
+    .action(async (opts) => {
+      const port = parseInt(opts.port, 10);
+      const verbose = opts.verbose || envVerbose();
+      const db = getDb(envDbPath());
+      const repo = new SessionRepo(db);
+      const server = createHookServer({ port, repo, verbose });
+
+      server.on("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "EADDRINUSE") {
+          console.error(`Port ${port} is already in use. Is zozul already running?`);
+          console.error("  Check with: lsof -ti :" + port);
+          db.close();
+          process.exit(0); // clean exit so launchd/systemd won't respawn
+        }
+        throw err;
+      });
+
+      server.listen(port, async () => {
+        console.log(`zozul listening on http://localhost:${port}`);
+        console.log(`  Dashboard:     http://localhost:${port}/dashboard`);
+        console.log(`  Hooks:         http://localhost:${port}/hook/<event>`);
+        console.log(`  OTLP receiver: http://localhost:${port}/v1/metrics & /v1/logs`);
+        console.log(`  API:           http://localhost:${port}/api/*`);
+        console.log("\nPress Ctrl+C to stop.\n");
+
+        const stopWatcher = await watchSessionFiles({ repo, verbose, catchUp: true });
+
+        process.on("SIGINT", () => {
+          stopWatcher();
+          server.close();
+          db.close();
+          process.exit(0);
+        });
+      });
+    });
+
+  program
+    .command("install")
+    .description("Install hooks, OTEL config, and optionally the background service")
+    .option("-p, --port <port>", "Hook server port", envPort())
+    .option("--otel-endpoint <endpoint>", "OTLP endpoint", envOtelEndpoint())
+    .option("--otel-protocol <protocol>", "OTLP protocol", envOtelProtocol())
+    .option("--no-otel", "Skip OTEL configuration")
+    .option("--no-hooks", "Skip hooks configuration")
+    .option("--service", "Also install zozul as a background service (starts on login)")
+    .option("--status", "Show background service status")
+    .option("--restart", "Restart the background service")
+    .option("--dry-run", "Print the config that would be installed without writing")
+    .action((opts) => {
+      if (opts.status) {
+        console.log(`Service status: ${serviceStatus()}`);
+        return;
+      }
+
+      if (opts.restart) {
+        try {
+          restartService();
+          console.log("Service restarted.");
+          console.log(`  Status: ${serviceStatus()}`);
+        } catch (err) {
+          console.error(`Restart failed: ${err instanceof Error ? err.message : err}`);
+          process.exit(1);
+        }
+        return;
+      }
+
+      const port = parseInt(opts.port, 10);
+
+      if (opts.dryRun) {
+        console.log("── Hooks Config (for ~/.claude/settings.json) ──\n");
+        console.log(JSON.stringify(generateHooksConfig({ port }), null, 2));
+        console.log("\n── OTEL Environment Variables ──\n");
+        console.log(generateOtelShellExports({ endpoint: opts.otelEndpoint }));
+        return;
+      }
+
+      if (opts.hooks !== false) {
+        const result = installHooksToSettings({ port });
+        console.log(`Hooks installed to ${result.path}`);
+        if (result.merged) console.log("  (merged with existing hooks)");
+      }
+
+      if (opts.otel !== false) {
+        const result = installOtelToSettings({
+          endpoint: opts.otelEndpoint,
+          protocol: opts.otelProtocol,
+        });
+        console.log(`OTEL config installed to ${result.path}`);
+      }
+
+      if (opts.service) {
+        try {
+          const result = installService({ port, dbPath: envDbPath() });
+          console.log(`Service installed: ${result.servicePath}`);
+          console.log("  zozul is now running in the background and will start automatically on login.");
+        } catch (err) {
+          console.error(`Service install failed: ${err instanceof Error ? err.message : err}`);
+          console.error("  Run 'zozul serve' manually as a fallback.");
+        }
+      } else {
+        console.log("\nDone. Start the server with: zozul serve");
+        console.log("Or install as a background service with: zozul install --service");
+      }
+
+      const gitResult = installGitHook();
+      if (gitResult) {
+        if (gitResult.created) {
+          console.log(`Git post-commit hook installed: ${gitResult.path}`);
+          console.log("  (auto-clears task context on commit)");
+        } else {
+          console.log("Git post-commit hook already installed.");
+        }
+      }
+
+      console.log("Launch Claude Code normally with: claude");
+    });
+
+  program
+    .command("uninstall")
+    .description("Remove zozul hooks, OTEL config, and background service")
+    .option("-p, --port <port>", "Hook server port (to match installed hooks)", envPort())
+    .action((opts) => {
+      const port = parseInt(opts.port, 10);
+
+      const hooksRemoved = uninstallHooksFromSettings({ port });
+      const otelRemoved = uninstallOtelFromSettings();
+      const gitRemoved = uninstallGitHook();
+
+      if (hooksRemoved) console.log("Hooks removed from Claude Code settings.");
+      if (otelRemoved) console.log("OTEL config removed from Claude Code settings.");
+      if (gitRemoved) console.log("Git post-commit hook removed.");
+
+      const serviceResult = uninstallService();
+      if (serviceResult.removed) {
+        console.log("Background service stopped and removed.");
+      }
+
+      if (!hooksRemoved && !otelRemoved && !gitRemoved && !serviceResult.removed) {
+        console.log("Nothing to remove.");
+      }
+    });
+
+  program
+    .command("context [tags...]")
+    .description("Set, view, or clear the active task tags for tagging turns")
+    .option("--clear", "Clear the active task context")
+    .option("--list", "List all tasks that have been used")
+    .action((tags: string[], opts: { clear?: boolean; list?: boolean }) => {
+      if (opts.clear) {
+        clearActiveContext();
+        console.log("Task context cleared.");
+        return;
+      }
+
+      if (opts.list) {
+        const db = getDb(envDbPath());
+        const repo = new SessionRepo(db);
+        const tasks = repo.listTasks();
+        if (tasks.length === 0) {
+          console.log("No tasks found.");
+        } else {
+          for (const t of tasks) {
+            console.log(`  ${t.task}  (${t.turn_count} turns, last tagged: ${t.last_tagged})`);
+          }
+        }
+        db.close();
+        return;
+      }
+
+      if (tags.length > 0) {
+        const ctx = setActiveContext(tags);
+        console.log(`Active tags: ${ctx.active.join(", ")}`);
+        console.log(`  Set at: ${ctx.set_at}`);
+        return;
+      }
+
+      // No arguments: show current context
+      const ctx = getActiveContext();
+      if (ctx?.active && ctx.active.length > 0) {
+        console.log(`Active tags: ${ctx.active.join(", ")}`);
+        console.log(`  Set at: ${ctx.set_at}`);
+      } else {
+        console.log("No active task context.");
+        console.log('Set one with: zozul context "UI" "Feature"');
+      }
+    });
+
+  program
+    .command("sync")
+    .description("Sync local data to the remote zozul backend")
+    .option("--dry-run", "Show what would be synced without sending data")
+    .option("-v, --verbose", "Print detailed progress")
+    .action(async (opts) => {
+      const apiUrl = process.env.ZOZUL_API_URL;
+      const apiKey = process.env.ZOZUL_API_KEY;
+
+      if (!apiUrl || !apiKey) {
+        console.error("Missing required environment variables:");
+        if (!apiUrl) console.error("  ZOZUL_API_URL — base URL of the zozul backend");
+        if (!apiKey) console.error("  ZOZUL_API_KEY — API key for authentication");
+        console.error("\nSet them in .env or export them in your shell.");
+        process.exit(1);
+      }
+
+      const db = getDb(envDbPath());
+      const repo = new SessionRepo(db);
+      const client = new ZozulApiClient({ apiUrl, apiKey });
+
+      if (opts.dryRun) {
+        console.log(`Dry run — checking what would sync to ${apiUrl}...\n`);
+      } else {
+        console.log(`Syncing to ${apiUrl}...\n`);
+      }
+
+      const result = await runSync(repo, client, {
+        verbose: opts.verbose || envVerbose(),
+        dryRun: opts.dryRun,
+      });
+
+      console.log("── Sync Summary ──");
+      const label = opts.dryRun ? "pending" : "synced";
+      for (const [table, counts] of Object.entries(result)) {
+        const status = counts.failed > 0 ? "PARTIAL" : "OK";
+        console.log(`  ${table.padEnd(15)} ${counts.synced} ${label}, ${counts.failed} failed  [${status}]`);
+      }
+
+      const totalFailed = Object.values(result).reduce((s, c) => s + c.failed, 0);
+      if (totalFailed > 0) {
+        console.error(`\n${totalFailed} items failed to sync. Re-run 'zozul sync' to retry.`);
+        db.close();
+        process.exit(1);
+      }
+
+      db.close();
+    });
+
+  // ── Hidden maintenance commands ──
+
+  program
+    .command("ingest", { hidden: true })
+    .description("Re-ingest all Claude Code session files (backfill)")
+    .option("-f, --force", "Re-ingest sessions that already exist in the database")
+    .option("--no-tag", "Skip tagging turns with the active task context")
+    .action(async (opts) => {
+      const db = getDb(envDbPath());
+      const repo = new SessionRepo(db);
+
+      console.log("Scanning for Claude Code session files...");
+      const result = await ingestAllSessions(repo, { force: opts.force, noTag: opts.tag === false });
+      console.log(`Ingested: ${result.ingested}  Skipped: ${result.skipped}`);
+      db.close();
+    });
+
+  program
+    .command("db-clean", { hidden: true })
+    .description("Remove invalid/test rows from the database")
+    .option("--session <id>", "Remove all data for a specific session ID")
+    .action((opts) => {
+      const db = getDb(envDbPath());
+
+      if (opts.session) {
+        const id: string = opts.session;
+        db.transaction(() => {
+          db.prepare(`DELETE FROM task_tags WHERE turn_id IN (SELECT id FROM turns WHERE session_id = ?)`).run(id);
+          for (const table of ["otel_metrics", "otel_events", "hook_events", "tool_uses", "turns"] as const) {
+            db.prepare(`DELETE FROM ${table} WHERE session_id = ?`).run(id);
+          }
+          db.prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
+        })();
+        console.log(`Removed all data for session: ${id}`);
+      } else {
+        const minDate = "2025-01-01";
+        const result = db.prepare(`
+          SELECT COUNT(*) as n FROM otel_metrics WHERE timestamp < ?
+        `).get(minDate) as { n: number };
+        if (result.n === 0) {
+          console.log("Nothing to clean.");
+        } else {
+          db.prepare(`DELETE FROM otel_metrics WHERE timestamp < ?`).run(minDate);
+          db.prepare(`DELETE FROM otel_events  WHERE timestamp < ?`).run(minDate);
+          console.log(`Removed ${result.n} row(s) with timestamps before ${minDate}.`);
+        }
+      }
+
+      db.close();
+    });
+
+  return program;
+}

package/src/cli/format.ts

@@ -0,0 +1,133 @@
+import type { SessionRow, TurnRow } from "../storage/db.js";
+
+export function formatSessionList(sessions: SessionRow[]): string {
+  if (sessions.length === 0) return "No sessions found.";
+
+  const lines: string[] = [];
+  lines.push(
+    pad("SESSION ID", 40) +
+    pad("STARTED", 22) +
+    pad("TURNS", 7) +
+    pad("TOKENS (in/out)", 20) +
+    pad("COST", 10) +
+    "MODEL",
+  );
+  lines.push("─".repeat(120));
+
+  for (const s of sessions) {
+    const started = formatTimestamp(s.started_at);
+    const tokens = `${fmtNum(s.total_input_tokens)}/${fmtNum(s.total_output_tokens)}`;
+    const cost = `$${s.total_cost_usd.toFixed(4)}`;
+    const id = s.id.length > 36 ? s.id.slice(0, 36) + "…" : s.id;
+
+    lines.push(
+      pad(id, 40) +
+      pad(started, 22) +
+      pad(String(s.total_turns), 7) +
+      pad(tokens, 20) +
+      pad(cost, 10) +
+      (s.model ?? "—"),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function formatSessionDetail(session: SessionRow, turns: TurnRow[]): string {
+  const lines: string[] = [];
+
+  lines.push(`Session: ${session.id}`);
+  lines.push(`Project: ${session.project_path ?? "—"}`);
+  lines.push(`Started: ${formatTimestamp(session.started_at)}`);
+  lines.push(`Ended:   ${session.ended_at ? formatTimestamp(session.ended_at) : "—"}`);
+  lines.push(`Model:   ${session.model ?? "—"}`);
+  lines.push("");
+  lines.push("── Token Usage ──");
+  lines.push(`  Input tokens:          ${fmtNum(session.total_input_tokens)}`);
+  lines.push(`  Output tokens:         ${fmtNum(session.total_output_tokens)}`);
+  lines.push(`  Cache read tokens:     ${fmtNum(session.total_cache_read_tokens)}`);
+  lines.push(`  Cache creation tokens: ${fmtNum(session.total_cache_creation_tokens)}`);
+  lines.push(`  Total cost:            $${session.total_cost_usd.toFixed(4)}`);
+  lines.push(`  Total turns:           ${session.total_turns}`);
+  lines.push(`  Total duration:        ${formatDuration(session.total_duration_ms)}`);
+
+  if (turns.length > 0) {
+    lines.push("");
+    lines.push("── Conversation ──");
+
+    for (const turn of turns) {
+      const role = turn.role === "assistant" ? "🤖 Assistant" : "👤 User";
+      lines.push("");
+      lines.push(`[${turn.turn_index}] ${role} (${formatTimestamp(turn.timestamp)})`);
+
+      if (turn.input_tokens > 0 || turn.output_tokens > 0) {
+        lines.push(
+          `    tokens: ${fmtNum(turn.input_tokens)} in / ${fmtNum(turn.output_tokens)} out` +
+          (turn.cost_usd > 0 ? ` | cost: $${turn.cost_usd.toFixed(4)}` : "") +
+          (turn.model ? ` | model: ${turn.model}` : ""),
+        );
+      }
+
+      if (turn.content_text) {
+        const preview = turn.content_text.length > 500
+          ? turn.content_text.slice(0, 500) + "…"
+          : turn.content_text;
+        lines.push(`    ${preview.replace(/\n/g, "\n    ")}`);
+      }
+
+      if (turn.tool_calls) {
+        try {
+          const calls = JSON.parse(turn.tool_calls);
+          for (const call of calls) {
+            lines.push(`    🔧 ${call.toolName}`);
+          }
+        } catch {
+          // skip
+        }
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function formatStats(stats: Record<string, unknown>): string {
+  const lines: string[] = [];
+  lines.push("── Aggregate Statistics ──");
+  lines.push(`  Total sessions:        ${stats.total_sessions ?? 0}`);
+  lines.push(`  Total input tokens:    ${fmtNum(Number(stats.total_input_tokens ?? 0))}`);
+  lines.push(`  Total output tokens:   ${fmtNum(Number(stats.total_output_tokens ?? 0))}`);
+  lines.push(`  Total cache read:      ${fmtNum(Number(stats.total_cache_read_tokens ?? 0))}`);
+  lines.push(`  Total cost:            $${Number(stats.total_cost_usd ?? 0).toFixed(4)}`);
+  lines.push(`  Total turns:           ${stats.total_turns ?? 0}`);
+  lines.push(`  Total active time:     ${formatDuration(Number(stats.total_duration_ms ?? 0))}`);
+  return lines.join("\n");
+}
+
+function pad(str: string, len: number): string {
+  return str.padEnd(len);
+}
+
+function fmtNum(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+function formatTimestamp(ts: string): string {
+  try {
+    return new Date(ts).toLocaleString();
+  } catch {
+    return ts;
+  }
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}

package/src/context/index.ts

@@ -0,0 +1,42 @@
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+
+const CONTEXT_PATH = path.join(os.homedir(), ".zozul", "context.json");
+
+export interface TaskContext {
+  active: string[];
+  set_at: string;
+}
+
+export function getActiveContext(): TaskContext | null {
+  if (!fs.existsSync(CONTEXT_PATH)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(CONTEXT_PATH, "utf-8"));
+    // Support legacy single-string format
+    if (typeof data.active === "string") {
+      return { active: [data.active], set_at: data.set_at ?? "" };
+    }
+    if (Array.isArray(data.active) && data.active.length > 0) {
+      return { active: data.active, set_at: data.set_at ?? "" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function setActiveContext(tasks: string[]): TaskContext {
+  const tags = tasks.map(t => t.trim()).filter(Boolean);
+  if (tags.length === 0) throw new Error("At least one tag is required");
+  const ctx: TaskContext = { active: tags, set_at: new Date().toISOString() };
+  fs.mkdirSync(path.dirname(CONTEXT_PATH), { recursive: true });
+  fs.writeFileSync(CONTEXT_PATH, JSON.stringify(ctx, null, 2) + "\n");
+  return ctx;
+}
+
+export function clearActiveContext(): void {
+  if (fs.existsSync(CONTEXT_PATH)) {
+    fs.unlinkSync(CONTEXT_PATH);
+  }
+}