Quick Start

This quickstart guide will augment your agent-coding experience in just a few minutes. By the end, you’ll be able to visualize your context and orcehstrate your coding agents using sudocode.

Step 1: Install sudocode

npm install -g sudocode

Step 2: Initialize project

cd your-project
sudocode init

Step 3: Start the web server

sudocode server

The server will start at http://localhost:3000. Keep this terminal running.

Step 4: Set up your agent (Optional)

Open a new terminal and set up the sudocode MCP integration with your AI agent.

This step is optional for all agents except for Cursor CLI.If you want to interact with sudocode directly in your own CLI agent, follow these instructions to do so.

Claude

Version requirement: Make sure you’re running Claude Code version 2.0.35 or higher.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 CLI (Required)

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 5: Open your project and create your first issue

Navigate to http://localhost:3000 in your browser. You’ll see the project selector where you can choose your project:

Project selector in the sudocode web interface

After selecting your project, you’ll see the issue board - your hub for tracking and managing work:

Click the ”+ Create Issue” button on the issue board to create an issue directly:

Step 6: Implement the issue

Once you’ve created your issue, select it and click the run button to start your issue.

Running an issue in the sudocode web interface

Now you can watch the issue execute, and continue the conversation in the issue session!

Next Steps

Now that you’ve created and run your first issue, explore these guides to learn more:

Agent Workflows Tutorial

See practical workflow examples for AI agents

Spec-Driven Development Tutorial

Follow a complete workflow from spec creation to implementation

Collaborative Data Analysis Tutorial

Build data analysis notebooks through iterative spec refinement

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

Getting Started

Examples & Tutorials

Core Concepts

Step 1: Install sudocode

Step 2: Initialize project

Step 3: Start the web server

Step 4: Set up your agent (Optional)

Step 5: Open your project and create your first issue

Step 6: Implement the issue

Next Steps

Agent Workflows Tutorial

Spec-Driven Development Tutorial

Collaborative Data Analysis Tutorial

Creating Issues

Creating Specs

Web Interface Overview

Getting Started

Examples & Tutorials

Core Concepts

​Step 1: Install sudocode

​Step 2: Initialize project

​Step 3: Start the web server

​Step 4: Set up your agent (Optional)

​Step 5: Open your project and create your first issue

​Step 6: Implement the issue

​Next Steps

Agent Workflows Tutorial

Spec-Driven Development Tutorial

Collaborative Data Analysis Tutorial

Creating Issues

Creating Specs

Web Interface Overview

Step 1: Install sudocode

Step 2: Initialize project

Step 3: Start the web server

Step 4: Set up your agent (Optional)

Step 5: Open your project and create your first issue

Step 6: Implement the issue

Next Steps