---

MAGI is a high-performance, task-based AI orchestrator designed to bring structure, persistence, and specialized intelligence to autonomous development. It operates as a bridge between your preferred AI models and your local environment, functioning simultaneously as a powerful interactive CLI and a background Model Context Protocol (MCP) server.

🌟 Why MAGI? (Key Benefits)

• Professional Interactive UI: Inspired by Claude Code, featuring dimmed reasoning for better focus, real-time action spinners, and clean result boxes.
• Hybrid Power: Use it directly in your terminal for dedicated focus, or annex it to your favorite AI client (Gemini CLI, Claude Desktop) via MCP.
• Persistent Orchestration: Unlike standard chat interfaces, MAGI manages its own state in a local .magi directory, including progress logs, activity history, and strict Guardrails (Signs) to prevent AI loops.
• Native SDK Integration: Fast and secure connections to official Google Gemini, Anthropic Claude, and OpenAI SDKs. No middleman proxies.
• Zero-Touch Automation: Registration and skill installation happen automatically. Just install and start orquestrating.

---

📦 Installation

Install MAGI Orchestrator globally via npm to get the magi command:

# Official installation
npm install -g magi-orchestrator

Note: The automatic registration script (postinstall) will detect your Gemini CLI and Claude Desktop configurations and inject the MAGI server/skill automatically.

---

🚀 How it Operates (Quick Start)

Option 1: Interactive CLI Mode (Recommended for Focus)

Run tasks directly from your terminal with rich, stylized feedback.

# Execute a task iteration interactively
magi run "build-auth-layer"

Option 2: The "Annexed" Mode (Skill Injection)

Open your Gemini CLI and use the native skill:

/magi fix-login-bug MAGI will run in the background and report progress directly in your chat session.

---

⚙️ Configuration

MAGI looks for a magi-config.json file in your project directory. If not found, it uses sensible defaults.

{
  "agents": [
    {
      "name": "gemini-flash",
      "type": "gemini",
      "model": "gemini-2.0-flash"
    },
    {
      "name": "claude-sonnet",
      "type": "claude",
      "model": "claude-3-5-sonnet-20241022"
    }
  ],
  "defaultAgent": "gemini-flash",
  "stateDirectory": ".magi"
}

🔑 Authentication

Set your API keys as environment variables:

• GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY.

---

🛠 Operation Mechanics: The .magi Directory

MAGI keeps your project context clean by orchestrating everything inside the .magi folder:

• progress.md: Tracking success criteria and current status.
• guardrails.md: Active "Signs" learned from previous failures to guide the AI.
• activity.log: Detailed history of every decision and action.

---

🛠 Available CLI Commands

Command	Description
magi run <task>	Start/Continue a task iteration interactively.
magi setup	Manually trigger auto-registration in AI clients.
magi serve	Start the MCP server (STDIO).
magi --version	Report the current version (v1.2.1).

---