yurtle-kanban: A Kanban Board Where Git Is the Database

Here's a question: what happens when you have three AI agents working in parallel — one on a DGX Spark, one on a MacBook, one on a Mac Mini — and they all need to pick up work, track progress, and not step on each other?

You need a coordination system. And it needs to be:

  • Atomic — two agents can't grab the same ID
  • Distributed — works offline, syncs through Git
  • Inspectable — humans can read the board without special tools
  • Durable — survives crashes, reboots, context window resets

We tried Jira. We tried Linear. We tried GitHub Issues. None of them worked for agents. The APIs were too slow, the data models were too rigid, and the agents couldn't reason about work items without expensive API round-trips.

So we built yurtle-kanban. Every work item is a Markdown file. Every status change is a Git commit. The kanban board is just ls plus some YAML parsing.

Two thousand expeditions. Three agents. No ID collision we have ever found, and no lost work item.

pip install yurtle-kanban

How It Works

A work item is a Markdown file with YAML frontmatter:

---
id: EXP-835
title: Website LHT Strategy Pivot
status: in-progress
created: 2026-02-14
priority: high
assignee: Mini
tags: [website, content, strategy]
---

# EXP-835: Website LHT Strategy Pivot

Update congruentsys.com to reflect the new publication strategy...

That's the entire data model. The file is the ticket. Read it with any text editor. Diff it with Git. Query it with SPARQL (via yurtle-rdflib). Render the board in your terminal:

yurtle-kanban board

Harbor          Provisioning    Underway        Approaching     Arrived
─────────       ────────────    ────────        ───────────     ───────
EXP-835         EXP-832         EXP-831         EXP-827         EXP-820
EXP-834                         EXP-830                         EXP-821
EXP-833                                                         EXP-822

The Multi-Agent Problem

The reason this tool exists is next-id. When two agents simultaneously need a new expedition ID, you have a race condition. Jira handles this with a database transaction. We handle it with Git's atomic file creation:

yurtle-kanban next-id EXP --json
# {"id": "EXP-836", "allocated": true}

This creates a lock file, checks the highest existing ID across all files and Git history, increments, and commits — atomically. Two agents running next-id at the same time will never get the same number.

We've run more than two thousand expeditions across three agents with this mechanism, and have not found a single ID collision. Worth being precise about what that is: we have no check that would positively detect one, so it is an absence of reports rather than a verified zero.

Themes: Speak Your Language

yurtle-kanban ships with two themes:

Software (default): Feature, Bug, Epic, Story. Columns: Backlog → To Do → In Progress → Review → Done.

Nautical (what we use): Expedition, Voyage, Hazard, Signal, Directive. Columns: Harbor → Provisioning → Underway → Approaching Port → Arrived.

The nautical theme isn't cosmetic — it's a different mental model. An expedition has a destination, a captain, and a crew. It can get stranded. It can be redirected. The metaphor shapes how agents think about work.

Claude Code Integration

yurtle-kanban ships with an MCP server and Claude Code skills out of the box:

pip install yurtle-kanban[mcp]

Skills include /work (pick up next expedition), /done (complete with tests + commit + push), /review (pre-merge checklist), /handoff (transfer to another agent), and /status (board overview).

Our agents use these skills every session. They pull up the board, claim work, execute, and close — without any human coordination.

The Complete Stack

With yurtle-kanban, the Yurtle open source ecosystem is now three tools:

  1. Yurtle — the format (Markdown as knowledge graph nodes)
  2. yurtle-rdflib — the engine (SPARQL queries + live sync)
  3. yurtle-kanban — the workflow (Git-native kanban for agents and humans)

All three are MIT-licensed. All three use the same underlying format. Together they form a complete knowledge-work platform where every artifact — documents, data, and work items — lives as a queryable Markdown file in Git.

Repository: github.com/hankh95/yurtle-kanban PyPI: pip install yurtle-kanban License: MIT