Quick Start - sudocode

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

Add sudocode plugin from marketplace and install

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

Expected output

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

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.

Codex

Add MCP Server

Add the sudocode MCP server to Codex:

codex mcp add sudocode-mcp -- sudocode-mcp

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:

Expected output

• 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 IDE/CLI

Cursor CLI uses an MCP configuration file in the .cursor directory of your project root.

Create .cursor directory

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

mkdir -p .cursor

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.

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 server

Option B: Enable via SettingsAlternatively, you can manually enable the MCP server:

Go to Cursor > Settings > Cursor Settings
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.

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:

Expected output

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"
  }
)

IDE Flow

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.

GitHub Copilot CLI

Start GitHub Copilot CLI

Start the Copilot CLI:

copilot

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.

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:

Expected output

● 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!

Optional IDE Support

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)

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

Select Command (stdio)

When prompted for the server type, select Command (stdio).

MCP server type selection dialog showing Command (stdio) option

Enter command

Type the command:

sudocode-mcp

Enter Command dialog with sudocode-mcp typed in

Name the server

Give it a name (we recommend sudocode-mcp).

Enter Server ID dialog with sudocode-mcp as the name

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

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:

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

​Step 1: Install sudocode

​Step 2: Initialize project

​Step 3: Configure your agent to use sudocode

​Step 4: Create a test issue

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

​Next Steps

Tracking Context Agentically

Test-Driven Debugging

Spec-Driven Development

Creating Issues

Creating Specs

Web Interface Overview

Step 1: Install sudocode

Step 2: Initialize project

Step 3: Configure your agent to use sudocode

Step 4: Create a test issue

Step 5: Visualize with the web UI (optional)

Next Steps