<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, 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, and opt-in Mission Control TUI. | [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, explicit `/compact`, default-off post-clean-turn automatic compaction for persisted primary sessions, `/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:
```sh
cargo install magi-code --locked
```
For this release, install exact version with:
```sh
cargo install magi-code --version 0.63.4 --locked
```
Install from this source checkout:
```sh
cargo install --path . --locked
```
Generic command above installs latest published version. Use exact `X.Y.Z` only when intentionally selecting 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).
- Automatic compaction is disabled when `compaction.auto` is absent or `enabled` is false. To enable it, set `compaction.auto.enabled: true` plus exactly one trigger: `threshold_percent` (`1`–`100`, projected next-request tokens as percentage of active model maximum) or `threshold_tokens` (positive fixed count). At or above trigger, eligible persisted primary sessions compact at clean completed-turn or settled tool-continuation boundaries before another provider request. If submitted input would push full request above hard usable context budget, eligible runs compact before recording or sending input, then send original input once. Pending steering replaces post-turn fallback; otherwise runtime persists and submits literal lowercase `continue` with `origin: "automatic_compaction"`, while UI labels prompt `automatic`. Repeated same-run compaction requires new provider-visible growth and is capped. See [Sessions, context, and cache](docs/features/sessions-context-cache.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>
