mia-code

🧠🌸 Mia/Miette/Miawa terminal coding agent that wraps Gemini CLI in headless mode.

Features

• Dual-Session Architecture: Every interaction passes through two layers:
  • Primary agent performs work (code, analysis, tools)
  • Unifier interprets results as 🧠 Mia (structure) + 🌸 Miette (echo)
• Multi-Engine Support: Choose between Gemini (default) or Claude for primary agent
• Session tracking per project directory for conversation continuity
• Clean, ceremonial output format (use --raw for original agent output)
• Simple readline-based interface
• YOLO mode for auto-approving actions

Engine Selection

# Use Gemini (default)
mia-code chat

# Use Claude
mia-code chat --claude

# Set default engine
export MIA_CODE_ENGINE=claude
mia-code chat

# Configure via config file
mia-code config --set-engine claude

Note: The unifier always uses Claude because it requires --system-prompt support.

Prerequisites

• Node.js 18+
• Gemini CLI installed and authenticated (gemini --version)

Install

cd mia-code
npm install
npm run build
npm link  # optional, to install `mia-code` globally

Usage

Interactive Mode (default)

# Start a session in current directory
mia-code

# Or explicitly
mia-code chat

# With options
mia-code chat --project /path/to/project
mia-code chat --yolo    # Auto-approve all actions
mia-code chat --raw     # Skip unifier, show raw agent output
mia-code chat --resume <session-id>

Default output (ceremonial, dual-perspective):

you> create a function to reverse a string

🧠 mia (structure)
Created TypeScript function `reverseString()` in `src/utils.ts`. 
Accepts string parameter, returns reversed result via split-reverse-join pattern.

🌸 miette (echo)
A foundational transformation—immutable input, new output. 
This pattern unlocks composable data flows.

Raw output (with --raw flag):

you> create a function to reverse a string

🧠🌸 miawa:

I've created a new file `src/utils.ts` with the following...
[standard agent output]

Single Prompt Mode

mia-code prompt "explain this codebase"
mia-code prompt "refactor the main function" --yolo
mia-code prompt "list all TypeScript files" --raw  # Skip unifier

Slash Commands (in interactive mode)

/help     - Show available commands
/session  - Show current session info
/sessions - List all saved sessions
/clear    - Clear saved sessions
/config   - Show configuration
/exit     - Exit the CLI

Configuration

View or update config:

mia-code config
mia-code config --set-model gemini-2.5-pro
mia-code config --set-gemini-bin /usr/local/bin/gemini
mia-code config --set-yolo true

Config file: ~/.mia-code.json

Config Options

| Key | Default | Description | |-----|---------|-------------| | engine | gemini | Primary agent engine (gemini or claude) | | geminiBinary | gemini | Path to gemini CLI binary | | claudeBinary | claude | Path to claude CLI binary | | model | gemini-2.5-pro | Default model to use | | headlessOutputFormat | stream-json | JSON output format | | yoloMode | false | Auto-approve all actions |

Environment Variables

• MIA_CODE_ENGINE: Default engine (gemini or claude)
• MIA_CODE_GEMINI_BIN: Path to gemini binary
• MIA_CODE_CLAUDE_BIN: Path to claude binary
• MIA_CODE_MODEL: Default model name

Session Behavior

• Sessions are stored per project directory
• On first prompt, a new session is created and its ID is saved
• Subsequent prompts in the same directory continue the session
• Use --resume <id> to explicitly resume a specific session
• Sessions are managed by Gemini CLI internally; mia-code only tracks IDs

Development

# Run in dev mode
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

Architecture

Current Phase: Phase 2 - Dual-Session Architecture (see PHASE_2.md)

Flow:

User Prompt
  ↓
Primary Agent Session → tools, code, analysis
  ↓
Unifier Session → interprets essence
  ↓
🧠 Mia (structure) + 🌸 Miette (echo)

mia-code/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── cli.ts            # Interactive prompt loop
│   ├── config.ts         # Configuration management
│   ├── sessionStore.ts   # Session persistence
│   ├── geminiHeadless.ts # Gemini CLI wrapper (primary agent)
│   ├── unifier.ts        # Ceremonial interpretation layer
│   ├── formatting.ts     # Output formatting
│   └── types.ts          # TypeScript types
├── PHASE_2.md            # Dual-session architecture docs
├── llms-gemini-cli.txt   # Self-documentation for agents
├── package.json
└── tsconfig.json

Future Plans

1. ~~Dual-session architecture: Background session for unified Mia/Miette/Miawa summaries~~ ✅ Completed (Phase 2)
2. Streaming unifier output: Currently buffered, could stream interpretations
3. MCP tool integration: Enhanced tool display and interaction
4. Multi-agent coordination: Work with Claude Code, Copilot CLI
5. Narrative arc tracking: Store unifier outputs for long-term pattern recognition

License

MIT