Skip to main content
This quickstart guide will augment your agent-coding experience in just a few minutes. By the end, you’ll be creating specs and issues through your AI agent, with an optional web UI for visualization.

​
Step 1: Install sudocode

npm install -g sudocode

​
Step 2: Initialize project

cd your-project
sudocode init

​
Step 3: Configure your agent to use sudocode

Set up the sudocode MCP integration with your AI agent.

Claude

Version requirement: Make sure you’re running an up to date version of Claude Code.Check your version:
claude --version
If your version is lower than 2.0.35, update Claude Code:
claude update
1

Add sudocode plugin from marketplace and install

claude plugin marketplace add sudocode-ai/sudocode
claude plugin install sudocode

✓ Added sudocode-ai/sudocode to plugin marketplace
✓ Installed sudocode plugin
✓ MCP server configured
2

Verify installation

Start Claude Code and test the integration:
claude
Then ask Claude:
Can you create a "Hello World" issue?
If you see Claude using tools like plugin:sudocode:sudocode - upsert_issue, the setup is working!
Claude Code is now configured with sudocode! The plugin automatically handles MCP server configuration and working directory detection.
1

Add MCP Server

Add the sudocode MCP server to Codex:
codex mcp add sudocode-mcp -- sudocode-mcp
2

Verify Setup

Test that sudocode is working:
codex "create me a hello world issue"
If the setup is working, you’ll see Codex use the sudocode MCP tools to create the issue:
• Called sudocode-mcp.upsert_issue({"title":"Hello World example","description":"Create a simple Hello World program or script and include basic run instructions.","status":"open","priority":3})
  └ {"id": "i-5hio", "title": "Hello World example", "status": "open"}
Codex is now configured with sudocode!
Cursor CLI uses an MCP configuration file in the .cursor directory of your project root.
1

Create .cursor directory

In your project root directory, create a .cursor directory if it doesn’t exist:
mkdir -p .cursor
2

Create or edit .cursor/mcp.json

Open or create .cursor/mcp.json and add the following configuration:
{
  "mcpServers": {
    "sudocode-mcp": {
      "command": "sudocode-mcp"
    }
  }
}
If you already have other MCP servers configured, just add the "sudocode-mcp" entry inside the existing "mcpServers" object.
3

Enable the MCP Server (IDE Only)

Note, this step is only relevant if you want to communicate with sudocode inside of the cursor IDE, in addition to the CLI.After creating the configuration, enable the MCP server in Cursor:Option A: Click Enable (when prompted)When Cursor detects the new MCP configuration, an Enable button will appear on the left side. Click it to activate the sudocode MCP server.Cursor showing Enable button for sudocode MCP serverOption B: Enable via SettingsAlternatively, you can manually enable the MCP server:
  1. Go to Cursor > Settings > Cursor Settings
  2. Enable the MCP server
Cursor Settings page showing MCP enable option
Restart may be required to see the MCP Server under the list of tools! Once you enable the MCP server, it will be active immediately.
4

Verify Setup

CLI Flow

Test that sudocode is working via the Cursor CLI:
cursor-agent agent create me a hello world issue
If the setup is working, you’ll see Cursor use the sudocode MCP tools:
sudocode-mcp: upsert_issue(
  {
    "title": "Create hello world example",
    "description": "Add a minimal hello world example (text output) and ensure it can be executed easily from the repository.\n\nAcceptance:\n- A new hello world entry point exists and prints a greeting.\n- Include simple instructions to run it.",
    "priority": 3,
    "tags": [
      "docs",
      "example",
      "hello-world"
    ],
    "status": "open"
  }
)
If you want to use sudocode within the Cursor IDE (not just the CLI), you can test it by asking Cursor to create an issue:
Can you create a "Hello World" issue using sudocode?
If the setup is working, you’ll see Cursor use the sudocode MCP tools:Cursor successfully creating an issue using sudocode MCP
Cursor is now configured with sudocode! The MCP server will automatically run when you use sudocode tools in Cursor.
1

Start GitHub Copilot CLI

Start the Copilot CLI:
copilot
2

Configure MCP Server

In the Copilot CLI, run:
/mcp
This will open the MCP server configuration screen:
Add New MCP Server

Server Name:
Unique name for this MCP server
╭──────────────────────────────────────────────────────────────────╮
│                                                                  │
╰──────────────────────────────────────────────────────────────────╯

Server Type:
Press 1 for Local, 2 for HTTP, 3 for SSE
[1] Local [2] HTTP [3] SSE

Command:
Command to start the server (e.g., python -m my_server)
╭──────────────────────────────────────────────────────────────────╮
╰──────────────────────────────────────────────────────────────────╯

Environment Variables:
Path is automatically inherited. All other environment variables must be configured
╭──────────────────────────────────────────────────────────────────╮
╰──────────────────────────────────────────────────────────────────╯

Tools:
Tools to include: "*" for all, or comma-separated list (no quotes needed)
╭──────────────────────────────────────────────────────────────────╮
│*                                                                 │
╰──────────────────────────────────────────────────────────────────╯

Navigation:
• Tab/Shift+Tab: Navigate fields
• Ctrl+S: Save server
• Esc: Cancel
Fill in the following:
  • Server Name: sudocode-mcp
  • Server Type: Select [1] Local (default)
  • Command: sudocode-mcp
  • Tools: * (default, for all tools)
Press Ctrl+S to save the server configuration.
3

Verify Setup

Test that sudocode is working:
copilot -i "Create a hello world issue"
If the setup is working, you’ll see a prompt asking to approve the tool call:
● upsert_issue

╭────────────────────────────────────────────────────────────────╮
│ upsert_issue                                                   │
│                                                                │
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ {                                                          │ │
│ │   "title": "Hello World",                                  │ │
│ │   "description": "A simple hello world issue to get        │ │
│ │                   started.",                               │ │
│ │   "status": "open"                                         │ │
│ │ }                                                          │ │
│ ╰────────────────────────────────────────────────────────────╯ │
│                                                                │
│ Do you want to use this tool?                                  │
│                                                                │
│ ❯ 1. Yes                                                       │
│   2. Yes, and approve tool "upsert_issue" from server         │
│      "sudocode-mcp" for the rest of the running session       │
│   3. Yes, and approve all tools from server "sudocode-mcp"    │
│      for the rest of the running session                      │
│   4. No, and tell Copilot what to do differently (Esc)        │
│                                                                │
│ Confirm with number keys or ↑↓ keys and Enter, Cancel with   │
│ Esc                                                            │
╰────────────────────────────────────────────────────────────────╯
GitHub Copilot CLI is now configured with sudocode!
If you want to use sudocode within VS Code (not just the CLI), you can set it up using the Command Palette or by creating a configuration file:Method 1: Command Palette (Recommended)
1

Open Command Palette

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) to open the Command Palette.Type and select:
MCP: Add Server
VS Code Command Palette showing MCP: Add Server command
2

Select Command (stdio)

When prompted for the server type, select Command (stdio).MCP server type selection dialog showing Command (stdio) option
3

Enter command

Type the command:
sudocode-mcp
Enter Command dialog with sudocode-mcp typed in
4

Name the server

Give it a name (we recommend sudocode-mcp).Enter Server ID dialog with sudocode-mcp as the name
5

Choose Workspace

When prompted to choose between Global or Workspace, select Workspace.
Make sure to select Workspace (not Global) so the MCP server runs in your project directory.
Installation location dialog showing Global vs Workspace options with Workspace selected
6

Verify configuration

Check that .vscode/mcp.json was created in your project root:
cat .vscode/mcp.json
You should see something like this:
{
  "servers": {
    "sudocode-mcp": {
      "type": "stdio",
      "command": "sudocode-mcp",
      "args": []
    }
  },
  "inputs": []
}
VS Code showing the created .vscode/mcp.json file with sudocode-mcp configuration
Method 2: Manual ConfigurationAlternatively, create .vscode/mcp.json manually:
{
  "servers": {
    "sudocode-mcp": {
      "type": "stdio",
      "command": "sudocode-mcp",
      "args": []
    }
  },
  "inputs": []
}
Then reload VS Code to apply the configuration.Verify SetupTest that MCP tools are available in VS Code by opening GitHub Copilot and asking:
Can you create a "Hello World" issue using sudocode?
You should see a tool call from sudocode. You’re all set!Example of sudocode creating a hello world issue

​
Step 4: Create a test issue

With the MCP integration configured, you can now use your agent to create and link spec or issue docs as needed. No extra steps required. Start a conversation with your agent to define work: 
> User: I want to add dark mode support to our app. Can you create
  a spec for this?

⏺ Agent: I'll create a spec capturing the dark mode requirements.

⏺ plugin:sudocode:sudocode - upsert_spec (MCP)
  (title: "Dark Mode Support",
   description: "# Dark Mode Support

## Overview
Add dark mode theming to the application.

## Requirements
- Toggle between light and dark themes
- Persist user preference across sessions
- Respect system-level theme preference

## Open Questions
- Should we support custom accent colors?
- How should we handle third-party component theming?
")
  ⎿  { "id": "s-4x2k", ... }

⏺ Agent: Created spec s-4x2k. Now let me create an issue to start
  implementation.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Implement dark mode theme toggle",
   description: "Add a theme toggle component and implement CSS
   custom properties for light/dark themes.

   Implements [[s-4x2k]]",
   status: "open",
   priority: 2)
  ⎿  { "id": "i-7m3n", ... }

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-7m3n", to_id: "s-4x2k", type: "implements")

⏺ Agent: Created issue i-7m3n linked to the spec. Ready to start
  implementation whenever you are.
Your specs and issues are now stored locally in the sudocode/ directory of your project. You can continue discussing, refining, and breaking down the work entirely through your agent.

​
Step 5: Visualize with the web UI (optional)

To get a visual overview of your specs, issues, and their relationships, start the sudocode web server: 
sudocode server
The server will start at http://localhost:3000. Navigate there in your browser to see the project selector:
Project selector in the sudocode web interface
After selecting your project, you’ll see the issue board — a visual hub for tracking the specs and issues you created through your agent:
Issue board showing project tasks
From the web UI you can also create and edit specs and issues, run issues, and monitor execution sessions:
Running an issue in the sudocode web interface

​
Next Steps

Now that you’ve set up sudocode and created your first spec and issue, explore these guides to learn more:

Tracking Context Agentically

See how sudocode fits into a normal coding session

Test-Driven Debugging

Track a bug investigation as a chain of issues

Spec-Driven Development

Plan and implement features with specs and issues

Creating Issues

Learn different methods for creating and organizing issues

Creating Specs

Write specifications that guide your AI agents

Web Interface Overview

Explore all features of the sudocode web interface