mimicode | Documentation

Installation

mimicode ships as a single prebuilt binary. No runtime or interpreter required.

macOS / Linux

curl -fsSL https://trymimicode.github.io/install.sh | bash

The installer detects your OS and architecture, downloads the correct binary to ~/.local/bin, and wires up your PATH.

Windows

irm https://trymimicode.github.io/install.ps1 | iex

Go install

go install github.com/trymimicode/mimicode-go/cmd/mimicode@latest

Build from source

git clone https://github.com/trymimicode/mimicode-go.git
cd mimicode-go
make install

Requirements: ripgrep and an ANTHROPIC_API_KEY. No Python, no Node, no other dependencies.

Quick Start

1. Set your API key

export ANTHROPIC_API_KEY="sk-ant-..."

On Windows:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Or store it permanently with the built-in key command:

mimicode key set sk-ant-...

2. Start watch mode

mimicode watch

A file called code.mimi appears in your project directory. Open it in your editor.

3. Write a question and save

why does this handler fire twice on the first request?

Save the file. mimicode diffs the new text, runs the agent, and writes the answer back into the same file below a divider. No tab switching. No chat window.

Tip: mimicode only reacts to new text. Its own answers are never replayed as input. Write anywhere in the file, edit in place, or clear and start fresh.

Configuration

Environment variables

Variable	Default	Description
`ANTHROPIC_API_KEY`	required	Anthropic API key
`MIMICODE_MODEL`	`claude-opus-4`	Model to use
`MIMICODE_THINKING`	`medium`	Thinking budget: `off` / `low` / `medium` / `high`
`MIMICODE_CONFIRM`	`0`	Set to `1` to confirm before each write, edit, or bash
`MIMICODE_CHECKPOINT`	`1`	Set to `0` to disable undo snapshots
`MIMICODE_MAX_STEPS`	`25`	Max tool calls per turn

Key management

Use the key subcommand to store your API key securely so you do not need to export it in every shell session:

mimicode key set sk-ant-...   # store
mimicode key show             # display stored key
mimicode key delete           # remove stored key

CLI Commands

Watch mode (default)

mimicode watch

Watches code.mimi in the current directory. This is the primary interface. Running mimicode with no arguments also starts watch mode.

One-shot

mimicode "add error handling to auth.go"

Execute a single task and exit. The response is printed to stdout.

REPL

mimicode --repl
mimicode --repl -s myproject

Interactive prompt. Type tasks line by line. Use :q or Ctrl-D to exit.

TUI

mimicode --tui

Full terminal UI built with Bubbletea, with rich formatting and session navigation.

Named session

mimicode -s auth-refactor "add rate limiting"

Create or resume a named session. Sessions persist across runs.

Confirm mode

mimicode --confirm "refactor calc.go"

Gates every bash, write, and edit call. Read-only tools never prompt.

Version

mimicode --version

Modes

Watch mode

The primary way to use mimicode. Open code.mimi in your editor alongside your code. Write a question or task, save, and the answer appears in the same file below a divider. No context switching.

mimicode watch

REPL mode

An interactive prompt for multi-turn sessions at the terminal. Supports inline REPL commands:

> read src/app.go and explain the handler
> add a middleware for request logging
> :undo          # revert last turn
> :compact       # compact long context
> :q             # exit

One-shot mode

Pass a task as an argument. Useful for scripts and CI pipelines:

mimicode "run the tests and fix any failures"

TUI mode

Full terminal UI with syntax-highlighted output, session history, and keyboard navigation.

mimicode --tui

Sessions

Every session is persisted on disk. Nothing is opaque.

Session files

~/.mimi/sessions/<id>/
  events.jsonl      # every tool call, model text, token counts, timing
  messages.json     # full conversation for resume

<project>/.mimi/
  MEMORY.md         # cross-session notes written by memory_write
  RULES.md          # behavioral rules learned from recovery

Named sessions

mimicode -s auth-refactor          # start or resume
mimicode --repl -s auth-refactor   # in REPL mode

Undo

Every turn that changes files is snapshotted. Your real .git is never touched.

:undo            # revert last turn
:undo 3          # revert last 3 turns
:undo list       # show all checkpoints

Disable snapshots with MIMICODE_CHECKPOINT=0.

Compaction

For long sessions, compaction summarises earlier turns to keep context lean:

:compact         # compact now
:compact on      # enable auto-compaction
:compact off     # disable auto-compaction
:compact status  # show current status

Tools

mimicode has ten tools. That is the entire surface area.

Tool	What it does
`bash`	Runs a shell command. Blocked dangerous patterns (rm -rf /, curl \| sh, etc.).
`read`	Reads a file with line numbers. Output capped at 100KB.
`write`	Creates or overwrites a file.
`edit`	Exact find-and-replace edits applied atomically. Fails if the old text is not unique.
`web_search`	DuckDuckGo search. Supports `site:` filters.
`web_fetch`	Fetches a URL. Has dedicated extractors for GitHub, Reddit, HN, and Stack Overflow.
`stackoverflow_search`	Returns Stack Overflow questions with top answers inline.
`memory_write`	Appends a structured note to `.mimi/MEMORY.md`.
`memory_search`	Full-text search across sessions, memory, and rules on disk.
`recall_compaction`	Loads a prior session summary by ID.

Safety: bash blocks: rm -rf /, curl | sh, grep -r, find, ls -R, and other broad destructive patterns. Use --confirm to gate every mutating call interactively.

Architecture

44 Go files across 13 packages. Readable in one sitting.

Package layout

Package	Purpose
`cmd/mimicode/`	Entry points: watch, tui, key subcommands and REPL/one-shot runners
`internal/agent/`	Turn loop, tool dispatch, stuck detection
`internal/provider/`	Anthropic API calls and streaming
`internal/tools/`	bash, read, write, edit, web, git source implementations
`internal/tui/`	Bubbletea terminal UI
`internal/watch/`	Notebook file watcher and diff engine
`internal/store/`	Session persistence via SQLite
`internal/memory/`	Cross-session memory and full-text search
`internal/reflect/`	Post-session summarisation
`internal/recovery/`	Stuck diagnosis: reads the event log and proposes a fix
`internal/checkpoint/`	Shadow-git undo snapshots
`internal/compactor/`	Long-session compaction
`internal/repomap/`	Symbol index for the current project
`internal/gitsource/`	Shallow-clone a library for inspection

Turn flow

User input (file diff / REPL / one-shot)
    |
    v
agent.AgentTurn          -- builds messages, calls API
    |
    v
provider (streaming)     -- Anthropic API, token tracking
    |
    v
tool dispatch            -- executes tool calls, appends results
    |
    v
stuck / recovery check   -- detects loops and error runs
    |
    v
store.SaveMessages       -- persists to SQLite + messages.json
    |
    v
compactor.MaybeCompact   -- trims context if over threshold
    |
    v
checkpoint.Snapshot      -- shadow-git snapshot for undo
    |
    v
reflect.RunReflect       -- post-session summarisation

Philosophy

mimicode is not a pair programmer. It does not pick architectures, debate tradeoffs, or volunteer opinions. It is a tool in the Unix sense: a rubber duck that can search your repo, run commands, and make mechanical edits when you ask.

The notebook interface keeps you in your editor. The diff engine means mimi only ever sees what is new. Its own answers are never replayed as prompts. Every file touched and every command run lands in a events.jsonl file you can read, replay, or audit. Memory lives in flat markdown. No black boxes.

The tool set is deliberately small. Ten tools with clear contracts beat a sprawling API that hides what the model is actually doing.

Frequently Asked Questions

Q: What changed from the Python version?

A: The entire codebase is now Go. Single prebuilt binary, no Python runtime, no pip, no virtual environment. Watch mode is the primary interface. Sessions are stored in SQLite. Undo, compaction, recovery, and the TUI are all new.

Q: Can I use this for production code?

A: Yes. Use --confirm to review every mutating action before it runs. Undo snapshots let you revert any turn without touching your real git history.

Q: Is my code sent to Anthropic?

A: Yes. Code read by tools is included in API requests to Anthropic. Do not use mimicode with secrets or sensitive data you are not comfortable sending over the API.

Q: How do I update mimicode?

A: Re-run the install script. It downloads the latest release binary and replaces the existing one.

curl -fsSL https://trymimicode.github.io/install.sh | bash

Q: Can I use a different AI provider?

A: Currently only Anthropic is supported.

Q: How do I contribute?

A: Submit issues and PRs to github.com/trymimicode/mimicode-go.

Troubleshooting

"ripgrep (rg) is required"

Install ripgrep for your platform:

# macOS
brew install ripgrep

# Ubuntu / Debian
sudo apt install ripgrep

# Fedora
sudo dnf install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Windows (Chocolatey)
choco install ripgrep

# Windows (Scoop)
scoop install ripgrep

"ANTHROPIC_API_KEY is not set"

Either export it in your shell:

export ANTHROPIC_API_KEY="your-key-here"

Or store it permanently:

mimicode key set your-key-here

"command 'mimicode' not found"

The install directory is not in your PATH. On Linux / macOS:

source ~/.bashrc   # or ~/.zshrc

Or add it manually:

export PATH="$HOME/.local/bin:$PATH"

Watch mode not responding

Make sure you are saving the file. mimicode reacts on save, not on keystroke. If the watcher exits unexpectedly, check for a stale code.mimi.lock file in your project directory and remove it.

Agent stuck in a loop

mimicode detects repeat patterns and error runs automatically. When triggered, it stops, reads its own event log, and proposes a fix. In REPL mode it asks before retrying. In one-shot mode it prints the diagnosis and exits.

You can also force a retry with context from the previous failure:

mimicode --repl "your original task --force"

Still stuck? Open an issue on GitHub with the relevant lines from ~/.mimi/sessions/<id>/events.jsonl.