MagicHorse ♞

Personal AI assistant in a box. Install with one command, pair your WhatsApp, plug a Code Plan API key, and you're live.

Status: early alpha (v0.1.0 under active construction — see magichorse.md in the parent magic-horse/ directory for the full plan).

Quick start

curl -fsSL --proto '=https' --tlsv1.2 \
  https://raw.githubusercontent.com/larteragia/magichorse/main/install.sh | sh

The installer will:

1. Check Node ≥22 (install via nvm if missing).
2. Install magichorse globally via npm.
3. Run the onboarding wizard:
   • Pick a name / emoji / language / tone.
   • Enter your phone number.
   • Pair WhatsApp (QR or pairing code) — optional, can skip for TUI-only.
   • Paste one of: Anthropic (Claude Code Max Plan OAuth), ZAI Code Plan, MiniMax Code Plan, Google Gemini, Groq, or OpenAI.
   • Pick the roteador agent.
   • Opt-in specialist agents (Search/Scraping, Frontend, Images, Video).
   • Deploy your own Convex for persistent memory (optional — falls back to local Markdown if declined).
   • Configure ponei flush interval (default 15 min).
4. Install the gateway as a systemd --user daemon (or macOS launchd).
5. Open the TUI immediately.

Then talk to your assistant on WhatsApp or in the TUI.

Manual install

Prefer not to pipe a script? Here's what it does:

npm install -g magichorse@latest
magichorse onboard --install-daemon
magichorse tui

Features

• Multi-channel: WhatsApp first; Telegram/Signal/Discord/etc. via plugins (v0.2+).
• Multi-provider LLM: Anthropic, OpenAI, ZAI (GLM), MiniMax, Google Gemini, Groq — all OAuth or API key, all rotatable via auth-profiles.json.
• Built-in specialists: 🔍 search, 🎨 frontend, ✨ images, 🎬 video — each with its own model and skills.
• TUI with live heartbeat: cavalinho spinner, braille logo, Ctrl+T status, slash commands for agent switching and streaming observers.
• Convex-backed memory (optional): your own Convex deploy for persistent RAG, not a SaaS shared pool.
• Streaming observers (watch tool): real-time reactions to log lines, file changes, HTTP polls — agent can wake itself up on events.
• Self-hosted: runs on a laptop, a VPS, or Oracle Always-Free.

Documentation

• docs/ — quickstart, providers, convex, whatsapp, troubleshooting (populated in Fase 8).
• ../magichorse.md — full implementation plan + design decisions.

License

MIT — see LICENSE. Experimental software, no warranty.

Status and roadmap

See magichorse.md in the parent directory for phases 0–8 of v0.1.0 delivery. v0.2+ adds: plugin marketplace, more channels, macOS app, web dashboard.