Doma

doma: Find, Tag, or Bookmark Directories

doma is a directory tag manager. The user attaches tags to directories (crystal, work/proj-a, bookmark, etc.) and persists them in a SQLite database under ~/.config/doma/. As an agent you have two jobs: query that database to drive other operations, and add to it when the user's intent calls for it.

When the user wants to discover paths

The request mentions a category of directories rather than specific ones. Check doma before guessing:

doma tags --names              # what tags exist on this machine?
doma list -t crystal --paths   # paths under that tag, one per line

If doma tags --names doesn't list a tag matching the user's category, fall back to whatever discovery method you'd use otherwise (filesystem search, asking the user). Don't guess at a tag name that wasn't returned — doma list -t guess returns nothing for a non-existent tag, and silent emptiness is worse than asking.

Read modes

When the user wants to register or bookmark paths

Write operations are real state changes; do them when the user's intent clearly maps to "remember this", not as a side effect of unrelated work.

mark is the right tool for transient session-style organization (code review, refactor sweep, debugging deep-dive). add is for durable categorization that survives multiple sessions.

Multi-tag and multi-path forms

doma add /path        -t crystal -t cli           # multiple tags, one path
doma add /a /b /c     -t shared                   # one tag, many paths
doma add . -t crystal --auto-tag --git-tag        # +basename, +github/repo derived
doma mark -p /elsewhere spike                     # mark a path other than cwd
doma mark spike skim review                       # multiple temp tags on cwd at once

Recovering from rm (the trash)

doma rm <path> defaults to a soft-delete: the row + tags are snapshotted into a trash store under ~/.config/doma/trash/ and the path disappears from list output. Anything older than 7 days is auto-pruned on the next trash op. --hard on either rm or prune --gone skips the snapshot and makes the deletion permanent.

A short_id printed by rm (e.g. trashed /foo (recover with doma trash restore abc1234)) is the same id list and info use; copy- paste works across all three.

Operating on read results

Two patterns. Pick based on whether the operation needs to step inside each directory or just needs the path string.

Pattern A — iterate paths in your own loop (most common):

doma list -t crystal --paths | while read -r dir; do
  # use $dir however — Read tool, Edit, Bash with cwd=$dir, etc.
done

For paths-with-spaces safety, prefer NUL-separated:

doma list -t crystal -0 | xargs -0 -I{} sh -c 'cd "{}" && grep -l TODO **/*.cr'

Pattern B — let doma run a command per directory:

doma run crystal --json -- shards build       # per-directory results, attributable (prefer this)
doma run crystal -- shards build              # sequential, streams to the terminal
doma run crystal --parallel -- ...            # concurrent; without --json the output interleaves
doma run crystal --parallel --jobs 4 -- ...   # cap concurrency (default: CPU count)
doma run crystal --fail-fast -- ...           # halt on first non-zero exit (sequential only)
doma run crystal --dry-run -- rm -rf build    # print the target set without running anything
doma run crystal --no-header -- pwd           # suppress ▶/✓ chrome (failures still surface)

Prefer --json in an agent. Without it, every directory's output lands on one shared stream, and under --parallel there is no way left to tell which repo produced which line. --json captures each child separately and emits one row per directory, in the same order as list --paths, whether or not the sweep ran in parallel:

[{"path":"/a","exit_code":0,"stdout":"ok\n","stderr":"","dry_run":false},
 {"path":"/b","exit_code":1,"stdout":"","stderr":"boom\n","dry_run":false}]

Answering "which of my repos failed?" is then jq '.[] | select(.exit_code != 0) | .path' rather than a guess at interleaved text. The process exit code is still 1 if any directory failed, so the old && semantics hold. Notes:

• --json suppresses the ▶/✓ chrome; the rows carry the status.
• --json --dry-run previews as [{"path":…,"dry_run":true}] — no exit_code key, because nothing ran. Reach for it before any destructive sweep to confirm the tag resolved to what you expect.
• --fail-fast truncates the array to the directories that actually ran; the rest are simply absent.
• A dead path becomes a row with exit_code: 127 and doma's explanation in stderr, not a hard error.

Use doma run only when the operation is uniform enough to express as a single shell command. For per-directory logic that involves reading files or making decisions, Pattern A keeps the work in your hands.

Exit codes

Every failure class has its own code, so you can branch on the status instead of matching on error text (which is human-facing and will be reworded).

Two of these matter most in practice:

• 0 with empty stdout is a real, successful outcome — not an error. Check for empty output before iterating.
• 4 from --pick means "I refuse to guess" — narrow the filter, pass --first, or use list -t TAG --paths if you actually wanted every match.

Pitfalls

• doma cd is a shell function, not a binary subcommand. Calling the bare binary with cd prints an error pointing at doma setup install. The agent-friendly equivalent is path=$(doma list -t <tag> --pick):

  • 0 matches → exit 3 with a hint
  • 1 match → prints the path
  • N matches + TTY → interactive picker
  • N matches + non-TTY → exits 4 (refuses to silently auto-pick). Pass --first to take the most-recent match, or set the default with doma config set selector first. --builtin forces the interactive picker even without a TTY.

  When you need every path, use doma list -t TAG --paths.

• Never invoke bare doma or doma tui. With a terminal attached they open a full-screen interactive finder and wait for a keypress — which will hang you if your shell runs on a pty. Set DOMA_NO_TUI=1 if you need bare doma to be safe (it prints help instead), and use doma list for everything you'd otherwise browse.

• Destructive ops refuse to run unattended. rm --hard, prune --gone --hard, import --replace, and trash empty exit 1 with "requires --yes" when there's no TTY. That guard is deliberate: treat it as a signal to go back to the user for confirmation, not as something to defeat by adding -y / DOMA_YES=1 on your own initiative.

• Symlinks are resolved. doma stores the canonical real path, so a registered /var/foo will surface as /private/var/foo on macOS. Don't be alarmed if the listed paths look "different" from what the user might type.

• Expired tags are hidden by default. When the user uses TTL tags (--ttl 7d, --tmp, mark), an expired row vanishes from list -t TAG but the directory itself remains under any non-expired tags. Add --include-expired if the user explicitly asked to audit.

• Empty result is a real outcome, not an error. doma list -t X with no matches exits 0 with a one-line stderr. Check for empty stdout before iterating; don't proceed assuming you have paths.

• Re-tagging refreshes / clears the TTL. doma add . -t reading --tmp resets the timer; the same call without --tmp reverts the tag to permanent. Be aware if you're scripting both operations on the same path.

• Bulk destructive ops need explicit user intent. prune --gone, prune --expired, and import --replace are sweeping operations. Don't reach for them as housekeeping unless the user asked. The per-path forms (rm <path>, rm <path> -t TAG) are fine when the user pointed at something specific.

• add/mark are state changes — match them to intent. Saying "look at this directory" is not the same as "track this directory." Persist only when the user's wording clearly implies "remember this for later" or "I want to come back here." When in doubt, ask.

Common request shapes

Stable identifiers

Every directory has a 7-char short_id (visible in list output and in --json). It survives re-tagging and renames, so when you need to refer to a specific entry across multiple steps, store the short_id — not the path (which can be moved) and not the index (which changes when the list reorders).

ID=$(doma list -t crystal --json | jq -r '.[] | select(.basename=="doma") | .short_id')
# ... later, after the user moved the directory ...
PATH_NOW=$(doma list --json | jq -r --arg id "$ID" '.[] | select(.short_id==$id) | .path')

short_ids are accepted by rm <id>, info <id>, and trash restore <id>. They are not accepted by list --pick (use the tag), and the bare binary's cd subcommand has been removed in favor of the shell-wrapper + list --pick split.

When NOT to invoke

• The user named explicit paths (/Users/me/projects/foo, ./bar) for one-shot work. Just operate on those — doma adds nothing.
• which doma returns nothing, or doma --version errors. Fall back to filesystem discovery (fd, find) and tell the user doma isn't available.
• The operation only touches the current directory and the user didn't ask to track it. doma is for cross-directory work and for persisting intent — one-shot tasks don't need it.