clefdirstat #

a file classification visualizer tui

install and run #

from the project directory:

cargo install --locked --path .

run on the current directory

clefdirstat

or run with a question and a directory

clefdirstat 'does this document discuss kubernetes?' ~/Documents

on first launch, enter your systemone endpoint URL and token leave the token blank for an unauthenticated endpoint use clefdirstat --setup to change the connection later

nix #

run without installing

nix run 'git+https://tangled.org/chancey.dev/clefdirstat'

or after cloning with

nix run . -- 'does this document discuss backups?' .
nix build .
nix develop .

each classified document's extracted text is sent to your configured endpoint

browsing and classification leave source files unchanged

connection #

clefdirstat uses a systemone/decisions API endpoint. --model selects the model (default clef-flash). for jev on openrouter, use https://openrouter.ai/api/alpha/decisions with --model typesafe/jev-1.13. chat-completions endpoints are not supported.

you can also configure the connection through your environment:

export CLEFDIRSTAT_PROVIDER_URL=https://your-server.example/v1/systemone
# set CLEFDIRSTAT_PROVIDER_TOKEN through your shell or secret manager
clefdirstat 'does this document discuss backups?' ~/Documents

an environment URL or --endpoint skips setup. --api-key-env reads a token from another environment variable; --env-file reads an explicit dotenv file.

setting	precedence, highest first
endpoint	CLEFDIRSTAT_PROVIDER_URL, --endpoint, saved URL
token	CLEFDIRSTAT_PROVIDER_TOKEN, --api-key-env, --env-file, saved token for the exact URL

saved settings live in ~/.config/clefdirstat/config.json and tokens live in ~/.local/share/clefdirstat/auth.json

browsing #

with a question active, supported files in the current directory are classified automatically in the background. recursive listing is on by default; press R (shift-r) to toggle it, c to toggle automatic current-directory classification, or x to cancel unfinished work and pause both. completed answers stay available until the question changes.

file colors follow your terminal palette:

• green: yes; red: no
• yellow ?: below 80%; yellow !: an error
• cyan: queued; blue: pending directory segments and requests in progress

directory bars show known file verdicts, pending work, and errors; the final verdict and percentage show the majority share of answered files. select a directory for exact counts.

--threshold sets the yes/no cutoff (default 0.5). confidence is the model's probability of the chosen answer r reloads and reclassifies the current view, or the subtree with recursive listing enabled; space retries a selected file.

keys #

key	action
↑ / k, ↓ / j	select a file or directory
→ / l / enter	enter the selected directory
← / h / backspace	go to the parent directory; scans pause outside an approved tree
home / g, end / G	first or last entry
page up, page down	move a page through entries
tab	enter or change the classification question
→ / l	focus details when there is no directory to enter
/	live fuzzy-filter filenames; reopen to clear, → completes the previous term
a	classify the current directory's visible files
A	classify the selected directory recursively, or the current subtree when a file is selected
space	queue or unqueue the selected file or directory
z, ctrl-p, s	recursively fuzzy-find paths in the browser (fzf required)
F (shift-f)	open the same filename filter as /
, then p	rank files by probability of yes, highest first
, then a	sort by name, with directories first
c	toggle automatic classification; approve a paused directory and its descendants for this session
R (shift-r)	toggle recursive listing classification (on by default)
x, ctrl-c	cancel queued work
ctrl-b	show or hide the parent pane
.	toggle hidden files
r	reload and reclassify the current view, or subtree with recursive listing enabled
ctrl-u, ctrl-d	page the focused pane
J, K	scroll the document preview
e	open the selected file in $VISUAL or $EDITOR (default vi)
E (shift-e)	export the current results as jsonl
? (shift-/), F1	show help
escape	cancel question/find/filter entry or close help
q, ctrl-c (2x)	quit
mouse wheel	scroll the pane under the pointer

files and exclusions #

supported formats include utf-8 text, markdown, common source/configuration files, docx, and pdfs with a text layer. docx extraction covers body paragraphs and tables. scanned pdfs need ocr separately; encrypted pdfs need a decrypted copy. symbolic links are never classified. zero-byte files are skipped without an endpoint request; exports record them with status skipped.

automatic classification and recursive discovery respect .gitignore rules (including parent and nested rules) and git's local/global excludes. common build, dependency, and cache directories are skipped. --hidden or . includes hidden files without overriding exclusions. you can still browse excluded directories and explicitly classify a selected file.

large documents #

long documents split into overlapping chunks. --context-tokens sets the request budget (default 16384); each chunk receives the same question.

clefdirstat 'does any part discuss backups?' ~/Documents --chunk-mode any
clefdirstat 'is every chunk about backups?' ~/Documents --chunk-mode all

any (default) uses the highest chunk yes score; all uses the lowest.

the default extraction limits are 10,000,000 bytes per file and 1,000,000 characters, with a 30-second request timeout. use --max-bytes, --max-chars, and --timeout to adjust them.

export and batch mode #

press E (shift-e) to export results as jsonl in the system temporary directory, or use --output to choose a destination. existing files are protected from overwriting.

--batch recursively classifies a directory without opening the explorer:

clefdirstat 'does this document discuss kubernetes?' ~/Documents \
  --batch --limit 10 --output results.jsonl

batch mode requires a saved connection, environment variables, or --endpoint; it will not save configuration. without --output, jsonl goes to standard output.

development #

cargo run -- 'does this document discuss kubernetes?' .
cargo test --locked
cargo clippy --all-targets -- -D warnings
cargo fmt --check
nix flake check

tests use local fixtures and mock endpoints; no provider credentials are needed.