sudocode

An open-source lightweight context management system for coding agents

Install

npm (global)

npm install -g sudocode
sudocode init

MCP Server (stdio)

{
  "mcpServers": {
    "sudocode": {
      "command": "sudocode-mcp"
    }
  }
}

Claude Code Plugin

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

What is sudocode?

sudocode is a lightweight context management system for coding agents that lives in your repo. Capture user intent as durable specs and track agent activity as issues.

Adding sudocode into your repo adds instant organizational capabilities to your coding agents. They'll gain the ability to track context over long-horizon tasks and work collaboratively on complex tasks.

Your context and designs are just as valuable as the code being written. With sudocode, you treat your git repo as a distributed context database to capture context and make it readily available to coding agents. Track user intent (specs), agent tasks (issues), and agent trajectories (executions) as they evolve alongside your codebase.

Why sudocode?

•Distributed Collaboration: Human developers and AI agents share one logical database across multiple environments through git synchronization
•Lightweight: All your context lives under your control in your repo
•Integrated Audit Trail: Context can be recovered with git's immutable change tracking
•Agent Persistence: Reduce agent hallucinations and amnesia by keeping task context in version-controlled files instead of ephemeral conversations
•Spec-Driven Development: Move from "vibe coding" to establishing clear, executable requirements for predictable outcomes

Key Features

•4-Tiered Context Structure: Specs (user intent) → Issues (agent tasks) → Agents (execution) → Artifacts (state changes)
•Dual Representation: Human-editable Markdown + YAML, machine-optimized JSONL + SQLite
•Bidirectional Linking: Rich graph relationships between specs and issues with automatic backlink tracking
•Graph-Based Planning: Topological ordering for execution, hierarchical organization, dependency management
•Agent Feedback Loops: Agents can update specs with findings during execution to keep humans in the loop
•Git-Native: Everything lives in git—no external databases or services required

Context Structure

1. Spec (Specification)

A primitive for user intent and context—requirements, RFCs, research questions, design decisions. Specs capture WHAT you want.

Stored as Markdown with YAML frontmatter in .sudocode/specs/

2. Issue

A primitive for agent intent and context—work items derived from specs, capturing tasks within agent scope.

Stored as Markdown + JSONL in .sudocode/issues/

3. Agent

The execution abstraction—represents the actual trajectory of an agentic loop run against an issue.

4. Artifact

A primitive representing state changes from agent execution—code diffs, reports, documentation updates.

Learn More