Kaddo

Kaddo is an open-source CLI and agent toolkit that helps new, pre-AI and legacy projects build a living knowledge layer close to the code. The CLI prepares and structures the context; your LLM agents turn it into product understanding.

New projects · Pre-AI codebases · Legacy systems

kaddo

# New project
$ npx @kaddo/cli init

# Existing or pre-AI project
$ kaddo scan

# Legacy project
$ kaddo scan —legacy

# Create a lightweight work item, then detect drift
$ kaddo create feature
$ kaddo guard
FYI src/payments/payments.service.ts matches WI-001
    WI-001 was not modified in this diff — consider reviewing it.

From scattered code to observable product knowledge.

Why Kaddo?

Your project already has knowledge. It is just scattered.

In new projects, decisions disappear fast. In pre-AI projects, context was never prepared for agents. In legacy projects, knowledge often lives in people’s heads.

Kaddo brings that knowledge closer to the code and helps keep it alive as the system changes.

Choose your starting point

New project

Start with structured knowledge from day one. → New project

Pre-AI project

Prepare an existing repo for humans and LLM agents. → Pre-AI project

Legacy project

Understand before changing risky systems. → Legacy project

See the full loop

The complete end-to-end workflow with expected artifacts. → Full workflow

Prefer to see it first? The Visual Guide maps the whole loop, the CLI/LLM split and Guard as diagrams. Not sure what Kaddo does and does not do? Read the Project scope.

CLI + LLM Agents

Kaddo works in two layers.

The CLI handles deterministic work: initializing the knowledge repository, scanning the codebase, creating work items and detecting possible knowledge drift.

Your LLM handles interpretation: using Kaddo agents to extract capabilities, reconstruct architecture, identify risks and propose a roadmap from the project context.

Kaddo does not try to make the CLI “understand everything”. The CLI collects and structures signals. The LLM agents turn those signals into product understanding.

How it works

Kaddo does not start by creating tasks. It starts by understanding the state of the project, then builds knowledge progressively before you evolve the code.

1 · Initialize & scan

kaddo init then kaddo scan — tell Kaddo your project state and detect stack, structure and technical signals deterministically.

2 · Prepare context

kaddo context builds an LLM context pack and kaddo add agents installs agent prompts.

3 · Understand with agents

kaddo understand guides the handoff — then use Kaddo agents in your LLM chat to extract capabilities, architecture, risks and a roadmap.

4 · Create from roadmap

kaddo create --from roadmap turns a roadmap candidate into a Work Item; kaddo owners suggest declares code ownership.

5 · Guard & explain

kaddo guard detects when code may drift from knowledge; kaddo explain summarizes what the project currently knows.

The full workflow

kaddo init          # state: new | pre-ai | legacy, team size, structure
kaddo scan          # deterministic technical inventory
kaddo context       # LLM context pack for agent handoff
kaddo add agents    # install agent prompt packs
kaddo understand    # guided CLI → LLM handoff plan
# use your LLM with the context pack + agents to create capabilities, architecture & roadmap
kaddo create --from roadmap
kaddo owners suggest
kaddo guard
kaddo explain

The CLI prepares context; your LLM interprets it. Kaddo never calls an LLM by itself.

See it in action

Four reproducible demo repositories ship with committed .kaddo/ and architecture/ artifacts — open one and inspect exactly what Kaddo produces. Each includes a prompt-flow.md with a Mermaid diagram, the CLI↔LLM split and copy/paste prompt handoffs for its scenario.

Task Pilot

Greenfield app · new — structured knowledge from day one; full loop.

Loyalty Lite

Existing app · pre-ai — scan + agents + a Guard drift demo.

Old Orders

Legacy MVC app · legacy — understand-before-change; risks & unknowns.

Commerce Stack

Many repos · multirepo — modules map + per-module artifacts.

Browse them in the Examples guide, or explore the Templates that capture minimum sufficient knowledge for each artifact.

Scale to multirepo

Kaddo also models a system that spans many repositories. From the architecture repo you map secondary repos as modules and keep their knowledge close to the code:

kaddo modules map        # register a secondary repo (frontend/backend/infra…) as a module
kaddo modules list       # list mapped modules
kaddo add standards|security|stack|git-strategy   # global, system-wide artifacts

Per-module knowledge

modules map generates template-based module-design, stack, security and standards artifacts under architecture/modules/<id>/, with front matter and code: ownership globs.

Module-aware context & explain

kaddo context and kaddo explain surface mapped modules and their artifact coverage — distinct from add-on modules installed with kaddo add.

Workspace Guard

Opt-in kaddo guard --workspace checks local mapped repos and flags possible drift against code: globs — non-blocking, no cloning, no remote APIs.

Global artifacts

Standards, security, stack and a recommended Git strategy document cross-cutting concerns once for the whole system.

See the Multirepo modules guide and the Visual Guide for the full system map.

Start with a repo that remembers

From new projects to legacy systems, Kaddo keeps product knowledge close to the code.

Get started →