sudocode

Overview

sudocode is a TypeScript-based agent orchestration system that lives in your repository, providing context management and task coordination for AI coding agents. It implements a 4-tiered abstraction structure: Specs (user intent), Issues (agent tasks), Agents (execution abstractions), and Artifacts (state changes). The system offers both human-editable Markdown formats and machine-optimized JSONL+SQLite storage with automatic synchronization. Its MCP server enables AI agents to track context over long-horizon tasks and collaborate on complex requirements through git-native memory management.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• create_spec

  Create a new specification in sudocode

  Try:Create a new spec for user authentication systemTry:Create a spec called api-design for the new REST API
• list_specs

  List all specifications in the sudocode system

  Try:Show me all specs in this projectTry:List existing specifications
• create_issue

  Create a new implementation issue linked to a spec

  Try:Create an issue for implementing OAuth 2.0Try:Create a new issue for the user registration flow
• list_issues

  List all issues in the sudocode system

  Try:Show me all issues for the auth system specTry:List all unimplemented issues
• update_spec

  Update an existing specification with new requirements

  Try:Update the auth system spec to include multi-factor authenticationTry:Add API rate limiting requirements to the API design spec
• update_issue

  Update an existing issue with new information or status

  Try:Mark the OAuth 2.0 issue as completedTry:Update the user registration issue with new requirements
• link_spec_to_issue

  Create a bidirectional link between a spec and an issue

  Try:Link the user auth spec to the OAuth issueTry:Connect the API design spec to the implementation issues
• execute_issue

  Execute an issue with a coding agent

  Try:Execute the user registration issue with a coding agentTry:Implement the OAuth 2.0 issue
• create_workflow

  Create a workflow to execute multiple issues in topological order

  Try:Create a workflow to execute all auth-related issuesTry:Build a workflow for the entire API implementation
• list_agents

  List all configured agents in the sudocode system

  Try:Show me all configured agentsTry:List available coding agents
• open_in_editor

  Open a spec or issue in the configured editor

  Try:Open the auth spec in VS CodeTry:Show the user registration issue in Cursor
• get_dependencies

  Get dependency graph for specs and issues

  Try:Show dependencies for the auth systemTry:What issues block the API implementation?

Note: Tool names inferred from CLI usage patterns and documentation. The README describes the system's capabilities but doesn't provide a complete API reference. Tool signatures are unknown as they are not explicitly documented.

Comparable tools

Installation

npm install -g sudocode

sudocode init

FAQ

What is the relationship between specs and issues?

Specs represent user intent and requirements (what to do), while issues are work items derived from specs that agents implement (how to implement). Issues can reference specific specs using [[SPEC-001]] syntax.

How does sudocode handle context persistence across agent sessions?

sudocode stores context as git-tracked files in .sudocode/specs/ and .sudocode/issues/, with both human-readable Markdown and machine-optimized JSONL formats. This creates a version-controlled memory system that persists across sessions.

On Hacker News

Recent discussion from the developer community.

• Show HN: sudocode – manage specs, tasks, and context-as-code for coding agents▲ 15💬 5
  Story by alexsngai · 2025-11-05

Compare sudocode with