agentleFS
degdeg/beads-utils/CLAUDE.md

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

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
  1. Very specific:

    Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists

    line 21
  2. Very specific:

    Run bd prime for detailed command reference and session close protocol

    line 22
  3. Very specific:

    Use bd remember for persistent knowledge — do NOT use MEMORY.md files

    line 23
  4. Distinctive:

    When ending a work session:

    line 27
  5. Distinctive:

    Before changing a script's behavior, make sure its rule file is in context, and read it directly if not.

    line 188
  6. Very specific:

    When adding/renaming a flag or script, update the matching flag list in both completion files — tests/test_completions.py fails if either …

    line 200
  7. Very specific:

    No build system, no package — but a Makefile as the single front door for every routine command, so neither a returning maintainer nor CI …

    line 211
  8. Very specific:

    Versioning: all scripts share a single bdutils.__version__.

    line 279
  9. Very specific:

    Do not bump __version__ as part of feature work — add a bullet under ## Unreleased in CHANGELOG.md and leave the number alone.

    line 286
  10. Very specific:

    Errors: use bdutils.error(msg) — exits non-zero with a lowercase error: ...

    line 300
  11. Very specific:

    Warnings: use bdutils.warn(msg) — writes warning: ...

    line 302
  12. Very specific:

    Project path: use bdutils.resolve_project_path(arg) for the expanduser/resolve/ .beads/-validation dance.

    line 303

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session:

  1. File issues for remaining work — create beads for anything that needs follow-up
  2. Run quality gates (if code changed) — tests, linters, builds
  3. Update issue status — close finished work, update in-progress items
  4. Commit — stage and commit your changes
  5. 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 to bd export --all --no-memories, parses the JSONL, and writes a flat CSV suitable for spreadsheet review. Supports -s/--sort with 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 under refs/dolt/data on the beads remote (the Dolt database's own remote, else sync.remote, else the git origin), invisible in GitHub's UI. It checks that ref with git 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 on OUT OF SYNC or UNCOMMITTED so CI can gate on it.
  • bd-dolt-diff — Previews what a bd dolt push would send: an issue-level diff between the remote-tracking ref and the local branch. --base/--head diff any two Dolt revisions. Read-only, exits 0 whenever the comparison ran. Requires the dolt CLI.
  • 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 computation bd-dolt-check renders). -g/--global checks every beads repo on the machine in parallel, one line each. Fetches first unless --no-fetch. Never runs bd. Exits 1 if anything is not backed up.
  • bd-log — Git-log-style timeline of bead and memory lifecycle events, newest first. --only picks the verb (create/change/end), --about the entity (beads/memories); --status, --open, --id, --children, --no-deferred and --no-blocked scope the beads. Memory events are reconstructed from Dolt commit history, because bd remember records no timestamps.
  • bd-view — Pretty-prints a single bead with rendered Markdown via rich, resolved through a uv run --script shebang; 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). --lean swaps each notes log for notes_len. Names what it left out on stderr. Feeds the /close-shop bead audit.
  • claude-session-find — Finds an old Claude Code session's UUID by grepping transcripts; current project by default, -g for 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 /rename would, 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. --kind picks failures, denials or outages; --json feeds /dream (beads-utils-c1k). Current project by default, -g for all.
  • claude-traffic-monitor — Live top-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 duplicate name: slugs, and a MEMORY.md out 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: .git at ~/claude-memories.git (or $CLAUDE_MEMORIES_GIT), work tree ~/.claude/projects, an allowlist .gitignore exposing only */memory/*.md. Fresh, or --remote URL to clone onto a new machine. Rerunnable.
  • bd-complete — Emits value<TAB>description completion candidates (ids, sessions); the single front door behind completions/.

Shared helpers, both stdlib-only:

  • bdutils.py — error(), warn(), resolve_project_path(), format_ts(), format_priority(), paged_output(), run_bd_json() (the bd ... --json runner bd-log and bd-find-live share), and color (add_color_arg(), want_color(), paint()), plus the git/Dolt plumbing (dolt_sync_state() and the dolt_* readers) that bd-dolt-check, bd-dolt-diff and bd-verify-backup share.
  • claudeutils.py — Claude session enumeration and resolution (path, UUID or title substring), shared by the claude-session-* scripts, claude-sessions-review, claude-traffic-monitor, bd-complete, and bd-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) — a bd update <id> --claim on 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 /defer when 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) — a systemMessage when 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 fileLoads for
bd-log.md, bd-dolt-check.md, bd-dolt-diff.md, bd-verify-backup.md, bd-view.md, bd-find-live.mdthat script and its test file
claude-memory.mdclaude-memory-check, claude-memory-setup, the two memory hooks, their tests
hooks.mdhooks/claim-guard.sh, hooks/defer-hint.sh, tests/test_workflow_hooks.py
skills.mdskills/, tests/test_skills.py
claude-sessions.mdclaude-session-*, claude-sessions-review, claudeutils.py, their tests
claude-traffic-monitor.mdclaude-traffic-monitor and its test file
completions.mdcompletions/, bd-complete, their tests
bdutils.mdbdutils.py and its tests
tests.mdanything under tests/, pytest.ini
makefile.mdMakefile, tests/test_makefile.py
screenshots.mdtools/, 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_at

bd-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-view needs rich for Markdown rendering); bdutils.py itself stays stdlib-only.
  • Argument parsing: argparse. Use RawDescriptionHelpFormatter with description= and epilog= when a richer help block is warranted.
  • Versioning: all scripts share a single bdutils.__version__; add the --version flag via bdutils.add_version_arg(parser) so every script prints <prog> <version> identically. Paging scripts also accept --no-pager. Colorizing scripts take --color=auto|always|never via bdutils.add_color_arg(parser) and resolve it once with bdutils.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 ## Unreleased in CHANGELOG.md and 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 in CLAUDE.md or the matching .claude/rules/ file, not in CHANGELOG.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 bold reaches 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 lowercase error: ... line to stderr. Never raise tracebacks at the top level.
  • Warnings: use bdutils.warn(msg) — writes warning: ... to stderr without exit.
  • Project path: use bdutils.resolve_project_path(arg) for the expanduser/resolve/ .beads/-validation dance.
  • Subprocess: pass cwd=project_path rather than os.chdir. Use check=True only 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 repo claude-memory-setup creates at the user's explicit request, outside any project. Nothing changes in the global environment without a yes: tools/doctor.py reports 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 ## Unreleased bullet and leaves __version__ alone. dc63e10 bumped mid-cycle instead, and 0.3.0's notes then went a full cycle missing the bd-log --status/--open entry 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.