using it

using it

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

getting started

One line, no toolchain to set up.

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.

source: src/micro_cc/models/