# micro·cc

> The thinnest harness that can rewrite itself. Plain Python. Source: https://github.com/GSequist/microcc

# micro·cc documentation

overview
 
micro·cc documentation
 

 micro·cc is a loop in plain Python that a model can open and edit while it runs. These
 pages are generated from the source tree itself, so what you read here is what the code
 declares.
 
 

 

 
where to start
 
 using itInstall, point it at a project, the full command list, tools and providers.
 changing itThe life of a self-edit: detect, wait for idle, restart, recover. The user layer, skills and MCP.
 referenceSettings, environment variables, ~/.micro-cc and a map of the package.
 
 

 

 
the whole harness, one mark per file
 

 Nothing here is sampled or illustrative: each mark is one file in the package,
 grouped by module, and its area is that file's real line count.
 Hover any mark for the path. This is every file a change to micro·cc could touch,
 at a glance — which is the whole argument, drawn.
 
 tui_native35 / 6,939tools20 / 4,370utils30 / 4,232package root6 / 3,718models17 / 3,587skills13 / 1,740browser5 / 1,419webui6 / 982postgres_store3 / 526cache2 / 128137 files · 27,641 linesmark area ∝ lines
 
generated at build time from the source tree
 

 

 
every claim has a source
 

 Each section ends with a link to the file it was derived from, and the foot of every page
 names the exact commit it was built from. The command, skill, settings and environment
 lists are extracted by script from the repository at build time, never typed by hand, so
 they cannot drift from the code.
 
 

 Docs for agents. The same content is published as plain text at
 /llms.txt and
 /llms-full.txt. Press / on any page
 to search.

---

# Using micro·cc

using it
 
using it
 
Install, point it at a directory, and let it work.
 

 

 
getting started
 
One line, no toolchain to set up.
 
 $
 curl -fsSL https://raw.githubusercontent.com/GSequist/microcc/main/install.sh | sh
 
 
 

 macOS, Linux and WSL. The bash_ tool needs a
 real POSIX shell. On Windows, run the PowerShell installer, which installs inside WSL:
 
 
> irm https://raw.githubusercontent.com/GSequist/microcc/main/install.ps1 | iex
 

 Prefer pip? pip install micro-cc installs the same package.
 
 

 Point it at a project directory. project_dir is fixed for the
 life of the session: relative paths in every tool call resolve against it, absolute paths
 work anywhere on the machine.
 
 
$ microcc /path/to/your/project
 

 First run, type /login to configure your model endpoint. Type
 / for the command list.
 
 
source: README.md
 

 

 
three surfaces, one process
 

 The terminal app and the browser tab are not two implementations kept in sync by hand:
 they are one process. The GUI server runs in a background thread beside the agent loop, so
 a tool call waiting on your approval is a single suspended call, reachable from whichever
 surface you answer it from.
 
 
terminal: 
the full app: microcc /path/to/project. Slash commands, live tool approvals, session history.
headless: 
one prompt in, one answer out, no TUI: microcc-headless, built for cron and CI.
browser: 
/gui opens a tab on the same running session. Same approvals, same state.
 

 

 
slash commands
 

 All 24, extracted from the harness's own command registry: the same registry the
 terminal autocomplete and the browser palette read from. Commands tagged
 terminal only are withheld from the browser palette, either
 because they quit or replace the process, or because they run autonomous loops that report
 through a status line a browser session does not have.
 
 
/model: 
switch model
/theme: 
switch color theme (or edit ~/.micro-cc/theme.json)
/dangerous: 
which tools need approval
/subagents terminal only: 
max headless subagents running at once (default 4)
/rewind: 
undo back to an earlier turn
/clear: 
erase this project's conversation
/copy: 
copy transcript to clipboard
/setup: 
configure settings + statusline
/new-skill: 
create a new skill
/new-mcp: 
register a new MCP server
/skills: 
list skills you have + how to add more
/mcp: 
list MCP servers you have + how to add more
/headless: 
run a single prompt headlessly (microcc-headless, the -p mode) — cron-friendly, no manifest
/graph terminal only: 
orchestrate multiple headless subagents toward a goal — diagram first, then spawn/monitor/adjust
/message-session: 
message another micro-cc session (live or headless) by project_dir
/optimize terminal only: 
start/resume an autonomous measure-change-keep-or-revert loop against a metric
/doctor: 
diagnose a broken/fragile install (pipx, uv, Homebrew-managed python…) and hand you the fix commands
/author: 
credit
/login terminal only: 
endpoint + API key
/keys terminal only: 
store project-scoped secrets — typed values never reach the model, written straight to {project_dir}/.env, auto-sourced into every bash_ call; no vaulting beyond that
/exit terminal only: 
quit
/update terminal only: 
install latest micro-cc
/reload terminal only: 
restart to pick up edits to micro-cc's own source (no PyPI install)
/gui terminal only: 
open this session in the browser
 
source: src/micro_cc/utils/command_registry.py
 

 

 
tools & memory
 

 Shell, filesystem, browser and MCP are the baseline, not an opt-in tier. The tradeoff is
 made explicit rather than hidden: /dangerous chooses which
 tools stop for your approval, and by default that is bash, edit and write.
 
 
bash: 
shell commands, defaulting to project_dir; project secrets auto-sourced
filesystem: 
read, write, edit, glob, grep
browser: 
drives a real browser session
computer use: 
screen-level control beyond the browser (macOS only)
vision: 
reads images and screenshots directly
web: 
search, fetch, archive, download
mcp client: 
external MCP servers, registered with /new-mcp
memory: 
durable keyed memory, per project and global
todos: 
multi-step plans that survive across turns
monitor: 
poll a subagent or process, stream a live watch, or schedule a prompt to fire later
message-session: 
talk to another running micro·cc session
search-history: 
full-text search over this project's whole conversation
ask-user: 
structured questions back to you, one at a time
skills: 
list and load skills
 

 Memory builds a picture of you and the project across sessions. Keys are
 indexed and surfaced each turn; the body expands on demand. Local JSON by default; set
 MICRO_CC_POSTGRES_URL and every read and write routes to
 Postgres instead, with no code change.
 
 
source: src/micro_cc/tools/
 

 

 
providers
 

 Switch providers mid-session with /model. Bring your own API
 keys: nothing routes through a third party you did not choose. Adapters shipped in the
 package: anthropic, catalog_, client, foundry, litellm, ollama, openai, openrouter, priming, types.
 
 

 

 The model list is not frozen into the build. It resolves in three tiers: your own entries in
 ~/.micro-cc/models.json first, then a catalog published in the
 repository, then a table built into the package. The remote catalog is refreshed in the
 background at most every six hours and cached, so nothing is fetched at startup
 — a new model can appear without waiting for a release, and an offline machine is
 unaffected.
 
 Configure endpoints with /login. Project-scoped secrets go
 through /keys: typed values are written straight to the
 project's .env and auto-sourced into every
 bash_ call, never passing through the model's context.
 
 
source: src/micro_cc/models/

---

# Changing micro·cc

changing it
 
changing it
 
The core has no extension API: the loop is a file, and the file is
 the extension point. What you add for yourself lives outside it, in
 ~/.micro-cc, where an update cannot reach it.
 

 

 
the life of a self-edit
 
 
 
 ~/.micro-cc/
 your additions, untouched
 
 

 
 
 
 
 SELF_HEAL_

 
 
 
 
 

 
 
 
 
 
 

 
 
 
 
 
 
 model
 machine

 
 claude_loop_.py
 
 
 the file it is running

 between turns
 
 
 the model edits its own file
 
 
 ↻ it restarts in place
 
 
 same pid · same conversation
 
 
 now it can do something new
 
 
 ✗ the new code will not boot
 
 
 ↻ the release is put back
 
 
 at most three tries
 
 

 
 ↻ it restarts in place
 same pid · same conversation

 
 
 
 
 + retry on error
 

 
 
 
 
 
 
 

 
 
 
 
 
 
 

 Edit any .py file in the package, by hand or by asking the
 model in plain words. A two-second poll compares a manifest of file modification times and
 sizes, and a change marks a reload as pending.
 
 

 The restart only fires when the app is idle: no turn in flight, no /gui
 session owning the conversation, no live subagent. Otherwise the poll keeps retrying until
 the first tick where every gate is clear. Then micro·cc stashes your unsent prompt, flushes
 messages.jsonl and re-executes in place with
 os.execv. The process id stays the same and the conversation is
 rebuilt from disk.
 
 

 Every launch goes through a small supervisor. If the edited tree fails to boot, it
 reinstalls the published release over it and retries, at most three consecutive times. A
 boot that succeeds clears the count, and a crash after a good boot never triggers a
 reinstall.
 
 
$ /reload re-execs this install: applies your edit now
$ /update installs a new version: replaces core edits, keeps your layer
 
source: src/micro_cc/utils/self_reload_.py · src/micro_cc/self_heal_.py · design/architecture.toml
 

 

 
adding to it without editing the core
 

 Editing the package is the strong way to change micro·cc and the fragile one: the next
 /update overwrites the file. So the things you are most likely
 to want have a second home, outside the package, where the installer never looks.
 
 

 Built-in defaults live in the package and are replaced on every release. What you add lives
 in ~/.micro-cc/, which pip never installs into. The two are merged
 by name at startup and yours wins — which is a trade, not a free lunch: a default you
 overrode stops improving for you, because the version you wrote is the one that runs. That is
 why the defaults are never copied into your directory. A copy would freeze you on today's
 version for no reason; a file you wrote on purpose is a choice you made.
 
 

 Editing the core is the other case, and it is not free. /update
 reinstalls the package and overwrites those edits, and so does the supervisor if a bad edit
 ever stops the harness booting. The user layer above is the answer for anything that fits it;
 for anything that does not, edit the core knowing the next update takes it back.
 
 
 
commands/<name>.md: 
a slash command as a prompt, with $ARGS substituted
 
commands/<name>.py: 
a slash command as code: async def run(ui, arg)
 
renderers/*.py: 
override how a message type or a tool call is drawn
 
panels/*.py: 
lines in the header, or above the input
 
glyphs.json: 
the glyph and label for each message type
 
keys.json: 
a key mapped to a slash command or an action
 
banner.txt: 
the wordmark
 
statusline.sh: 
a script that gets JSON on stdin and prints one line; leave it out and the built-in one runs, and still improves with the package
 
 

 Your files are handed a small, stable facade — notify,
 get_input, set_input,
 send_prompt, project_dir,
 model(), request_render() — and
 never the app's internals. The facade is
 versioned: a file written against a different version is disabled rather than left to
 half-work. A file that will not import is skipped and reported; it never stops the harness
 booting. Most edits here restart the app into the change at the next idle moment — the
 status line and the model catalog need no restart at all.
 
 
source: src/micro_cc/utils/user_layer_.py
 

 

 
skills
 

 Skills are packaged instructions the model loads when a task calls for them: a workflow
 with its own reference files, not a single prompt. /new-skill
 writes one and /skills lists what is installed. They load from
 ~/.micro-cc/skills/<name>/SKILL.md (every project) or
 {project_dir}/skills/<name>/SKILL.md (this project only).
 Bundled with the package:
 
 
customizing-micro-cc: 
Read before changing micro-cc itself (slash commands, look of the TUI, keys, status line, banner, models, or harness source)
design: 
Create visual design artifacts, in two modes
docx: 
Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction
github: 
Research public GitHub repositories
graph-orchestration: 
Reference for the /graph subagent-orchestration mechanism
painted-video: 
Use when the user wants a painted/brushstroke-style animation synced to music: a real music video (not a typographic lyric video), or any WebGL2 canvas animation keyed to…
pptx: 
Use this skill any time a .pptx presentation is being created from scratch
system-design-review: 
Review downstream system effects before and after code changes: concurrency, asyncio task lifetime, cancellation, persistence, process/deployment boundaries, ownership an…
xlsx: 
Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization
 
source: src/micro_cc/skills/
 

 

 
MCP servers
 

 /new-mcp registers an external MCP server and
 /mcp lists what you have. Their tools join the same list as the
 built-ins, so the model does not care where a tool came from.
 
 
source: src/micro_cc/tools/mcp_client_.py

---

# micro·cc reference

reference
 
reference
 
Where things live, and what the knobs are.
 

 

 
settings.json
 

 ~/.micro-cc/settings.json. Edit it by hand or ask
 /setup. A key missing from an older install is filled in with
 its default on first read.
 
 
dangerous: 
tool names gated behind an approval prompt
model: 
the endpoint currently in use, written by every /login path
tokens_budget: 
the context budget the loop trims against
max_subagents: 
how many headless subagents one session may run at once
 
source: src/micro_cc/utils/settings_store_.py
 

 

 
environment variables
 
MICROCC_BASH_ENV_DENYLIST: 
extra variable names stripped from the environment handed to bash_ source
MICROCC_CALLER_PROJECT_DIR: 
internal: set by bash_ so a headless run can register with the session that spawned it source
MICROCC_FIRST_EVENT_TIMEOUT: 
how long a headless run waits for the model's first event before giving up source
MICROCC_HEADLESS_VERDICT_FD: 
internal: the pipe a spawned headless run uses to report whether it came up source
MICRO_CC_MIRROR_POSTGRES_URL: 
 source
MICRO_CC_POSTGRES_URL: 
set it and every message, memory and settings read or write routes to Postgres instead of local JSON source
MICRO_CC_TRIM_BUDGET: 
overrides the context budget the loop trims against, on every backend source
 

 

 
~/.micro-cc/
 

 Everything durable lives here, outside the package, so it survives
 /update and any self-edit. pip never installs into
 it. Built-in defaults stay in the package and the files you add here are merged
 over them, by name, at runtime.
 
 
 
settings.json: 
model, dangerous tools, budgets
 
models.json: 
your own model entries; merged over the remote catalog and the built-in table
 
memory.json: 
the keyed memory, global tier
 
theme.json: 
colours for the terminal surface; yours, not the package's
 
statusline.sh: 
the status line, run as a script; whatever it prints is used verbatim
 
.env: 
shared secrets for bash_
 
commands/: 
your slash commands: name.md is a prompt, name.py is code
 
renderers/: 
override how a message type or a tool call is drawn
 
panels/: 
lines in the header, or above the input
 
glyphs.json: 
the glyph and label for each message type
 
keys.json: 
a key mapped to a slash command or an action
 
banner.txt: 
the wordmark
 
skills/: 
global skills, one directory each
 
mcps/: 
globally registered MCP servers
 
projects/{name}_{hash}/: 
per-project conversation, memory, tracked subagents, inbox
 
sessions/: 
the live-session registry used by message-session
 
self_heal_state.json: 
the supervisor's consecutive boot-failure count
 
cache/: 
the harness's own scratch: the remote model catalog, and the built-in status line it falls back to
 
 
source: src/micro_cc/utils/msg_store_.py
 

 

 
the package
 

 Resolve it with
 python3 -c "import micro_cc, os; print(os.path.dirname(micro_cc.__file__))",
 then read any of it.
 
 
browser/: 
the browser driver behind the browser tool
cache/: 
local caches
models/: 
provider adapters and the model registry
postgres_store/: 
optional Postgres backend for messages, memory and settings
skills/: 
bundled skills
tools/: 
every tool, one file each
tui_native/: 
the terminal UI
utils/: 
storage, prompt assembly, settings, command registry, the reload poll
webui/: 
the browser surface and its server
claude_loop_.py: 
the agent loop: builds the system prompt, assembles tools, consumes the event stream
execute_tool.py: 
tool dispatch
self_heal_.py: 
the boot supervisor: reinstalls the published wheel if an edit breaks startup
start_headless_.py: 
the one-shot headless entry point
start_live_tui_.py: 
the interactive entry point and the self-reload poll