beads-utils
CLAUDE.md2 starsChanged 6 days agoMITView on GitHub
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands. When ending a work session: Pushing (git push / bd dolt push) is the user's call, not the agent's. Commit, then ask — do not push autonomously. <!-- END BEADS INTEGRATION --> A small collection of Python utility scripts that augment the beads (bd) issue tracker and its Dolt-backed storage, plus the Claude Code skills under skills/ and hooks under hooks/ that…
- Commits and pushes
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- changelogSkill
- close-shopSkill
- deferSkill
- finalizeSkill
- review-titlesSkill
- start-taskSkill
- statusSkill
The file
We split this CLAUDE.md into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Very specific: line 22
Run bd prime for detailed command reference and session close protocol
- Very specific: line 23
Use bd remember for persistent knowledge — do NOT use MEMORY.md files
- Distinctive: line 27
When ending a work session:
- Distinctive: line 188
Before changing a script's behavior, make sure its rule file is in context, and read it directly if not.
- Very specific: line 200
When adding/renaming a flag or script, update the matching flag list in both completion files — tests/test_completions.py fails if either …
- Very specific: line 211
No build system, no package — but a Makefile as the single front door for every routine command, so neither a returning maintainer nor CI …
- Very specific: line 279
Versioning: all scripts share a single bdutils.__version__.
- Very specific: line 286
Do not bump __version__ as part of feature work — add a bullet under ## Unreleased in CHANGELOG.md and leave the number alone.
- Very specific: line 300
Errors: use bdutils.error(msg) — exits non-zero with a lowercase error: ...
- Very specific: line 302
Warnings: use bdutils.warn(msg) — writes warning: ...
- Very specific: line 303
Project path: use bdutils.resolve_project_path(arg) for the expanduser/resolve/ .beads/-validation dance.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->Beads Issue Tracker
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete workRules
- Use
bdfor ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists - Run
bd primefor detailed command reference and session close protocol - Use
bd rememberfor persistent knowledge — do NOT use MEMORY.md files
Session Completion
When ending a work session:
- File issues for remaining work — create beads for anything that needs follow-up
- Run quality gates (if code changed) — tests, linters, builds
- Update issue status — close finished work, update in-progress items
- Commit — stage and commit your changes
- Hand off — provide context for next session
Pushing (git push / bd dolt push) is the user's call, not the agent's. Commit, then ask — do not push autonomously.
<!-- END BEADS INTEGRATION -->What This Is
A small collection of Python utility scripts that augment the beads (bd) issue
tracker and its Dolt-backed storage, plus the Claude Code skills under skills/ and
hooks under hooks/ that plug into the agent itself. Each script sits in bin/ alongside a
shared bdutils.py helper module — no package, no build step. Scripts run from the
clone as bin/<script> (Python's default sys.path[0] resolves the sibling bdutils
import), or from anywhere via the symlinks make install puts in PREFIX, since
sys.path[0] is the resolved directory and the sibling import survives the link.
Current scripts:
bd-export-csv— Shells out tobd export --all --no-memories, parses the JSONL, and writes a flat CSV suitable for spreadsheet review. Supports-s/--sortwith comma-separated keys and--prefixed descending order.bd-dolt-check— Verifies that a beads repo's Dolt data is committed and pushed. The Dolt data lives underrefs/dolt/dataon the beads remote (the Dolt database's own remote, elsesync.remote, else the git origin), invisible in GitHub's UI. It checks that ref withgit ls-remote, compares the local Dolt branch with its remote-tracking ref, and reads the Dolt working set (dolt_status) for tables changed but in no commit. Exits 1 onOUT OF SYNCorUNCOMMITTEDso CI can gate on it.bd-dolt-diff— Previews what abd dolt pushwould send: an issue-level diff between the remote-tracking ref and the local branch.--base/--headdiff any two Dolt revisions. Read-only, exits 0 whenever the comparison ran. Requires thedoltCLI.bd-verify-backup— Is everything on GitHub? Per repo: no uncommitted files or stashes, every local branch has an upstream and is not ahead of it, and the beads data is committed and pushed (bdutils.dolt_sync_state(), the same computationbd-dolt-checkrenders).-g/--globalchecks every beads repo on the machine in parallel, one line each. Fetches first unless--no-fetch. Never runsbd. Exits 1 if anything is not backed up.bd-log— Git-log-style timeline of bead and memory lifecycle events, newest first.--onlypicks the verb (create/change/end),--aboutthe entity (beads/memories);--status,--open,--id,--children,--no-deferredand--no-blockedscope the beads. Memory events are reconstructed from Dolt commit history, becausebd rememberrecords no timestamps.bd-view— Pretty-prints a single bead with rendered Markdown viarich, resolved through auv run --scriptshebang; falls back to plain text without it. Takes an issue id.bd-find-live— The beads that are live work, as JSON: open or in progress, minus those parked behind a deferred bead (a chain of blockers that reaches one).--leanswaps each notes log fornotes_len. Names what it left out on stderr. Feeds the/close-shopbead audit.claude-session-find— Finds an old Claude Code session's UUID by grepping transcripts; current project by default,-gfor all.claude-session-list— Git-log-style listing of recent Claude Code sessions, with prompt/reply counts and titles; hides empty sessions.claude-session-report— Renders a session transcript as Markdown, with each content category (thinking, tools, skill bodies, …) a separate toggle.claude-session-rename— Retitles a session from the shell exactly as/renamewould, by appending the same two records. Refuses a running session.claude-sessions-review— Recurring tool failures across sessions: each failed tool result reduced to a signature, grouped, ranked by distinct sessions.--kindpicks failures, denials or outages;--jsonfeeds/dream(beads-utils-c1k). Current project by default,-gfor all.claude-traffic-monitor— Livetop-style screen (curses) of internet traffic per running Claude Code session since the monitor started: 5 s / 1 min / 15 min rates plus a 1-minute peak, totals, API share, context size, images in context and the estimated upload of the next request, plus the busiest non-Claude processes.top-style keys (?lists them). macOS only (nettop). Needs a terminal.claude-memory-check— Lints Claude Code memory directories (every project's by default): broken[[links]]that were meant to resolve, bad or duplicatename:slugs, and aMEMORY.mdout of step with its directory are errors (exit 1); links to memories not written yet are listed as pending.claude-memory-setup— Gives Claude Code's memory files a git repo of their own:.gitat~/claude-memories.git(or$CLAUDE_MEMORIES_GIT), work tree~/.claude/projects, an allowlist.gitignoreexposing only*/memory/*.md. Fresh, or--remote URLto clone onto a new machine. Rerunnable.bd-complete— Emitsvalue<TAB>descriptioncompletion candidates (ids,sessions); the single front door behindcompletions/.
Shared helpers, both stdlib-only:
bdutils.py—error(),warn(),resolve_project_path(),format_ts(),format_priority(),paged_output(),run_bd_json()(thebd ... --jsonrunnerbd-logandbd-find-liveshare), and color (add_color_arg(),want_color(),paint()), plus the git/Dolt plumbing (dolt_sync_state()and thedolt_*readers) thatbd-dolt-check,bd-dolt-diffandbd-verify-backupshare.claudeutils.py— Claude session enumeration and resolution (path, UUID or title substring), shared by theclaude-session-*scripts,claude-sessions-review,claude-traffic-monitor,bd-complete, andbd-verify-backup(which reads the project list in~/.claude.json).
Claude Code skills, one directory each under skills/<name>/SKILL.md, linked
by make install-claude into ~/.claude/skills/<name> so each answers to
/<name>: start-task, finalize, close-shop, defer, status,
changelog, review-titles. All but status and changelog read
~/.claude/skill-extensions/<name>.md and then the project's
.claude/skill-extensions/<name>.md. Why skills and not a plugin, what was
scrubbed from the dotfiles originals, and why the title rules ship as a file
of their own, is in .claude/rules/skills.md.
Claude Code hooks, bash, under hooks/ (not bin/, so shebang discovery
does not sweep them into ruff and the --version smoke test), installed by
make install-claude into ~/.claude/hooks and wired into settings.json by
hand:
claim-guard.sh(PreToolUse, matcher Bash) — abd update <id> --claimon a dirty git tree becomes a permission ask: one bead, one commit, at the boundary..beads/does not count as dirt.defer-hint.sh(UserPromptSubmit) — one injected line pointing at/deferwhen the prompt has both a park-ish verb and a task-ish noun.commit-memories.sh(SessionEnd) — commits the memories repo, pushes if it has an upstream; fails closed when any non-memory path is visible.check-memories-pushed.sh(SessionStart) — asystemMessagewhen a refusal is recorded, a push was rejected, there is no upstream, or commits sat unpushed for a day.
Most scripts accept an optional project path argument (default: cwd) and print a
user-facing summary to stdout / errors to stderr with non-zero exit on failure.
Exceptions: bd-view takes an issue id (and relies on bd's own .beads/
auto-discovery from the current directory); claude-session-find takes a search
query; claude-session-report takes a
Claude session UUID, title substring, or .jsonl path; claude-session-list
and claude-sessions-review take no positional args (current project
unless -g/--global);
claude-session-rename takes a session and a title; claude-traffic-monitor
takes none (it watches the whole machine); claude-memory-check takes memory
directories (default: every project's); claude-memory-setup takes none (flags
only); bd-complete
takes a candidate kind (ids or sessions).
Design notes live in .claude/rules/
The rationale behind each script — why a flag delegates to bd, what was
verified rather than assumed, which alternatives were tried and rejected —
lives in path-scoped files under .claude/rules/. Claude Code loads each one
when a matching file is read, so it arrives when you open the script or its
tests and costs nothing otherwise:
| Rule file | Loads for |
bd-log.md, bd-dolt-check.md, bd-dolt-diff.md, bd-verify-backup.md, bd-view.md, bd-find-live.md | that script and its test file |
claude-memory.md | claude-memory-check, claude-memory-setup, the two memory hooks, their tests |
hooks.md | hooks/claim-guard.sh, hooks/defer-hint.sh, tests/test_workflow_hooks.py |
skills.md | skills/, tests/test_skills.py |
claude-sessions.md | claude-session-*, claude-sessions-review, claudeutils.py, their tests |
claude-traffic-monitor.md | claude-traffic-monitor and its test file |
completions.md | completions/, bd-complete, their tests |
bdutils.md | bdutils.py and its tests |
tests.md | anything under tests/, pytest.ini |
makefile.md | Makefile, tests/test_makefile.py |
screenshots.md | tools/, docs/img/ |
Before changing a script's behavior, make sure its rule file is in context, and read it directly if not. New rationale goes into the matching rule file, not here: this file loads into every session, so it holds only what every session needs. Each script's rule file ends with its manual checks.
Shell completion
completions/beads-utils.zsh and completions/beads-utils.bash provide tab
completion (sourced from the user's rc file; see docs/development.md). They are pure
glue — compdef/complete wiring plus per-command flag lists transcribed
from each script's argparse — and route every dynamic lookup through
bd-complete, so enumeration logic is never duplicated across the two shells.
When adding/renaming a flag or script, update the matching flag list in both
completion files — tests/test_completions.py fails if either drifts from the
script's argparse, which is how claude-session-report's --prompts /
--replies / --slash-commands were found missing from both. There is no
caching yet; if added, it wraps bd-complete alone.
The shell-specific corrections both files carry, and how to test them in a
real shell, are in .claude/rules/completions.md.
Running & Testing
No build system, no package — but a Makefile as the single front door for
every routine command, so neither a returning maintainer nor CI has to recall
an invocation. make help lists all of it; make alone shows that help.
make test # the suite (rich installed; nothing skips if jq and GNU timeout are present)
make test PYTEST_ARGS='tests/test_bd_log.py -k SelectSubtreesBranches'
make test-minimal # without rich: 3 more skips, no failures
make check # ruff + a --version smoke test of each script
make ci # exactly what CI runs
make coverage # suite + htmlcov/
make dolt-check / dolt-diff / export-csv # this repo's own beads data
make install / uninstall # symlink the scripts onto PATH (PREFIX=)
make install-claude / uninstall-claude # symlink skills/ and hooks/ into ~/.claude (CLAUDE_HOME=)
make doctor # which tools are present; offers to install the missing ones
make screenshots # regenerate the docs pages' terminal images
make completions # the rc-file line for tab completion
make outdated # newer releases of the pinned tools.github/workflows/lint.yml invokes make check and make test rather than
spelling the commands out, so a command and its pinned tool version exist in
exactly one place. Add a target rather than documenting a raw invocation.
Tests are a pytest suite under tests/, run through uv so nothing is
installed into any global environment (pytest.ini is config, not packaging —
a pyproject.toml would read as packaging the collection).
The suite's traps — fake bd/dolt on PATH, the two assertion styles,
timezone pinning, cache clearing — are in .claude/rules/tests.md; notes
for editing the Makefile are in .claude/rules/makefile.md.
Also verify manually against a real beads project (this repo itself is
one). Each rule file lists its script's commands; bd-export-csv has no
rule file, so its are here:
./bin/bd-export-csv . # Export this repo to CSV in cwd
./bin/bd-export-csv . --sort=-priority,created_atbd-dolt-check assumes the dolt CLI is installed for its richest output but
degrades gracefully when it isn't. bd-log is in the same position for its
memory row only: without dolt (or in a JSONL-only repo) the bead half still
renders in full, and nothing is said unless --about asked for memories.
bd-view requires uv on PATH — its shebang
is #!/usr/bin/env -S uv run --script and PEP 723 inline metadata declares the
rich + markdown-it-py deps, which uv resolves into a per-script cached venv
(no global Python install touched). All other scripts are Python 3 stdlib only.
bd itself is needed only by bd-export-csv, bd-log, bd-find-live, bd-view
and bd-complete's ids. bd-dolt-check and bd-verify-backup read git, Dolt and
.beads/ files directly. bd-verify-backup never runs bd and does need dolt:
without it the beads check is UNVERIFIABLE, which fails there, though
bd-dolt-check exits 0 on it. The claude-session-* scripts,
claude-sessions-review and claude-memory-check need neither; claude-memory-setup
and the hooks under hooks/ need git and jq (the setup refuses to run without jq;
claim-guard.sh also runs bd, and skips that part when bd or timeout is absent).
claude-traffic-monitor is macOS-only: it reads macOS's nettop and draws with
curses, so it needs a terminal.
Conventions
- Shebang:
#!/usr/bin/env python3— no hardcoded paths. - Python:
from __future__ import annotations; stdlib only by default. Third-party deps allowed where they're load-bearing for the script's purpose (e.g.bd-viewneedsrichfor Markdown rendering);bdutils.pyitself stays stdlib-only. - Argument parsing:
argparse. UseRawDescriptionHelpFormatterwithdescription=andepilog=when a richer help block is warranted. - Versioning: all scripts share a single
bdutils.__version__; add the--versionflag viabdutils.add_version_arg(parser)so every script prints<prog> <version>identically. Paging scripts also accept--no-pager. Colorizing scripts take--color=auto|always|neverviabdutils.add_color_arg(parser)and resolve it once withbdutils.want_color()— same rationale as--version, so the flag spelling and the auto-detection rules can't drift between scripts. Do not bump__version__as part of feature work — add a bullet under## UnreleasedinCHANGELOG.mdand leave the number alone; it moves only at release time (see Releases). - Changelog bullets: one short outcome clause each — what a user gets, not
how it works. Group by category in the order
[breaking],[feature],[fix],[refactor],[cleanup]; nest sub-bullets under a multi-part feature rather than spreading it across several top-level lines. Design rationale belongs inCLAUDE.mdor the matching.claude/rules/file, not inCHANGELOG.md— the one thing a bullet must never drop is a[breaking]change's migration path. - Color: plain 30–37 hues only. Solarized repurposes the bright slots
(90–97) as greys, and
boldreaches those slots on terminals that draw bold in bright colors, so either can erase a hue. See.claude/rules/bdutils.md. - Errors: use
bdutils.error(msg)— exits non-zero with a lowercaseerror: ...line to stderr. Never raise tracebacks at the top level. - Warnings: use
bdutils.warn(msg)— writeswarning: ...to stderr without exit. - Project path: use
bdutils.resolve_project_path(arg)for the expanduser/resolve/.beads/-validation dance. - Subprocess: pass
cwd=project_pathrather thanos.chdir. Usecheck=Trueonly for calls that must succeed; tolerate empty/missing output where it's a valid state. - No config files, no state beyond what
bd/ Dolt already manage under.beads/. The one exception is the memories repoclaude-memory-setupcreates at the user's explicit request, outside any project. Nothing changes in the global environment without a yes:tools/doctor.pyreports missing tools and offers to install them on a terminal, and never installs from a pipe.
Releases
Nothing here is packaged or published — no pyproject.toml, no PyPI, no
installer; the scripts run in place. A release is only a marker of a known-good
point: ## Unreleased in CHANGELOG.md becomes ## vX.Y.Z (DDMonYY),
bdutils.__version__ is set to match, and the commit is tagged vX.Y.Z
(annotated). The one exception is v0.2.0, a lightweight tag backfilled long
after the fact — an annotated one would have stamped the backfill date onto a
May release.
Two rules carry the weight:
- The version moves only at release time. Feature work adds a
## Unreleasedbullet and leaves__version__alone.dc63e10bumped mid-cycle instead, and 0.3.0's notes then went a full cycle missing thebd-log --status/--openentry that same commit shipped. - Bump from the last release tag, not from
__version__. Pre-1.0, any[breaking]or[feature]bullet takes the minor;[fix]/[cleanup]/[refactor]alone take the patch. Bumping off__version__after a stray mid-cycle bump skips a version.
The procedure itself is scripted as the /release slash command
(.claude/commands/release.md) — run it rather
than working through the steps by hand. It gathers the commit range from the
last tag, audits ## Unreleased for completeness against that range, runs the
CI gates, and stops before pushing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

