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. The vibecoding command and old installer package names remain compatibility aliases. Configuration is read only from .mothx project directories and the MothX global configuration directory; legacy directories are neither read nor migrated.

✨ 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)

MothX reads configuration only from the .mothx locations above. It does not read or migrate legacy .vibecoding or .vibe directories. Use MOTHX_DIR to select a custom global configuration directory.

Environment Variables

Variable	Description
`DEEPSEEK_API_KEY`	DeepSeek API key
`MOTHX_DIR`	Override config directory
`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!

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.workflow		.workflow
agent		agent
bootstrap		bootstrap
cmd/mothx		cmd/mothx
desktop		desktop
docs		docs
example		example
experts		experts
internal		internal
npm		npm
packaging		packaging
pypi		pypi
scripts		scripts
ui		ui
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
install.bat		install.bat
install.ps1		install.ps1
install.sh		install.sh

Navigation Menu

Repository files navigation

MothX

✨ Why MothX?

🎯 Key Highlights

🚀 Get Started in 30 Seconds

🎮 Three Modes for Every Situation

🏗️ Architecture at a Glance

📚 Documentation

🚀 Getting Started

⚙️ Configuration

🏗️ Architecture

🔒 Security

💻 IDE Integration

🌐 Serve Mode

📊 Analytics

📖 Tutorials

🇨🇳 中文文档

🎯 Use Cases

💻 Daily Development

🔍 Code Review

🚀 CI/CD Integration

🌐 API Server

📱 Chatbot

📊 Usage Analytics

🔄 Dynamic Workflows

🖼️ Image Analysis

🛠️ Built-in Tools

🔧 Configuration

Settings Files

Environment Variables

Serve Configuration

🤝 Contributing

📄 License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

MothX

✨ Why MothX?

🎯 Key Highlights

🚀 Get Started in 30 Seconds

🎮 Three Modes for Every Situation

🏗️ Architecture at a Glance

📚 Documentation

🚀 Getting Started

⚙️ Configuration

🏗️ Architecture

🔒 Security

💻 IDE Integration

🌐 Serve Mode

📊 Analytics

📖 Tutorials

🇨🇳 中文文档

🎯 Use Cases

💻 Daily Development

🔍 Code Review

🚀 CI/CD Integration

🌐 API Server

📱 Chatbot

📊 Usage Analytics

🔄 Dynamic Workflows

🖼️ Image Analysis

🛠️ Built-in Tools

🔧 Configuration

Settings Files

Environment Variables

Serve Configuration

🤝 Contributing

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages