mothx

README

MothX

默思 | 中文名称

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

Stop switching between Claude Code, Codex, Claw, and Channels.
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 JavaScript 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
🌐 Serve	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)
curl -fsSL https://mothx.net/install.sh | bash       # Linux/macOS/FreeBSD; installs Node.js LTS if needed
# Windows (Command Prompt):
curl.exe -fsSL https://mothx.net/install.bat -o install.bat && install.bat

# Docker (GHCR, Linux amd64/arm64)
docker run --rm -it --entrypoint bash ghcr.io/startvibecoding/mothx:latest
docker run --rm -it -v "$PWD:/workspace" -w /workspace ghcr.io/startvibecoding/mothx:latest

# 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://mothx.net/install.sh | bash -s -- --uninstall

# Windows
npm uninstall -g mothx-installer

---

🎮 Three Modes for Every Situation

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

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)
│   ├── serve/             # Unified OpenAI API, Web UI, and messaging channels
│   ├── a2a/               # A2A protocol server & master mode
│   ├── acp/               # ACP / MCP integration
│   ├── stats/             # Usage statistics web dashboard
│   ├── workflow/          # JavaScript workflow runtime
│   └── memory/            # Persistent memory (memory.md)
└── agent/               # Public Go SDK types and interfaces (bootstrap/ wires implementations)

---

📚 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 — JavaScript workflow automation

🔒 Security

• Security & Sandbox — Sandbox modes, permissions, approval

💻 IDE Integration

• ACP Protocol — VS Code, Zed, JetBrains integration

🌐 Serve Mode

• Serve Mode — OpenAI-compatible HTTP API, Web UI, and messaging channels
• A2A Protocol — Agent-to-Agent protocol

📊 Analytics

• Stats & Monitoring — 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 serve  # Start OpenAI-compatible HTTP server

📱 Chatbot

mothx serve   # 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 JavaScript 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 JavaScript 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

Serve Configuration

Serve config lives in serve.json (global ~/.mothx/serve.json, project .mothx/serve.json) and covers the OpenAI-compatible API, Web UI, cron, memory, and messaging channels. See Serve 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!