Skald

Track work from idea to release, in Markdown, in your repo, with your coding agents.

Skald turns a folder of Markdown files into a backlog that travels with your code. Capture an idea, plan it, hand it to an agent, answer the questions it raises, review the result, and ship it in a release, with every step recorded as a dated note in the story's own file. Agents drive it from a small CLI that fits in a session's context. You drive it from a local board that shows every project and worktree on the machine. There is no database and no service: one dependency-free Python package, and git is the history.

.skald/
├── config.json   # project name, story format version, columns  (committed)
├── AGENTS.md     # what an agent needs to know, written by `init` (committed)
├── stories/      # one Markdown file per story                   (committed)
│   └── a3f9c2-implement-wireguard-overlay.md
└── archive/      # stories shipped in a release, moved out of the way

Stories are committed with the code they describe, so the board travels with the branch and shows up in pull request diffs.

An agent's session: claim, resume, hand off, move, and see the diff.	The same story on the board: dependencies, acceptance criteria, notes.

What you get

• A workflow agents can follow. context orients a session in one block, next and claim pick work without stepping on other agents, resume reads what the last session left behind, notes carry kinds such as decision and handoff, and acceptance checklists gate the move to done. The contract is one Markdown file that init writes for you.
• A board for the human. Every registered project in one page, live updates, drag, multi-select, dependency graph, the working tree of every worktree on the machine, read-only views of other branches, dark mode, and a Help panel with the full CLI reference.
• Git as the database. Story changes commit with the code they describe and carry Skald-Story trailers. diff, activity, and changelog read history back; render commits a snapshot GitHub shows in place; release turns the done column into a changelog section and a versioned archive.
• More than one repository. A machine-local index gives you one board and project:id dependencies across every repository you use Skald in.
• Nothing to run. Python standard library only, Python 3.9 or newer, Linux, macOS, and Windows. Tab completion for bash, zsh, and fish.

Is Skald the right tool?

Several projects keep a tracker inside the repository. They make different trade-offs, so this table is about focus rather than ranking. Checked against each project's README in September 2026; follow the links for current detail.

Skald is a good fit when agents do most of the work, a human wants to see that work on one board across repositories, and the backlog should read well in a pull request diff. Reach for something else when you want threaded discussion on issues (git-bug, or the hosted tracker you already use), a long history that needs summarising to save context (Beads), or two-way sync with GitHub issues (git-bug, git-issue).

Install

pip install skald-kanban
# or: pipx install skald-kanban
# or: uv tool install skald-kanban
# latest from source: pip install git+https://github.com/Vitund-AI/skald.git
cd your-repo
skald init

The distribution name is skald-kanban; the command is skald, and git skald works too. init creates .skald/, writes the agent contract, registers the project on your machine, and points your CLAUDE.md or AGENTS.md at the contract. Shell completion is one line in your rc file:

eval "$(skald completion zsh)"       # or bash; fish: skald completion fish > ~/.config/fish/completions/skald.fish

Quick start

skald new "Implement WireGuard overlay" --tags infra --body "Configure wg0 on every node."
skald new "Write the network docs" --status ready --blocked-by a3f9c2
skald ls
skald open            # starts the board server if needed and opens this project

An agent's session looks like this:

skald context --as claude         # mine, next, blockers, claims elsewhere, uncommitted
skald claim a3f9c2 --as claude    # assign it and move it to in_progress
skald resume a3f9c2               # requirements, checklist, deps, latest handoff
skald note a3f9c2 "Why we chose X" --as claude --kind decision
skald note a3f9c2 "Done: ... Remaining: ... Next: ..." --as claude --kind handoff
skald move a3f9c2 review
git add .skald src && git commit --trailer "Skald-Story: a3f9c2"

For Claude Code, skald hooks claude --install --as claude adds a SessionStart hook that runs skald context so every session begins oriented without reading the whole backlog, a Stop hook that refuses to end with a broken backlog, and a skill that loads the contract. Agents without a shell can use skald mcp.

Documentation

The design is in SPEC.md and the reasoning behind non-obvious choices in DECISIONS.md.

Development

pip install -e .
python -m unittest          # standard library only
skald serve                 # run against this repository's own backlog
skald docs                  # regenerate docs/cli.md after changing a command

This repository dogfoods Skald: its own backlog is in .skald/, and the board rendered from it is at .skald/README.md.

License

MIT. See LICENSE.