mothx

README

MothX

🚀 One Binary to Rule Them All — Your AI Coding Assistant in the Terminal

Stop switching between Claude Code, Codex, Claw, and Hermes.
MothX packs everything into a single file — providers, tools, sandbox, sessions, skills, and more.

国内镜像: Gitee

Rename notice: MothX was formerly known as VibeCoding. During this transition release, legacy entry points such as the vibecoding command, the old installer package names, and VIBECODING_* environment variables are kept for compatibility. Legacy .vibecoding and .vibe directories are automatically migrated to .mothx when found.

---

✨ Why MothX?

The Problem: You're juggling multiple AI coding tools — Claude Code for one thing, Codex for another, Claw for something else. Each has its own setup, its own quirks, its own dependencies.

The Solution: MothX is the all-in-one terminal AI coding assistant that does it all. One binary. One config. Zero hassle.

🎯 Key Highlights

Feature	What It Means for You
⚙️ Workflow Mode	Dynamic Elisp workflows with phases, parallel execution, and multi-worker coordination — automate complex development pipelines
🤖 Multi-Provider	DeepSeek, OpenAI, Anthropic, Volcengine/Doubao, LongCat, Mistral, GitHub Copilot, Cloudflare, Amazon Bedrock, and 20+ vendor adapters — switch models instantly
⚡ Lightning Fast	SSE streaming, real-time token delivery, cache hit optimization
🧠 Think Mode	Extended reasoning for complex problems (DeepSeek, o1, Claude, inline <think> parsing)
🛡️ Sandboxed	bwrap process isolation — safe file ops, network control, approval gates
📝 Sessions	Persistent SQLite-backed history with branching, compaction, and tree structure
🧩 Skills	Reusable prompt snippets for project conventions — share across teams
💻 IDE Ready	ACP protocol for VS Code, Zed, JetBrains — native editor integration
🌐 Gateway	OpenAI-compatible HTTP API — use MothX as a backend service
📱 Messaging	WeChat, Feishu, WebSocket — deploy as a chatbot
🤝 Multi-Agent	Async sub-agents with --multi-agent, blocking delegation with --delegate, and A2A master mode
🎨 Rich TUI	Markdown rendering, syntax highlighting, thinking display, tool modals, multiline input
📊 Stats Dashboard	Web-based usage analytics with charts, filtering by time/vendor/protocol, and CLI fallback
🖼️ Multimodal	Image preprocessing, crop support, browser screenshots, and vision model integration
🔒 Security	bashBlacklist > whitelist, YOLO mode safety, --print fails fast
📦 Pure Go	No external binary dependencies — uses pure-Go grep/find SDKs, supports FreeBSD
⚡ Approval V2	Interactive approval dialog, project-level bash auto-approval rules, and auto-edit whitelists

---

🚀 Get Started in 30 Seconds

# Install (pick one)
npm install -g mothx-installer               # npm (recommended)
pipx install mothx-installer                # PyPI
curl -fsSL https://raw.githubusercontent.com/startvibecoding/mothx/main/install.sh | bash  # Linux/macOS/FreeBSD (GitHub)
curl -fsSL https://gitee.com/startvibecoding/mothx/raw/main/install.sh | bash  # Linux/macOS/FreeBSD (Gitee 国内镜像)

# Set your API key
export DEEPSEEK_API_KEY=sk-...

# Run
mothx

That's it. You're coding with AI.

Supported Platforms: Linux (x86_64, arm64), macOS (x86_64, arm64), Windows (x86_64), FreeBSD (x86_64, arm64)

Uninstall:

# npm
npm uninstall -g mothx-installer

# Compatibility package, if installed before the rename
npm uninstall -g vibecoding-installer

# PyPI
pipx uninstall mothx-installer

# Linux/macOS (one-line install)
curl -fsSL https://gitee.com/startvibecoding/mothx/raw/main/install.sh | bash -s -- --uninstall

# Windows (one-line install)
irm https://gitee.com/startvibecoding/mothx/raw/main/install.ps1 | iex; Uninstall-MothX

---

🎮 Three Modes for Every Situation

🗒️  Plan    → Read-only analysis & planning. Safe, sandboxed, no surprises.
🔧  Agent   → Standard read/write. Bash approval required. (Default)
🚀  YOLO    → Full system access. No restrictions. For the brave.

Switch modes anytime with /mode plan|agent|yolo or press Tab.

---

🏗️ Architecture at a Glance

mothx/
├── cmd/mothx/        # CLI entry point
├── internal/
│   ├── agent/             # Core agent loop
│   ├── provider/          # LLM provider abstraction (20+ vendors)
│   ├── tools/             # Built-in tools (read, write, bash, grep, find, ...)
│   ├── sandbox/           # bwrap sandbox implementation
│   ├── session/           # SQLite session storage
│   ├── skills/            # Skills system
│   ├── tui/               # Terminal UI (BubbleTea + Lipgloss)
│   ├── gateway/           # OpenAI-compatible HTTP gateway
│   ├── hermes/            # Messaging gateway (WeChat/Feishu/WebSocket)
│   ├── a2a/               # A2A protocol server & master mode
│   ├── acp/               # ACP / MCP integration
│   ├── stats/             # Usage statistics web dashboard
│   ├── workflow/          # Elisp workflow runtime
│   └── memory/            # Persistent memory (memory.md)
└── pkg/sdk/               # Public SDK interface

---

📚 Documentation

🚀 Getting Started

• Quick Start — Installation, configuration, first run
• CLI Reference — All commands and flags

⚙️ Configuration

• Configuration Guide — Settings, env vars, authentication
• Provider Guide — Provider/vendor configuration

🏗️ Architecture

• System Architecture — Core components, data flow
• Tool System — Built-in tools guide
• Skills System — Reusable prompt snippets
• Online Skill Marketplace — SkillHub / ClawHub integration
• Dynamic Workflows — Elisp workflow automation

🔒 Security

• Security & Sandbox — Sandbox modes, permissions, approval

💻 IDE Integration

• ACP Protocol — VS Code, Zed, JetBrains integration

🌐 Gateway Modes

• Gateway Mode — OpenAI-compatible HTTP API
• Hermes Mode — WeChat/Feishu/WebSocket chatbot
• A2A Protocol — Agent-to-Agent protocol

📊 Analytics

• Stats Dashboard — Usage statistics and monitoring

📖 Tutorials

• Scenarios & Walkthroughs — Practical examples
• FAQ — Common questions answered

🇨🇳 中文文档

• 中文文档首页 — 完整中文文档

---

🎯 Use Cases

💻 Daily Development

mothx -P "Refactor this function to use generics"
mothx -P "Write tests for the UserService struct"
mothx -P "Explain what this regex does"

🔍 Code Review

mothx --mode plan "Review this PR and suggest improvements"

🚀 CI/CD Integration

mothx -p "Generate changelog from git log" > CHANGELOG.md

🌐 API Server

mothx gateway  # Start OpenAI-compatible HTTP server

📱 Chatbot

mothx hermes   # Deploy as WeChat/Feishu bot

📊 Usage Analytics

mothx stats    # Start web dashboard on 127.0.0.1:7878
mothx stats --cli  # Print stats in terminal

🔄 Dynamic Workflows

mothx --workflows  # Enable Elisp workflow automation
# Use workflow_run, workflow_status, workflow_cancel tools

🖼️ Image Analysis

mothx -P "Describe this screenshot" --image screenshot.png
mothx -P "Extract text from this image" --image document.jpg

---

🛠️ Built-in Tools

Tool	Description
read	Read file contents
write	Create/overwrite files
edit	Precise text replacement
bash	Execute shell commands
grep	Search file contents (powered by pure-Go ripgrep)
find	Find files by pattern (powered by pure-Go fd)
ls	List directory contents
plan	Publish task plans
jobs	Manage background jobs
kill	Stop background jobs
skill_ref	Load skill references
workflow_run	Execute Elisp workflow DSL
workflow_status	Check workflow run status
workflow_cancel	Cancel running workflows
delegate_subagent	Blocking single sub-agent delegation
subagent_spawn	Async sub-agent execution
question	Interactive user prompts (plan/agent modes)

---

🔧 Configuration

Settings Files

Location	Platform	Scope
~/.mothx/settings.json	Linux/macOS/FreeBSD	Global
%APPDATA%\mothx\settings.json	Windows	Global
.mothx/settings.json	All	Project (overrides global)

Existing .vibecoding and .vibe directories are automatically migrated to .mothx when the destination does not already exist. VIBECODING_* environment variables remain supported for compatibility; use MOTHX_DIR for new custom config directory overrides.

Environment Variables

Variable	Description
DEEPSEEK_API_KEY	DeepSeek API key
MOTHX_DIR	Override config directory
VIBECODING_DIR	Override config directory (legacy compatibility)
VIBECODING_PROVIDER	Override default provider
VIBECODING_MODEL	Override default model
VIBECODING_MODE	Override default mode
VIBECODING_DEBUG	Enable debug output
VIBECODING_NO_UPDATE_CHECK	Disable update notifications
VIBECODING_NPM_REGISTRY	Override npm registry URL

Gateway Configuration

Gateway-specific config lives in gateway.json (global ~/.mothx/gateway.json, project .mothx/gateway.json). See Gateway Mode for details.

Hermes Configuration

Hermes-specific config lives in hermes.json (global <GLOBAL_DIR>/hermes.json, project .mothx/hermes.json). See Hermes Mode for details.

---

🤝 Contributing

We welcome contributions! See Development Guide for details.

git clone https://github.com/startvibecoding/mothx.git
cd mothx
make build
make test

---

📄 License

MIT — see LICENSE for details.

---

Ready to vibe? ⭐ Star this repo and start coding!