logmind: log decisions as you work
Applies when the project has .logmind/config.yml or an AGENTS.md
mentioning logmind. Log a decision before writing non-trivial code.
When to log
- An architectural or design choice
- A choice between alternatives
- Significant new code (> 20 lines or a new module)
- A non-obvious change to existing functionality
- Adding or removing a dependency
- A security or performance decision
When in doubt, log it — an entry is cheap; recovering the context later is not. But don't log every tiny edit: the 20-line rule is a guideline; use judgement.
logmind log "Use PostgreSQL" -r "Need ACID + joins" -a "MongoDB" -a "SQLite" -i "Pooling"
logmind log IS the commit primitive — no manual git around it
One invocation replaces git add + git commit. This skill describes
logmind v1.2.0, the latest release; logmind version shows yours.
- Appends to
docs/decisions-branches/<sanitized-branch>.mdon a feature branch (decisions.branch_aware, on by default) — one file per branch, append-only. On the default branch, a detached HEAD or a non-git directory it appends todocs/decisions.mdinstead.logmind logroutes this, you don't. - Stages the whole working tree (
--stage all, the default) so the decision and its code land in one commit — don'tgit addfirst.--stage scopedstages only the decision file when you have unrelated WIP you don't want swept in. git commitwith messagelogmind: <decision>. It does not push —git.auto_pushis in the config but v1.2.0 never reads it. Rungit pushyourself.- Link-checks the markdown. On findings it prints an advisory; in a
terminal it offers up to three fix-and-recheck tries, and
--no-interactive(or piped stdin) skips the prompt and exits 0. The prompt path exits 1 onqor after three failed rechecks. The commit has landed either way.
logmind log does not regenerate the derived docs — see below. After it
you owe only the push.
Enforcement: a local hook and a PR gate
- The pre-commit hook (
logmind check-decisions) blocks (exit 1) a sizeable commit with no decision-file update. It never reads[skip-logmind]; its escape isgit commit --no-verify. logmind initalso installscheck-decisions.yml, a PR gate on 20+ non-doc changed lines. It honors[skip-logmind]in the PR title only.- In a commit subject,
[skip-logmind]only makes thecommit-msghook echo a notice; nothing else reads it.
Reading prior context
Before non-trivial work, read in order:
docs/timeline.md— the generated union of decision entries across every branch, brief by default (first and last entry per month;logmind timeline --fullprints every one).docs/decisions-branches/<your-branch>.mdif present — earlier decisions on this branch, in full.docs/decisions.mdanddocs/decisions-archive.md— default-branch decisions; grep them for a term before re-deciding it.docs/file-structure.md— project tree, capped at depth 2 by default (--max-depth Nonlogmind file-structure/logmind tree;0= unbounded).
Derived docs are generated — never hand-edit them
docs/timeline.md and docs/file-structure.md are computed from sources
(the decision files above; a tree walk). Edit the sources instead.
regen-timeline.yml regenerates both on every PR. If they are stale it
pushes the fix to the branch when LOGMIND_AUTO_REGEN_PAT is set; with no
PAT, or on a fork PR, it fails red with Stale derived docs. The fix is
regeneration, not a hand edit and not a copy from another branch:
logmind timeline --write docs/timeline.md
logmind file-structure --write docs/file-structure.md
Commit both. Add --check to either for a CI exit status without writing.
The same regeneration resolves a merge conflict in either file: re-run it,
never pick a side. It reads only your checkout's sources, so there is no
base or tip copy to choose between.
Parallel-PR merges
Two PRs that both run logmind log don't conflict on the derived docs:
logmind init installs a .gitattributes merge-driver block, the
per-clone git config defining the drivers, and a .git/hooks/post-merge
sweep that regenerates what the driver missed (unstaged — the next
logmind log picks it up); logmind doctor reports drift on all three.
Client-side only — it can't help a server-side merge.
Authoring skills — logmind skill …
For skills in your own project (.claude/skills/<name>/SKILL.md): new
scaffolds; test validates frontmatter + structure; bench measures
per-call token cost, suggests trims, buckets by loaded cost (tight /
typical / verbose / over-budget); audit reports each local SKILL.md's
bytes, decision-mentions and staleness, flagging ghost (loaded every
context, author never iterates) and aging (untouched 90+ days) skills;
suggest --since 30d drafts a candidate-skill issue from tokens repeated
across decisions. Pair with clud-bug usage --health (loads vs. citations
on real PRs).
Local and read-only against remotes except push: without
--dry-run it clones the catalog, pushes a branch, and opens a real pull
request the moment you run it — no confirmation prompt. Run logmind skill push <name> --dry-run first, every time. Nomination isn't
publication: the catalog's editor gate decides, and can say no. suggest
is also not local by default: with ANTHROPIC_API_KEY set it sends
pattern candidates and evidence to api.anthropic.com; pass --no-llm.
Setup and health
brew install thrillmade/tap/logmind # or: curl -fsSL https://logmind.dev/install.sh | bash
logmind init # scaffolds docs/, AGENTS.md, workflows, merge drivers, hooks
logmind doctor # confirm clean install
logmind init --with-skdd accepts the flag but currently defers — it
prints a note to run npx clud-bug@latest init yourself. Run them
separately.
logmind doctor flags stale workflow templates, stale hooks, merge-driver
drift and an outdated AGENTS.md block-version, exiting non-zero on drift
so it's CI-pluggable (--json for scripts, --exit-zero for informational
runs). It has no clud-bug probe, and its installed-vs-latest version line
is not reliable in v1.2.0 — don't read it as "up to date".
Don'ts
- Don't write the decision after the fact in past tense for trivial code.
- Don't reword a decision someone else already logged — link or extend it.
- Don't bypass the auto-commit (
--no-commit) unless the project's branch protection requires it.
Cross-references
- token-frugal-tooling — token-frugal defaults for agent sessions.
- clud-bug-collaboration — the review half.