mothx

module

v1.3.108-pre-2 Latest Latest Go to latest Published: Nov 11, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/oschina/mothx

Links

Open Source Insights

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. 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/oschina/mothx:latest
docker run --rm -it -v "$PWD:/workspace" -w /workspace ghcr.io/oschina/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/oschina/mothx.git
cd mothx
make build
make test

📄 License

MIT — see LICENSE for details.

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

Directories ¶

Path	Synopsis
agent Package agent defines the public Agent interface and related types.	Package agent defines the public Agent interface and related types.
bootstrap Package bootstrap wires the internal agent and provider implementations into the public agent package.	Package bootstrap wires the internal agent and provider implementations into the public agent package.
cmd
mothx command
example
custom_provider command
simple_agent command
experts Package experts embeds the built-in expert bundle seed packages shipped with the binary.	Package experts embeds the built-in expert bundle seed packages shipped with the binary.
internal
a2a Package a2a implements the A2A (Agent-to-Agent) protocol server.	Package a2a implements the A2A (Agent-to-Agent) protocol server.
acp
acp/client Package client implements the client side of ACP v1 over stdio, WebSocket, or streamable HTTP/SSE.	Package client implements the client side of ACP v1 over stdio, WebSocket, or streamable HTTP/SSE.
agent
agentruntime Package agentruntime contains front-end-neutral execution policy primitives.	Package agentruntime contains front-end-neutral execution policy primitives.
agentruntime/workerdriver Package workerdriver resolves the typed capability surface of one external ACP worker.	Package workerdriver resolves the typed capability surface of one external ACP worker.
ai/title Package title provides provider-neutral conversation title generation.	Package title provides provider-neutral conversation title generation.
browser
config
context
contextfiles
cron Package cron implements scheduled task management for vibecoding.	Package cron implements scheduled task management for vibecoding.
dao Package dao contains persistence-only data access objects.	Package dao contains persistence-only data access objects.
db Package db owns the process-wide SQLite connection lifecycle.	Package db owns the process-wide SQLite connection lifecycle.
debugpprof
doctor Package doctor owns the machine-readable installation and runtime checks.	Package doctor owns the machine-readable installation and runtime checks.
esm
expert Package expert implements the expert bundle format (manifest + persona markdown) and the ExpertCenter layered directory sources (builtin/global/project with name shadowing) used to bind persona content packs to sessions.	Package expert implements the expert bundle format (manifest + persona markdown) and the ExpertCenter layered directory sources (builtin/global/project with name shadowing) used to bind persona content packs to sessions.
imageproc
mcp
memory Package memory implements persistent memory storage for serve channels.	Package memory implements persistent memory storage for serve channels.
messaging Package messaging defines the messaging platform abstraction for serve channels.	Package messaging defines the messaging platform abstraction for serve channels.
messaging/feishu Package feishu implements the Feishu (Lark) messaging platform adapter.	Package feishu implements the Feishu (Lark) messaging platform adapter.
messaging/wechat Package wechat implements the WeChat iLink Bot messaging platform adapter.	Package wechat implements the WeChat iLink Bot messaging platform adapter.
platform Package platform provides cross-platform compatibility utilities.	Package platform provides cross-platform compatibility utilities.
provider
provider/anthropic
provider/factory
provider/google
provider/openai
sandbox
serve
serve/channels
serve/hooks Package hooks implements shell hook scripts for serve channels.	Package hooks implements shell hook scripts for serve channels.
serve/openaiapi
serve/runtime
session
skillhub Package skillhub provides marketplace clients and safe local installation for skills.	Package skillhub provides marketplace clients and safe local installation for skills.
skills
stats
systeminit Package systeminit builds the prompt used by the /systeminit command to generate (or refresh) a project-level AGENTS.md guide for AI agents.	Package systeminit builds the prompt used by the /systeminit command to generate (or refresh) a project-level AGENTS.md guide for AI agents.
terminal
tools
tui
tui/components/editor
tui/components/suggest
tui/components/vscroll
tui/i18n
tui/renderutil
tui/statusline
ua Package ua provides User-Agent string generation for vibecoding.	Package ua provides User-Agent string generation for vibecoding.
update Package update provides non-blocking version update detection based on the npm registry.	Package update provides non-blocking version update detection based on the npm registry.
util
version Package version contains the product version shared by every entry point.	Package version contains the product version shared by every entry point.
workflow
workspacefiles Package workspacefiles provides the single read-only file projection used by every front-end adapter (WebUI/API, future ACP).	Package workspacefiles provides the single read-only file projection used by every front-end adapter (WebUI/API, future ACP).
workspaceopen Package workspaceopen is the ONE owner of external-launch policy for a session working directory.	Package workspaceopen is the ONE owner of external-launch policy for a session working directory.
worktree Package worktree owns the git worktree mechanics used by the Runtime: name planning, materialization, listing, removal and reset.	Package worktree owns the git worktree mechanics used by the Runtime: name planning, materialization, listing, removal and reset.
ui

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL