260119-MIA-CODE--98090899-8aff-4e11-9dc3-8b99466d12b6

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)¹²
  • GitHub Copilot CLI (terminal-native agent with repo context and tasks)³⁴⁵
• 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.⁶¹
• 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²
• 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.)⁷⁴⁸³⁶
  • Research / benchmarks around terminal agents and agentic coding in the terminal (Terminal-Bench, agentic coding surveys, code agent benchmarks).^{9101112131415161718}

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.<sup>2</sup>

```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.<sup>1</sup>
• 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.<sup>1</sup>
• A more agentic / streaming flavor would use --output-format stream-json.<sup>1</sup>

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).<sup>21</sup>

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.<sup>19621</sup>

```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.<sup>2017</sup>
  • 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.<sup>453</sup>
  • 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.<sup>19621</sup>
  • 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.<sup>6</sup>
  • 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.<sup>8</sup>
  • 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.<sup>1518</sup>
  • 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.<sup>2110111213221416179</sup>
  • 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.<sup>23</sup>

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"><sup>242526272829303132333435</sup></span>