https://github.com/motus-os/motus
A work-packet and ledger specification with a local reference CLI.
https://github.com/motus-os/motus
cli control-plane developer-tools evidence governance local-first python receipts work-items work-ledger
Last synced: 23 days ago
JSON representation
A work-packet and ledger specification with a local reference CLI.
- Host: GitHub
- URL: https://github.com/motus-os/motus
- Owner: motus-os
- License: apache-2.0
- Created: 2025-12-18T14:09:42.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-05-04T21:59:14.000Z (about 1 month ago)
- Last Synced: 2026-05-04T23:41:02.963Z (about 1 month ago)
- Topics: cli, control-plane, developer-tools, evidence, governance, local-first, python, receipts, work-items, work-ledger
- Language: Python
- Homepage: https://www.motussupra.com/
- Size: 6.48 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
# Motus
> Motus is a local event-backed work ledger with a reference CLI.
> It records work as Store runs and append-only events, then derives packets,
> evidence, decisions, and receipts as projections you can trust later.
[](LICENSE)
[](https://pypi.org/project/motusos/)
[](https://pypi.org/project/motusos/)
[](https://github.com/motus-os/motus/actions/workflows/quality-gates.yml)
## What Motus Solves
Important work usually disappears into chat, tickets, logs, and memory. That
makes it hard to answer basic questions later:
- What was the work?
- Who owned it?
- What proof exists?
- What was accepted?
- What should happen next?
Motus makes those answers durable.
It records work as a **Store run**, appends useful **events**, and projects those
facts into operator-facing **packets**, **evidence**, **decisions**, and
**receipts**. Existing `motus work` commands use a lease-backed compatibility
path for active custody. The 0.4 kernel direction keeps that user-facing path
while making Store runs and append-only events the deepest durable truth.
Optional locks are for protected mutable resources, not the primary meaning of
work.
Motus is useful with one person in one environment. It is also composable
across environments that share the packet format. Neither mode requires the
other.
The practical asymmetry is simple: if reconstructing a handoff costs more than
recording it once, Motus is worth using.
## What Motus Is
Motus defines the local work-truth surfaces that a work loop depends on:
1. records work as a bounded Store run,
2. appends structured proof while the work happens,
3. closes the run with an explicit outcome,
4. derives receipts and packets from durable facts,
5. preserves the result as deterministic lineage.
The shipped CLI is the reference implementation. Motus should not require a
second implementation to be useful, but the kernel boundary is kept small enough
that another implementation could preserve the same run, event, projection, and
receipt truth.
## What Motus Is Not
Motus is not:
1. a replacement for Git, CI, ticketing, or your runtime,
2. a scheduler or orchestration product,
3. a hosted control tower,
4. a chat transcript archive.
Those systems still run work. Motus defines how work becomes reviewable,
receiptable, and reusable.
## Good First Use Cases
Start where reconstruction is already painful:
- AI-assisted code changes that need evidence and reviewable closeout,
- release decisions that need explicit scope, verification, and approval,
- CI validation handoffs where the next actor must inherit proof,
- exception approvals that need rationale, approver identity, and expiry,
- review or approval workflows where the accepted outcome must stay durable.
Do not start by trying to model every task, every transcript, or every agent
memory surface. Start with one workflow where losing the contract, custody,
evidence, or accepted outcome is already expensive.
## Start Light With The Store
When command execution is the useful evidence, start with the Store-backed
`motus wrap` adapter. It records one Store run and terminal outcome without
manual evidence authoring.
Routine compatibility work can still use the light path. It writes a
project-local Store run/event record by default while preserving the lease ID
as a compatibility custody alias:
```bash
motus work claim ...
motus work evidence ...
motus work release ...
```
Set `MOTUS_KERNEL_STORE_PATH` or `MOTUS_STORE_PATH` only when you need to
override the default `.motus/kernel-store.db` location. Set
`MOTUS_WORK_STORE_BRIDGE=disabled` only for compatibility recovery; normal work
should leave the bridge in `auto` mode.
Use governed packet workflows only when the consequence of the work justifies
the extra structure. Typical reasons:
- another actor must inherit the evidence and decision,
- the work changes a release, approval, or policy boundary,
- the closeout needs a stricter final receipt than the light loop provides.
## Auto-Capture: Wrap A Command
When the useful evidence is command execution, use the Store-backed adapter
instead of hand-authoring output evidence:
```bash
motus wrap -- pytest
```
`motus wrap` runs the command normally, streams stdout/stderr back to your
terminal, and records one Store run with start, metadata-only output, and
terminal outcome events. Raw stdout/stderr content is not persisted by default;
the Store payload records byte counts, line counts, truncation state, and the
terminal outcome. It is an adapter over the Store, not a workflow engine or
scheduler.
## GitHub Actions
Use the GitHub Action when CI command evidence should produce the same Store
truth and receipt projection:
```yaml
- uses: motus-os/motus@v0.4.10
with:
command: "pytest"
export-path: "motus-run-export.json"
receipt-path: "motus-receipt.json"
```
The Action writes a Store run, a deterministic Store export, and a receipt
projection. Upload those files with your normal artifact policy if another
reviewer or job needs them. Use `if: always()` on the artifact upload step if
you want receipts from failing commands. The Action is a thin adapter over the
Store path; it does not own workflow routing, approvals, or orchestration.
## Install
```bash
pip install motusos
motus --help
```
## Quickstart: First Store Run
```bash
motus wrap -- python3 -c "print('motus store run')"
```
This proves the Store-backed adapter path without hand-authoring evidence or
using the legacy lease custody loop.
## Compatibility Quickstart: First Work Item
```bash
motus install
motus init --empty --path .
motus doctor
LEASE_ID=$(motus work claim ADHOC-QUICKSTART-001 --intent "First local work item" --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["lease_id"])')
motus work evidence "$LEASE_ID" test_result --passed 1 --failed 0
motus work release "$LEASE_ID" success
motus work receipt "$LEASE_ID"
```
The compatibility loop records linked Store run/event truth by default in
`.motus/kernel-store.db`. Set `MOTUS_KERNEL_STORE_PATH` or `MOTUS_STORE_PATH`
only when you need a different Store location.
PowerShell:
```powershell
$LEASE_ID = (motus work claim ADHOC-QUICKSTART-001 --intent "First local work item" --json | ConvertFrom-Json).lease_id
motus work evidence $LEASE_ID test_result --passed 1 --failed 0
motus work release $LEASE_ID success
motus work receipt $LEASE_ID
```
The shell pipeline extracts the `lease_id` from JSON output so you can reuse it
in the next two commands. If you prefer, run `motus work claim ... --json`
first, copy the returned `lease_id`, and paste it into the evidence and release
commands manually. `motus work release` prints the `receipt_id`; `motus work
receipt` lets you inspect that close record directly.
What each command does:
- `motus install` applies local defaults Motus expects.
- `motus init --empty --path .` creates the minimum neutral workspace layout.
- `motus doctor` checks that the environment is healthy before execution.
- `motus work claim ...` opens a compatibility lease for one bounded work item.
- `motus work evidence ...` attaches proof to that active lease and appends a
Store evidence event.
- `motus work release ...` closes the lease and closes the linked Store run.
- `motus work receipt ...` inspects the durable close record and prefers the
Store receipt projection when one exists.
- `success`, `failure`, and `partial` close as released attempts.
- `aborted` and `expired` remain distinct terminal states rather than accepted
closeout.
What success looks like:
- `motus doctor` reports healthy.
- `claim` returns a `lease_id`.
- `evidence` succeeds against that lease.
- `release` returns a `receipt_id`.
- `receipt` shows the durable close record for that lease, or the Store receipt
projection when the bridge is configured.
## Core Ideas
- **Store run**: the kernel lifecycle container.
- **Event**: append-only durable fact recorded for a run.
- **Work packet**: operator-facing projection over a run and its events.
- **Evidence**: proof-bearing events and references.
- **Receipt**: deterministic close projection for accepted work.
- **Lease**: current compatibility custody for `motus work`; not the long-term
kernel lifecycle primitive.
- **Lock**: optional fenced protection for Motus-controlled mutable resources.
- **Adapter**: CLI, wrapper, hook, CI, or MCP surface that writes through the
Store path.
## Runtime Boundary
Motus is intentionally runtime-agnostic.
You can use it with:
- local scripts,
- CI jobs,
- agent workflows,
- N8N or other orchestrators,
- your own server/runtime stack.
Motus owns the local run/event truth and deterministic projections. You choose
the downstream execution stack.
## Public Boundary
Motus keeps three public layers distinct:
- **Core**: the invariant Store path plus the compatibility work-item loop:
claims, evidence, receipts, declared routes, and durable ledger truth.
- **Adapters**: runtime- or vendor-specific observation and integration
surfaces.
- **Userland**: governed workspace conventions, review packets, and operating
opinions layered on top of the core loop.
The package is strongest when those boundaries stay explicit.
The 0.4 migration target makes that boundary smaller: Store runs and events are
the durable kernel truth, while work packets, evidence lists, decisions,
receipts, handoffs, and route summaries are deterministic projections over that
truth. Existing `motus work claim/evidence/release/receipt` commands remain the
current compatibility path while that target proves itself.
If you want a reviewable, file-backed governed workflow on top of that core
loop, use the optional
[Governed Workspace Layout](packages/cli/docs/implementation/governed-workspace.md).
## Start Here
1. [Quickstart](packages/cli/docs/implementation/README.md)
2. [First Real Workflow](packages/cli/docs/implementation/first-real-workflow.md)
3. [Evidence and Receipts](packages/cli/docs/implementation/evidence-and-receipts.md)
4. [Using the Work Ledger](packages/cli/docs/implementation/work-ledger.md)
5. [Kernel Concepts](packages/cli/docs/implementation/kernel.md)
6. [Kernel Boundary](packages/cli/docs/implementation/kernel-boundary.md)
7. [GitHub Actions](packages/cli/docs/github-actions.md)
8. [Governed Workspace Layout](packages/cli/docs/implementation/governed-workspace.md)
9. [Architecture](ARCHITECTURE.md)
10. [Docs Index](packages/cli/docs/README.md)
## Links
- PyPI: https://pypi.org/project/motusos/
- GitHub: https://github.com/motus-os/motus
- Contributing: CONTRIBUTING.md
- Security Policy: SECURITY.md
## License
Apache License 2.0. See LICENSE.