Motus Work Ledger

Motus Work Ledger

A work ledger for people, agents, and automations.

Motus keeps a durable record of what happened and why it matters. The current release links technical command runs to findings that people or agents can retrieve before related work.

See the model Install Motus

Proposed work-ledger model

The model follows work from request to acceptance.

Today, Motus records technical command runs and linked findings in one local ledger. The diagram shows the broader model across teams and organizations while source systems remain authoritative. Read the strategic vision or download the 4-slide PDF.

Source systems

  • Project Management
  • Incident Management
  • Engineering & Systems
  • Master Data
  • Access Controls

Hold the authoritative records

Work execution

  • People
  • Agents
  • Automations

Perform, route, and review within assigned authority

Source references and work actions enter the ledger

Work ledger

  1. Requestwhat was required
  2. Workwhat was done
  3. Evidencewhat supports it
  4. Judgmentwhy this approach
  5. Acceptancereview and decision

Governance & standards

  • Policies
  • Playbooks
  • Documentation

People decide which findings become future rules

A lesson from actual use

A misleading result became a safer rule for later agents.

A cleanup command reported success even though it had stopped the active coding session. Motus kept the recorded run and the faulty assumption behind it. The operator turned that finding into a rule that later agents follow before cleanup.

Run record
Process cleanup
Reported success
recorded run · commit 84f18a7

Active coding session terminated

Finding
Faulty assumption

Session age was treated as proof of inactivity. The cleanup terminated the active coding session.

finding_36f5a91e

Finding linked to original run

Agent instruction
AGENTS.md
Process cleanup
  • Identify the current session
  • Exclude it explicitly
  • Show the remaining targets

Rule applies before future cleanup

The lesson no longer depended on one coding session. The operator added the rule to AGENTS.md, which later coding agents read before cleanup. Motus retains the original run, the finding, and the later run that exercised the safer process.

Start locally

Start with one command.

Download a prebuilt release for macOS, Linux, or Windows. Unpack it and place motus or motus.exe on your PATH. Releases include checksums, SBOMs, and GitHub artifact attestations. Full installation guide.

Or install with Go

$ go install github.com/motus-os/work-ledger/cmd/motus@latest
$ motus version
How it works

01

Record the run

Motus records selected facts about a test, build, script, or check.

02

Add a finding

Add the explanation, decision, constraint, or lesson worth keeping.

03

Retrieve it later

Search the same local ledger from a terminal, coding agent, or CI job.

Try it in a Git repository.

This records a Git check, links one finding to that run, and retrieves it.

OUTPUT="$(motus wrap -- git rev-parse --show-toplevel 2>&1)"
printf '%s\n' "$OUTPUT"

RUN_ID="$(printf '%s\n' "$OUTPUT" | sed -n 's/^motus: recorded \(run_[^ ]*\).*/\1/p')"

printf '%s\n' 'Run commands from the Git root.' |
  motus finding add --run "$RUN_ID" --file -

motus finding list --query 'Git root'

Replace the check and finding with work from your project.

Motus stores the local ledger in .motus/ledger.db at the Git root. Add .motus/ to .gitignore.