doma

name: doma description: Use doma both to (1) discover directory paths the user has already tagged so you can operate on them in bulk, and (2) register or bookmark new directories when the user's intent calls for persistence ("track this", "bookmark this", "I'll come back later"). Trigger when the user references "my X projects" / "all directories tagged Y" / "every repo I marked as Z", asks for a category-spanning chore ("update CI for all my Crystal projects"), or asks to save/track/remember a path. Skip when the user names explicit paths for one-shot work, or when which doma shows it isn't installed.

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 -- shards build              # sequential, stops on Ctrl-C
doma run crystal --parallel -- ...            # concurrent, 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 --no-header -- pwd           # suppress ▶/✓ chrome (failures still surface)

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.

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.

• 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.