<p align="center">
<img src="logo.png" alt="magi-code logo" width="100%">
</p>
<h1 align="center">magi-code</h1>
<p align="center">
Local Rust CLI coding agent for repository-aware terminal work, provider-backed assistant turns, bounded tools, sessions, skills, subagents, and optional Mission Control TUI.
</p>
<p align="center">
<img alt="Rust 2024" src="https://img.shields.io/badge/Rust-2024-000000?logo=rust&logoColor=white">
<img alt="Version pre-1.0" src="https://img.shields.io/badge/version-pre--1.0-blue">
<img alt="License: Apache 2.0 plus Commons Clause" src="https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-lightgrey">
<img alt="Binary: magi-code" src="https://img.shields.io/badge/binary-magi--code-4EAA25">
<a href="docs/features/provider-authentication.md"><img alt="Providers" src="https://img.shields.io/badge/providers-Codex%20%7C%20Anthropic%20%7C%20custom-412991"></a>
<a href="docs/features/mission-control-tui.md"><img alt="TUI" src="https://img.shields.io/badge/TUI-Mission%20Control-8A2BE2"></a>
<a href="https://evalforge.ai/public/projects/b012a4a6-3110-4b0c-afe8-8dd1e0597de2"><img alt="EvalForge" src="https://evalforge.ai/api/cards/projects/b012a4a6-3110-4b0c-afe8-8dd1e0597de2/badge.svg"></a>
</p>
> **TL;DR:** install published versions with Cargo after first crates.io release, run `magi-code`, use `/login` to connect provider, then launch from repository you want agent to work in.
---
## Table of contents
- [What it does](#what-it-does)
- [Quick start](#quick-start)
- [Feature documentation](#feature-documentation)
- [Configuration essentials](#configuration-essentials)
- [Security essentials](#security-essentials)
- [Repository layout](#repository-layout)
- [Project docs](#project-docs)
- [Evaluations](#evaluations)
- [License](#license)
## What it does
| Capability | Included behavior | More detail |
| --- | --- | --- |
| Repository-aware assistant | Runs from active working directory, discovers user/repo `AGENTS.md`, assembles prompt context, and streams provider responses. | [Instructions, prompts, skills, and primary agents](docs/features/instructions-prompts-skills-and-agents.md) |
| Multiple interfaces | Classic interactive shell, one-shot `--print` mode, opt-in Mission Control TUI, and experimental workspace-only `--tui-experimental` shell. | [Commands and interfaces](docs/features/commands-and-interfaces.md), [Mission Control TUI](docs/features/mission-control-tui.md) |
| Provider support | `openai-codex`, first-class Anthropic Messages API-key provider, direct `claude-code` Anthropic Messages integration using Claude Code OAuth with API-key fallback, plus configured OpenAI-compatible custom providers, with provider-authored reasoning summaries where supported and hidden chain-of-thought kept hidden. | [Provider authentication](docs/features/provider-authentication.md) |
| Local configuration | Defaults to `~/.magi-code`; supports `MC_HOME` for isolated profiles/tests, global non-secret `settings.json`, and cwd-local `.magi-code/settings.json` project overrides. | [Configuration](docs/features/configuration.md) |
| Bounded tools | File read/write/search, unified `read` for local files, internal schemes, and direct URLs, in-process grep, hashline `hash_edit` for tag-anchored multi-hunk edits, structural `repo_map`, guarded shell execution, local image inspection through configured vision models, browser control, web/code search, opt-in LSP `diagnostics`/`references`, skill loading, visible tool effects, TTSR streaming reminders, schema-validated subagent output, and safe subagent summaries. | [Tools and safety model](docs/features/tools-and-safety.md), [LSP diagnostics](docs/features/lsp-diagnostics.md), [Security notes](docs/features/security.md) |
| Sessions and context | JSONL sessions, structured replay, context budget checks with local BPE token counting, `/compact` checkpoints, `/prune-sessions`, and local cache data. | [Sessions, context, and cache](docs/features/sessions-context-cache.md) |
| Extensibility | User/repo skills, prompt fragment overrides, primary-agent profiles, subagent identity profiles, tool-call hooks, and optional tool output compression. | [Instructions, prompts, skills, and primary agents](docs/features/instructions-prompts-skills-and-agents.md), [Tool-call hooks](docs/features/tool-call-hooks.md), [Tool output compression](docs/features/tool-output-compression.md), [Parallel subagents](docs/features/parallel-subagents.md) |
| Maintainer evals | Prompt-fixture dump, tool-choice evals, native skill benches, candidate skill gates, and SkillOpt artifact bridge live in isolated eval harness crate. | [Eval harness and skill benches](docs/features/eval-harness-and-skill-benches.md), [Eval crate README](evals/magi-code-evals/README.md) |
| Maintainer duplicate detection | `cargo-dupes` and `jscpd` configs detect structural Rust clones and token-level duplicates across source/docs/config. | [Duplicate detection](docs/features/duplicate-detection.md) |
The crate builds one command-line binary: `magi-code`. If you prefer shorter command, define shell alias such as `alias mc='magi-code'`; this repository does not ship `mc` binary target.
File `read` defaults local files to hashline mode: `[path#TAG]` header plus `LINE:TEXT` anchors for `hash_edit`. Use selectors such as `:raw`, `:50-100`, or `:raw:50-100` for plain text and line windows. `read` also accepts `skill://<name>`, `skill://<name>/<relative-reference>`, `session://`, `issue://`, `pr://`, and direct `http`/`https` targets through bounded internal readers. `hash_edit` uses latest current-session tag; after edit or stale-tag failure, use fresh response tag or re-read before more edits. Use `hash_edit` for existing-file edits and `write` for new files.
## Quick start
Requirements: Rust 1.88.0+ with Cargo, provider network access, and credentials for `openai-codex`, `anthropic`, or configured custom provider. Content search runs in-process; external ripgrep is not required.
Install from crates.io after first publication:
```sh
cargo install magi-code --locked
```
For this release, install exact version with:
```sh
cargo install magi-code --version 0.61.0 --locked
```
Before first publication, crates.io installation is unavailable; install from this checkout instead:
```sh
cargo install --path . --locked
```
After publication, the generic command above installs the latest published version. Use an exact `X.Y.Z` only when intentionally selecting a known published version.
Run from target repository:
```sh
magi-code
magi-code --version
```
Connect provider from interactive shell or environment:
```text
/login
/login openai-codex
```
```sh
ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>" magi-code --provider anthropic --model claude-sonnet-4-5-20250929 --print "Reply with only: ok"
# Claude Code direct HTTP path; reads Claude Code OAuth from Keychain or ~/.claude.
claude auth login
magi-code --provider claude-code --model sonnet --print "Reply with only: ok"
```
Launch Mission Control TUI:
```sh
magi-code --tui
```
Run one prompt for scripts/logs:
```sh
magi-code --print "Summarize this repository."
```
Add bounded local context to prompts:
```text
Review current changes. #git-status
Map repository layout first. #tree
```
`#git-status` and `#tree` work in `--print`, classic shell, and Mission Control. Commands run from active cwd through guarded bash; failures become bounded context blocks instead of aborting prompt.
Update installed binary by reinstalling desired crates.io version:
```sh
cargo install magi-code --version X.Y.Z --locked --force
```
Common slash commands: `/help`, `/login`, `/logout`, `/setmodel`, `/models`, `/usage`, `/new`, `/changes`, `/rewind [--to <turn>] [--dry-run]`, `/compact`, `/prune-sessions`, `/sessions`, `/skills`, `/tools`, `/subagents`, `/mcp`, `/system-prompt`, `/quit`. Full flags, slash-command behavior, Mission Control modal keys, and prompt tags live in [Commands and interfaces](docs/features/commands-and-interfaces.md).
Repair broad legacy session permissions without shell commands:
```sh
magi-code sessions repair-permissions --dry-run
magi-code sessions repair-permissions
```
Use `--yes` for automation. Command resolves `MC_HOME`, changes only validated legacy session objects, and fails closed on unsafe layouts.
Maintainer/debug prompt fixture dump:
```sh
magi-code --dump-prompt --provider anthropic
```
`--dump-prompt` exits before authentication and prints provider-ready eval JSON. Eval harness and skill bench docs live in [Eval harness and skill benches](docs/features/eval-harness-and-skill-benches.md) and [evals/magi-code-evals/README.md](evals/magi-code-evals/README.md).
User customization/auth files live under `MC_HOME` when set, otherwise `~/.magi-code`; project-scoped settings can live at `<cwd>/.magi-code/settings.json` and override global settings for that cwd only. Full configuration and customization rules live in [Configuration](docs/features/configuration.md) and [Instructions, prompts, skills, and primary agents](docs/features/instructions-prompts-skills-and-agents.md).
Provider-visible local prompt sources use bounded byte reads with per-file and startup aggregate limits; profile and skill symlinks are rejected. Details: [Instructions, prompts, skills, and primary agents](docs/features/instructions-prompts-skills-and-agents.md).
See [Installation and updates](docs/features/installation-and-updates.md) for crates.io installs, manual versioned updates, source-checkout installs, and aliases.
## Feature documentation
| Area | Dedicated docs |
| --- | --- |
| Install/update flow | [Installation and updates](docs/features/installation-and-updates.md) |
| Commands and interfaces | [Commands and interfaces](docs/features/commands-and-interfaces.md) |
| Configuration | [Configuration](docs/features/configuration.md) |
| Provider login/logout | [Provider authentication](docs/features/provider-authentication.md) |
| Mission Control interface | [Mission Control TUI](docs/features/mission-control-tui.md) |
| Sessions, context, cache | [Sessions, context, and cache](docs/features/sessions-context-cache.md) |
| Instructions, prompt templates, skills, primary agents | [Instructions, prompts, skills, and primary agents](docs/features/instructions-prompts-skills-and-agents.md) |
| Built-in tools and boundaries | [Tools and safety model](docs/features/tools-and-safety.md) |
| MCP stdio/HTTP tools | [MCP stdio and HTTP tools](docs/features/mcp-stdio-tools.md) |
| LSP live diagnostics | [LSP diagnostics](docs/features/lsp-diagnostics.md) |
| Provider-visible tool summaries | [Tool output compression](docs/features/tool-output-compression.md) |
| Tool-call hooks | [Tool-call bash hooks](docs/features/tool-call-hooks.md) |
| Subagent delegation | [Parallel subagents](docs/features/parallel-subagents.md) |
| Common fixes | [Troubleshooting](docs/features/troubleshooting.md) |
| Credential and shell safety | [Security notes](docs/features/security.md) |
| Maintainer eval harness | [Eval harness and skill benches](docs/features/eval-harness-and-skill-benches.md), [Eval crate README](evals/magi-code-evals/README.md) |
| Maintainer duplicate detection | [Duplicate detection](docs/features/duplicate-detection.md) |
Feature docs index: [docs/features/](docs/features/)
## Configuration essentials
- Runtime state defaults to `~/.magi-code`; set `MC_HOME` to isolate runs, profiles, or tests. Diagnostics name resolved `MC_HOME` paths.
- Project overrides live only at exact cwd `<cwd>/.magi-code/settings.json`; no parent-directory search.
- `settings.json` is non-secret; `auth.json` stores provider credentials and must stay private.
- `--color <auto|always|never>` controls ANSI color. Precedence: CLI flag > `settings.no_color` > `NO_COLOR` > auto TTY detection. `NO_COLOR` disables ANSI color only; Unicode marks and line editor remain TTY-gated.
- Exit codes: `0` success/help, `1` runtime/provider/tool/general failure, `2` usage/config/launch-validation failure.
- `openai_responses.text_verbosity` optionally selects `low`, `medium`, or `high` for OpenAI Responses requests. Shared value overrides legacy `openai_codex.text_verbosity` for Codex; legacy setting remains Codex fallback with default `low`. Custom Responses providers send field only when `use_responses_endpoint` and `supports_text_verbosity` are both true; otherwise `text` stays omitted. Hint affects visible detail, output size, latency, and cost, not reasoning effort, hidden chain-of-thought, tool calls, or hard output-token limits.
- `selected_model.thinking_level` persists universal values (`default`, `low`, `medium`, `high`, `xhigh`, `max`). Explicit provider catalog efforts win; built-in profiles protect known model families from generic catalog booleans; boolean reasoning metadata only enables generic effort levels for otherwise unknown models. Anthropic `high`/`max` maps to Messages API thinking budgets; `default` omits thinking.
- `anthropic_cache_ttl` is optional in `settings.json`; accepted values are `"5m"` and `"1h"`. It enables Anthropic prompt-cache request fields for `anthropic` and direct `claude-code` providers only. Claude Code sends no cache control when setting absent. Cache writes can increase cost; savings depend on provider cache eligibility, minimum cacheable length, and repeated prompt shape.
- Precedence: CLI flags > environment variables > cwd project settings > global settings/auth > defaults.
- Configuration docs cover schema, paths, project/global merge behavior, subdirectory `AGENTS.md` discovery, MCP servers, custom providers, `view_image`, hooks, tool settings, and environment variables: [Configuration](docs/features/configuration.md).
- Custom providers support optional `reasoning_protocol`: `gpt-like` (default) or `anthropic-like` request fields on existing OpenAI-compatible endpoints; it does not enable Anthropic Messages transport. `gpt-like` controls request dialect only. Exact non-empty catalog `reasoning_efforts` metadata determines levels; otherwise `supports_reasoning: true` enables `default|low|medium|high`, while missing or false metadata exposes only `default`. Unsupported persisted levels clamp non-destructively to `default`.
Optional LSP diagnostics are disabled by default. Enable them only when matching language servers are installed on `PATH`; LSP adds a fast edit feedback loop but does not replace `cargo check`, tests, or project-specific verification.
```json
{
"lsp": {
"enabled": true,
"inject_diagnostics_on_edit": true,
"diagnostics_wait_ms": 2000,
"idle_shutdown_minutes": 10,
"servers": {
"rust-analyzer": { "command": "rust-analyzer", "args": [] },
"typescript-language-server": { "command": "typescript-language-server", "args": ["--stdio"] }
}
}
}
```
When enabled, successful `write`/`hash_edit` calls can append a redacted `DIAGNOSTICS` block capped at 20 diagnostics and about 2 KiB. Missing, slow, crashed, or indexing servers degrade silently for edit injection; edits still succeed or fail only by normal file-tool rules. The `diagnostics` tool reads cached file/workspace diagnostics, and `references` returns bounded `path:line:column` reference sites for safe paths. See [LSP diagnostics](docs/features/lsp-diagnostics.md).
## Security essentials
- Provider credentials are assistant transport credentials only; Cargo installation uses Cargo's own authentication and is not performed by magi-code.
- `bash` / `shell` has guardrails but no OS-level isolation; sandbox hostile repositories separately.
- `settings.json` is non-secret. Use environment references for sensitive MCP HTTP headers; keep OAuth tokens under `$MC_HOME/mcp-tokens/<server>.json`.
- Search tools require `EXA_API_KEY` from process environment only.
See [Security notes](docs/features/security.md) and [Tools and safety model](docs/features/tools-and-safety.md) for full boundaries.
If normal startup reports broad session permissions, run `magi-code sessions repair-permissions --dry-run`, then use interactive mode or `--yes`. Command resolves `MC_HOME`, repairs only validated legacy objects, never follows links or recurses, and fails closed on unsafe layouts. See [sessions, context, and cache](docs/features/sessions-context-cache.md) and [troubleshooting](docs/features/troubleshooting.md).
## Repository layout
```text
.
├── README.md # Project overview and feature-doc entrypoint
├── Cargo.toml # Rust 2024 crate; lib `magi_code`, bin `magi-code`
├── Cargo.lock # Locked dependency graph
├── config/ # Example non-secret settings
├── docs/ # Feature docs, PRDs, ADRs, RFCs, release notes
├── evals/ # Maintainer eval harness crates and cases
├── prompts/ # Bundled runtime prompt fragments
├── scripts/ # Maintainer audit/profiling/live-check helpers
├── src/ # CLI, provider, tool, session, skill, subagent, TUI code
└── tests/ # Integration regressions
```
## Project docs
Public Rust API compatibility is guarded in CI with `cargo semver-checks` on pull requests against base branch. New public exports should be intentional and covered by `tests/foundation.rs` or equivalent external-use evidence.
- [Feature documentation](docs/features/)
- [Eval harness and skill benches](docs/features/eval-harness-and-skill-benches.md)
- [Eval crate README](evals/magi-code-evals/README.md)
- [Release checklist and update policy](docs/release.md)
- [PRDs](docs/prd/)
- [ADRs](docs/adr/)
- [RFCs](docs/rfc/)
## Evaluations
<a href="https://evalforge.ai/public/projects/b012a4a6-3110-4b0c-afe8-8dd1e0597de2"><img alt="EvalForge Report" src="https://evalforge.ai/api/cards/projects/b012a4a6-3110-4b0c-afe8-8dd1e0597de2.svg"></a>
Maintainer evals cover prompt-fixture dumps, tool-choice cases, native skill benches, candidate skill gates, and SkillOpt bridge artifacts. See [Eval harness and skill benches](docs/features/eval-harness-and-skill-benches.md) and [Eval crate README](evals/magi-code-evals/README.md).
## Maintainer test commands
Use narrow convenience scopes while changing one ownership domain, then run full checks before merge:
```sh
cargo test --locked --lib agent::
cargo test --locked --lib providers::
cargo test --locked --lib tools::
cargo test --locked --lib tui::
cargo test --locked --lib mcp::
cargo test --locked --lib config::
cargo test --locked --lib sessions::
cargo test --locked --lib context::
cargo test --locked --bin magi-code
cargo test --locked --test foundation
cargo test --locked --test cli_smoke
cargo test --locked --doc
cargo test --manifest-path evals/magi-code-evals/Cargo.toml --locked
```
`--lib` limits execution to unit tests in `src`; it excludes integration tests, binary tests, and doctests. Cargo filters use substring matching; trailing `::` is a module-qualified convenience scope, not ownership-exact. Current `cargo test --locked --lib <filter> -- --list` counts are: `agent::` 246, `providers::` 295, `tools::` 344, `tui::` 777, `mcp::` 109, `config::` 168, `sessions::` 141, and `context::` 122. Known cross-domain matches include 3 `cli::mcp` tests in `mcp::`, 50 `cli`/`tui` tests in `sessions::`, and 32 `agent` prompt-context tests in `context::`; inspect `--list` output when exact ownership matters. Counts are test-list evidence, not coverage claims. CI runs root library, binary, `foundation`, `cli_smoke`, doctests, and eval tests as serial steps for failure isolation and scoped reruns; partitioning is not claimed to reduce aggregate wall time.
This project uses Apache License 2.0 with Commons Clause. It is source-available and not an OSI-approved open-source license or plain Apache-2.0. Apache permissions allow modification, derivative works, free redistribution, and free sublicensing when attribution, license, modification, and Commons Clause notices are retained; internal commercial use remains allowed. Commons Clause prohibits selling magi-code itself or offering a paid product or service whose value derives entirely or substantially from magi-code functionality. See [LICENSE](LICENSE).
---
<p align="center">
Keep mission bounded. Keep credentials redacted. Let tools do useful work, not magic tricks.
</p>
