Skip to main content

​
Prerequisites

Before installing Genie, make sure you have: 
# Check your Node.js version
node --version

# Should output v18.0.0 or higher
If you need to install or upgrade Node.js:
  • macOS: brew install node
  • Ubuntu/Debian: sudo apt install nodejs npm
  • Windows: Download from nodejs.org
# Check if Git is installed
git --version
Genie works with Git repositories for context understanding.
For AI-powered features, you’ll need API keys:
  • Claude: Anthropic API key
  • OpenAI: OpenAI API key
  • Gemini: Google AI API key

​
Installation Methods

  • NPM (Global)
  • NPM (Project)
  • NPX (No Install)
  • From Source
Install Genie globally to use it from anywhere:
npm install -g automagik-genie
Verify installation:
genie --version

​
Configuration

After installation, initialize Genie in your project: 
# Initialize Genie workspace
genie init

# This creates a .genie/ directory with configuration
Configure your AI settings in .genie/config.json: 
{
  "mcp": {
    "enabled": true,
    "port": 3000
  },
  "agents": {
    "coder": {
      "enabled": true,
      "llm": "claude"
    },
    "reviewer": {
      "enabled": true,
      "llm": "claude"
    }
  },
  "llms": {
    "claude": {
      "apiKey": "your-anthropic-api-key",
      "model": "claude-3-5-sonnet-20241022"
    }
  }
}
Security Tip: Never commit .genie/config.json to version control! Add it to .gitignore.

​
MCP Server Setup (Optional)

To expose Genie as an MCP server for other AI agents: 
# Start the MCP server
genie serve

# Or specify a port
genie serve --port 3001
Add to your MCP client configuration (e.g., Claude Desktop): 
{
  "mcpServers": {
    "genie": {
      "command": "genie",
      "args": ["serve"]
    }
  }
}

​
Verify Installation

Test that everything is working: 
# Check version
genie --version

# Get help
genie --help

# Initialize a workspace (if not done yet)
genie init

# Check MCP server status
genie serve --check
You should see output similar to: 
automagik-genie v1.0.0

✓ Workspace initialized
✓ Configuration created
✓ MCP server ready

​
Troubleshooting

If you installed globally but get “command not found”:
  1. Check NPM global bin path: 
    npm config get prefix
  2. Add to your PATH (add to ~/.bashrc or ~/.zshrc): 
    export PATH="$PATH:$(npm config get prefix)/bin"
  3. Reload your shell: 
    source ~/.bashrc  # or ~/.zshrc
Check if the port is already in use:
# Try a different port
genie serve --port 3001
Or kill the process using the port:
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
Make sure you’re in a Git repository:
git init  # If not already a Git repo
git remote add origin <your-repo-url>
Genie uses Git for template synchronization.

​
Next Steps

Quick Start

Create your first AI-powered workspace

Introduction

Learn more about Genie