What is Kodebase?

Kodebase is a git-native project intelligence system that provides structured context for AI coding assistants. It stores project artifacts as YAML files directly in your repository, giving LLMs the context they need to understand your project's scope, dependencies, and workflow.

The Problem

AI coding assistants are powerful, but they lack project context. They can write code, but they don't know:

• What you're building and why
• Which features are planned vs. in progress
• How tasks relate to each other
• What decisions have been made and their rationale

This leads to fragmented development where the AI helps with isolated code snippets but can't contribute to the bigger picture.

The Solution

Kodebase bridges this gap by maintaining structured project intelligence that:

1. Lives in your repo - Artifacts are YAML files in .kodebase/, version-controlled alongside your code
2. Provides LLM context - AI assistants can read and understand your project structure
3. Tracks progress - Every artifact has a lifecycle from idea to completion
4. Connects via MCP - Model Context Protocol lets any compatible AI access your project context

Git-Native by Design

Traditional project management tools store data in external databases. Kodebase takes a different approach:

your-project/
├── .kodebase/
│   ├── artifacts/
│   │   └── A.my-initiative/
│   │       ├── A.yml                 # Initiative
│   │       └── A.1.my-milestone/
│   │           ├── A.1.yml           # Milestone
│   │           ├── A.1.1.my-issue.yml # Issue
│   │           └── A.1.2.another.yml  # Issue
│   └── config.yml
├── src/
└── ...

This means:

• Version control - Track changes to project plans like code
• Branch-aware - Different branches can have different artifact states
• No external dependencies - Your project context travels with your code
• Transparent - Anyone can read the YAML files directly

Bring Your Own Model (BYOM)

Kodebase doesn't lock you into a specific AI provider. Through MCP (Model Context Protocol), it works with:

• Claude (via Claude Code or API)
• Cursor (with MCP support)
• Any MCP-compatible client

You choose the AI that works best for you. Kodebase provides the project context; your AI provides the intelligence.

Why Artifacts Live in .kodebase/

Storing artifacts alongside code provides several benefits:

Benefit	Description
Atomic commits	Code changes and artifact updates in the same commit
Branch isolation	Feature branches have their own artifact state
Code review	Project management changes go through PR review
History	Git log shows when and why project decisions changed
Portability	Clone the repo, get the full project context

Next Steps

• Learn about Core Concepts like artifacts, initiatives, and issues
• Understand The Workflow with Scout and Sherpa agents
• See how IDE Integration connects everything