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

Want	Command	Why
One path per line, for while read / xargs	doma list -t TAG --paths	The default newline-separated form
NUL-separated, paths with spaces	doma list -t TAG -0	Pipe to xargs -0. Safer than --paths when paths might contain spaces
Structured JSON (short_id, path, basename, tags, created_at, last_used_at)	doma list -t TAG --json	Timestamps are unix epoch seconds — filter your own recency window instead of relying on --by recent ordering (last_used_at == 0 means never used). TTL'd tags add an expirations map (tag → unix epoch); --check adds a boolean exists
Substring across path/basename/tag	doma list <query>	Single substring match. Combines with -t for intersection. Multiple positional args are joined by a space — they are not AND-ed
Sorted by recency	doma list --by recent	Most-recently-used first; aliases: used, recency. Useful when "the project I was just working on" is in scope
Mark missing paths inline	doma list --check	Tags entries whose path is gone with [gone]. Without it, the footer just counts them
Just the tag names	doma tags --names	Cheap probe before committing to a tag. doma tags --tree shows the work/proj/... hierarchy; doma tags -0 is NUL-separated for xargs -0
Git state across a tagged set	doma status -t TAG --json	Per-repo branch, ahead/behind, dirty, clean, untracked, etc. Use for "which of my X repos have uncommitted changes?" — filter .[] | select(.dirty > 0). Add --dirty to pre-filter. Shells out to git

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.

User says...	Command	Notes
"Track this project" / "I'll be working on it"	doma add <path> -t <category> (or --json for structured result incl. short_id)	Permanent (no TTL)
"Track all of these as <name>"	doma add <path1> <path2> ... -t <name>	Multi-path is one command
"Bookmark this for review" / "Remember this for later"	doma mark <bookmark-name>	cwd + 7-day TTL — equivalent to add . -t NAME --tmp, just shorter
"Mark these for the auth review session"	doma mark -p <each-path> auth-review	One call per path; tags accumulate. -p skips the cd dance
"Save this for the next week"	doma add . -t reading --tmp	Or doma mark reading
"Save this for two days"	doma add . -t reading --ttl 2d	Custom duration; mark only covers the 7d default
"Untag this"	doma rm <path> -t <tag>	Removes the tag; the path entry stays if it has other tags
"Forget this directory"	doma rm <path>	Soft-delete: routes to trash, recoverable for 7d via doma trash restore <id>
"Delete permanently, skip the trash"	doma rm <path> --hard	Same --hard is available on doma prune --gone for sweeping dead paths irrecoverably

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.

User says...	Command	Notes
"What can I recover?"	doma trash list or doma trash list --json	Human table (newest first) or structured JSON array with short_id, path, tags, deleted_at, expirations, etc. Prefer --json in agents.
"Bring it back"	doma trash restore <short_id>	7-char prefix from trash list. Add --merge if the path was re-registered in the meantime
"Empty the trash"	doma trash empty	Confirmation prompt unless -y / --yes / DOMA_YES=1
"Just clean up old trash"	doma trash empty --older 7d	Same duration grammar as --ttl

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

Code	Means	Typical cause
0	Success — including an empty result set	list -t X matched nothing
1	Generic failure	bad flag; run had at least one directory exit non-zero
2	Validation	invalid tag name, conflicting output flags, add given a non-directory
3	Not found	info/rm on an unregistered path; list --pick matched nothing
4	Conflict / ambiguous	list --pick matched N directories with no TTY and no --first
5	Config	unreadable or invalid config.yml
6	Import	malformed snapshot file
130	Cancelled	user hit Ctrl-C in an interactive picker

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.

Common request shapes

User says...	First doma call
"Update Crystal version in CI for all my Crystal projects"	doma list -t crystal --paths
"Check git status across my work repos"	doma list -t 'work/*' --paths (glob applies to list -t and run)
"Find that bookmarked thing about auth"	doma list -t bookmark auth (tag filter ∩ substring auth)
"What was I working on last?"	doma list --by recent (top entries are most-recent cd targets)
"Is this directory registered? with what tags?"	doma info --json (cwd), or with <path> / <short_id> / <name> (substring fallback). Always emits JSON — {"found":true,…} or {"found":false,"error":…,"hint":…} with exit 3. Branch on found; no need to scrape stderr
"Run specs across all the Crystal projects in parallel"	doma run crystal --parallel --json -- crystal spec (--json is what makes each repo's output attributable; cap concurrency with --jobs N)
"Which of my Crystal projects fail to build?"	doma run crystal --json -- shards build | jq -r '.[] | select(.exit_code != 0) | .path'
"What have I touched in the last week?"	doma list --json → filter .last_used_at against your own epoch cutoff
"I'll be working on this project for a while"	doma add . -t <category> (use --json to capture the new short_id immediately)
"Bookmark this so I come back later"	doma mark <name>
"Mark these dirs for the auth review"	doma mark -p <each-path> auth-review (no need to cd around)
"Forget the bookmark"	doma rm <path> -t bookmark (or wait for the TTL)
"Show me what's expiring soon"	doma list --include-expired (then filter by in )

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.