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

Install the MothX extension
Make sure the mothx CLI is installed and available on your PATH (see MothX)
Open the MothX panel from the Activity Bar
Click MothX to connect
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.

MothX

Mothx Code Agent