catalog

Once you have 20 or more files in a repository, agents do a pretty poor job of deciding which files to load into context. They'll randomly load ones files they don't need, and they won't load the ones that they do need.

catalog is a command-line tool that profiles the documents in your repo provides agents with a catalog so they can load precisely what they need. This means better answers, faster responses, and more context window left for the actual work.

If you want to add catalog capabilities to your repo, install the catalog skill and then use it to set your repo up. It will prompt you to install this utility and set up the necessary configuration.

If you want to do development on this repo, See SETUP.md for developer installation and first-run instructions.

How it works

Each entry in .catalog.md is a profile: a description of the conditions under which a document is relevant — the same idea as a skill's description field, which tells the harness when to load the skill body. A profile says "open this file when the task involves X," not "this file is about X." That distinction is what makes routing work: a wrong summary is ugly; a wrong profile sends the agent to the wrong file.

The tool infers profiles by reading each document with the surrounding catalog as context, so it can distinguish near-neighbors from each other rather than describing them in isolation.

Documents aren't limited to Markdown. Plain text and CSV work today with no extra setup — just point a glob at them in .catalog/config.toml. PDFs are also supported: catalog sends them to the model as native PDF documents rather than raw text.

Commands

Run from the repo root. Profiles live in a committed SQLite database at .catalog/catalog.db — the sole source of truth; .catalog.md is always a generated artifact rendered from it. Three commands write profiles and need ANTHROPIC_API_KEY. status and diff read only the database and the filesystem, need no key, and have no dependency on Git.

• catalog bootstrap — rebuild the database from scratch: infer profiles for every enumerated document in two passes (the second pass sharpens each profile using the full catalog as context), then write .catalog.md. Ignores any existing database or .catalog.md entirely. Use this when setting up a new repo or after major reorganization.
• catalog update — re-infer profiles for documents that are new or have changed content, drop rows for documents that are deleted or no longer enumerated, and always rewrite .catalog.md. Run this after editing or removing a document, the same way you'd run a formatter.
• catalog force [file ...] — re-infer the named documents (or all documents) unconditionally. Use it to redo a few entries you're unhappy with, or to rebuild everything after a prompt change.
• catalog status — report which documents are new, modified, or deleted relative to the database, and whether .catalog.md on disk matches a fresh render of it. Exits non-zero if anything is out of sync. No model call needed.
• catalog diff — show a unified diff between .catalog.md on disk and a fresh render of the database: exactly what update would change. No model call needed.

Why bootstrap needs two passes

A profile's job is to distinguish a document from the things it might be confused with — usually its neighbors. On the first pass, those neighbors have no profiles yet, so every entry is written without that context. bootstrap runs a second pass once all entries exist, re-inferring each profile with the full catalog in view. That second pass is what "bootstrap" refers to: the catalog uses its own first-pass output to improve itself.

update and force skip the second pass because the entries they leave untouched already hold real profiles, which serve as neighbor context for the entries being rewritten.

Repository layout

catalog/
  *.go                  Go source (at the repo root)
  .goreleaser.yaml      release config

Installing in a repo

The skill walks through the decision and setup. Install it from the hq repo alongside the other West Arete skills. The short version: create .catalog/config.toml, run catalog bootstrap to generate the first .catalog.md, wire @.catalog.md into CLAUDE.md, and register the pre-commit hook.

Releases

Releases are tagged from main and published via GoReleaser. The primary install surface is the westarete/homebrew-tap Homebrew tap; GitHub Releases carries the raw binaries as a secondary surface for CI and non-Homebrew environments.

brew tap westarete/tap
brew trust westarete/tap
brew install catalog

To upgrade later:

brew upgrade catalog

Making a release

Only tag a release when something changes for the user — new features, bug fixes, behavior changes, or documentation that affects how they use the tool. Workflow changes, CI fixes, and internal docs do not warrant a release.

This project uses semantic versioning. Patch releases fix bugs without changing behavior. Minor releases add functionality. Major releases make breaking changes.

Before picking a version number, fetch tags from upstream so you have the full picture:

git fetch --tags
git tag --sort=-v:refname

Increment the appropriate part of the latest tag, create an annotated tag with a one-line summary of what changed, and push it:

git tag -a vX.Y.Z -m "Short summary of what changed"
git push origin main
git push origin vX.Y.Z

Pushing the tag triggers the GoReleaser workflow, which builds binaries, creates the GitHub release, and opens a PR against the tap repo to update the cask.

macOS Gatekeeper and code signing

Released binaries are code-signed and notarized. They pass Gatekeeper on macOS 15+ without any security prompt. See APPLE.md for how the signing and notarization pipeline works.

Why Go

The Anthropic SDK requires a recent version of Python, and managing Python versions on macOS is fragile — the system Python is too old, and juggling pyenv, virtualenvs, or Homebrew Python versions adds friction for every user who wants to use the tool. Go sidesteps all of that: a single static binary with no runtime dependencies, distributed via Homebrew with no version management required on the user's end.

Development workflow

Near-term work in progress is tracked in TODO.md.

Before committing: make test after touching any .go file (it lints with golangci-lint, then runs the Go test suite — one command, no separate lint step to remember), and make markdown after touching any .md file (formats and lints the whole repo).

The typical cycle when working on the binary:

1. Build locally into ~/.local/bin to shadow the Homebrew version:

   go build -o ~/.local/bin/catalog

2. Verify you're running the local build:

   which catalog   # should show ~/.local/bin/catalog

3. Test in real repos — run catalog update, catalog status, etc. against actual content repositories to confirm the change works as expected in practice, not just in unit tests.

4. Release — when satisfied, commit, tag, and push. GoReleaser publishes the signed binary to Homebrew.

5. Remove the local build to fall back to the released Homebrew version:

   rm ~/.local/bin/catalog
   brew upgrade catalog