OpenMono Agent
Publisher: StartupHakk
Extension ID: StartupHakk.openmono-agent
A VS Code / Cursor chat panel for the OpenMono coding agent. The extension handles workspace tools (files, bash, grep, patches, permissions). The .NET agent handles the LLM, sessions, memory, MCP, and playbooks.
Architecture
VS Code (this extension) ──HTTP/SSE──► ACP agent :7475 ──► LLM (local or relay)
| Component |
Role |
| OpenMono Agent extension |
Chat UI, tool execution in your workspace |
OpenMono CLI agent (--acp-only) |
ACP server on port 7475, LLM calls, session history |
| LLM |
llama-server locally, or remote relay (e.g. relay.openmonoagent.ai) |
Requirements
- VS Code 1.85+ or Cursor
- .NET 10 SDK (to run the agent from source)
- OpenMono agent running in ACP mode for the same workspace folder you have open in the editor
- LLM endpoint configured in
%USERPROFILE%\.openmono\settings.json (Windows) or ~/.openmono/settings.json (macOS/Linux)
Optional: Docker — only if you want the extension to auto-spawn the agent in a container (not required when you start the agent manually).
Quick start
Create or edit %USERPROFILE%\.openmono\settings.json:
{
"llm": {
"endpoint": "http://relay.openmonoagent.ai:10422",
"api_key": "YOUR_LLAMA_API_KEY"
}
}
2. Start the ACP agent (per workspace)
The agent --workdir must match the folder open in VS Code.
Windows (PowerShell):
cd D:\path\to\openmono.ai\public
dotnet run --project src\OpenMono.Cli\OpenMono.Cli.csproj -c Release -- `
--workdir D:\path\to\your-project `
--acp-only `
--acp-port 7475
Leave this terminal running. You should see:
ACP server listening on http://127.0.0.1:7475
3. Use the extension
- Install OpenMono Agent from the marketplace (or install a
.vsix).
- Open your project folder in VS Code (same path as
--workdir).
- Open the OpenMono Agent icon in the activity bar → Chat.
- Click Start Agent (or it connects automatically if discovery succeeds).
Verify the agent
(Invoke-WebRequest http://127.0.0.1:7475/api/v1/discovery -UseBasicParsing).Content
host_workspace in the JSON must match your editor workspace path (case-insensitive on Windows).
Extension settings
| Setting |
Default |
Description |
openmono.agentImage |
openmono/agent:latest |
Docker image if the extension spawns the agent |
openmono.agentLifecycle |
managed |
managed stops container on exit; persistent keeps it running |
openmono.dockerCommand |
docker |
Path to Docker CLI |
openmono.acpPort |
7475 |
Port the extension probes to find a locally-run agent; must match the agent's --acp-port |
LLM settings (endpoint, api_key, model, etc.) live in the agent config (~/.openmono/settings.json), not in this extension.
Commands
| Command |
Description |
| OpenMono Agent: Start Agent for Workspace |
Connect / spawn agent for active folder |
| OpenMono Agent: Stop Agent |
Disconnect (stops managed Docker container if spawned) |
| OpenMono Agent: Clear Session |
Clear chat session with the agent |
| OpenMono Agent: Select Workspace Folder |
Switch folder in multi-root workspaces |
Troubleshooting
| Symptom |
Fix |
| Agent unavailable / Docker error |
Start the .NET agent with --acp-only (Docker is optional). |
| No ACP agent found for this workspace |
--workdir must equal the folder open in VS Code. |
| Port 7475 already in use |
Stop the old process or use another port (extension defaults to 7475). |
| Agent works in terminal but not extension |
You started --classic (TUI only). Use --acp-only for the extension. |
Development
cd extensions/openmono-agent
npm install
npm run compile
npm test
Press F5 in VS Code to launch an Extension Development Host (see PUBLISHING.md).
License
AGPL-3.0-or-later — see repository root / public/LICENSE.
Links
