Getting started
harness is an AI coding agent for your terminal. It edits your project and runs commands in a sandbox, asking first when its mode says to. Every session is recorded.
Install
curl -fsSL https://megacode-harness.vercel.app/install.sh | sh
Linux (x86_64), macOS 15.4+ (Apple Silicon or Intel), or Windows through WSL2. Installs one binary to ~/.local/bin, no sudo.
Read the script first. HARNESS_VERSION pins a release; HARNESS_INSTALL_DIR
picks the folder.
On Linux the sandbox needs bubblewrap: sudo apt install bubblewrap.
Update: type /update in a session (0.29.0 and later; it installs without leaving, then /restart switches over and keeps the conversation), or run harness update in a terminal (0.24.0 and later; before that, run the install again). A release build checks at start and every hour, and the status bar tells you when one is out
(what it sends). A start is quiet: one line of notes, and /notices lists the rest (the quiet start). Uninstall: delete ~/.local/bin/harness.
Windows (WSL2)
Run harness inside WSL2, as a Linux install. In PowerShell, wsl -l -v lists your distributions;
the VERSION column must say 2 (wsl --set-version <name> 2 converts one; wsl --install sets up
WSL2 with Ubuntu). Inside the distribution, install bubblewrap and run the installer above. Keep
projects in the Linux file system (~/code), not under /mnt/c. The sandbox hides each Windows
drive’s Users folder, and a project inside one makes the sandbox unavailable; Windows programs (cmd.exe)
do not start from a sandboxed command. WSL1 and Windows on ARM are not supported, and this has
been checked on one Windows machine. The details are in the sandbox page.
Free models, or your own keys
Free models
Type /login in a session, or run harness login, and sign in with Google. You get mega:flash
and mega:full, free up to a daily allowance (resets 00:00 UTC). harness logout signs out.
Signed in, harness also sends daily usage counts (no prompts, files or commands); telemetry = false turns
them off (what it sends). Privacy.
Your own keys
Export the key in your shell’s startup file:
export ANTHROPIC_API_KEY=your-key
| Provider | Variable |
|---|---|
| Anthropic | ANTHROPIC_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Gemini | GEMINI_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| Together | TOGETHER_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY |
| Z.AI | ZAI_API_KEY |
| xAI | XAI_API_KEY |
| Ollama, LM Studio (local) | no key |
Auto mode on your own keys also needs TYPESAFE_API_KEY (typesafe.ai).
Other OpenAI-compatible providers: [providers.<name>].
Start
harness run
harness run --model gemini:gemini-3.8-flash
Model ids are provider:model; /model switches mid-session. Set a default in
~/.config/harness/config.toml:
model = "gemini:gemini-3.8-flash"
harness resume continues an earlier session.
Modes
manualasks before every command, edit, skill and sub-agent.planreads freely, writes only its plan file.autoedits without asking; the judge approves commands and asks you about risky ones.
Shift+Tab cycles them. See Modes and the judge.
From a script
git diff | harness -p "review this change"
One turn, answer on stdout. See harness -p.