> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Git-native context management for AI-assisted software development

**sudocode** is a lightweight, git-native context management system for AI-assisted software development. It helps you capture requirements, track agent work, and maintain bidirectional connections between specifications and implementation, all living directly in your repository.

Think of sudocode as **"context-as-code"**: a structured way to organize collaboration between humans and AI agents throughout your development workflow.

* **Specs** capture user intent and requirements
* **Issues** track agent tasks and implementation work
* **Relationships** model dependencies between work items
* **Feedback** enables agents to improve specs as they implement

Everything is version-controlled alongside your code. No external services required.

<img src="https://mintcdn.com/sudocode/Ik176kmcsPL91kj4/media/intro-demo.gif?s=b6acf0c28cfce76fbeaac01e188260d0" alt="sudocode in action" style={{ borderRadius: '0.5rem' }} width="1920" height="1048" data-path="media/intro-demo.gif" />

## Why sudocode?

<Card title="Learn Why sudocode Matters" icon="lightbulb" href="/why-sudocode">
  Understand the problems sudocode solves and how it transforms AI-assisted development
</Card>

## Who is sudocode for?

### Perfect For

<CardGroup cols={2}>
  <Card title="AI-Assisted Development Teams" icon="robot">
    Teams using Claude Code, Cursor, Copilot, or custom agents for daily development work
  </Card>

  <Card title="Long-Horizon Projects" icon="calendar">
    Projects spanning weeks/months where context needs to persist across many sessions
  </Card>

  <Card title="Complex Requirements" icon="diagram-project">
    Features with many interdependent tasks, dependencies, and design decisions to track
  </Card>

  <Card title="Multi-Agent Workflows" icon="users-gear">
    Running multiple AI agents concurrently (e.g., one on backend, one on frontend)
  </Card>

  <Card title="Spec-Driven Development" icon="file-contract">
    Teams that value written requirements and want iterative refinement from implementation
  </Card>

  <Card title="Open Source Projects" icon="code-branch">
    Need context that lives in the repo, accessible to all contributors without external accounts
  </Card>
</CardGroup>

### Maybe Not For

* **Quick prototypes**: Single-session exploratory coding without need for persistence
* **Solo scripts**: One-off automation where there's no ongoing maintenance
* **Non-AI workflows**: Teams not using AI coding assistants (though sudocode still works as a lightweight issue tracker)

## Quick Start

Get up and running in minutes:

<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
  Create your first spec and issue in under 5 minutes
</Card>

## Learn the Core Concepts

Understand how sudocode organizes context:

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines" href="/concepts/specs">
    Capture user requirements and design decisions
  </Card>

  <Card title="Issues" icon="circle-check" href="/concepts/issues">
    Track agent tasks and implementation work
  </Card>

  <Card title="Relationships" icon="diagram-project" href="/concepts/relationships">
    Model dependencies and connections between work
  </Card>

  <Card title="Feedback" icon="comments" href="/concepts/feedback">
    Enable bidirectional learning between agents and specs
  </Card>
</CardGroup>

## Integration Guides

Connect sudocode to your AI agents and workflows:

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Set up sudocode and create your first issue in minutes
  </Card>

  <Card title="Workflows" icon="diagram-next" href="/workflows/spec-driven-development">
    Learn spec-driven development and best practices
  </Card>

  <Card title="MCP Integration" icon="plug" href="/mcp/overview">
    Use sudocode with Claude Code and other MCP-compatible agents
  </Card>
</CardGroup>

## Key Features

* **Dual representation**: Human-readable markdown + machine-queryable JSONL
* **Graph-based planning**: Topological ordering finds ready work automatically
* **Bidirectional linking**: Obsidian-style `[[SPEC-001]]` references with backlinks
* **Smart anchoring**: Feedback tracks specific lines and relocates intelligently
* **Distributed sync**: Git handles distribution; AI handles merge conflicts
* **Multiple interfaces**: CLI, MCP server, REST API, and web UI

## Community & Support

<CardGroup cols={2}>
  <Card title="GitHub Discussions" icon="comments" href="https://github.com/sudocode-ai/sudocode/discussions">
    Ask questions and share use cases
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/sudocode-ai/sudocode/issues">
    Report bugs and request features
  </Card>
</CardGroup>

***

<Note>
  **Philosophy:** Context should be treated like code—version-controlled, collaboratively edited, and evolved alongside your implementation. sudocode makes this possible for AI-assisted development.
</Note>
