# AGENTS.md — miii-cli

Instructions for AI agents (Claude Code, Codex, Gemini CLI, Cursor, etc.) working on this repo.

## What this repo is

miii is a local-first autonomous coding agent CLI — like Claude Code but runs on Ollama by default. No cloud required. Source stays on the user's machine.

Key guarantee: the system prompt that governs Miii's behavior lives in `src/prompts/SYSTEM_PROMPT.md`. To change how Miii reasons, edits, or communicates — edit that file, not TypeScript.

## Architecture map

```
src/index.ts              entry point — mounts Ink TUI
src/tui/InputBar.tsx      root Ink component
src/tui/hooks/
  useSubmit.ts            slash command dispatch + message routing
  useRunLoop.ts           agentic loop — LLM → parse → permission → tool → loop
  useSession.ts           session/history/memory management
src/llm/stream.ts         provider-agnostic streaming (Ollama / Anthropic / OpenAI-compat)
src/parser/stream-parser.ts  splits narration text from <tool_call> blocks
src/prompts/
  SYSTEM_PROMPT.md    ← system prompt source of truth (edit this to tune behavior)
  system.ts               reads SYSTEM_PROMPT.md, injects {{TOOL_DOCS}} at runtime
src/tools/index.ts        all built-in tools (read_file, edit_file, run_command, etc.)
src/checkpoints/store.ts  pre-edit snapshots + Esc rollback
src/graph/               symbol call graph (no model — pure AST walk)
src/index/               semantic vector index (embeddings via Ollama)
src/memory/              long-term fact extraction + storage
src/hooks/runner.ts       .miii/hooks/<event> lifecycle hooks
src/sandbox/wrap.ts       sandbox-exec (macOS) / bwrap (Linux) shell wrapper
src/config.ts             config loading + MIII.md project-instructions walker
src/sessions.ts           session persistence (~/.config/miii/sessions/)
```

## How to run and test

```bash
npm install
npm run dev          # tsx src/index.ts — no build needed for dev
npm test             # vitest, ~48 tests
npm run build        # tsc + copies src/prompts/SYSTEM_PROMPT.md → dist/prompts/SYSTEM_PROMPT.md
```

Node minimum: 20.12 (vitest 4 uses `node:util styleText` added in 20.12).

## Key conventions

**Tuning agent behavior:** Edit `src/prompts/SYSTEM_PROMPT.md`. The `{{TOOL_DOCS}}` placeholder is replaced at runtime with the live tool list from `src/tools/index.ts`. Do not touch `system.ts` for prompt changes.

**Adding a tool:** Add to `src/tools/index.ts` `tools` array — shape `{ name, params, description, execute }`. It auto-appears in the agent's tool list and in the system prompt.

**Provider support:** `src/llm/stream.ts` normalizes Ollama, Anthropic, and OpenAI-compat into one `chat()` call. Add new providers there.

**Permission gates:** `PERMISSION_TOOLS` set in `useRunLoop.ts` controls which tools require user approval. `PARALLEL_SAFE` controls which can be batched concurrently.

**Checkpoints:** Every write tool snapshots the file to `.miii/checkpoints/` before executing. Esc in the TUI calls `restoreCheckpoint`. Never skip this for file-mutating tools.

**Project instructions (MIII.md):** `loadProjectInstructions()` in `config.ts` walks cwd→root collecting MIII.md files, appended to the system prompt. This is the user-facing equivalent of this file.

## What NOT to do

- Do not hardcode prompt text into `system.ts` — it belongs in `src/prompts/SYSTEM_PROMPT.md`.
- Do not bypass the permission gate in `useRunLoop.ts` for write tools.
- Do not add `any` types — the codebase is strictly typed.
- Do not commit `.miii/` — it is gitignored (checkpoints, shadow git, local index).
- Do not skip `npm test` before opening a PR — CI enforces it on Node 20 and 22.

## Tests

```
src/__tests__/
  checkpoints.test.ts   snapshot + restore
  compactor.test.ts     context compaction
  guardPath.test.ts     path sandbox (symlink escapes, cwd enforcement)
  hooks.test.ts         pre/post-tool hook runner
  integration.test.ts   end-to-end tool execution
  sandbox.test.ts       shell sandbox wrapping
  stream-parser.test.ts <tool_call> block parsing from LLM output
```

Add tests for any new tool or loop-behavior change.
