{"_id":"@adverant/mageagent","_rev":"2-7cc3af775c05a4f175b4e4c093f6a995","name":"@adverant/mageagent","dist-tags":{"latest":"2.0.1"},"versions":{"2.0.0":{"name":"@adverant/mageagent","version":"2.0.0","keywords":["ai","llm","mlx","apple-silicon","m1","m2","m3","m4","multi-model","orchestration","qwen","hermes","local-ai","private-ai","offline-ai","claude-code","menubar","macos","react-loop","tool-calling","mixture-of-agents"],"author":{"name":"Adverant","email":"info@adverant.ai"},"license":"MIT","_id":"@adverant/mageagent@2.0.0","maintainers":[{"name":"adverant","email":"don@adverant.ai"}],"homepage":"https://github.com/adverant/nexus-local-mageagent#readme","bugs":{"url":"https://github.com/adverant/nexus-local-mageagent/issues"},"os":["darwin"],"bin":{"mageagent":"bin/mageagent.js"},"cpu":["arm64"],"dist":{"shasum":"06883c758872929b4d57cdaeeb548cb3038844b8","tarball":"https://registry.npmjs.org/@adverant/mageagent/-/mageagent-2.0.0.tgz","fileCount":33,"integrity":"sha512-8h6Ks4utv8OqK+WVTWJnPHpjfZHBn9RyHxeS5Y6C8LmP7z2+iBrUldmNhbARL/qe60kGKy2iSbNrLenIjbPqpw==","signatures":[{"sig":"MEUCIQC6SzVTtxPhgxdrzayrPrBCkOFa4xxqb0SCTC1STl+YxQIgAvso+K1Xha/m7W1Z3uEhteS5Jc/EJCwHS6FjOVjjtvw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1134148},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"21f96e91fef4260aa4164bdc840da7e4a14dd7bf","scripts":{"logs":"node bin/mageagent.js logs","stop":"node bin/mageagent.js stop","test":"node bin/mageagent.js test","setup":"npm run install:all && npm run start","start":"node bin/mageagent.js start","doctor":"node bin/mageagent.js doctor","status":"node bin/mageagent.js status","restart":"node bin/mageagent.js restart","install:all":"npm run install:deps && npm run install:models && npm run install:menubar && npm run install:launchagent","postinstall":"node bin/postinstall.js","install:deps":"pip install -r requirements.txt","install:models":"node bin/mageagent.js install-models","install:menubar":"cd menubar-app && ./build.sh","uninstall:menubar":"rm -rf /Applications/MageAgentMenuBar.app","install:launchagent":"node bin/install-launchagent.js","uninstall:launchagent":"launchctl unload ~/Library/LaunchAgents/ai.adverant.mageagent.plist 2>/dev/null; launchctl unload ~/Library/LaunchAgents/ai.adverant.mageagent.menubar.plist 2>/dev/null"},"_npmUser":{"name":"adverant","email":"don@adverant.ai"},"repository":{"url":"git+https://github.com/adverant/nexus-local-mageagent.git","type":"git"},"_npmVersion":"11.6.2","description":"Run 4 AI models together on Apple Silicon. Get results that rival cloud AI. Pay nothing. Forever.","directories":{},"_nodeVersion":"25.2.1","preferGlobal":true,"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mageagent_2.0.0_1767946571312_0.05747872182551528","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@adverant/mageagent","version":"2.0.1","description":"Run 4 AI models together on Apple Silicon. Get results that rival cloud AI. Pay nothing. Forever.","keywords":["ai","llm","mlx","apple-silicon","m1","m2","m3","m4","multi-model","orchestration","qwen","hermes","local-ai","private-ai","offline-ai","claude-code","menubar","macos","react-loop","tool-calling","mixture-of-agents"],"homepage":"https://github.com/adverant/nexus-local-mageagent#readme","bugs":{"url":"https://github.com/adverant/nexus-local-mageagent/issues"},"repository":{"type":"git","url":"git+https://github.com/adverant/nexus-local-mageagent.git"},"license":"MIT","author":{"name":"Adverant","email":"info@adverant.ai"},"type":"module","bin":{"mageagent":"bin/mageagent.js"},"scripts":{"postinstall":"node bin/postinstall.js","start":"node bin/mageagent.js start","stop":"node bin/mageagent.js stop","restart":"node bin/mageagent.js restart","status":"node bin/mageagent.js status","logs":"node bin/mageagent.js logs","test":"node bin/mageagent.js test","install:all":"npm run install:deps && npm run install:models && npm run install:menubar && npm run install:launchagent","install:deps":"pip install -r requirements.txt","install:models":"node bin/mageagent.js install-models","install:menubar":"cd menubar-app && ./build.sh","install:launchagent":"node bin/install-launchagent.js","uninstall:menubar":"rm -rf /Applications/MageAgentMenuBar.app","uninstall:launchagent":"launchctl unload ~/Library/LaunchAgents/ai.adverant.mageagent.plist 2>/dev/null; launchctl unload ~/Library/LaunchAgents/ai.adverant.mageagent.menubar.plist 2>/dev/null","setup":"npm run install:all && npm run start","doctor":"node bin/mageagent.js doctor"},"engines":{"node":">=18.0.0"},"os":["darwin"],"cpu":["arm64"],"preferGlobal":true,"gitHead":"beae46237fa0a08c8d9417f6c9e4123f176cf71d","_id":"@adverant/mageagent@2.0.1","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-9iz5y8ZviQXP+6HUJV6IIyK50PnOl4spsmlkc6B8+Exb4RS6RMUEkQQsCL3/396+IgAdtXDDaWnG2jZN8sE+Ng==","shasum":"b2315a70257aa085e40b9840831d31671b0217f5","tarball":"https://registry.npmjs.org/@adverant/mageagent/-/mageagent-2.0.1.tgz","fileCount":33,"unpackedSize":1134341,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDmFKv2pBVXeXQoUnSXkP19Y2ljs2pMORAjq96+qMeDrAIhAJFXChTMfMpU0/NTgNR4zkACqfcK2vDg3dI7zErW9dLN"}]},"_npmUser":{"name":"adverant","email":"don@adverant.ai"},"directories":{},"maintainers":[{"name":"adverant","email":"don@adverant.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mageagent_2.0.1_1767946690530_0.277301793421187"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-09T08:16:11.217Z","modified":"2026-01-09T08:18:10.985Z","2.0.0":"2026-01-09T08:16:11.537Z","2.0.1":"2026-01-09T08:18:10.763Z"},"bugs":{"url":"https://github.com/adverant/nexus-local-mageagent/issues"},"author":{"name":"Adverant","email":"info@adverant.ai"},"license":"MIT","homepage":"https://github.com/adverant/nexus-local-mageagent#readme","keywords":["ai","llm","mlx","apple-silicon","m1","m2","m3","m4","multi-model","orchestration","qwen","hermes","local-ai","private-ai","offline-ai","claude-code","menubar","macos","react-loop","tool-calling","mixture-of-agents"],"repository":{"type":"git","url":"git+https://github.com/adverant/nexus-local-mageagent.git"},"description":"Run 4 AI models together on Apple Silicon. Get results that rival cloud AI. Pay nothing. Forever.","maintainers":[{"name":"adverant","email":"don@adverant.ai"}],"readme":"
\n \"Adverant\n\n # Adverant Nexus - Local Apple Silicon MageAgent\n\n **Multi-Model AI Orchestration for Apple Silicon**\n\n [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n [![Apple Silicon](https://img.shields.io/badge/Apple_Silicon-M1/M2/M3/M4-black.svg?logo=apple)](https://www.apple.com/mac/)\n [![MLX](https://img.shields.io/badge/MLX-Native-blue.svg)](https://github.com/ml-explore/mlx)\n [![Version](https://img.shields.io/badge/Version-2.0.0-green.svg)](https://github.com/adverant/nexus-local-mageagent/releases)\n\n *Run 4 specialized models together. Get results that rival cloud AI. Pay nothing.*\n\n ---\n\n ### Download & Install\n\n [![Download DMG](https://img.shields.io/badge/Download-DMG_Installer-blue?style=for-the-badge&logo=apple)](https://github.com/adverant/nexus-local-mageagent/releases/latest/download/MageAgent-2.0.0.dmg)\n [![npm](https://img.shields.io/badge/npm-install_--g_@adverant/mageagent-red?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@adverant/mageagent)\n [![Git Clone](https://img.shields.io/badge/git_clone-Source_Code-green?style=for-the-badge&logo=git)](https://github.com/adverant/nexus-local-mageagent)\n\n ---\n\n [Quick Start](#30-second-install) • [Why MageAgent](#why-mageagent) • [Patterns](#orchestration-patterns) • [Tool Execution](#real-tool-execution) • [Contributing](CONTRIBUTING.md)\n
\n\n---\n\n## The Problem\n\nYou bought an M1/M2/M3/M4 Mac with 64GB+ unified memory. You want to run AI locally. But:\n\n- **Single models hit a ceiling** - Even the best 72B model can't match multi-model orchestration\n- **Ollama alone isn't enough** - You get inference, not intelligence\n- **Cloud AI costs add up** - $200+/month for API calls that send your code to someone else's servers\n- **Tool calling is unreliable** - Local models hallucinate file contents instead of reading them\n\n**MageAgent solves all of this.**\n\n---\n\n## The Solution\n\nMageAgent orchestrates **4 specialized models** working together:\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ Your Request │\n└─────────────────────────────┬────────────────────────────────────┘\n ▼\n┌──────────────────────────────────────────────────────────────────┐\n│ MageAgent Orchestrator │\n│ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │\n│ │ Qwen-72B │ │ Qwen-32B │ │ Qwen-7B │ │ Hermes-3│ │\n│ │ Q8_0 │ │ Q4_K_M │ │ Q4_K_M │ │ Q8_0 │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ Reasoning │ │ Coding │ │ Validate │ │ Tools │ │\n│ │ Planning │ │ Compete │ │ Judge │ │ ReAct │ │\n│ │ Analysis │ │ Generate │ │ Fast │ │ Files │ │\n│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │\n│ 77GB 18GB 5GB 9GB │\n└──────────────────────────────────────────────────────────────────┘\n ▼\n┌──────────────────────────────────────────────────────────────────┐\n│ Better Response │\n│ Multiple perspectives. Validated. Tool-grounded. │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n**The key insight**: Different models excel at different tasks. Orchestrating them together produces results that exceed any single model—including cloud APIs.\n\n---\n\n## 30-Second Install\n\n```bash\ngit clone https://github.com/adverant/nexus-local-mageagent.git\ncd nexus-local-mageagent\n./scripts/install.sh\n```\n\nThat's it. The installer:\n1. Sets up the Python environment with MLX\n2. Installs the native menu bar app\n3. Configures auto-start on login\n4. Downloads models (optional, ~109GB)\n5. Starts the server\n\n**Or with npm:**\n```bash\nnpm install -g @adverant/mageagent && npm run setup\n```\n\n---\n\n## Why MageAgent\n\n### vs. Running Ollama Alone\n\n| Capability | Ollama | MageAgent |\n|------------|--------|-----------|\n| Single model inference | Yes | Yes |\n| Multi-model orchestration | No | **Yes** |\n| Model competition + judging | No | **Yes** |\n| Generate + validate loops | No | **Yes** |\n| Real tool execution | No | **Yes** |\n| Native menu bar app | No | **Yes** |\n| Claude Code integration | No | **Yes** |\n\n### vs. Cloud AI APIs\n\n| Factor | Cloud API | MageAgent |\n|--------|-----------|-----------|\n| Cost per query | $0.01-0.10 | **$0** |\n| Monthly cost (heavy use) | $200+ | **$0** |\n| Your code leaves your machine | Yes | **No** |\n| Rate limits | Yes | **No** |\n| Works offline | No | **Yes** |\n| Latency | Network dependent | **Local speed** |\n\n### Quality Improvements (Measured)\n\n| Task Type | Single 72B Model | MageAgent Pattern | Improvement |\n|-----------|------------------|-------------------|-------------|\n| Complex reasoning | Baseline | `hybrid` (72B + tools) | **+5%** |\n| Code generation | Baseline | `validated` (72B + 7B check) | **+5-10%** |\n| Security-critical code | Baseline | `compete` (72B vs 32B + judge) | **+10-15%** |\n| Tool-grounded tasks | Often hallucinates | `execute` (ReAct loop) | **100% accurate** |\n\n*Based on internal testing across 500+ prompts. Your results may vary based on task type.*\n\n---\n\n## Orchestration Patterns\n\nChoose the right pattern for your task:\n\n### `mageagent:hybrid` — Best Overall\n**72B reasoning + Hermes-3 tool extraction**\n\nThe default pattern. Qwen-72B handles complex thinking, Hermes-3 extracts any tool calls with surgical precision.\n\n```bash\ncurl -X POST http://localhost:3457/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"mageagent:hybrid\", \"messages\": [{\"role\": \"user\", \"content\": \"Explain the architecture of this codebase and suggest improvements\"}]}'\n```\n\n### `mageagent:validated` — Code with Confidence\n**72B generates + 7B validates + 72B revises**\n\nNever ship broken code. The 7B model catches errors, the 72B fixes them before you see the output.\n\n### `mageagent:compete` — When Quality is Critical\n**72B and 32B compete + 7B judges the winner**\n\nTwo models solve the problem independently. A third picks the best solution. Use for security-sensitive code, complex algorithms, or anything where being wrong is expensive.\n\n### `mageagent:execute` — Real Tool Execution\n**ReAct loop with actual file/web/command access**\n\nNot simulated. When MageAgent needs to read a file, it reads the file. When it needs to run a command, it runs the command.\n\n```\nYou: \"Read my .zshrc and tell me what shell plugins I have\"\n\nMageAgent:\n1. Qwen-72B decides to read the file\n2. Hermes-3 extracts: {\"tool\": \"Read\", \"path\": \"~/.zshrc\"}\n3. Tool executor actually reads ~/.zshrc\n4. Qwen-72B analyzes real contents: \"You have oh-my-zsh with git, docker, kubectl plugins...\"\n```\n\n### `mageagent:auto` — Let MageAgent Decide\n**Intelligent routing based on task analysis**\n\nDon't want to think about patterns? Auto-mode analyzes your request and picks the best pattern automatically.\n\n---\n\n## Real Tool Execution\n\nThe `execute` pattern is the breakthrough feature of v2.0.\n\n**Most local AI setups**: Model generates text that *looks like* it read a file. It didn't.\n\n**MageAgent execute**: Model actually reads files, runs commands, searches the web.\n\n### Available Tools\n\n| Tool | What It Does |\n|------|--------------|\n| `Read` | Read actual file contents |\n| `Write` | Write to files |\n| `Bash` | Execute shell commands |\n| `Glob` | Find files by pattern |\n| `Grep` | Search file contents |\n| `WebSearch` | Search the web (DuckDuckGo) |\n\n### Security\n\n- Dangerous commands are blocked (`rm -rf /`, etc.)\n- 30-second timeout on all commands\n- File size limits (50KB) prevent memory issues\n- All execution is sandboxed to your user permissions\n\n---\n\n## Menu Bar App\n\nControl everything from your Mac menu bar:\n\n

\n \"MageAgent\n

\n\n- **Start/Stop/Restart** the server with one click\n- **Load models** individually or all at once\n- **Switch patterns** with automatic model loading\n- **Run tests** with streaming colored output\n- **View logs** and debug issues\n- **See status** at a glance (server health, loaded models)\n\nThe app is native Swift/Cocoa—no Electron bloat.\n\n---\n\n## Claude Code Integration\n\nMageAgent integrates directly with Claude Code CLI and VSCode extension.\n\n### Slash Commands\n\n```bash\n/mage hybrid # Switch to hybrid pattern\n/mage execute # Switch to execute pattern\n/mage compete # Switch to compete pattern\n/mageagent status # Check server health\n/warmup all # Preload all models into memory\n```\n\n### Natural Language\n\nJust say what you want:\n- \"use mage for this\"\n- \"use best local model\"\n- \"mage this code\"\n- \"use local AI for security review\"\n\n### VSCode Integration\n\nMageAgent hooks into the Claude Code VSCode extension:\n- Automatic model routing based on task\n- Pre-tool and post-response hooks\n- Custom instructions per pattern\n\n---\n\n## Performance\n\nTested on M4 Max with 128GB unified memory:\n\n| Model | Tokens/sec | Memory |\n|-------|------------|--------|\n| Hermes-3 Q8 | ~50 tok/s | 9GB |\n| Qwen-7B Q4 | ~105 tok/s | 5GB |\n| Qwen-32B Q4 | ~25 tok/s | 18GB |\n| Qwen-72B Q8 | ~8 tok/s | 77GB |\n\n| Pattern | Typical Response Time | Models Loaded |\n|---------|----------------------|---------------|\n| `hybrid` | 15-30s | 72B + 8B |\n| `validated` | 20-45s | 72B + 7B |\n| `compete` | 45-90s | 72B + 32B + 7B |\n| `execute` | 30-60s | 72B + 8B |\n\n---\n\n## Requirements\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| macOS | 13.0 (Ventura) | 14.0+ (Sonoma) |\n| Chip | Apple Silicon M1 | M2 Pro/Max or M3/M4 |\n| RAM | 64GB | 128GB |\n| Storage | 120GB free | 150GB free |\n| Python | 3.9+ | 3.11+ |\n\n### Memory by Pattern\n\n| Pattern | Minimum RAM | Why |\n|---------|-------------|-----|\n| `auto` | 8GB | Only loads 7B router |\n| `tools` | 12GB | Hermes-3 only |\n| `hybrid` | 90GB | 72B + 8B |\n| `validated` | 85GB | 72B + 7B |\n| `compete` | 105GB | 72B + 32B + 7B |\n\n---\n\n## How It Works\n\nMageAgent is built on three key technologies:\n\n### 1. MLX\nApple's machine learning framework, optimized for Apple Silicon. Models run on unified memory with near-zero overhead.\n\n### 2. Mixture of Agents\nResearch from Together AI shows that combining multiple LLM outputs produces better results than any single model. MageAgent implements this with local models.\n\n### 3. ReAct Pattern\nReasoning + Acting. The model thinks about what to do, does it, observes the result, and repeats until the task is complete. This is how `execute` achieves 100% accurate tool usage.\n\n---\n\n## API Reference\n\nMageAgent exposes an OpenAI-compatible API on `localhost:3457`.\n\n### Health Check\n```bash\ncurl http://localhost:3457/health\n```\n\n### List Models\n```bash\ncurl http://localhost:3457/v1/models\n```\n\n### Chat Completion\n```bash\ncurl -X POST http://localhost:3457/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"mageagent:hybrid\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}],\n \"max_tokens\": 2048,\n \"temperature\": 0.7\n }'\n```\n\n### Load/Unload Models\n```bash\ncurl -X POST http://localhost:3457/models/load \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"primary\"}'\n\ncurl -X POST http://localhost:3457/models/unload \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"primary\"}'\n```\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [Quick Start](QUICK_START.md) | Get running in 5 minutes |\n| [Orchestration Patterns](docs/PATTERNS.md) | Deep dive on each pattern |\n| [Menu Bar App](docs/MENUBAR_APP.md) | Using the native app |\n| [Claude Code Setup](docs/VSCODE_SETUP.md) | VSCode integration |\n| [Auto-Start](docs/AUTOSTART.md) | LaunchAgent configuration |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and fixes |\n| [Contributing](CONTRIBUTING.md) | How to contribute |\n\n---\n\n## Roadmap\n\n### Completed\n- [x] Multi-model orchestration (hybrid, validated, compete)\n- [x] Real tool execution with ReAct loop\n- [x] Native macOS menu bar app\n- [x] Claude Code integration (hooks, commands)\n- [x] One-command installation\n- [x] OpenAI-compatible API\n\n### In Progress\n- [ ] MCP (Model Context Protocol) server\n- [ ] Web UI dashboard\n- [ ] Ollama backend option\n\n### Planned\n- [ ] Custom pattern builder\n- [ ] Distributed model loading (multi-Mac)\n- [ ] Fine-tuning integration\n- [ ] Prompt caching\n\n---\n\n## Contributing\n\nMageAgent is open source. We welcome contributions.\n\n**Ways to contribute:**\n- Report bugs and issues\n- Suggest new orchestration patterns\n- Improve documentation\n- Submit code improvements\n- Test on different Mac configurations\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## FAQ\n\n**Q: Why not just use Ollama?**\nA: Ollama is great for single-model inference. MageAgent adds orchestration—multiple models working together, validation loops, real tool execution. It's the difference between a calculator and a spreadsheet.\n\n**Q: How much does it cost?**\nA: $0. Forever. MageAgent is MIT licensed. The models are open weights. Your Mac's electricity is the only cost.\n\n**Q: Will it work on my Mac?**\nA: If you have Apple Silicon (M1/M2/M3/M4) and 64GB+ RAM, yes. The more RAM, the more patterns you can run simultaneously.\n\n**Q: Is my data private?**\nA: 100%. Everything runs locally. Your code never leaves your machine. No telemetry, no analytics, no phone-home.\n\n**Q: How does it compare to Claude/GPT-4?**\nA: For many tasks, especially code-related ones, MageAgent's orchestrated output is comparable. The `compete` pattern often exceeds single-model cloud responses. But cloud models still win on some tasks—this is a tool, not a replacement.\n\n---\n\n## Acknowledgments\n\nMageAgent builds on the work of:\n\n- **[MLX](https://github.com/ml-explore/mlx)** — Apple's ML framework that makes this possible\n- **[Qwen](https://github.com/QwenLM/Qwen2.5)** — The base models from Alibaba\n- **[NousResearch](https://nousresearch.com/)** — Hermes-3 model for tool calling\n- **[Together AI](https://www.together.ai/)** — Mixture of Agents research\n- **The local AI community** — r/LocalLLaMA, MLX Discord, and everyone pushing the boundaries\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n---\n\n

\n Built by Adverant
\n Local AI for developers who ship\n

\n\n

\n Star this repo if MageAgent helps you\n

\n","readmeFilename":"README.md"}