sudocode

https://github.com/sudocode-ai/sudocode
Admin
sudocode is a lightweight, Git-native agent orchestration system that automates the logistics of...
Tokens:122,793
Snippets:1,065
Trust Score:7.2
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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
```

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

### 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
```

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

### 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
}
```

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

### 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
```

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

### 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"]}
```

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

### 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"
```

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

### 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
```

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

### 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
```

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

### 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)
```

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

### 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
```

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

### Git Repository Not Found Error Example

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

Shows the error message when a command is run outside a Git repository, with guidance on initializing one.

```bash
✗ Git repository not found

  This command must be run from within a git repository.
  
  To initialize a repository:
    git init
```

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

### 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`
```

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

### Manual Editor Test Command

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

A command-line example to test if an editor can be launched manually. This is useful for troubleshooting IDE integration issues.

```bash
code /path/to/directory
```

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

### Issue Markdown File Example

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

Demonstrates the structure of an Issue's Markdown file, including its YAML frontmatter and content. Frontmatter captures details like ID, description, status, assignee, and related specs.

```markdown
---
id: issue-001
title: Implement OAuth 2.0 token endpoint
description: Create REST endpoint for OAuth token exchange
status: open
priority: 1
issue_type: task
assignee: agent-backend-dev
estimated_minutes: 120
created_at: 2025-10-16T10:00:00Z
updated_at: 2025-10-16T15:30:00Z
closed_at: null
created_by: agent-planner
spec_refs: [spec-001]
parent: null
blocks: [issue-002]
blocked_by: []
related: [issue-010]
tags: [auth, backend, api]
---

# Implement OAuth 2.0 token endpoint

Content here is flexible markdown. Common sections might include:

## Description
Create REST endpoint for OAuth token exchange following RFC 6749.
```

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

### 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
```

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

### 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
```

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

### Essential Sudocode Tools

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

Quick reference for essential sudocode tools used for managing specs and issues. These tools cover finding work, getting details, creating/updating entities, linking them, and adding feedback.

```bash
ready                → Find unblocked work
show_issue/show_spec → Get details with relationships
upsert_issue/spec    → Create/update (status, priority, parent)
link                 → Create relationships (blocks, implements, parent-child)
add_feedback         → Document implementation results on specs
```

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

### 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>
```

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

### Initiate Interactive Claude Code Authentication

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

Starts an interactive process to set up authentication for Claude Code, including checking for the Claude CLI, launching an OAuth flow, storing the token, and verifying the configuration.

```bash
sudocode auth claude
```

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

### 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]
```

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

### 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
```

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

### 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 };
}
```

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

### 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
```

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

### 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)
```

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

### 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
```

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

### 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>
```

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

### Render Label Component

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

Renders a label with optional click handling and styling. Supports trimming the '@' symbol from the start of the label.

```javascript
const Qh=({label:u,href:i,onClick:c,colorIndex:f,trimAtSymbolPrefix:r})=>{
const o=m.jsx("span",{className:Ye("label","label-color-"+(f!==void 0?f:Q5(u))),onClick:c?d=>c(d,u):void 0,children:r&&u.startsWith("@")?u.slice(1):u});
return i?m.jsx("a",{className:"label-anchor",href:Qe(i),children:o}):o
}
```

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

### Handling Unexpected Deployment Stops

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

Understand causes for unexpected stops (idle timeout, cleanup, quota) and reconfigure timeouts before redeploying.

```bash
# Check configuration
sudocode remote codespaces config

# Increase timeouts for longer tasks
sudocode remote codespaces config \
  --idle-timeout 1440 \
  --keep-alive 168

# Redeploy
sudocode remote codespaces spawn --branch <branch>
```

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

### Show Relationship Graph

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

Visualizes entity relationships and dependencies. Supports filtering by starting entity, depth, and output format.

```bash
# Show relationship graph
sudocode graph [--from <id>] [--depth <n>] [--format ascii|dot|json]

# Examples:
# Show dependencies from a spec
sudocode graph --from spec-001

# Generate DOT format for Graphviz
sudocode graph --from spec-001 --format dot > graph.dot
dot -Tpng graph.dot -o graph.png

# Show full project graph
sudocode graph --depth 10
```

```bash
** ASCII output example:**
```
spec-001 (Authentication System)
├─[blocks]─> spec-002 (API Gateway)
├─[related]─> spec-005 (Security Guidelines)
└─[implements]─> issue-010 (Auth tokens)
              └─[blocks]─> issue-012 (Token refresh)
```
```

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

### Configure Development Environment

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

Sets Codespace configuration for rapid development cycles with short idle timeouts and retention periods.

```bash
sudocode remote codespaces config \
  --idle-timeout 30 \
  --keep-alive 4 \
  --retention 1
```

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

### API Route for Execution Changes

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

Defines the API route to get a list of modified files and their diffs for a given execution.

```http
GET /api/executions/:executionId/changes
    - Get list of modified files with diffs
```

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

### Deploy Current Branch

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

Deploys the current git branch to a new GitHub Codespace, including dependency installation and server startup.

```bash
# Working on feature branch
git checkout feature/user-auth
git add .
git commit -m "WIP: implementing OAuth"
git push origin feature/user-auth

# Deploy this branch
sudocode remote codespaces spawn
```

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

### Dependency Graph Building Checklist

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

A checklist for building dependency graphs, emphasizing identifying foundational and parallel work, creating issues, adding hierarchy and execution order, and verifying the graph.

```text
- [ ] Identify foundation work (must happen first)
- [ ] Identify parallel work (no dependencies)
- [ ] Create all issues first (don't worry about order)
- [ ] Add parent-child for hierarchy
- [ ] Add blocks for execution order
- [ ] Verify no circular dependencies
- [ ] Use ready to verify graph correct
```

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

### Create a New Spec

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

Creates a new specification with a given description and priority level.

```bash
sudocode spec create "User authentication system" -p 4
```

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

### Markdown Reference to Sub-Spec

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

Example of referencing a sub-specification within a Markdown document. This is used to establish hierarchical or cross-cutting relationships between specifications.

```markdown
See [[SPEC-002]] for detailed API contracts.
```

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

### Deploy and Run a Quick Task

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

Deploys a codespace for a specific branch to perform a quick task, such as a bug fix or small feature development.

```bash
sudocode remote codespaces spawn --branch feature/quick-fix
```

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

### Markdown with Bidirectional Links

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

Example of defining requirements and linking to issues or specifications using Markdown syntax. Backlinks are automatically tracked.

```markdown
## Requirements
1. Support OAuth 2.0 [[ISSUE-001]]
2. Multi-factor authentication [[ISSUE-002]]

See also [[SPEC-010]] for API design patterns.
```

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

### Clean and rebuild project

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

Execute these commands to clean the project artifacts and rebuild the project from scratch. Useful for resolving build failures.

```bash
npm run clean
npm run build
```

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

### Get Default Configuration

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

Returns the current default configuration object for Playwright reports. This is useful for inspecting or using the default settings.

```javascript
function O2() {
  return Jn;
}
```

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

### Create a New Spec

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

Use this command to create a new specification with a title and optional priority, description, design notes, file path, parent ID, and tags.

```bash
sudocode spec create <title> [options]
  -p, --priority <0-4>        Priority level (default: 2)
  -d, --description <text>    Description
  --design <text>             Design notes
  --file-path <path>          Custom markdown file path
  --parent <id>               Parent spec ID
  --tags <tags>               Comma-separated tags
```

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

### Get Status of a Specific Codespace Deployment in JSON

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

Retrieves detailed information about a specific Codespace deployment and formats the output as JSON.

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

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

### Get Current Event Priority

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

Retrieves the current event priority, likely from a global or context variable. Defaults to 32 if no event is available.

```javascript
function Rr(){var t=_.p;return t!==0?t:(t=window.event,t===void 0?32:u1(t.type))}
```

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

### Get Zip Entry Option

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

Retrieves a specific option for a zip entry, prioritizing the entry's options over the general options if available.

```javascript
function ee(u,i,c){return i\[c\]===qt?u.options\[c\]:i\[c\]}
```

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

### Register Event Handlers

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

Registers event handlers for both bubbling and capturing phases. This function is part of React's event system setup.

```javascript
function la(t,e){Ha(t,e),Ha(t+"Capture",e)}
```

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

### Integration with TodoWrite Pattern

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

Explains the pattern for integrating Sudocode issues with TodoWrite for session-scoped checklists and immediate task tracking, contrasting their primary uses.

```text
Use TodoWrite for: Session-scoped checklists, immediate execution tracking
Use Issues for: Multi-session work, dependencies, spec implementation

Pattern: Start session with ready → Create TodoWrite for immediate tasks → Update issue status as you work → Close issue when complete
```

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

### Parse URLs in Text

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

Parses a string to find and wrap URLs in anchor tags. Handles various URL formats including those starting with 'www.'.

```javascript
function Ri(u){const i=[];let c=0,f;for(;(f=H5.exec(u))!==null;){const o=u.substring(c,f.index);o&&i.push(o);const d=f[0];i.push(B5(d)),c=f.index+d.length}const r=u.substring(c);return r&&i.push(r),i}
function B5(u){let i=u;return i.startsWith("www.")&&(i="https://"+i),m.jsx("a",{href:i,target:"_blank",rel:"noopener noreferrer",children:u})}
```

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

### Stream State Initialization

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

Initializes the internal state (keys and CRC keys) for a stream based on a provided password. This is a setup function for encryption streams.

```typescript
function G2(u,i){const c=[305419896,591751049,878082192];
Object.assign(u,{keys:c,crcKey0:new ec(c[0]),crcKey2:new ec(c[2])});
for(let f=0;f<i.length;f++)lr(u,i.charCodeAt(f))
}
```

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

### Authenticating with GitHub

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

Log in to GitHub using the CLI and authenticate through a browser.

```bash
# Login to GitHub
gh auth login

# Select GitHub.com
# Choose HTTPS or SSH
# Authenticate in browser
```
Tokens:
Raw