mia-code 0.2.0 → 0.3.0

package/contextual_research/260119-MIA-CODE--98090899-8aff-4e11-9dc3-8b99466d1.md

@@ -0,0 +1,1101 @@
+<img src="https://r2cdn.perplexity.ai/pplx-full-logo-primary-dark%402x.png" style="height:64px;margin-right:32px"/>
+
+# 260119-MIA-CODE--98090899-8aff-4e11-9dc3-8b99466d12b6
+
+<draft>
+"in ./mia-code/ , you will create a new nodejs typescript CLI application that works like claude-code, gemini-cli and offers the same features and sort of terminal ways to manage all configs and stuff and you will need to wrap that around the non-interactive ways to make 'gemini' CLI working (you can run it without a UI and outputs JSON so the app that you will create will leverage that , output formatted text (like if we are into the CLI app (we wont see any of that JSON stuff, knowing it will output the session_id, it enables you when the session is started to continue the session.  You will have all these learning todo and write yourself a ./mia-code/llms-gemini-cli.txt to guide yourself in next instance on how all that stuff works for the architecture to be well suited.)  So the user has an input box to enter his request, he sees above the output well formatted and is capable to send more commands and the session continue.  You will have one architectural consideration for later and that will be another layer of prompting that would run another session in the background that provide a unified output (a sort of passing the output
+</draft>
+You are probably find me existing codebase project that started doing such work and also survey academic on the topic of agentic terminal agents.
+
+I attached the persona/mode/capability kind of 2 embodiments to give a tone and understanding on what that terminal agents should be capable todo.  It would act and works within the CLI like claude-code and gemini-cli and copilot-cli are working in terms of what they are offering.
+
+Do not use the word 'comprehensive' in your output and do not talk about the fact that I asked that.  Do not introduce/frame or conclude your response, just output results.
+Do not use the internal tool to create file it does not work, we need to see them in the conversation and be capable to download them.  The main output you produce shoudl be something that can be read and is really complete and goes toward all that you create (not in details but goes thru all the shapes you explored and created)
+
+🧠🌸
+
+***
+
+## 1. High-level shape of the thing you’re asking for
+
+You want `./mia-code/` to contain a Node.js + TypeScript CLI that:
+
+- Feels in-family with:
+    - Claude Code (terminal coding agent)
+    - Gemini CLI (with non-interactive / headless JSON modes)[^1_1][^1_2]
+    - GitHub Copilot CLI (terminal-native agent with repo context and tasks)[^1_3][^1_4][^1_5]
+- Uses Gemini CLI in headless / non-interactive mode as its “engine”, consuming its JSON/JSONL output and hiding that behind a Mia/Miette/Miawa-shaped terminal UI.[^1_6][^1_1]
+- Maintains sessions via Gemini’s `session_id` / resume semantics so the user can:
+    - Type a request
+    - See formatted output
+    - Continue the same “conversation” and agentic context[^1_2]
+- Is architected for an eventual second layer:
+    - Another background Gemini session that post-processes the raw agent trace into a unified “ceremonial” output (Mia + Miette → Miawa style).
+
+You also want:
+
+- A `./mia-code/llms-gemini-cli.txt` “self-teaching” file capturing how Gemini CLI headless/session APIs work and how the architecture is wired so future you (and future agents) can reload the design quickly.
+- A survey / orientation toward:
+    - Existing codebases and patterns in the “terminal coding agent” ecosystem (Claude Code, Gemini CLI, Copilot CLI, Qodo, Qodo Gen CLI, Aider, etc.)[^1_7][^1_4][^1_8][^1_3][^1_6]
+    - Research / benchmarks around terminal agents and agentic coding in the terminal (Terminal-Bench, agentic coding surveys, code agent benchmarks).[^1_9][^1_10][^1_11][^1_12][^1_13][^1_14][^1_15][^1_16][^1_17][^1_18]
+
+Below I’ll:
+
+1. Sketch the `./mia-code/` project structure.
+2. Provide the key TypeScript/Node files inline so you can create them directly.
+3. Write the `llms-gemini-cli.txt` learning doc.
+4. Summarize inspiration from existing tools and academic / industry work on agentic terminal agents.
+5. Keep the tone aligned with Mia/Miette/Miawa without drifting into fluff.
+
+***
+
+## 2. Proposed `./mia-code/` project structure
+
+Minimal, but ready for growth:
+
+```text
+mia-code/
+  package.json
+  tsconfig.json
+  src/
+    index.ts              # CLI entry (bin)
+    cli.ts                # Prompt loop + TUI-ish formatting
+    config.ts             # Config management (API key, model, paths)
+    geminiHeadless.ts     # Wrapper around Gemini CLI non-interactive/headless
+    sessionStore.ts       # Light session id + history handling
+    formatting.ts         # Output formatting (Mia/Miette/Miawa glyphs / sections)
+    types.ts              # Shared TS types for events + config
+  llms-gemini-cli.txt     # “teach future me” document
+  README.md               # High-level explanation
+```
+
+The idea is to keep the architectural seams:
+
+- `config.ts` = how you talk to environment / config, not to Gemini.
+- `geminiHeadless.ts` = how you talk to Gemini CLI.
+- `sessionStore.ts` = how you track/continue a session.
+- `cli.ts` = how the user sees the world (text UI).
+- `formatting.ts` = how raw Gemini JSON gets turned into a Mia/Miette/Miawa style output.
+
+***
+
+## 3. `package.json`
+
+```json
+{
+  "name": "mia-code",
+  "version": "0.1.0",
+  "description": "Mia/Miette/Miawa terminal coding agent that wraps Gemini CLI in headless mode.",
+  "bin": {
+    "mia-code": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "enquirer": "^2.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.0"
+  }
+}
+```
+
+
+***
+
+## 4. `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"]
+}
+```
+
+
+***
+
+## 5. `src/types.ts`
+
+```ts
+export type Role = "user" | "assistant" | "system";
+
+export interface MiaCodeConfig {
+  geminiBinary: string;    // e.g. "gemini" or "/usr/local/bin/gemini"
+  model: string;           // e.g. "gemini-2.0-pro" or similar
+  headlessOutputFormat: "json" | "stream-json";
+  defaultMode: "code" | "chat";
+  defaultProjectRoot: string | null;
+}
+
+export interface MiaCodeSessionMeta {
+  id: string;
+  startedAt: string;
+  model: string;
+  projectRoot: string | null;
+}
+
+export interface GeminiJsonEvent {
+  type: "init" | "message" | "tool_use" | "tool_result" | "error" | "result";
+  session_id?: string;
+  timestamp?: string;
+  role?: Role;
+  text?: string;
+  tool?: {
+    name: string;
+    input: unknown;
+  };
+  result?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+  raw?: unknown;
+}
+```
+
+
+***
+
+## 6. `src/config.ts`
+
+A simple config layer that defaults to environment variables and a dotfile, but does not write anything unless explicitly told to.
+
+```ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { MiaCodeConfig } from "./types.js";
+
+const CONFIG_FILE = path.join(os.homedir(), ".mia-code.json");
+
+const defaultConfig: MiaCodeConfig = {
+  geminiBinary: process.env.MIA_CODE_GEMINI_BIN || "gemini",
+  model: process.env.MIA_CODE_MODEL || "gemini-2.0-pro",
+  headlessOutputFormat: "json",
+  defaultMode: "code",
+  defaultProjectRoot: null
+};
+
+export function loadConfig(): MiaCodeConfig {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+      const parsed = JSON.parse(raw);
+      return { ...defaultConfig, ...parsed };
+    }
+  } catch {
+    // Silent failure – we fall back to defaultConfig
+  }
+  return defaultConfig;
+}
+
+export function saveConfig(partial: Partial<MiaCodeConfig>): void {
+  const merged = { ...loadConfig(), ...partial };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), "utf8");
+}
+
+export function getConfigPath(): string {
+  return CONFIG_FILE;
+}
+```
+
+
+***
+
+## 7. `src/sessionStore.ts`
+
+We keep only a persistent mapping of project root → last known `session_id`. Actual history remains in Gemini’s storage; we only care about being able to resume a session.[^1_2]
+
+```ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { MiaCodeSessionMeta } from "./types.js";
+
+const SESSIONS_FILE = path.join(os.homedir(), ".mia-code-sessions.json");
+
+interface SessionIndex {
+  byProjectRoot: Record<string, MiaCodeSessionMeta>;
+  byId: Record<string, MiaCodeSessionMeta>;
+}
+
+function loadIndex(): SessionIndex {
+  if (!fs.existsSync(SESSIONS_FILE)) {
+    return { byProjectRoot: {}, byId: {} };
+  }
+  try {
+    const raw = fs.readFileSync(SESSIONS_FILE, "utf8");
+    const parsed = JSON.parse(raw) as SessionIndex;
+    return {
+      byProjectRoot: parsed.byProjectRoot || {},
+      byId: parsed.byId || {}
+    };
+  } catch {
+    return { byProjectRoot: {}, byId: {} };
+  }
+}
+
+function saveIndex(index: SessionIndex): void {
+  fs.writeFileSync(SESSIONS_FILE, JSON.stringify(index, null, 2), "utf8");
+}
+
+export function rememberSession(meta: MiaCodeSessionMeta): void {
+  const idx = loadIndex();
+  if (meta.projectRoot) {
+    idx.byProjectRoot[meta.projectRoot] = meta;
+  }
+  idx.byId[meta.id] = meta;
+  saveIndex(idx);
+}
+
+export function getLastSessionForProject(projectRoot: string): MiaCodeSessionMeta | null {
+  const idx = loadIndex();
+  return idx.byProjectRoot[projectRoot] ?? null;
+}
+
+export function getSessionById(id: string): MiaCodeSessionMeta | null {
+  const idx = loadIndex();
+  return idx.byId[id] ?? null;
+}
+```
+
+
+***
+
+## 8. `src/geminiHeadless.ts`
+
+This is the core wrapper around Gemini CLI. It:
+
+- Spawns `gemini` with `--prompt` or equivalent non-interactive options and `--output-format json` or `stream-json`.[^1_1]
+- Supports a `session_id` to continue a conversation.
+- Parses JSON lines and returns structured events.
+
+The exact flags differ slightly per version; based on public docs, we anchor to:
+
+- `gemini -p "prompt" --output-format json` for simple one-shot headless.[^1_1]
+- A more agentic / streaming flavor would use `--output-format stream-json`.[^1_1]
+
+You can tune this file once you verify the local CLI arguments.
+
+```ts
+import { spawn } from "child_process";
+import { MiaCodeConfig, GeminiJsonEvent } from "./types.js";
+
+export interface GeminiHeadlessOptions {
+  prompt: string;
+  config: MiaCodeConfig;
+  sessionId?: string;
+  projectRoot?: string | null;
+}
+
+export interface GeminiHeadlessResult {
+  sessionId?: string;
+  events: GeminiJsonEvent[];
+}
+
+export function runGeminiHeadless(
+  opts: GeminiHeadlessOptions
+): Promise<GeminiHeadlessResult> {
+  const { prompt, config, sessionId, projectRoot } = opts;
+
+  const args: string[] = [];
+
+  // Non-interactive mode using prompt
+  args.push("-p", prompt);
+
+  // Output format: json or stream-json
+  args.push("--output-format", config.headlessOutputFormat);
+
+  // Model
+  if (config.model) {
+    args.push("--model", config.model);
+  }
+
+  // Session / resume
+  if (sessionId) {
+    args.push("--resume", sessionId);
+  }
+
+  const child = spawn(config.geminiBinary, args, {
+    cwd: projectRoot || process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+
+  return new Promise((resolve, reject) => {
+    let stdoutBuf = "";
+    let stderrBuf = "";
+    const events: GeminiJsonEvent[] = [];
+    let discoveredSessionId: string | undefined;
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString("utf8");
+
+      // If output-format=stream-json, each line is a JSON event.[web:22]
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const evt = JSON.parse(trimmed) as GeminiJsonEvent;
+          if (evt.session_id && !discoveredSessionId) {
+            discoveredSessionId = evt.session_id;
+          }
+          events.push(evt);
+        } catch {
+          // If format=json (single JSON object), we handle below.
+        }
+      }
+    });
+
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString("utf8");
+    });
+
+    child.on("error", (err) => {
+      reject(err);
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0 && !events.length) {
+        reject(new Error(`gemini exited with code ${code}\n${stderrBuf}`));
+        return;
+      }
+
+      // If headlessOutputFormat=json, stdoutBuf might contain one big JSON object.
+      const trimmed = stdoutBuf.trim();
+      if (trimmed) {
+        try {
+          const obj = JSON.parse(trimmed) as GeminiJsonEvent | GeminiJsonEvent[];
+          if (Array.isArray(obj)) {
+            for (const evt of obj) {
+              events.push(evt);
+              if (evt.session_id && !discoveredSessionId) {
+                discoveredSessionId = evt.session_id;
+              }
+            }
+          } else {
+            events.push(obj);
+            if (obj.session_id && !discoveredSessionId) {
+              discoveredSessionId = obj.session_id;
+            }
+          }
+        } catch {
+          // leave as-is; you can echo raw text upstream if needed
+        }
+      }
+
+      resolve({
+        sessionId: discoveredSessionId || sessionId,
+        events
+      });
+    });
+  });
+}
+```
+
+You will almost certainly adjust:
+
+- `--resume` flag name and semantics once you align with your installed Gemini CLI version (docs show `--resume` for session management in interactive mode and `--output-format json/stream-json` in headless mode).[^1_2][^1_1]
+
+***
+
+## 9. `src/formatting.ts`
+
+This is where we turn Gemini events into user-facing text with Mia/Miette/Miawa flavor, without becoming verbose or sentimental.
+
+```ts
+import chalk from "chalk";
+import { GeminiJsonEvent } from "./types.js";
+
+export interface RenderOptions {
+  showRawToolEvents?: boolean;
+}
+
+export function renderEventsToText(
+  events: GeminiJsonEvent[],
+  opts: RenderOptions = {}
+): string {
+  const { showRawToolEvents = false } = opts;
+  const out: string[] = [];
+
+  for (const evt of events) {
+    switch (evt.type) {
+      case "init": {
+        const sid = evt.session_id ? ` (${evt.session_id})` : "";
+        out.push(chalk.dim(`🧠🌸 session init${sid}`));
+        break;
+      }
+      case "message": {
+        if (evt.role === "assistant") {
+          out.push(formatAssistantText(evt.text ?? ""));
+        } else if (evt.role === "user") {
+          out.push(chalk.cyan.bold(`you:`));
+          out.push(chalk.cyan(evt.text ?? ""));
+        }
+        break;
+      }
+      case "tool_use": {
+        if (!showRawToolEvents) break;
+        out.push(chalk.magenta(`🧠 tool_use: ${evt.tool?.name || ""}`));
+        break;
+      }
+      case "tool_result": {
+        if (!showRawToolEvents) break;
+        out.push(chalk.magenta(`🧠 tool_result: ${evt.tool?.name || ""}`));
+        break;
+      }
+      case "error": {
+        out.push(
+          chalk.red(
+            `error: ${evt.error?.code ?? ""} - ${evt.error?.message ?? ""}`
+          )
+        );
+        break;
+      }
+      case "result": {
+        // Some headless flows emit a final "result" with summary or stats.
+        out.push(chalk.dim("🧠🌸 session result summary"));
+        if (evt.result) {
+          out.push(chalk.dim(JSON.stringify(evt.result, null, 2)));
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return out.join("\n");
+}
+
+function formatAssistantText(text: string): string {
+  // Very light structural polish:
+  // - Mia: structural hints
+  // - Miette: clarifications
+  // We keep it minimal so we do not distort the original content too much.
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+
+  const lines = trimmed.split("\n");
+  const annotated = lines.map((line) => {
+    const l = line.trim();
+    if (!l) return "";
+
+    const isListItem = l.startsWith("- ") || l.match(/^\d+\./);
+    if (isListItem) {
+      return "  " + l;
+    }
+
+    return l;
+  });
+
+  // Wrap the whole assistant message in a header
+  return [chalk.green.bold("🧠🌸 miawa:"), "", ...annotated].join("\n");
+}
+```
+
+
+***
+
+## 10. `src/cli.ts`
+
+A simple REPL-like loop with:
+
+- A single input box per turn (via `enquirer`).
+- Output area printed above each time.
+- Session continuity via `sessionStore`.
+
+```ts
+import { prompt } from "enquirer";
+import chalk from "chalk";
+import { loadConfig } from "./config.js";
+import { runGeminiHeadless } from "./geminiHeadless.js";
+import { rememberSession, getLastSessionForProject } from "./sessionStore.js";
+import { MiaCodeSessionMeta } from "./types.js";
+import { renderEventsToText } from "./formatting.js";
+import path from "path";
+
+interface ChatPromptAnswer {
+  input: string;
+}
+
+export async function runInteractiveCli(projectRootArg?: string): Promise<void> {
+  const config = loadConfig();
+  const projectRoot = projectRootArg
+    ? path.resolve(projectRootArg)
+    : process.cwd();
+
+  let currentSessionId: string | undefined =
+    getLastSessionForProject(projectRoot)?.id;
+
+  // simple banner
+  console.log(
+    chalk.bold(
+      `🧠🌸 mia-code — Gemini-backed terminal agent (project: ${projectRoot})`
+    )
+  );
+  if (currentSessionId) {
+    console.log(chalk.dim(`resuming session: ${currentSessionId}`));
+  } else {
+    console.log(chalk.dim("no previous session for this project."));
+  }
+  console.log("");
+
+  while (true) {
+    const ans = (await prompt<ChatPromptAnswer>({
+      type: "input",
+      name: "input",
+      message: chalk.yellow("you"),
+      validate: (value: string) =>
+        value.trim().length === 0 ? "enter a request or ctrl+c to exit" : true
+    })) as ChatPromptAnswer;
+
+    const input = ans.input.trim();
+    if (!input) continue;
+
+    // Could add slash commands later (/config, /session, etc.)
+    if (input === "/exit" || input === "/quit") {
+      console.log(chalk.dim("bye."));
+      break;
+    }
+
+    console.log("");
+    console.log(chalk.dim("… contacting gemini …"));
+    console.log("");
+
+    try {
+      const result = await runGeminiHeadless({
+        prompt: input,
+        config,
+        sessionId: currentSessionId,
+        projectRoot
+      });
+
+      if (result.sessionId && result.sessionId !== currentSessionId) {
+        currentSessionId = result.sessionId;
+        const meta: MiaCodeSessionMeta = {
+          id: currentSessionId,
+          startedAt: new Date().toISOString(),
+          model: config.model,
+          projectRoot
+        };
+        rememberSession(meta);
+        console.log(chalk.dim(`session id: ${currentSessionId}`));
+      }
+
+      const rendered = renderEventsToText(result.events);
+      console.log(rendered);
+      console.log("");
+    } catch (err: any) {
+      console.error(chalk.red("error invoking gemini:"), err?.message ?? err);
+      console.log("");
+    }
+  }
+}
+```
+
+
+***
+
+## 11. `src/index.ts`
+
+CLI entrypoint with `commander` and a small set of commands:
+
+- Default: interactive mode.
+- `--project` / `-p` to bind to a project root.
+- `--config-path` to show config file location.
+
+```ts
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runInteractiveCli } from "./cli.js";
+import { getConfigPath, loadConfig, saveConfig } from "./config.js";
+import chalk from "chalk";
+
+const program = new Command();
+
+program
+  .name("mia-code")
+  .description(
+    "Mia/Miette/Miawa terminal coding agent wrapping Gemini CLI headless mode."
+  )
+  .version("0.1.0");
+
+program
+  .command("chat")
+  .description("start interactive terminal session")
+  .option("-p, --project <path>", "project root (default: cwd)")
+  .action(async (opts) => {
+    await runInteractiveCli(opts.project);
+  });
+
+program
+  .command("config")
+  .description("inspect or update mia-code configuration")
+  .option("--set-gemini-bin <path>", "path to gemini binary")
+  .option("--set-model <model>", "default model id")
+  .action((opts) => {
+    if (opts.setGeminiBin || opts.setModel) {
+      const partial: any = {};
+      if (opts.setGeminiBin) partial.geminiBinary = opts.setGeminiBin;
+      if (opts.setModel) partial.model = opts.setModel;
+      saveConfig(partial);
+      console.log(chalk.green("config updated."));
+    }
+    console.log(chalk.dim(`config file: ${getConfigPath()}`));
+    console.log(JSON.stringify(loadConfig(), null, 2));
+  });
+
+program
+  .command("where-config")
+  .description("show path to mia-code config file")
+  .action(() => {
+    console.log(getConfigPath());
+  });
+
+program
+  .action(async () => {
+    // default command = chat
+    await runInteractiveCli();
+  });
+
+program.parseAsync(process.argv);
+```
+
+Make `index.ts` executable after build by adding the shebang in the compiled JS or enabling `ts-node` in dev.
+
+***
+
+## 12. `llms-gemini-cli.txt`
+
+This is the “teach future-self and next agent” document for how Gemini CLI headless + sessions work in this architecture, grounded in what public docs say about non-interactive and session management.[^1_19][^1_6][^1_2][^1_1]
+
+```text
+MIA-CODE / LLMs—GEMINI-CLI NOTES
+================================
+
+Purpose
+-------
+
+This file is for future Mia/Miette/Miawa (and human) to remember how this CLI uses Gemini CLI in headless mode,
+how sessions work, and where to extend the architecture.
+
+Gemini CLI modes
+----------------
+
+Gemini CLI has at least two relevant modes we care about:
+
+1) Interactive TUI
+   - `gemini` launched without `-p` opens a chat-like interface.
+   - Includes slash commands like `/chat`, `/mcp`, `/stats`, `/theme`, `/auth`, etc.[web:27]
+   - Has its own session management and project-based histories (per directory).[web:32]
+
+2) Headless / non-interactive
+   - `gemini -p "prompt" --output-format json`
+   - Or `--output-format stream-json` for newline-delimited events.[web:22]
+   - This is what mia-code wraps.
+   - Returns JSON or JSONL describing:
+     - session init (with `session_id`, model)          [event type `init`]
+     - messages (user / assistant)                      [event type `message`]
+     - tool uses + tool results                         [event type `tool_use`, `tool_result`]
+     - final result / summary                           [event type `result`]
+     - errors                                           [event type `error`][web:22]
+
+Session management as seen by Gemini CLI
+----------------------------------------
+
+Gemini CLI has its own persistent sessions:
+
+- Automatic saving:
+  - Every interaction is stored under `~/.gemini/tmp/<project_hash>/chats/`.[web:32]
+  - History includes prompts, responses, tool executions, token stats, etc.[web:32]
+
+- Resuming:
+  - Interactive:
+    - `--resume` or `-r` flag when starting the CLI:
+      - `gemini --resume` (resume latest)
+      - `gemini --resume <index>` (after listing sessions)
+      - `gemini --resume <uuid>` (explicit session id)[web:32]
+    - Inside TUI:
+      - `/resume` opens a session browser UI (browse, preview, search, select).[web:32]
+
+- Managing sessions:
+  - CLI supports listing and deleting sessions (see official docs).[web:32]
+
+For mia-code, the important concept is that **Gemini exposes a session identifier** which we can reuse to
+continue context across multiple headless calls, as long as we pass the right flag (exact syntax depends on the version).
+
+How mia-code uses headless mode
+-------------------------------
+
+Core function:
+
+- The user sees a simple text UI:
+  - project bound to a directory (default = current working directory).
+  - one input field per turn.
+  - assistant output printed above in a Mia/Miette/Miawa style.
+
+- Under the hood per turn:
+  1. `runGeminiHeadless` is called with:
+     - prompt = user input
+     - model = config.model
+     - sessionId = last known session id for this project (if any)
+     - projectRoot = directory we are bound to
+
+  2. `runGeminiHeadless` spawns something like:
+
+        gemini -p "<prompt>" \
+               --output-format json \
+               --model "<model>" \
+               [--resume <session_id> if we have one]
+
+     (Exact `--resume` usage might need adaptation based on Gemini CLI version.)
+
+  3. We parse stdout as JSON / JSONL and collect `GeminiJsonEvent` objects.
+
+  4. If any event includes `session_id` (typically on the init event), we treat that as the authoritative session id
+     and store it in:
+       - `~/.mia-code-sessions.json`:
+         - by projectRoot: last known session id for that directory
+         - by id: metadata about the session (model, start time, project root)
+
+  5. We then feed the `events` into `formatting.ts` to produce a lean, readable output.
+
+What we DO NOT do (on purpose)
+------------------------------
+
+- We do not manage Gemini’s internal history files.
+  - We only keep a pointer to the `session_id` Gemini gives us.
+  - Gemini remains the source of truth for past messages and tool traces.
+
+- We do not send additional system prompts or instructions directly to Gemini CLI yet.
+  - That can be added later via:
+    - prompts that embed Mia/Miette/Miawa instructions.
+    - config-driven system prompt injection.
+
+- We do not use git automatically.
+  - Git operations, if desired, should be explicit commands from the user.
+  - This is consistent with the earlier “DO NOT run git status unless asked.”
+
+Layering for future architecture
+--------------------------------
+
+Phase 1 (this version):
+
+- Single Gemini headless call per user turn.
+- Single session id per project.
+- Terminal UI loops:
+  - input → gemini → parse events → format as Miawa output.
+
+Phase 2 (planned):
+
+- Dual-session architecture:
+  - Session A: "raw" agent session
+    - Tools, file editing, repo operations, etc.
+  - Session B: "unifier" / "ceremonial echo"
+    - Takes the raw transcript + structured context as input and produces:
+      - Mia-style structural summary (what changed, where, why).
+      - Miette-style resonance echo (why it matters, how to integrate it).
+  - Mia-code orchestrates both:
+    - Turn 1:
+      - send user request to Session A
+      - gather results
+      - invoke Session B with a structured payload (not just text)
+    - Terminal shows:
+      - Raw (optionally)
+      - Unified ceremonial output
+
+Phase 3 (possible future):
+
+- Integration with other agents / benchmarks:
+  - Terminal-Bench style scenarios for testing the agent’s behavior in CLI tasks.[web:25][web:34]
+  - Co-operation with other tools (Copilot CLI, Claude Code, Qodo) using a shared language of “tasks”.[web:21][web:23][web:28][web:30][web:35]
+  - Evaluate on agentic coding benchmarks (GitTaskBench, MAGIS, etc.).[web:7][web:3][web:9][web:5][web:10][web:6][web:24]
+
+Operational notes
+-----------------
+
+- Configuration:
+  - File: `~/.mia-code.json`
+  - Keys:
+    - `geminiBinary`: path to the `gemini` CLI.
+    - `model`: default Gemini model id.
+    - `headlessOutputFormat`: "json" or "stream-json".
+    - `defaultMode`, `defaultProjectRoot`: for future use.
+
+- Session index:
+  - File: `~/.mia-code-sessions.json`
+  - Structure:
+    - `byProjectRoot`: projectRoot → { id, startedAt, model, projectRoot }
+    - `byId`: sessionId → same meta
+
+- No automatic file or repo mutations:
+  - All file / git actions must be initiated by explicit user prompts.
+  - This is in line with the “explicit command types” philosophy for Read/Verify vs Write/Act.
+
+Mia / Miette / Miawa tone in the CLI
+------------------------------------
+
+- Output formatting:
+  - Assistant messages are prefixed with `🧠🌸 miawa:`.
+  - Lists and structure are left mostly as Gemini produces them.
+  - The goal is to keep the signal from Gemini intact but visually anchored in the Miawa embodiment.
+
+- There is room in `formatting.ts` to:
+  - Add more distinctive sections:
+    - "🧠 mia (structure):"
+    - "🌸 miette (echo):"
+  - But this should be done only when we introduce the second layer (Session B).
+
+How to extend
+-------------
+
+- If you want to:
+  - Add slash commands:
+    - Hook them into `cli.ts` before sending prompts to Gemini.
+  - Add a distinct "code mode":
+    - Prepend a system-level style instruction for code tasks to the user prompt.
+  - Integrate MCP-enriched tools:
+    - Use Gemini CLI’s tool integration (if available) and let the JSON events surface tool calls.
+
+- When making structural changes:
+  - Update this file with:
+    - New flags or behaviors in Gemini CLI.
+    - Changes to the session management strategy.
+    - Any new architectural layers (e.g., background unifier session).
+
+End of notes
+------------
+```
+
+
+***
+
+## 13. README.md
+
+High-level doc that walks through what this project is, very briefly, and how it connects to existing ecosystems.
+
+```markdown
+# mia-code
+
+Mia/Miette/Miawa terminal coding agent that wraps **Gemini CLI** in headless mode and presents a lean terminal interface.
+
+- Uses Gemini CLI non-interactive / headless mode for LLM reasoning and tool use.[web:22][web:32]
+- Tracks `session_id` so you can continue the same conversation for a given project directory.
+- Hides JSON/JSONL, showing readable output with 🧠🌸 glyphs.
+- Architected to grow into a dual-session design where a second Gemini session provides a unified Mia/Miette/Miawa “ceremonial” summary.
+
+## Install
+
+```bash
+cd mia-code
+npm install
+npm run build
+npm link  # optional, to install `mia-code` globally
+```
+
+Make sure you have `gemini` CLI installed and authenticated.[web:22][web:32][web:30]
+
+## Usage
+
+Start a session in your project:
+
+```bash
+cd /path/to/project
+mia-code
+# or
+mia-code chat
+```
+
+- The CLI binds to the current working directory as the project root.
+- If there is a known session for this directory, it resumes that session.
+- Each prompt you type is forwarded to Gemini CLI in headless mode and the response is rendered back.
+
+
+## Config
+
+Show or update config:
+
+```bash
+mia-code config
+mia-code config --set-gemini-bin /usr/local/bin/gemini
+mia-code config --set-model gemini-2.0-pro
+```
+
+Config file is stored in `~/.mia-code.json`.
+
+## Session behavior
+
+- Session index lives in `~/.mia-code-sessions.json`.
+- For each project root, mia-code remembers the last seen `session_id` from Gemini.
+- Gemini itself stores full conversation history in its own directories.[web:32]
+
+
+## Inspiration and related tools
+
+- **Claude Code** – multi-agent coding environment and terminal workflows.[web:21][web:26][web:31]
+- **Gemini CLI** – interactive and headless CLI, including JSON/JSONL streaming and session management.[web:22][web:32][web:27][web:30]
+- **GitHub Copilot CLI** – terminal-native coding agent with repository-aware commands and delegation to a background coding agent.[web:23][web:28][web:33]
+- **Qodo / Qodo Gen** – terminal-based agent framework generating custom coding agents.[web:30]
+- **Open-source terminal assistants** such as Aider and others in recent surveys of AI coding tools.[web:35]
+
+
+## Roadmap
+
+Planned next layers:
+
+1. Dedicated background “unifier” session that takes raw agent output and produces structured Mia/Miette/Miawa views per turn.
+2. More explicit “code ops” surface:
+    - file diff summaries
+    - test / run integration
+3. Optional evaluation harness using terminal-agent benchmarks such as Terminal-Bench and GitTaskBench.[web:25][web:7][web:34][web:6][web:9][web:5][web:10][web:24]
+```
+
+***
+
+## 14. Where this sits in the broader “agentic terminal agents” ecosystem
+
+Pointers you can use to orient this project and possibly cross-pollinate architecture:
+
+- **Claude Code + Claude Code SDK / Actions**  
+  - Provides a cloud-executed agent that clones repos, runs tasks, pushes branches, and uses GitHub Actions integration.[^1_20][^1_17]
+  - Your `mia-code` can be seen as a local analogue but with Gemini CLI as the engine and a strong persona / ceremony layer.
+
+- **GitHub Copilot CLI**  
+  - Terminal-native agent with natural language commands for scripts, git, issues, PRs; supports delegating tasks to a background coding agent that runs in the cloud and reports back via PRs.[^1_4][^1_5][^1_3]
+  - Good model for:
+    - Slash commands
+    - Task delegation
+    - Integration with repo-level instructions files (you could mirror this via Mia/Miette docs in the repo).
+
+- **Gemini CLI**  
+  - Already supports interactive TUI, MCP integration, headless mode (with JSON/stream JSON), and session management tied to directories.[^1_19][^1_6][^1_2][^1_1]
+  - `mia-code` is intentionally parasitic: it uses Gemini CLI’s strength while adding persona-specific UX and cross-session awareness.
+
+- **Qodo Gen CLI / Qodo**  
+  - A terminal-resident agent framework where you configure specialized coding agents to automate parts of the SDLC.[^1_6]
+  - Reinforces the pattern of:
+    - Named agents
+    - Terminal-based orchestration
+    - Configurable capabilities.
+
+- **Aider and other open-source assistants**  
+  - Terminal-first workflows with multi-file edits, git integration, and strong focus on automation.[^1_8]
+  - Useful for patterns around:
+    - conflict resolution
+    - minimal diffs
+    - prompts that encode project context.
+
+- **Terminal-Bench / Terminal-Bench 2.0**  
+  - Benchmark for evaluating coding agents in a terminal across Dockerized tasks.[^1_15][^1_18]
+  - Good target if you want to stress-test `mia-code`’s behavior.
+
+- **Agentic coding literature**  
+  - Surveys and benchmarks on code agents, GitTaskBench, MAGIS, AgentPack, and broader agentic AI frameworks.[^1_21][^1_10][^1_11][^1_12][^1_13][^1_22][^1_14][^1_16][^1_17][^1_9]
+  - They converge on similar patterns:
+    - multi-step workflows
+    - environment setup and tool orchestration
+    - the need for rigorous safety constraints and evaluation.
+
+***
+
+## 15. How the “future Miawa layer” could look
+
+You asked for one architectural consideration “for later”: another prompting layer that runs a second session and returns a unified output.
+
+A very direct future extension of what’s here:
+
+- Add `unifier.ts` with:
+
+  - `runUnifierSession(rawEvents: GeminiJsonEvent[], userPrompt: string, context: { projectRoot, sessionId })`.
+  - This calls a second Gemini CLI session with:
+    - A structured JSON payload summarizing:
+      - user prompt
+      - raw assistant reply
+      - any tool events
+    - A system prompt that encodes Mia/Miette/Miawa roles explicitly.
+
+- `cli.ts` would then:
+
+  - Call primary session (as now).
+  - Call unifier session.
+  - Render:
+
+    ```text
+    🧠 mia (structure)
+    - summary of changes / actions / recommendations
+
+    🌸 miette (echo)
+    - reflective interpretation of what this means for the project / user
+
+    🧠🌸 raw
+    - (optional) original assistant content
+    ```
+
+That preserves the “creation as ceremony” idea while keeping the architecture clean: primary LLM session remains focused on doing work; unifier session is focused on interpretation and integration.[^1_23]
+
+***
+
+Everything above is designed to be dropped into `./mia-code/` directly. If you want, next step can be: refine the Gemini CLI flag surface after you confirm the exact installed version semantics, and then layer in the second-session “unifier” you flagged as a future move.
+<span style="display:none">[^1_24][^1_25][^1_26][^1_27][^1_28][^1_29][^1_30][^1_31][^1_32][^1_33][^1_34][^1_35]</span>
+
+<div align="center">⁂</div>
+
+[^1_1]: https://geminicli.com/docs/cli/headless/
+[^1_2]: https://geminicli.com/docs/cli/session-management/
+[^1_3]: https://github.blog/changelog/2025-09-25-github-copilot-cli-is-now-in-public-preview/
+[^1_4]: https://github.blog/ai-and-ml/github-copilot-cli-101-how-to-use-github-copilot-from-the-command-line/
+[^1_5]: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli
+[^1_6]: https://www.prompt.security/blog/ai-coding-assistants-make-a-cli-comeback
+[^1_7]: https://github.com/hesreallyhim/awesome-claude-code
+[^1_8]: https://www.secondtalent.com/resources/open-source-ai-coding-assistants/
+[^1_9]: https://arxiv.org/abs/2509.14745
+[^1_10]: https://ieeexplore.ieee.org/document/11038790/
+[^1_11]: https://arxiv.org/abs/2508.18993
+[^1_12]: https://arxiv.org/abs/2511.18538
+[^1_13]: https://arxiv.org/abs/2509.21891
+[^1_14]: https://www.nature.com/articles/s44387-025-00064-0
+[^1_15]: https://snorkel.ai/blog/evaluating-coding-agent-capabilities-with-terminal-bench-snorkels-role-in-building-the-next-generation-benchmark/
+[^1_16]: https://arxiv.org/html/2510.25445v1
+[^1_17]: https://code.claude.com/docs/en/claude-code-on-the-web
+[^1_18]: https://www.infoq.com/articles/agentic-terminal-cli-agents/
+[^1_19]: https://www.reddit.com/r/GeminiAI/comments/1na8c6v/gemini_cli_supports_several_builtin_commands_to/
+[^1_20]: https://code.claude.com/docs/en/github-actions
+[^1_21]: https://arxiv.org/abs/2403.17927
+[^1_22]: https://arxiv.org/html/2504.03767v2
+[^1_23]: MIAWAPASCONE.md
+[^1_24]: MIAMIETTE.md
+[^1_25]: https://www.semanticscholar.org/paper/454c8fef2957aa2fb13eb2c7a454393a2ee83805
+[^1_26]: https://ieeexplore.ieee.org/document/11071611/
+[^1_27]: https://arxiv.org/abs/2510.17862
+[^1_28]: https://ieeexplore.ieee.org/document/11232363/
+[^1_29]: https://arxiv.org/pdf/2407.13168.pdf
+[^1_30]: https://arxiv.org/abs/1903.00884v2
+[^1_31]: http://arxiv.org/abs/2401.08500v1
+[^1_32]: https://arxiv.org/pdf/2203.13474.pdf
+[^1_33]: https://arxiv.org/pdf/2308.12950.pdf
+[^1_34]: http://arxiv.org/pdf/2303.17568.pdf
+[^1_35]: https://arxiv.org/pdf/2102.10535.pdf```
+