MothX for VS Code

The official MothX extension for Visual Studio Code — an AI coding agent powered by the Agent Client Protocol (ACP). Chat with MothX directly from your editor, let it read and edit files, run commands, and manage your sessions all from a dedicated sidebar.

Features

• First-class MothX integration: ships with MothX pre-configured — just connect and start chatting
• Multi-session support: each agent in the Agents view is expandable into its previous sessions. Click a session to restore its history in the chat. Backed by session/list when the agent supports it, or by a local per-workspace cache otherwise
• Session Config Options: dynamic per-session selectors (mode, model, reasoning level, …) advertised by the agent are rendered automatically in the composer toolbar
• Interactive Chat: built-in chat panel with Markdown rendering, inline tool call display, and collapsible tool sections
• Thinking Display: see agent reasoning in a collapsible block with streaming animation and elapsed time
• Slash Commands: autocomplete popup for agent-provided commands with keyboard navigation
• Mode & Model Picker: switch agent modes and models directly from the chat toolbar
• File System Integration: MothX can read and write files in your workspace
• Terminal Execution: MothX can run commands with terminal output display
• Permission Management: configurable auto-approve policies for agent actions
• Protocol Traffic Logging: inspect all ACP JSON-RPC messages with request/response/notification labels
• Chat Persistence: conversations are preserved when switching panels

Quick Start

1. Install the MothX extension
2. Make sure the mothx CLI is installed and available on your PATH (see MothX)
3. Open the MothX panel from the Activity Bar
4. Click MothX to connect
5. Start chatting!

Requirements

• Node.js 18+
• The mothx CLI installed and on your PATH
• VS Code 1.85+

Default Agent

The extension comes pre-configured with MothX:

Agent	Command
MothX	mothx acp --mode agent

You can add more ACP-compatible agents in settings if you wish.

Extension Settings

Setting	Default	Description
mothx.agents	{ MothX }	Agent configurations. Each key is the agent name, value has command, args, and env.
mothx.autoApprovePermissions	ask	How agent permission requests are handled: ask or allowAll.
mothx.defaultWorkingDirectory	""	Default working directory for agent sessions. Empty uses the current workspace.
mothx.logTraffic	true	Log all ACP protocol traffic to the MothX Traffic output channel.

Commands

All commands are accessible via the Command Palette (Ctrl+Shift+P):

Command	Description
MothX: Connect to Agent	Connect to an agent
MothX: New Conversation	Start a new conversation with the connected agent
MothX: Send Prompt	Send a message to the agent
MothX: Cancel Current Turn	Cancel the current agent turn
MothX: Disconnect Agent	Disconnect from the current agent
MothX: Restart Agent	Restart the current agent process
MothX: Open Chat Panel	Focus the chat webview
MothX: Add Agent Configuration	Add a new agent to settings
MothX: Remove Agent	Remove an agent configuration
MothX: Set Agent Mode	Change the agent's operating mode
MothX: Set Agent Model	Change the agent's model
MothX: Refresh Sessions	Re-fetch the session list for an agent
MothX: Show Log	Open the MothX log output channel
MothX: Show Protocol Traffic	Open the MothX Traffic output channel
MothX: Browse Agent Registry	Browse the ACP agent registry

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+A (Cmd+Shift+A on Mac)	Open Chat Panel
Escape (when a turn is in progress)	Cancel Current Turn

Development

Prerequisites

• Node.js 18+
• VS Code 1.85+

Setup

npm install

Build & Run

npm run compile    # One-time build
npm run watch      # Watch mode for development
npm run dev        # Launch a VS Code Extension Development Host with the MothX extension loaded (auto-recompiles on save)

You can also open a specific workspace in the dev host:

npm run dev -- /path/to/your/project

Alternatively, open the project in VS Code and press F5 to launch the Extension Development Host (this uses the bundled .vscode/launch.json and also starts the webpack watch task).

Testing

npm run pretest    # Compile tests + lint
npm test           # Run tests

Packaging

npm run package               # Production build
npx @vscode/vsce package      # Create .vsix

Architecture

The extension follows a modular architecture:

• Core: AgentManager, ConnectionManager, SessionManager, AcpClientImpl
• Handlers: FileSystemHandler, TerminalHandler, PermissionHandler, SessionUpdateHandler
• UI: SessionTreeProvider, ChatWebviewProvider, StatusBarManager
• Config: AgentConfig, RegistryClient
• Utils: Logger, StreamAdapter

Communication with agents uses the ACP protocol (JSON-RPC 2.0 over stdio).

License

MIT — see LICENSE for details.