Content
<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>
