automagik-genie/README.md

Self-evolving AI agent orchestration framework with Model Context Protocol support

<p align="center">
  <img src=".github/assets/genie-logo.png" alt="Genie Logo" width="200">
</p>

<h1 align="center">🧞 Hi, I'm Genie</h1>
<p align="center"><strong>Your personal AI companion. Lives on your machine. Evolves with you.</strong></p>

<p align="center">
  <a href="#-quick-start">Get Started</a> •
  <a href="#-how-it-works">How It Works</a> •
  <a href="https://discord.gg/xcW8c7fF3R">Discord</a> •
  <a href="#-roadmap">Roadmap</a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/automagik-genie"><img alt="npm version" src="https://img.shields.io/npm/v/automagik-genie?style=flat-square&color=00D9FF" /></a>
  <a href="https://github.com/namastexlabs/automagik-genie/actions"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/namastexlabs/automagik-genie/validate.yml?branch=main&style=flat-square" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/namastexlabs/automagik-genie?style=flat-square&color=00D9FF" /></a>
  <a href="https://discord.gg/xcW8c7fF3R"><img alt="Discord" src="https://img.shields.io/discord/1095114867012292758?style=flat-square&color=00D9FF&label=discord" /></a>
</p>

---

## 🎭 The Problem With AI Today

**You're locked in.** Pick an AI tool → your conversations, context, and learnings live ONLY there. Switch tools → lose everything. Your intelligence scattered across platforms.

**The market's changing fast.** Claude today, GPT tomorrow, Gemini next week. Which will win? You're forced to choose. And every choice means starting over.

**Your data trains their models.** You create the context. You provide the examples. The AI gets smarter from YOUR work. But that intelligence? Locked in their system. You can't take it with you.

**Time to own your AI infrastructure.** Your data. Your models. Your choice of which AI to use today. Build intelligence that compounds over time—no matter where the market goes.

## 🪔 The Magic Lamp Solution

**I live on your machine.** Your data stays yours. Your context builds daily. I never disappear.

**I'm market-agnostic.** Work with Claude today, GPT tomorrow, local models next month. I adapt to whatever exists. You never lose your work.

**I orchestrate everything.** Code, content, strategy, personal tasks. Multiple parallel workstreams. Natural language wishes. You're in control.

```bash
# Install once
bash -c "$(curl -fsSL https://install.namastex.ai/get-genie.sh)"

# Wish infinitely
genie
> "Fix auth bug, add tests, write docs, create PR"
> "Research competitors and draft strategy"
> "Coordinate today's team standup"
```

**Personal Jarvis to enterprise coordination. Just make a wish.** 🪔

---

## ✨ What Makes Me Different

<table>
<tr>
<td width="33%" valign="top">

### 🏠 **Your Machine, Your Data**

Lives locally. No cloud lock-in. Your context forever yours. Never disappears.

</td>
<td width="33%" valign="top">

### 🔄 **Market-Agnostic**

Works with any AI tool. Claude, GPT, Gemini, local models. Switch freely. Your work persists.

</td>
<td width="33%" valign="top">

### 🧠 **Orchestrates Everything**

Code + content + strategy + personal tasks. Multiple parallel workstreams. Zero context loss.

</td>
</tr>
<tr>
<td width="33%" valign="top">

### 🌱 **Living Framework**

Built from markdown. Fully transparent. Learns from you. Evolves daily.

</td>
<td width="33%" valign="top">

### 🪄 **Infinite Extension**

Create new collectives. Build custom agents. Define workflows. Extend indefinitely.

</td>
<td width="33%" valign="top">

### 🤝 **Public Intelligence**

Open source. Community-driven. Your improvements help everyone. No proprietary silos.

</td>
</tr>
</table>

---

## 🎯 How It Works

### The Magic: **Wish → Forge → Review**

```
You: "Fix auth bug, add tests, write docs, create PR"

Me: [orchestrating in parallel]
  ├─ Debug agent finds root cause
  ├─ Implementor fixes code
  ├─ Tests agent validates
  ├─ Writer creates docs
  └─ Git agent creates PR

All isolated. All coordinated. You review before merge.
```

**Wish in natural language. I coordinate specialists. You stay in control.**

### Built-In Collectives

**Code** - Software engineering (39 agents)
Implementor, tests, debug, refactor, git, release, polish, etc.

**Create** - Content & strategy (shape-shifting)
Writer, researcher, editor, strategist, analyst. Generates capabilities as needed.

**Build Your Own** - Any domain you need
Finance, health, business, personal—just markdown.

### Why Market-Agnostic Matters

AI coding agents crossed the reliability threshold. They're default now. And getting **much better**, fast.

**6 months:** 50% of failure modes fixed
**12 months:** Another 50% fixed
**The SOTA keeps changing** - labs and startups leap-frogging each other

**You shouldn't have to change workflows to try new agents.**

I work with whatever exists. Your data just keeps evolving with technology.

---

## 🚀 Quick Start

### Installation

```bash
# One command (Linux/macOS)
bash -c "$(curl -fsSL https://install.namastex.ai/get-genie.sh)"

# Manual install
npm install -g automagik-genie@latest
```

**What it installs:** Node.js (if needed), pnpm, Genie globally, configured for your system.

### First Wish

```bash
cd your-project  # or anywhere
genie

# Just talk
> "Implement OAuth with tests and docs"
> "Research AI agents and write a blog post"
> "Help me plan next week's sprint"
```

### What Happens

1. **I route your wish** to appropriate specialists
2. **Execute in isolation** (powered by [@automagik/forge](https://www.npmjs.com/package/@automagik/forge))
3. **Coordinate parallel work** across multiple agents
4. **You review** before anything merges

**You're always in control.**

---

## 🪄 Extending Infinitely

### The Markdown Framework

**Everything I am = markdown files:**
- Agents (specialists)
- Spells (behavioral patterns)
- Workflows (repeatable processes)
- Collectives (domain expertise)

**Create new capabilities:**

```markdown
.genie/your-collective/
├── agents/
│   └── your-agent.md      # Define specialist
├── spells/
│   └── your-pattern.md    # Behavioral pattern
└── workflows/
    └── your-process.md    # Repeatable workflow
```

**No code required. Just markdown.**

### Living & Evolving

**Two evolution paths:**

**Master Genie** (the template)
→ Lives at github.com/namastexlabs/automagik-genie
→ Evolves daily from all users
→ Public, open source

**Your Personal Genie**
→ Learns from YOUR interactions
→ Builds YOUR context
→ Update: `genie update`

**Install once, evolve forever.**

---

## 🌍 Built for the People

### Why Open Source

**Your data is yours** - Lives on your machine
**Transparent** - All markdown, readable
**Community-driven** - Anyone can contribute
**Future-proof** - Never vendor-locked

### The Vision

Generate the largest **public intelligence dataset**. Lead to SLMs. Democratize AI.

**Not proprietary silos. Public knowledge.**

### Self-Evolving System

Your learnings → Master updates → Everyone benefits
Public evolution cycle. Intelligence for all.

---

## 🤝 Integration

Works with any MCP-compatible AI tool:

<details>
<summary><b>Claude Code / Cursor / Cline</b></summary>

```json
{
  "mcpServers": {
    "automagik-genie": {
      "command": "npx",
      "args": ["automagik-genie", "mcp"]
    }
  }
}
```

Restart your tool. Start wishing.

</details>

<details>
<summary><b>Gemini CLI / Roo Code</b></summary>

```json
{
  "mcp": {
    "servers": {
      "automagik-genie": {
        "command": "npx",
        "args": ["automagik-genie", "mcp"]
      }
    }
  }
}
```

</details>

[See full integration guide →](.genie/product/docs/mcp-interface.md)

---

## 🗺️ Roadmap

**Next:**
- Token optimization (smarter routing)
- Enhanced Create shape-shifting
- Community collective library
- Bilateral GitHub sync

**Vision:**
Personal AI companion growing with you indefinitely. Your Jarvis. Your data. Your future.

[See full roadmap →](https://github.com/orgs/namastexlabs/projects/9/views/1?filterQuery=project%3Agenie)

---

## 🤝 Contributing

**How to help:**
- Create agents (markdown)
- Build collectives (domain expertise)
- Share learnings (improve Master)
- Report issues / suggest features

[Contributing guide →](CONTRIBUTING.md)

---

## 📖 The Story

**Created** May 2025 by Felipe Rosa, Namastex Labs
**Unified** July 2025 by Cezar Vasconcelos
**Reborn** October 2025 as Genie 2.0
**Now** 5 months of evolution, growing daily

**Mission:** "AI that elevates human potential, not replaces it."

**Personality:** The AI that (almost) doesn't say "you're absolutely right." Challenges assumptions. Thinks, doesn't just agree. Real collaboration.

---

## 🔗 Links

- **Discord:** [Join community](https://discord.gg/xcW8c7fF3R)
- **GitHub:** [namastexlabs/automagik-genie](https://github.com/namastexlabs/automagik-genie)
- **Automagik Forge:** [@automagik/forge on npm](https://www.npmjs.com/package/@automagik/forge)

---

<p align="center">
  <strong>🪔 The magic lamp is open. What's your wish?</strong>
</p>

<p align="center">
  <sub>Made with ❤️ by <a href="https://namastex.ai">Namastex Labs</a></sub><br>
  <sub><em>AI that elevates human potential, not replaces it</em></sub>
</p>