Choose the model. Keep the workspace, history, and rules.
εgo is a Rust coding-agent harness for your terminal, scripts, and ACP clients. It gives local models, hosted APIs, and supported subscription providers the same file and process tools, durable sessions, and permission controls. The model proposes an action; the harness decides whether and where it can run.
Review a repository without permitting edits, and select read-only operating-system confinement independently:
ego --mode plan --sandbox ro "Explain the parser and identify missing tests"Permission modes control which effects are allowed. Confinement controls the
filesystem boundary. Even yolo does not remove a sandbox. Inspect the admitted
boundary with /config perimeter, and inspect resolved settings with
ego config ls --effective.
macOS uses Seatbelt; Linux uses its supported confinement backends. If the host
cannot provide a requested guarantee, ego refuses rather than weakening it.
Windows supports execution and host protocols, but not workspace, ro, or
--offline confinement. See permissions.
Interactive and headless runs use the same durable session store. Reopen work, branch a conversation, or export it without copying a terminal buffer:
ego ls
ego resume SESSION_ID
ego fork SESSION_ID
ego export SESSION_ID --format mdego compact creates a compacted successor when context grows. Builtin file
writes and edits in Git worktrees also create session-owned checkpoints;
ego checkpoint SESSION_ID preview lists recovery points. Restore refuses
conflicting external changes instead of overwriting them.
ego --worktree feat/parser-check "Review the parser and propose a focused fix"The branch must be new. The checkout stays after exit, so unfinished work does
not disappear with the process. Use ego worktree show RECEIPT_UUID to inspect
it and ego worktree cleanup RECEIPT_UUID to request safe removal. Cleanup
refuses dirty or unmerged work; creating a worktree does not grant extra tool
authority. See worktrees.
Use ego models to inspect the shared model catalogue, capabilities, and available
provider profiles. Select local Ollama models, hosted APIs, or supported
subscription logins with the same -m provider/model option. Unknown or
unsupported capabilities are not silently assumed.
With a running Ollama daemon:
ollama pull qwen3
ego models --provider ollama --refresh
ego -m ollama/qwen3 --thinking off "Explain the main entry points"Use a model listed by your daemon. For hosted APIs and subscription login, see providers; keep credentials out of project files.
Configure an ACP client to launch ego acp. The host supplies the conversation
and permission UI; ego supplies the session and execution machinery. Connect
external tools through ego mcp, or expose scoped runs to an MCP client through
ego mcp-server. See ACP and MCP.
For scripts, select structured output and explicit run bounds:
printf '%s\n' 'Summarize what a coding harness does in one sentence.' | \
ego run -m ollama/qwen3 --thinking off --no-tools \
--max-turns 1 --timeout 30s --output json -Headless runs never ask for trust or permissions and start bare and untrusted by default. JSON and live JSONL output, schema-validated answers, token or money budgets, turn limits, and timeouts let a caller define the run contract. See automation before enabling effects.
Keep the whole workflow in one harness. See CLI.md for arguments and options.
ego run— Give scripts a bounded, non-interactive agent run.ego resume— Reopen a durable session without losing its history.ego continue— Pick up an existing session with the resume alias.ego fork— Explore another direction without rewriting the original session.ego rm— Remove sessions you no longer need.ego compact— Carry the useful context into a compacted successor.ego export— Take session history into your own reports and tools.ego ls— Find the sessions attached to your work.ego usage— See where tokens and costs go.ego models— Find models and provider profiles for the next task.ego hooks— Inspect the hooks that extend your workflow.ego doctor— Diagnose your installation before starting work.ego checkpoint— Inspect recovery points and restore session-owned edits.ego setup— Configure saved settings through a staged screen.ego acp— Put the harness behind an ACP client's conversation UI.ego a2a— Expose local agent discovery over the A2A protocol.ego auth— Manage supported provider logins.ego mcp— Connect and manage external MCP tools.ego config— Inspect and change the settings that shape your runs.ego roots— Manage the filesystem roots available to the harness.ego rules— Inspect and manage tool permission rules.ego mcp-server— Expose scoped agent runs to an MCP client.ego worktree— Inspect retained checkouts and request safe cleanup.
On macOS and Linux:
brew install sstraus/tap/egoOr use release downloads and the
installation and source-build guide.
Keep the complete checkout, including vendor/, when building from source.
Run ego --version to identify your installed build and ego --help for its
command set.
- User guide · guide source
- Getting started and interactive use
- Sessions, worktrees, and instructions and memory
- CLI reference and configuration
- Permissions, providers, and tools
- ACP, MCP, skills, and hooks
- Architecture, contributing, and release notes
εgo is licensed under Apache-2.0. Releases through v0.4.1 remain
under MIT. Vendored dependencies and other third-party material retain their own
licenses; see third-party licenses.