by sudocode-ai
Lightweight agent orchestration dev tool that lives in your repo
# Add to your Claude Code skills
git clone https://github.com/sudocode-ai/sudocodeNo comments yet. Be the first to share your thoughts!
sudocode is a lightweight agent orchestration system that lives in your repo. 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.
sudocode tracks human-specified requirements and objectives (what to do) as specs, and agent runtime context and plans (how to implement) as issues. These are trackable in git as a form of version-controlled memory for your agents. Specs/issues are both human and agent-editable. This allows agents to manage their own context and leave contextual breadcrumbs as they run for all agents to reference.
Specs and issues form the backbone for advanced agent coordination and automation. Use specs to define high-level requirements and let agents carry out the implementation and manage their own issues.
The sudocode package includes a CLI, local server/UI, and an MCP server.
Use the CLI for managing specs and issues in sudocode's agent memory system. It contains a complete interface for viewing, editing, and managing relationships between entities.
Use the local server to automatically sync memory and enable agent execution and visualization. The issue kanban view helps you track issue status and progress. You can spawn new agents, update agent implementation plans, and provide feedback or guidance to running agents in a single, focused view.
The spec editor view boosts spec-driven development to new heights. Edit and review specs with a full-featured block or markdown editor. Agents leave feedback on specs as they execute, so you can track their work and stay in the know for with the code they produce.
Once you have a dependency graph of issues, you can also automate the implementation of each issue in the graph as a workflow. This runs each issue in topological order and accumulates changes in a temp branch/worktree. As it's executing, each issue will have its own commit, so you can revert backwards in the commit history if you want to continue developing from a specific point.
If you're up for it, you can even monitor all running agent trajectories at the same time.
sudocode provides a structured yet flexible system for organizing the chaos of human-AI collaboration in software development.
# Install globally (recommended: use npx instead to avoid Node version conflicts)
npm install -g sudocode
# Initialize a sudocode project in your project directory.
sudocode init
# Run the local sudocode server from anywhere
sudocode server
# To connect your agent directly to sudocode, install our plugin
claude plugin marketplace add sudocode-ai/sudocode
claude plugin install sudocode
# Note, instructions for other agents can be found in the quick start guide
Check out our Quick Start Guide for tutorials and walkthroughs.
sudocode now supports syncing with external spec and issue tracking systems through a plugin-based integration framework. This allows you to maintain specs and issues in your preferred tools while keeping sudocode's agent memory system in sync.
Supported Integrations:
| Integration | Description | Sync Direction | |-------------|-------------|----------------| | Beads | Git-native issues system | Bidirectional | | Spec-Kit | Markdown-based specification system | Bidirectional | | OpenSpec | Structured spec and change proposal system | Bidirectional | | Jira | Atlassian issue tracking | Coming soon | | Linear | Modern issue tracking | Coming soon |
In the sudocode UI, enable integrations in Settings > Integrations. Via the CLI, update with sudocode plugin.
Integrations automatically create specs, issues, and relationships between synced entities and support real-time file watching for immediate sync updates. Use sudocode to link and implement work items across different systems.
We're actively adding support for new integration targets. Please file an issue or drop a message for anything you would like sudocode to support!
Your context and designs are just as valuable as the code being written. Code is often over-specified, while your actual requirements are under-specified and come with design choices and intent that is not immediately captured.
With sudocode, you treat your git repo as a distributed context database to capture context and make it readily available to coding agents. You can track user intent (specs), agent tasks (issues), and agent trajectories (executions) as they evolve alongside your codebase.
Git handles distribution while AI handles merge conflicts.
A spec can be thought of as user intent + relevant context. Combined, a spec contains enough information for an agent to carry out the requirements defined in the task.
Reduce the chaos of "vibe coding" by establishing clear, executable requirements in order to produce predictable outcomes.
sudocode implements a 4-tiered abstraction structure for representing context, corresponding to increasing granularity from high-level requirements to low-level implementation:
A primitive for user intent and context—requirements, RFCs, research questions, design decisions. Specs capture WHAT you want.
.sudocode/specs/A primitive for agent intent and context—work items derived from specs, capturing tasks within agent scope.
[[@ISSUE-001]] referencesblocks, related, parent-child, discovered-from.sudocode/issues/)The execution abstraction—represents the actual trajectory of an agentic loop run against an issue.
.sudocode/agents/A primitive representing state changes from agent execution.
Every entity has both a **hum