日本語 | English

bcuz

Run a command with a reason, and keep a record of when, why, what and the result.

At a glance · Features · Installation · Usage · Exit codes · Documentation

At a glance

$ bcuz --init
bcuz: created .bcuz/
$ bcuz "run the tests" make test
$ bcuz -H
2026-10-12 06:35:12    0    8.3s  .  run the tests  $ make test

Put one reason in front of a command. Later, the history tells you why you typed it.

Features

• 📝 The reason is kept with the command: bcuz "reason" command. Like sudo, you only put it in front
• 🔍 You know later: when, why, what and the result (exit code and duration), as one JSON line per run
• 🧩 Nothing else changes: output, TTY and exit code pass through as they are. No shell is involved
• 📦 A single binary, no dependencies: written in Go. Linux, macOS and Windows
• 🤖 Good for AI agents too: read with bcuz -H what an agent typed and for what purpose
• 🗂️ Just a file: the append-only .bcuz/history.jsonl. Use it as it is with grep, jq and git

Installation

go install github.com/amisonnet8/bcuz/cmd/bcuz@latest

Pre-built binaries (Linux, macOS and Windows, amd64 and arm64) are on the Releases page.

Shell completion (bash, zsh, fish or powershell; see --completion):

bcuz --completion bash > ~/.local/share/bash-completion/completions/bcuz

Usage

bcuz --init                             # create .bcuz/ here (the first time)
bcuz "run the tests" make test          # run and record
bcuz -- "-v this time" go test -v       # a reason that starts with -
bcuz -H                                 # the history, newest first
bcuz -H --date 2026-10-12               # one day (also --since and --until)
gzip -dc old.jsonl.gz | bcuz -H -       # records moved away, from standard input

bcuz [--] <reason> <command> [args...]   run the command and record it
bcuz -H, --history [-] [--date D | --since D] [--until D]
bcuz --init
bcuz --completion <shell>
bcuz -h, --help
bcuz --version

What a record looks like (one line of .bcuz/history.jsonl)

{"v":1,"ts":"2026-10-11T21:35:12.345Z","why":"run the tests","cmd":["make","test"],"dir":".","exit":0,"ms":8312}

Good to know

• Records are appended to the first .bcuz/history.jsonl found from the current directory going up through its parents
• No shell is used. && and pipes are interpreted by the shell that called bcuz (use sh -c '…' to record them whole)
• Without .bcuz/, the command still runs (only a warning)

Exit codes

Exit code	Meaning
The command's	Passed through as it is
128 + number	Ended by a signal (130 for Ctrl-C)
125	An error of bcuz itself (not recorded)
126	Found but cannot be started (recorded)
127	Not found (recorded)

Documentation

• Command reference: output, messages, exit codes
• Record format: one line of history.jsonl
• Examples: real input and output
• Design: purpose, reasons for the decisions, limitations
• Interactive guide: explore bcuz by asking questions (made with Gemini Notebook)

License

MIT