Design Philosophy

Kanbus is built on a set of core principles that prioritize developer experience, transparency, and longevity.

Why Kanbus Exists

Game-changing technology for the age of AI agents.

The Sleep Factor

The motivation for Kanbus came from a simple need: to offload mental context without constantly switching applications. When you are juggling dozens of open loops—chat sessions, pending tasks, architectural decisions—you need a place to put them that doesn't require logging in or managing infrastructure.

Kanbus allows you (and your AI agents) to dump context immediately into the repository. It's the difference between keeping 15 plates spinning in your head and putting them on a shelf.

Inspiration & Lineage

Standing on the shoulders of giants.

A Spiritual Successor to Beads

This project was inspired by Beads and is intended as a spiritual successor that embraces the elegant domain-specific cognitive framework it pioneered. Deep gratitude to the Beads author and community for proving the concept so well.

Kanbus represents the next generation of this idea, improved for the era of AI agents:

  • Thinner layer over Git: Kanbus removes the secondary SQLite database to eliminate synchronization complexity.
  • Git-aligned storage: Separate files for separate tasks mean no merge conflicts when agents work in parallel.
  • Focused Cognitive Model: Kanbus strips away 100+ unused attributes to focus on the core cognitive framework, reducing context pollution for AI models.
  • Standard Nomenclature: Kanbus uses standard terms (Epics, Tasks) to leverage the massive pre-training AI models already have on these concepts.

Core Principles

The fundamental rules that guide the development of the Kanbus system.

1. Files are the database

There is no hidden SQLite file, no background daemon, and no remote API. The state of your project is strictly defined by the JSON files in your repository. Each command scans those files directly—the files are the truth.

2. One File Per Issue

Other systems store everything in a single JSONL file. This guarantees merge conflicts when two people (or agents) work on different tasks simultaneously. Kanbus splits every issue into its own file, letting Git handle the merging naturally.

3. Helpful Cognitive Model

The task model should unburden your mind, not add to it. Kanbus strips away 100+ unused attributes to focus on a core, elegant framework (Status, Priority, Dependencies). This helps AI agents focus on solving problems, not navigating the tool.

4. Agent-Native

Kanbus is basically Jira + Confluence for agents. The CLI allows agents to read the current state of the world, and the Wiki engine allows them to read dynamic summaries of initiatives. It is designed to be the memory bank for your AI workforce.

5. Git-Native Scoping

No complex roles needed to handle private tasks. Just use .gitignore. Kanbus respects your directory structure: run it at the root to see everything, or in a subfolder to focus on that module. It leverages the tools you already use.

Architecture

How Kanbus works under the hood.

No Friction

Git hooks should help you, not block you. Kanbus removes the concept of syncing entirely. There is no secondary database to maintain, so you are never blocked from pushing your code.

The Wiki Engine

The wiki command renders Markdown templates using the Jinja2 engine. It injects a project context object that gives you access to the entire issue graph. This allows you to write living documents that always reflect the latest status.