Kanbus

A tiny Jira clone for your repo.

Inspiration & Lineage

Kanbus is a spiritual successor to Beads, inspired by its elegant, domain-specific approach to project management. We are deeply grateful to the Beads author and community for proving that a dedicated cognitive framework for tasks is game-changing.

Kanbus builds on this foundation by adapting the model to be a thinner, more native layer over Git—optimizing for AI agents and distributed teams:

• A Thinner Layer over Git: We removed the secondary SQLite index. The complexity of maintaining and synchronizing a shadow database isn't worth the operational cost. Kanbus reads files directly.
• Better Storage Alignment: Things like "exclusively claiming" a task don't align well with the distributed Git model. We removed them to ensure the tool behaves exactly like the version control system underneath it.
• Conflict-Free Storage: Instead of a single JSON-L file (which guarantees merge conflicts when agents work in parallel), Kanbus stores separate tasks in separate files. This eliminates conflicts and allows deep linking to specific issues from GitHub.
• Streamlined Cognitive Model: Beads is powerful but complex, with 130+ attributes per issue. We streamlined this to a focused core (Status, Priority, Dependencies) to reduce the "context pollution" for AI agents. We want the model to think about the work, not how to use the tracker. The goal is a helpful cognitive model that unburdens your mental state rather than adding to it.
• AI-Native Nomenclature: Instead of teaching models new terms like "beads", we use the standard Jira vocabulary (Epics, Tasks, Sub-tasks) that AI models are already extensively pre-trained on. This leverages their existing knowledge graph for better reasoning.
• Git-Native Scoping: We replaced complex "contributor roles" with standard Git patterns. Want local tasks? Just .gitignore a folder. Working in a monorepo? Kanbus respects your current directory scope automatically.

Frictionless Workflow

Kanbus is designed to remove friction, not add it.

• No Syncing: There is no secondary database to synchronize. The files on disk are the source of truth. You will never be blocked from pushing code because a background daemon is out of sync.
• Git Hooks Help You: Git hooks should assist your workflow, not interrupt it. Kanbus hooks are designed to be invisible helpers, ensuring data integrity without stopping you from getting work done.

For a detailed comparison, see Kanbus vs. Beads.

Why Kanbus?

1. The Sleep Factor

Offload your mental context. Instead of keeping 15 different chat sessions and open loops in your head, tell your agent to "record the current state" into Kanbus. It's a permanent, searchable memory bank for your AI workforce.

2. Files are the Database

• No SQL Server: We removed the SQLite daemon entirely. Each command reads the JSON files directly, so there is nothing to synchronize or keep running.
• No JSONL Merge Conflicts: There is no monolithic JSONL file. Every issue has its own JSON document, which eliminates merge conflicts when teams (or agents) edit work in parallel.
• No Daemon: There is no background process to crash or manage.
• No API: Your agents read and write files directly (or use the simple CLI).

3. Concurrency Solved

Unlike other file-based systems that use a single JSONL file (guaranteeing merge conflicts), Kanbus stores one issue per file. This allows multiple agents and developers to work in parallel without blocking each other.

4. Jira + Confluence for Agents

Kanbus includes a Wiki Engine that renders Markdown templates with live issue data. Your planning documents always reflect the real-time state of the project, giving agents the "forest view" they often lack.

5. Zero Cost Footprint

There are no per-seat licenses or hosted fees. If you have a git repository, you already have the database—and that keeps Kanbus affordable for very large teams (or fleets of agents).

Status: Planning Phase

This repository contains the complete vision, implementation plan, and task breakdown for building Kanbus. We are building it in public, using Kanbus to track itself.

Quick Start

# Initialize a new project
kanbus init

# Create an issue
kanbus create "Implement the login flow"

# List open tasks
kanbus list --status todo

# Show details
kanbus show kanbus-a1b

Daemon Behavior

Kanbus uses a just-in-time index daemon for read-heavy commands such as kanbus list. The CLI auto-starts the daemon when needed, reuses a healthy socket, and removes stale sockets before restarting.

To disable daemon mode for a command:

KANBUS_NO_DAEMON=1 kanbus list

Operational commands:

kanbus daemon-status
kanbus daemon-stop

Python vs Rust

We provide two implementations driven by the same behavior specification:

Choose Python if:

• You want easy pip install with no compilation
• You are scripting custom agent workflows

Choose Rust if:

• You need maximum performance (sub-millisecond queries)
• You have a massive repository (> 2000 issues)

Project Structure

Kanbus/
|-- planning/
|   |-- VISION.md                  # Complete specification
|   `-- IMPLEMENTATION_PLAN.md     # Detailed technical plan
|-- specs/                         # Shared Gherkin feature files
|-- python/                        # Python implementation
|-- rust/                          # Rust implementation
|-- apps/                          # Public website (Gatsby)
`-- .beads/                        # Project task database

Contributing

We welcome contributions! Please:

1. Pick a task from kanbus ready.
2. Follow the BDD workflow in AGENTS.md.
3. Ensure all quality gates pass.

Testing

Run the full quality gates:

make check-all

Run only Python checks:

make check-python

Run only Rust checks:

make check-rust

Benchmarking

Run index build and cache load benchmarks:

python tools/benchmark_index.py
cd rust && cargo run --release --bin index_benchmark

License

MIT