Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monk.io/llms.txt

Use this file to discover all available pages before exploring further.

The Monk agent plugin lets Claude Code, Codex, and Cursor install and connect to Monk directly. Use this flow when you want Monk available from your coding agent without installing the Monk IDE extension first.
The plugin installs the local monk-agent companion and connects to its MCP endpoint on 127.0.0.1:7419. The agent still asks for approval before privileged Monk operations.

​
Choose the Right Install Flow

FlowBest forWhat configures Monk
IDE extension setupVS Code, Cursor, Windsurf, Antigravity, Copilot, and existing IDE workflowsThe Monk extension writes MCP config for the current workspace
Agent plugin setupClaude Code, Codex, and Cursor users who want direct plugin installThe host plugin installs the Monk skill, starts monk-agent, and exposes Monk over MCP
You only need one flow for a given agent. If Monk is already working through the IDE extension, you do not need to install the agent plugin.

​
Requirements

  • Claude Code, OpenAI Codex, or Cursor with plugin support.
  • Network access to GitHub and https://get.monk.io/stable so the plugin can download the signed monk-agent archive.
  • Permission to run a local helper process on loopback, normally 127.0.0.1:7419.
  • On macOS and Linux, a shell that can run the bundled scripts/start-monk-agent.sh.
  • On Windows, PowerShell or cmd.exe for the bundled Windows launcher.
The plugin installs monk-agent under your user profile:
OSInstalled files
macOS / Linux~/.monk/bin/monk-agent, ~/.monk/bin/monk-agent.sha256, ~/.monk/agent
Windows%USERPROFILE%\.monk\bin\monk-agent.exe, %USERPROFILE%\.monk\bin\monk-agent.sha256, %USERPROFILE%\.monk\agent

​
Install in Claude Code

Run these commands inside Claude Code: 
/plugin marketplace add monk-io/monk-plugin
/plugin install monk@monk-plugins
Then reload the current Claude Code session: 
/reload-plugins
After reload, run: 
/mcp
Monk should appear as an MCP server. If Claude Code asks you to authenticate MCP, complete the browser sign-in flow from /mcp.

​
Updating Claude Code

When a new Monk plugin version is available, update and reload: 
/plugin update monk@monk-plugins
/reload-plugins
If Claude Code still shows an old version, run the update command again and then reload plugins.

​
Install in Codex

Add the Monk marketplace from your terminal: 
codex marketplace add monk-io/monk-plugin
Start Codex in the project where you want to use Monk: 
codex
Open the plugin browser: 
/plugins
In the plugin browser, open the monk-plugins marketplace and install Monk. Restart Codex after installation so the Monk skill and MCP config are loaded. Verify the MCP connection: 
/mcp
If Codex reports that Monk needs authentication, run: 
codex mcp login monk
Complete the browser sign-in flow, then return to Codex and run /mcp again.
The tested Codex CLI command is codex marketplace add monk-io/monk-plugin. Do not use codex plugin marketplace add; that is not the Codex CLI marketplace command.

​
Install in Cursor

Run this command inside Cursor chat: 
/add-plugin https://github.com/monk-io/monk-plugin
Restart Cursor after installation. Then open Settings → Tools & MCP and confirm Monk is listed and enabled. If Cursor reports that Monk needs login, use Cursor’s MCP login flow for the monk server. Clearing host-side MCP auth is not the same as signing out of Monk; after auth is cleared, the Monk MCP endpoint returns 401 until Cursor obtains a new bearer token.

​
What Happens During Plugin Startup

After the host installs the plugin:
1

The host loads the Monk skill and plugin manifest

Claude Code, Codex, or Cursor reads the plugin metadata and makes Monk available to the agent.
2

The plugin starts monk-agent

The bundled launcher installs monk-agent if it is missing, starts it locally, and waits for the MCP endpoint.
3

monk-agent checks runtime state

The local agent verifies Monk CLI, daemon, auth, and workspace state. If setup is needed, it opens the local dashboard or browser sign-in flow.
4

Your coding agent connects over MCP

The host talks to Monk at http://127.0.0.1:7419/mcp. Privileged operations still go through Monk approval flows.
The coding agent should call Monk MCP tools for infrastructure and runtime operations. It should not run direct monk ... shell commands to operate live Monk-managed infrastructure.

​
Local Development Install

Use these commands only when testing a local checkout.

​
Claude Code local plugin

From Claude Code: 
/plugin install /path/to/monk-plugin
/reload-plugins
From a local monk-agent checkout, you can refresh the generated plugin and local agent together: 
deno task plugin:local
That task builds monk-agent, installs it to ~/.monk/bin, renders the generated plugin, restarts the local agent, and refreshes Claude Code’s local plugin marketplace/cache copies.

​
Codex local plugin

From a local monk-agent checkout: 
deno task plugin:build
codex marketplace add ./dist/plugin
codex
Then run /plugins, open the monk-plugins marketplace, and install Monk.

​
Uninstall

First uninstall the plugin from the host:
HostUninstall path
Claude CodeUse Claude Code’s plugin commands for monk@monk-plugins
CodexOpen /plugins and remove Monk from the monk-plugins marketplace
CursorRemove Monk from Cursor’s plugin UI
Host uninstall removes the host plugin, but hosts do not currently run a portable cleanup hook for companion processes or runtime packages. To remove the local companion, run the cleanup script from the plugin checkout: 
./scripts/uninstall-monk-agent.sh --yes
On Windows: 
.\scripts\uninstall-monk-agent.ps1 -Yes
To also remove the Monk runtime components installed by Monk, add the runtime option: 
./scripts/uninstall-monk-agent.sh --runtime --yes

.\scripts\uninstall-monk-agent.ps1 -Runtime -Yes

​
Troubleshooting

​
The host does not show Monk

  • Reload or restart the host after installation.
  • In Claude Code, run /reload-plugins, then /mcp.
  • In Codex, run /plugins and confirm Monk is installed from monk-plugins.
  • In Cursor, open Settings → Tools & MCP and confirm Monk is enabled.

​
The MCP server is missing or offline

  • Confirm no other process is blocking 127.0.0.1:7419.
  • Restart the host so the bundled launcher can start monk-agent again.
  • If you are testing locally, rebuild the plugin with deno task plugin:build before installing it.

​
Authentication is required

  • Claude Code: run /mcp and use the MCP authentication prompt.
  • Codex: run codex mcp login monk.
  • Cursor: use Cursor’s MCP login flow for the monk server.

​
The plugin downloaded but Monk runtime setup is incomplete

Ask your coding agent: 
ask Monk to check installation status
Monk will inspect the local runtime, open any required sign-in or setup flow, and continue after checks pass.

Troubleshooting

More setup and connection issues