A local record of failures and fixes.

Motus connects a failed command, your explanation, and the successful run after the fix. Search the ledger when the problem returns.

Install Motus See the workflow

01  FAILED RUN
npm test
run_0370...  failure

02  YOUR FINDING
The generated file was stale.

03  SUCCESSFUL RUN
npm test
run_c588...  success

04  SEARCH LATER
finding list --query stale
finding_1457...  resolved

local run-linked searchable

How Motus works.

A run is one command execution. A finding is the short note you keep about a failure. Motus links the failed run, your finding, and the successful run after the fix.

01 Record
Run a test, build, script, or tool through Motus.
motus wrap -- ...
02 Add a finding
Save the detail you will need if the failure returns.
motus finding add
03 Link the fix
After the fix works, link the finding to that successful run.
motus finding close
04 Find later
Search the finding and inspect both runs when the problem returns.
motus finding list --query

Find what worked the last time.

Motus output with shortened IDs.

$ motus finding list --query stale
finding_1457...  resolved
The generated file was stale.

$ motus finding show finding_1457...
Origin run:    run_0370...  failure
Resolving run: run_c588...  success
Closure note: Refreshed the generated file
              before running the check.

Run facts

Command name, Git state, timing, exit status, outcome, and output counts.

Your finding

A summary, likely cause, and next step that you choose to save.

Resolution

A note and a link to the successful run after the fix.

Try the full workflow.

This example uses npm test. Replace it with any command you already run. Paths and IDs are shortened.

Install Motus

Use Go 1.26.5 or newer, or download a verified archive from GitHub Releases.

$ go install github.com/motus-os/work-ledger/cmd/motus@latest

Record the failing command

Motus prints a run ID. After a failure, it also prints the exact command for adding a finding.

$ motus wrap -- npm test
motus: recorded run_0370... (failure)
Keep why this failed:
  motus finding add --run run_0370... --file -

Save a finding

Copy the printed command. Type a short note and finish input with Ctrl-D, or Ctrl-Z and Enter on Windows. Motus prints a finding ID.

$ motus finding add --run run_0370... --file -
The generated file was stale.
Recorded finding_1457... (open)

Record the successful check

Fix the problem and run the same command again. Keep the new run ID if it succeeds.

$ motus wrap -- npm test
motus: recorded run_c588... (success)

Link and search

Use the finding ID and successful run ID. Enter a closure note, finish input the same way, then search your saved words.

$ motus finding close finding_1457... --disposition resolved --run run_c588... --file -
Refreshed the generated file before running the check.
Closed finding_1457... (resolved)

$ motus finding list --query stale

Read the full install and workflow guide

What Motus keeps.

Run facts are captured when you use motus wrap. Finding text is stored only when you add it.

Recorded with a run

stable run and event IDs
timestamps and duration
executable name and argument count
Git repository, commit, and dirty state
exit code, signal, timeout, and outcome
output byte and line counts

Written by you

finding summary and likely cause
next step, when useful
resolution or dismissal note
links to the failed and successful runs

Common questions.

Why not Git, shell history, or CI logs?: Git tracks source changes; shell history and CI keep commands and logs. Motus connects the failed run, your note, and the successful run.
Does Motus store raw command output?: No. Motus streams output normally and records only counts. It stores finding text only when you add it.
What does a receipt establish?: A receipt is a repeatable JSON view of a closed run. Its digest detects changes to the receipt body. It is not a signature. Read the security model.

Record the next failure you solve.

Keep the failed run, your explanation, and the successful run together.

Install Motus