### CLI Config Command Examples

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/specs/markdown-source-of-truth.md

Shows how to use the `sudocode config` command to set and get the `sourceOfTruth` setting, which determines the primary storage mode.

```bash
# Set source of truth
sudocode config set sourceOfTruth markdown

# View current setting
sudocode config get sourceOfTruth
```

--------------------------------

### Workflow Example: Working on Issues

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Guide for finding ready issues, updating their status to 'in_progress', closing them upon completion, and checking project statistics.

```bash
# 1. Find ready issues
sudocode ready --type issue

# 2. Start work on an issue
sudocode issue update issue-010 --status in_progress

# 3. Complete the issue
sudocode issue close issue-010 --reason "Implemented and tested"

# 4. Check project status
sudocode stats
```

--------------------------------

### Sudocode Quickstart Guide Content

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/mcp.md

Provides an introduction to the Sudocode workflow, core concepts like specs and issues, and a typical agent workflow. It also lists relationship types.

```markdown
# Sudocode Quickstart

Sudocode is a git-native spec and issue management system designed for AI-assisted development.

## Core Concepts

**Specs**: Technical specifications stored as markdown files
- Types: architecture, api, database, feature, research
- Status: draft → review → approved → deprecated
- Each spec has a unique ID (e.g., sudocode-spec-1) and file path

**Issues**: Work items tracked in the database
- Types: bug, feature, task, epic, chore
- Status: open → in_progress → blocked → closed
- Can reference and implement specs

**Feedback**: Issues can provide anchored feedback on specs
- Anchors track specific lines/sections in spec markdown
- Auto-relocates when specs change (smart anchoring)
- Types: comment, suggestion, request

## Typical Workflow

1. **Check ready work**: `ready` tool to find tasks with no blockers
2. **Claim work**: `update_issue` with status=in_progress
3. **Review specs**: `show_spec` to understand requirements
4. **Provide feedback**: `add_feedback` when specs are unclear
5. **Complete work**: `close_issue` when done
6. **Link entities**: Use `link` to create relationships

## Relationship Types
- `blocks`: Hard blocker (to_id must complete before from_id)
- `implements`: Issue implements a spec
- `references`: Soft reference
- `depends-on`: General dependency
- `parent-child`: Epic/subtask hierarchy
- `discovered-from`: New work found during implementation

```

--------------------------------

### Workflow Example: Create New Feature Spec

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Step-by-step guide to creating a new feature spec, linking it to dependencies, creating implementation issues, and checking readiness.

```bash
# 1. Create the spec
sudocode spec create --title "WebSocket Support" --type feature --priority 1

# 2. Open in editor (opens automatically or run:)
vim specs/spec-012-websocket-support.md

# 3. Add relationships
sudocode spec link spec-012 spec-001 --type depends-on

# 4. Create implementation issues
sudocode issue create --title "Implement WebSocket server"
sudocode issue link issue-025 spec-012 --type implements

# 5. Check what's ready
sudocode ready
```

--------------------------------

### Install Spec-kit Sync Integration

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode AI integration plugin for Spec-kit synchronization.

```bash
npm install @sudocode-ai/integration-speckit
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Installs the GitHub CLI, which is a prerequisite for deploying to GitHub Codespaces.

```bash
# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh  # Debian/Ubuntu
```

--------------------------------

### Install Beads Sync Integration

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode AI integration plugin for Beads synchronization.

```bash
npm install @sudocode-ai/integration-beads
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Clone the sudocode repository and install all workspace dependencies.

```bash
git clone https://github.com/sudocode-ai/sudocode.git
cd sudocode

npm install
```

--------------------------------

### Start Development Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/server/tests/integration/README.md

Starts the development server for multi-project tests. This should be run before executing multi-project integration tests.

```bash
npm --prefix server run dev
```

--------------------------------

### Install OpenSpec Sync Integration

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode AI integration plugin for OpenSpec synchronization.

```bash
npm install @sudocode-ai/integration-openspec
```

--------------------------------

### Install Sudocode CLI

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode command-line interface globally.

```bash
npm install -g @sudocode-ai/cli
```

--------------------------------

### Add Reference with Display Text Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of adding a reference with custom display text.

```bash
# Add with display text
sudocode spec add-ref SPEC-001 ISSUE-003 --line 45 --display "OAuth implementation"
```

--------------------------------

### Installing GitHub CLI

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Provides commands to install the GitHub CLI on macOS, Windows, and Linux.

```bash
# macOS
brew install gh

# Windows  
winget install GitHub.cli

# Linux
sudo apt install gh

# Verify installation
gh --version
```

--------------------------------

### Install Sudocode Local Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode local backend server package globally.

```bash
npm install -g @sudocode-ai/local-server
```

--------------------------------

### Example JSON Output for Codespaces List

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of the JSON output when listing Codespaces deployments.

```json
[
  {
    "id": "codespace-ab12cd",
    "name": "deployment-ab12cd",
    "provider": "codespaces",
    "status": "running",
    "git": {
      "owner": "myorg",
      "repo": "myproject",
      "branch": "main"
    },
    "urls": {
      "workspace": "https://myorg-myproject-ab12cd.github.dev",
      "sudocode": "https://myorg-myproject-ab12cd-3000.app.github.dev",
      "ssh": "gh cs ssh -c codespace-ab12cd"
    },
    "createdAt": "2026-01-14T10:30:00Z",
    "keepAliveHours": 72,
    "idleTimeout": 4320
  }
]
```

--------------------------------

### Workflow Example: Reviewing Dependencies

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Demonstrates how to review blocked items, visualize specific dependency graphs, and update entity statuses to unblock others.

```bash
# 1. Show blocked items
sudocode blocked

# 2. Show specific dependency graph
sudocode graph --from spec-001

# 3. Update spec status to unblock others
sudocode spec update spec-002 --status approved
```

--------------------------------

### Install GitHub Integration Plugin

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode AI integration plugin for GitHub issues import.

```bash
npm install @sudocode-ai/integration-github
```

--------------------------------

### Install Sudocode CLI and MCP Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/mcp/README.md

Installs the sudocode CLI and MCP server globally using npm. This is an alternative to installing the full sudocode package.

```bash
npm install -g @sudocode-ai/cli @sudocode-ai/mcp
```

--------------------------------

### Integration Test Example Pattern

Source: https://github.com/sudocode-ai/sudocode/blob/main/server/tests/integration/README.md

A common pattern for writing integration tests, including setup in `beforeAll` and cleanup in `afterAll` hooks. It demonstrates skipping tests based on an environment variable and setting a timeout.

```typescript
describe.skipIf(SKIP_INTEGRATION_TESTS)('My Integration Test', () => {
  let testDir: string
  let pool: ExecutionWorkerPool

  beforeAll(() => {
    // Setup test infrastructure
    testDir = join(tmpdir(), `test-${Date.now()}`)
    mkdirSync(testDir, { recursive: true })
  })

  afterAll(async () => {
    // Cleanup resources
    if (pool) {
      await pool.shutdown()
    }
    if (existsSync(testDir)) {
      rmSync(testDir, { recursive: true, force: true })
    }
  })

  it('should do something', async () => {
    // Test implementation
  }, 15000) // Timeout for slow operations
})
```

--------------------------------

### Run the Local Sudocode Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Start the local sudocode server from any directory to enable agent execution and visualization.

```bash
sudocode server
```

--------------------------------

### JSONL-First Configuration (Default)

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/specs/markdown-source-of-truth.md

Example JSON configuration for the default JSONL-first storage mode. This can also be achieved by omitting the 'sourceOfTruth' field.

```json
{
  "sourceOfTruth": "jsonl"
}
```

--------------------------------

### Start Server for Integration Tests

Source: https://github.com/sudocode-ai/sudocode/blob/main/server/tests/README.md

Starts the sudocode server in development mode, which is a prerequisite for running integration tests, particularly the WebSocket test.

```bash
npm run dev
```

```bash
npm run build && npm start
```

--------------------------------

### React Context Provider Setup

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Initializes a context provider with a new AbortController, a data map, and a reference count. Used for managing resources and cancellation.

```javascript
function Wc(){return{controller:new Pg,data:new Map,refCount:0}}
```

--------------------------------

### Install Sudocode Types

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode type definitions package, primarily for development purposes.

```bash
npm install @sudocode-ai/types
```

--------------------------------

### Install Sudocode Agent Plugin

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Install the sudocode plugin for agents to connect them directly to the sudocode system.

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

--------------------------------

### Add Reference with Relationship Type Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of adding a reference with a specified relationship type.

```bash
# Add with relationship type
sudocode issue add-ref ISSUE-001 SPEC-002 --text "Design" --type implements
```

--------------------------------

### Session Start Checklist for Sudocode

Source: https://github.com/sudocode-ai/sudocode/blob/main/skills/sudocode/SKILL.md

Always perform these checks at the start of a session to ensure you are working on unblocked and relevant issues. This includes checking for ready work and current in-progress tasks.

```bash
- [ ] Use ready tool to find unblocked work
- [ ] Use list_issues with status=in_progress to see current work
- [ ] Ask user which work to pursue (if not specified)
```

--------------------------------

### Add Reference by Text Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of adding a reference by searching for specific text to find the insertion point.

```bash
# Add reference after specific text
sudocode spec add-ref SPEC-001 ISSUE-003 --text "Requirements:"
```

--------------------------------

### Install Sudocode MCP Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Install the Sudocode Multi-Claude Protocol (MCP) server package globally.

```bash
npm install -g @sudocode-ai/mcp
```

--------------------------------

### Custom Editor Configuration Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Configuration for a custom editor, specifying the editor type as 'custom' and providing the command to launch it. This allows integration with any command-line executable editor.

```json
{
  "editor": {
    "editorType": "custom",
    "customCommand": "code-insiders"
  }
}
```

--------------------------------

### Deployment Not Found Error Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Displays the error message when a specified deployment does not exist, with instructions to list available deployments.

```bash
✗ Deployment 'codespace-xyz' not found

  The specified deployment does not exist or has been deleted.
  
  To list all deployments:
    sudocode remote codespaces list
```

--------------------------------

### Add Reference on New Line Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of adding a reference on a new line before specific text.

```bash
# Add on new line before text
sudocode spec add-ref SPEC-001 ISSUE-004 --text "## Tasks" --format newline --position before
```

--------------------------------

### Good Feedback Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/skills/sudocode/SKILL.md

An example of comprehensive feedback, detailing requirements met, design decisions made, challenges encountered, evidence of completion, and suggestions for spec improvement.

```text
✅ Requirements met: OAuth flow working per spec
📝 Design decisions: Used Redis for tokens (horizontal scaling), added rate limiting
⚠️ Challenges: PKCE needed for mobile (not in spec), token refresh race condition solved with 10s buffer
✅ Evidence: 47 tests passing, 3 OAuth providers tested, security scan clean
💡 Suggestions: Add mobile requirements, document token refresh edge case
```

--------------------------------

### IDE Configuration Example (VS Code)

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Configuration for the Sudocode editor settings, specifying Visual Studio Code as the editor type. This file is typically gitignored.

```json
{
  "editor": {
    "editorType": "vs-code"
  }
}
```

--------------------------------

### React Start Transition Functionality

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Handles the start of a React transition, managing state updates and asynchronous operations within the transition.

```javascript
ht.startTransition=function(b){var q=V.T,P={};V.T=P;try{var J=b(),it=V.S;it!==null&&it(P,J),typeof J=="object"&&J!==null&&typeof J.then=="function"&&J.then(dt,$)}catch(mt){$(mt)}finally{V.T=q}}
```

--------------------------------

### Invalid Configuration Error Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Shows the error message for invalid configuration values, specifically for the 'port' setting, and how to view current configuration.

```bash
✗ Invalid configuration: port

  Port must be between 1024 and 65535
  
  To view current configuration:
    sudocode remote codespaces config
```

--------------------------------

### Show Ready Entities

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Displays entities (specs or issues) that have no blocking dependencies. Useful for identifying tasks that can be started immediately.

```bash
# Show all ready-to-work entities
sudocode ready [--type spec|issue]

# Output:
# Ready Specs (no blocking dependencies):
#   spec-005  API Documentation       [process]    P2
#   spec-008  Logging Strategy        [decision]   P3
#
# Ready Issues (no blocking dependencies):
#   issue-010 Implement auth tokens   [feature]    P1
#   issue-015 Fix CORS headers        [bug]        P1
```

--------------------------------

### Authentication Error Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Illustrates the error message when GitHub CLI is not authenticated, with instructions to log in.

```bash
✗ GitHub CLI is not authenticated

  Sudocode needs GitHub CLI to deploy to Codespaces.
  
  To authenticate:
    gh auth login
```

--------------------------------

### CLI Sync Subcommand Examples

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/specs/markdown-source-of-truth.md

Demonstrates the usage of the `sudocode sync` subcommand for different synchronization scenarios, including rebuilding from markdown, rebuilding markdown from JSONL, and auto-detection.

```bash
# Rebuild DB + JSONL from markdown (markdown-first mode)
sudocode sync --from-markdown

# Rebuild markdown from JSONL (jsonl-first mode)
sudocode sync --to-markdown

# Auto-detect based on config
sudocode sync --auto
```

--------------------------------

### Build Sudocode MCP from Source

Source: https://github.com/sudocode-ai/sudocode/blob/main/mcp/README.md

Clones the sudocode repository, navigates to the mcp directory, installs dependencies, and builds the project using esbuild for bundled and minified output.

```bash
git clone https://github.com/sudocode-ai/sudocode.git
cd sudocode/mcp
npm install
npm run build
```

--------------------------------

### CLI Commands for Managing Feedback

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/feedback-mechanisms.md

Provides example command-line interface commands for interacting with the feedback system. Includes listing feedback by spec or status, and resolving feedback items.

```bash
# List all feedback for a spec
sudocode feedback list spec-001

# Show open feedback across all specs
sudocode feedback list --status open

# Address feedback
sudocode feedback resolve FB-001 --comment "Updated spec section 3.2"
```

--------------------------------

### Test Specific File

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Run tests for a specific file within a package. This example targets a file in the server package.

```bash
npm --prefix server test -- --run tests/unit/services/editor-service.test.ts
```

--------------------------------

### Network Connection Failed Error Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Illustrates the error message for network connection failures, providing troubleshooting steps.

```bash
✗ Network connection failed

  Unable to list deployments due to network issues.
  
  Suggested actions:
    • Check your internet connection
    • Verify VPN or proxy settings
    • Try again in a few moments
```

--------------------------------

### Port Conflict Error Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Demonstrates the error message when a requested port is already in use, suggesting how to specify an alternative port.

```bash
✗ Port 3000 is already in use

  The requested port is not available on your system.
  
  To use a different port:
    sudocode remote codespaces spawn --port 3001
```

--------------------------------

### Add Sudocode Plugin for Claude Code

Source: https://github.com/sudocode-ai/sudocode/blob/main/mcp/README.md

Adds the sudocode-ai/sudocode plugin from the marketplace and installs it. This is the recommended method for integrating MCP server setup with Claude Code.

```bash
/plugin marketplace add sudocode-ai/sudocode
/plugin install sudocode
```

--------------------------------

### Run WebSocket Integration Test

Source: https://github.com/sudocode-ai/sudocode/blob/main/server/tests/README.md

Executes the WebSocket integration test after the server has been started. This test verifies WebSocket functionality.

```bash
node tests/integration/websocket.test.js
```

--------------------------------

### Sudocode Metadata File Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/storage.md

The `.sudocode/meta.json` file stores ID counters, configuration, and a collision log for managing unique identifiers and resolving sync conflicts.

```json
{
  "version": "1.0",
  "next_spec_id": 43,
  "next_issue_id": 157,
  "id_prefix": {
    "spec": "spec-",
    "issue": "issue-"
  },
  "last_sync": "2025-10-16T15:30:00Z",
  "collision_log": [
    {"old_id": "issue-042", "new_id": "issue-158", "reason": "merge_conflict", "timestamp": "2025-10-16T15:00:00Z"}
  ]
}
```

--------------------------------

### Initialize a Sudocode Project

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Initialize a new sudocode project within your current project directory.

```bash
sudocode init
```

--------------------------------

### Test with Pattern Matching

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Run tests within a package that match a specific pattern. This example targets tests related to 'auto-save' in the frontend package.

```bash
npm --prefix frontend test -- --run -t "auto-save"
```

--------------------------------

### Run Development Server with Hot Reload

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Start the development server with hot reload enabled. The server will run at http://localhost:3000 and automatically reload on file changes.

```bash
npm run dev:server
```

--------------------------------

### init

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/mcp.md

Initializes the sudocode environment in the current directory. This command sets up the necessary configuration and database for sudocode to operate.

```APIDOC
## init

### Description
Initialize sudocode in current directory.

### Returns
`{ success: boolean, path: string }`

### CLI Command
`sudocode init`
```

--------------------------------

### Initializing Git Repository

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Initialize a new Git repository, add a remote origin, and perform an initial commit and push.

```bash
# Initialize git repository
git init

# Add remote
git remote add origin https://github.com/myorg/myproject.git

# Commit and push
git add .
git commit -m "Initial commit"
git push -u origin main
```

--------------------------------

### Build the Server

Source: https://github.com/sudocode-ai/sudocode/blob/main/server/tests/integration/README.md

Builds the server using npm. This is a prerequisite for running integration tests.

```bash
npm --prefix server run build
```

--------------------------------

### Install Sudocode Claude Plugin

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Installs the sudocode plugin for Claude Code after it has been added from the marketplace.

```bash
claude plugin install sudocode
```

--------------------------------

### Build All Packages

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Build all packages in the workspace, following the specified order: types, cli, mcp, frontend, server.

```bash
npm run build
```

--------------------------------

### Add Reference Inline Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of adding a reference inline after a specific line number.

```bash
# Add reference inline after line 45
sudocode spec add-ref SPEC-001 ISSUE-003 --line 45
```

--------------------------------

### Full Codespace Lifecycle Management

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Demonstrates the complete lifecycle: configuring Codespace settings, deploying a feature branch, and then listing and checking the status of the deployed Codespace.

```bash
# 1. Configure for your needs
sudocode remote codespaces config \
  --port 8080 \
  --machine "standardLinux32gb" \
  --idle-timeout 120 \
  --keep-alive 24

# 2. Deploy
sudocode remote codespaces spawn --branch feature/new-feature

# 3. Monitor
sudocode remote codespaces list
sudocode remote codespaces status <id>
```

--------------------------------

### Preinitialize a Resource

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Use `preinit` to fetch and initialize a resource, such as a stylesheet or script, before it's needed. This can improve perceived performance by loading critical resources earlier.

```javascript
le.preinit = function(v, A) {
  if (typeof v == "string" && A && typeof A.as == "string") {
    var E = A.as,
      w = y(E, A.crossOrigin),
      R = typeof A.integrity == "string" ? A.integrity : void 0,
      z = typeof A.fetchPriority == "string" ? A.fetchPriority : void 0;
    E === "style" ? f.d.S(v, typeof A.precedence == "string" ? A.precedence : void 0, {
      crossOrigin: w,
      integrity: R,
      fetchPriority: z
    }) : E === "script" && f.d.X(v, {
      crossOrigin: w,
      integrity: R,
      fetchPriority: z,
      nonce: typeof A.nonce == "string" ? A.nonce : void 0
    })
  }
}
```

--------------------------------

### Remote Deployment Command Structure

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Illustrates the general command structure for managing remote deployments, specifying the provider and command.

```bash
sudocode remote <provider> <command> [options]
```

--------------------------------

### Example JSON Output for Codespaces Status

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Example of the JSON output when retrieving the status of a specific Codespaces deployment.

```json
{
  "id": "codespace-ab12cd",
  "name": "deployment-ab12cd",
  "provider": "codespaces",
  "status": "running",
  "git": {
    "owner": "myorg",
    "repo": "myproject",
    "branch": "main"
  },
  "urls": {
    "workspace": "https://myorg-myproject-ab12cd.github.dev",
    "sudocode": "https://myorg-myproject-ab12cd-3000.app.github.dev",
    "ssh": "gh cs ssh -c codespace-ab12cd"
  },
  "createdAt": "2026-01-14T10:30:00Z",
  "keepAliveHours": 72,
  "idleTimeout": 4320
}
```

--------------------------------

### Unit Test for Spec Create Command

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

An example of a unit test for the 'spec create' command using a testing framework. It sets up a temporary directory, initializes Sudocode, executes the command, and asserts the expected output and file creation.

```typescript
describe('spec create command', () => {
  let tmpDir: string;

  beforeEach(() => {
    tmpDir = createTempDir();
    process.chdir(tmpDir);
    execSync('sudocode init');
  });

  afterEach(() => {
    removeTempDir(tmpDir);
  });

  it('should create a new spec', async () => {
    const result = await execCommand(
      'sudocode spec create --title "Test Spec" --type feature'
    );

    expect(result.stdout).toContain('Created spec-001');
    expect(fs.existsSync('specs/spec-001-test-spec.md')).toBe(true);
  });
});
```

--------------------------------

### Specs JSONL Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/storage.md

An example of a single spec entry in JSONL format, including core fields, relationships, and tags.

```json
{"id":"spec-001","title":"Auth System","file_path":".sudocode/specs/specs.jsonl","content":"# Auth System\n\n...","type":"architecture","status":"draft","priority":1,"created_at":"2025-10-16T10:00:00Z","updated_at":"2025-10-16T15:00:00Z","created_by":"alice","updated_by":"alice","parent_id":"spec-000","relationships":[{"from":"spec-001","to":"spec-002","type":"blocks"}],"tags":["auth","security"]}
```

--------------------------------

### Sudocode Project File Structure

Source: https://github.com/sudocode-ai/sudocode/blob/main/sudocode/README.md

Illustrates the default file structure created by `sudocode init`, including configuration, data, and generated markdown files.

```text
.sudocode/
├── meta.json         # Config & ID counters (git tracked)
├── specs.jsonl       # All specs (git tracked)
├── issues.jsonl      # All issues (git tracked)
├── cache.db          # SQLite cache (gitignored)
├── specs/            # Generated markdown that you can edit (gitignored)
├── issues/           # Generated markdown that you can edit (gitignored)
└── .gitignore        # Ignores cache and generated files
```

--------------------------------

### Install Sudocode Globally

Source: https://github.com/sudocode-ai/sudocode/blob/main/README.md

Install the sudocode package globally using npm. It is recommended to use npx to avoid potential Node version conflicts.

```bash
npm install -g sudocode
```

--------------------------------

### Issues JSONL Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/storage.md

An example of a single issue entry in JSONL format, detailing fields like ID, title, status, assignee, and relationships.

```json
{"id":"issue-001","title":"Implement OAuth endpoint","description":"Create REST endpoint...","content":"# Details\n\n...","status":"open","priority":1,"issue_type":"task","assignee":"agent-backend","estimated_minutes":120,"created_at":"2025-10-16T10:00:00Z","updated_at":"2025-10-16T15:00:00Z","closed_at":null,"created_by":"agent-planner","parent_id":null,"relationships":[{"from":"issue-001","to":"spec-001","type":"implements"},{"from":"issue-001","to":"issue-002","type":"blocks"}],"tags":["auth","backend"]}
```

--------------------------------

### Initialize Commander.js CLI Program

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Sets up the main command-line program using Commander.js, defining its name, description, version, and initial commands.

```typescript
import { Command } from 'commander';

const program = new Command();

program
  .name('sudocode')
  .description('Technical specification and issue tracker')
  .version('0.1.0');

program
  .command('init')
  .description('Initialize sudocode in current directory')
  .action(initCommand);

program
  .command('spec')
  .description('Manage specifications')
  .addCommand(makeSpecCommands());

// ... more commands
```

--------------------------------

### Show Spec with Implementations

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/feedback-mechanisms.md

Use this command to view a specification and see all the code artifacts that implement it. This aids in navigating between specs and code.

```bash
sudocode spec show spec-001 --implementations
```

--------------------------------

### Get request headers

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Extracts request headers from options, returning them as an object.

```typescript
function rr({options:u}){const{headers:i}=u;if(i)return Symbol.iterator in i?Object.fromEntries(i):i}
```

--------------------------------

### Creating Codespaces

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Troubleshoot Codespace creation failures by checking authentication, repository access, and attempting creation with a specific repository.

```bash
# Check GitHub authentication
gh auth status

# Verify repository access
gh repo view myorg/myproject

# Check Codespaces status
gh codespace list

# Try again with specific repo
sudocode remote codespaces spawn --repo myorg/myproject
```

--------------------------------

### Get Entries Generator

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Generates entries from the archive. Handles data extraction and processing for each entry.

```typescript
async getEntriesGenerator(i={}){const c=new a2(this);for await(const f of this.getEntriesGenerator(i))yield f;const K={};Object.assign(K,{rawComment:P,filename:bn,comment:na,directory:ut||bn.endsWith(X1)}),T=Math.max(Dt,T),Oh(K,K,I,D+6),K.zipCrypto=K.encrypted&&!K.extraFieldAES;const Fe=new a2(K);Fe.getData=(Oa,ce)=>K.getData(Oa,Fe,c.readRanges,ce),Fe.arrayBuffer=async Oa=>{const ce=new TransformStream,\\[sc] = await Promise.all(\\[new Response(ce.readable).arrayBuffer(), K.getData(ce, Fe, c.readRanges, Oa))\\];return sc},D=q;const{onprogress:ji}=i;if(ji)try{await ji(F+1,x,new a2(K))}catch{}yield Fe}const L=ee(c,i,z3),W=ee(c,i,G3);return L&&(c.prependedData=T>0?await Jt(f,0,T):new Uint8Array),c.comment=E?await Jt(f,A+gn,E):new Uint8Array,W&&(c.appendedData=w<f.size?await Jt(f,w,f.size-w):new Uint8Array),!0}async getEntries(i={}){const c=\\[]};for await(const f of this.getEntriesGenerator(i))c.push(f);return c}async close(){}}
```

--------------------------------

### Update Issue Status

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/feedback-mechanisms.md

Use this command to update the status of an issue, for example, to 'in_progress' when development begins.

```bash
sudocode issue update issue-010 --status in_progress
```

--------------------------------

### Get URL Search Parameters

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Hook to access the URL search parameters from the nearest URLSearchParams context.

```javascript
function ue(){
return new URLSearchParams(ct.useContext(zh))
}
```

--------------------------------

### Get Merged Configuration

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/specs/markdown-source-of-truth.md

Combines project and local configurations, with local settings overriding project settings.

```typescript
/**
 * Get merged config (project + local)
 */
export function getConfig(outputDir: string): Config {
  const project = readProjectConfig(outputDir);
  const local = readLocalConfig(outputDir);
  return { ...project, ...local };
}
```

--------------------------------

### Hierarchical Feature with Dependencies Example

Source: https://github.com/sudocode-ai/sudocode/blob/main/skills/sudocode/SKILL.md

Illustrates creating a hierarchical structure for an authentication system with child components like OAuth and Sessions, and defining execution order using 'blocks' dependencies.

```text
s-2a7c: Auth System (parent)
├── s-8h2k: OAuth (child)
├── s-9j3m: Sessions (child)
└── s-4k8p: Permissions (child)

i-5n7q: Implement auth (parent epic, implements s-2a7c)
├── i-7x9m: OAuth flow (child, implements s-8h2k)
├── i-3p6k: Session storage (child, implements s-9j3m)
└── i-8w2n: Permissions (child, implements s-4k8p)
```

```text
link: i-7x9m blocks i-3p6k (OAuth before sessions)
link: i-3p6k blocks i-8w2n (sessions before permissions)
```

--------------------------------

### Getting Component Queue with `d0`

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Retrieves the memoized queue for a component. This is an internal function used for state management.

```javascript
d0:function(t){var e=t.memoizedState;if(e!==null)return e;e={memoizedState:$,baseState:$,baseQueue:null,queue:{pending:null,lanes:0,dispatch:null,lastRenderedReducer:an,lastRenderedState:$},next:null};var n={};return e.next={memoizedState:n,baseState:n,baseQueue:null,queue:{pending:null,lanes:0,dispatch:null,lastRenderedReducer:an,lastRenderedState:n},next:null},t.memoizedState=e,t=t.alternate,t!==null&&(t.memoizedState=e),e}
```

--------------------------------

### Convert Project to Markdown-First Mode

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/specs/markdown-source-of-truth.md

Command sequence to migrate an existing project to the markdown-first storage mode. It ensures all entities have corresponding markdown files, updates the configuration, and performs a verification sync.

```bash
# 1. Ensure all entities have markdown files
sudocode sync --to-markdown

# 2. Update config
sudocode config set sourceOfTruth markdown

# 3. Verify
sudocode sync --from-markdown --dry-run
```

--------------------------------

### Fetch data with HEAD request

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Fetches data using a HEAD request to get headers, specifically the size.

```typescript
async function n2(u,i,c){if(u.preventHeadRequest)await c(u,u.options);else{const r=(await i(n3,u,rr(u))).headers.get(P8);r?u.size=Number(r):await c(u,u.options)}}
```

--------------------------------

### List Ready Issues and Specs CLI Command

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/mcp.md

Use this command to find issues and specs that are ready to work on, meaning they have no blockers. Optional filters include limit, priority, assignee, and whether to show specs or issues.

```bash
sudocode ready --json [--limit N] [--priority P] [--assignee A] [--specs] [--issues]
```

--------------------------------

### Get Default Content Type

Source: https://github.com/sudocode-ai/sudocode/blob/main/frontend/playwright-report/index.html

Returns the default content type, which is 'application/octet-stream'. This is often used for binary data.

```javascript
function f8() {
  return "application/octet-stream";
}
```

--------------------------------

### Get Status of a Specific Codespace Deployment

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Retrieves detailed information about a specific Codespace deployment using its ID.

```bash
sudocode remote codespaces status codespace-ab12cd
```

--------------------------------

### Spawn Codespaces Deployment Options

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Lists the available options for spawning a GitHub Codespaces deployment, including repository, branch, port, machine type, and various timeout/retention settings.

```bash
# Spawn Deployment

sudocode remote codespaces spawn [options]

**Options:**
- --repo <owner/repo> - Override repository (default: auto-detected from git remote)
- --branch <name> - Override branch (default: current branch or from config)
- --port <number> - Server port (default: 3000 or from config)
- --machine <type> - Machine type (default: "basicLinux32gb" or from config)
- --idle-timeout <minutes> - Idle timeout in minutes (default: 4320 or from config)
- --keep-alive <hours> - Keep-alive duration in hours (default: 72 or from config)
- --retention <days> - Retention period in days (default: 14 or from config)
```

--------------------------------

### Manage Sudocode Configuration

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Allows viewing, setting, and getting configuration values for Sudocode. Configuration is stored in `.sudocode/config.json`.

```bash
# Show current configuration
sudocode config list

# Set configuration
sudocode config set editor "code --wait"
sudocode config set author.name "Alex Ngai"
sudocode config set sync.auto true

# Get configuration value
sudocode config get editor
```

```bash
**Config file location:** .sudocode/config.json
```

--------------------------------

### Troubleshoot Claude CLI Not Found Error

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Provides the command to install the Claude CLI if it's not found by the sudocode CLI.

```bash
npm install -g @anthropic-ai/claude-cli
```

--------------------------------

### Initialize sudocode CLI

Source: https://github.com/sudocode-ai/sudocode/blob/main/docs/cli.md

Initializes the sudocode environment in the current directory. This command creates necessary configuration files and directories, including a cache database and spec/issue storage.

```bash
sudocode init

# Creates:
# - .sudocode/ directory
# - .sudocode/cache.db
# - .sudocode/specs/ directory (for JSONL)
# - .sudocode/issues/ directory (for JSONL)
# - specs/ directory (for markdown files)
# - issues/ directory (for markdown files)
```

--------------------------------

### Automate Deployment with JSON Output

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

Deploys a Codespace, captures its ID using JSON output and jq, and monitors its status in a loop until it's running.

```bash
# Deploy and capture ID
DEPLOY_ID=$(sudocode remote codespaces spawn --json | jq -r '.id')

# Monitor status
while true; do
  STATUS=$(sudocode remote codespaces status $DEPLOY_ID --json | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "running" ]; then
    break
  fi
  sleep 5
done

# Get Sudocode URL
SUDOCODE_URL=$(sudocode remote codespaces status $DEPLOY_ID --json | jq -r '.urls.sudocode')
echo "Sudocode UI: $SUDOCODE_URL"
```

--------------------------------

### Troubleshoot Dependency and Build Issues

Source: https://github.com/sudocode-ai/sudocode/blob/main/CONTRIBUTING.md

Commands to clean up and rebuild the project in case of dependency conflicts or build issues.

```bash
npm unlink

npm run clean

npm run build

npm link
```

--------------------------------

### Managing Deployments

Source: https://github.com/sudocode-ai/sudocode/blob/main/cli/README.md

List available deployments to find the correct ID and check the status of a specific deployment.

```bash
# List all deployments
sudocode remote codespaces list

# Use correct ID from list
sudocode remote codespaces status <correct-id>
```