go-magic

go-magic

Magic Agent -- A high-performance, ultra-lightweight AI Agent framework written in Go.

Overview

go-magic is a full-featured AI Agent framework that combines a powerful Go backend with a modern Vue 3/TypeScript web dashboard. It supports 22+ AI providers, ships a built-in TUI (BubbleTea), and offers extensive tooling for file operations, code execution, web browsing, and more.

Features

Multi-Provider Support (22+)

DeepSeek, OpenAI, Anthropic, Gemini, Ollama, vLLM, Groq, 硅基流动, Kimi, 智谱GLM, 通义千问, 文心一言, MiniMax, MiMo, 腾讯混元, 豆包, Moonshot, OpenRouter, Together AI, Mistral AI, Cohere, Perplexity, and any OpenAI-compatible endpoint.

Multi-Model per Provider

Each provider can configure multiple models. The first model in the array is the current active model. Switch models instantly without restart (hot-reload).

TUI Interface

Built with BubbleTea, featuring multi-line input, Markdown rendering, streaming output, and slash commands.

Web Dashboard

Vue 3/TypeScript frontend with:

• Real-time chat with streaming responses
• Session management (create, search, resume)
• Provider and model configuration with hot-reload
• Skills management
• Cron job scheduling
• Kanban board
• Token usage dashboard with budget alerts
• Group chat for multi-agent conversations

Coding Mode

A dedicated mode with relaxed permissions, longer timeouts, and support for Python/Node.js code execution -- designed for development workflows.

Tool System

15+ built-in tools organized into toolsets:

Skills System

Auto-creation and progressive loading (L0/L1/L2). Skills are learned from usage patterns and can be installed from Skills Hub.

Cortex (Cognitive Architecture)

A complete agent cognitive system:

• Memory System: SOUL.md (personality), USER.md (user profile), snapshot memory, FTS search
• Perception: Input analysis, intent recognition, complexity assessment
• Cognition: Planning, decision making, LLM-based task decomposition
• Execution: Tool invocation and result processing
• Skill Evolution (GEPA): Automatic skill creation from historical patterns

Messaging Gateway

Connect your agent to external platforms:

Telegram, Discord, Slack, WhatsApp, WeChat, WeCom, DingTalk, Feishu, QQ, LINE, Matrix.

MCP Protocol

Connect to external MCP (Model Context Protocol) servers to extend agent capabilities.

Group Chat

Create group conversations with multiple AI agents. Each agent can have different providers and models.

Session Management

SQLite-based persistence with FTS5 full-text search across all sessions.

Token Usage Statistics

Track API consumption with detailed statistics:

• Real-time usage dashboard in Web Dashboard
• CLI command: magic usage
• Monthly budget with alert thresholds
• Per-model and per-session breakdown

Sensitive Data Redaction

Automatic redaction of API keys, tokens, passwords, and other sensitive information in logs and outputs.

Quick Start

Download Release

Download the latest binary from GitHub Releases:

# Linux / macOS
curl -L https://github.com/magicwubiao/go-magic/releases/latest/download/magic-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz
chmod +x magic-*
sudo mv magic-* /usr/local/bin/magic

Go Install

go install github.com/magicwubiao/go-magic/cmd/magic@latest

Docker

# Quick run
docker run -it magicwubiao/go-magic

# Docker Compose (includes optional Redis and PostgreSQL)
docker compose up -d

One-Line Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/magicwubiao/go-magic/main/scripts/install.sh | bash

First Run

# Interactive setup wizard
magic setup

# Start chatting
magic chat

# Start web dashboard
magic server

CLI Commands

TUI Slash Commands

Coding Mode

Switch to coding mode for development tasks:

/mode coding

Switch back with /mode chat.

Default Mode Configuration

Set the default startup mode in your config file:

{
  "chat_mode": "coding"
}

Available values: "chat" (default) or "coding".

Web Dashboard

Start the web server:

magic server

Then open http://localhost:5000 in your browser.

Features:

• Real-time chat with streaming responses
• Session management (create, search, resume)
• Provider and model configuration with hot-reload
• Skills management
• Cron job scheduling
• Kanban board
• Token usage dashboard with budget tracking
• Group chat for multi-agent conversations

Token Usage Tracking

Track your API consumption:

# Show today's usage
magic usage

# Show last 7 days
magic usage -d 7

# Show last 30 days
magic usage -d 30

In the Web Dashboard, navigate to the Usage page to see:

• Today's statistics
• Daily trend chart
• Monthly breakdown
• Budget progress bar with alerts
• Top models and sessions

Configuration

Create or edit ~/.magic/config.json:

{
  "profile": "default",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "providers": {
    "deepseek": {
      "api_key": "your-deepseek-api-key",
      "models": ["deepseek-chat", "deepseek-coder"]
    },
    "openai": {
      "api_key": "your-openai-api-key",
      "base_url": "https://api.openai.com/v1",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    },
    "anthropic": {
      "api_key": "your-anthropic-api-key",
      "models": ["claude-3-opus-20240229", "claude-3-sonnet-20240229"]
    },
    "ollama": {
      "base_url": "http://localhost:11434",
      "models": ["llama3", "codellama"]
    }
  },
  "tools": {
    "enabled": ["all"],
    "disabled": []
  },
  "gateway": {
    "enabled": false,
    "platforms": {
      "telegram": {
        "token": "your-telegram-bot-token",
        "enabled": false
      },
      "discord": {
        "token": "your-discord-bot-token",
        "enabled": false
      }
    }
  }
}

Multi-Model Configuration

Each provider supports multiple models:

"providers": {
  "deepseek": {
    "api_key": "your-api-key",
    "models": ["deepseek-chat", "deepseek-coder", "deepseek-reasoner"]
  }
}

• The first model in the array is the current active model
• Switch models instantly from Web Dashboard (no restart needed)
• Use /model provider:model in TUI to switch

Environment Variables

Building from Source

Requirements

• Go 1.25+
• Node.js 20+ (for web dashboard)

Build for Current Platform

make build

Cross-Platform Build

# All common platforms (Linux, macOS, Windows)
make build-all

# All supported platforms
make build-cross

# Specific platform
make build-linux
make build-macos
make build-windows

Supported Platforms

Download

Get the latest version from GitHub Releases.

License

MIT License -- see LICENSE for details.