{"id":49096904,"url":"https://github.com/motus-os/motus","last_synced_at":"2026-05-11T21:01:54.139Z","repository":{"id":349788431,"uuid":"1118945815","full_name":"motus-os/motus","owner":"motus-os","description":"A work-packet and ledger specification with a local reference CLI.","archived":false,"fork":false,"pushed_at":"2026-05-04T21:59:14.000Z","size":6795,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T23:41:02.963Z","etag":null,"topics":["cli","control-plane","developer-tools","evidence","governance","local-first","python","receipts","work-items","work-ledger"],"latest_commit_sha":null,"homepage":"https://www.motussupra.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/motus-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-18T14:09:42.000Z","updated_at":"2026-05-04T21:59:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/motus-os/motus","commit_stats":null,"previous_names":["motus-os/motus"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/motus-os/motus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/motus-os%2Fmotus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/motus-os%2Fmotus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/motus-os%2Fmotus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/motus-os%2Fmotus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/motus-os","download_url":"https://codeload.github.com/motus-os/motus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/motus-os%2Fmotus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32912661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","control-plane","developer-tools","evidence","governance","local-first","python","receipts","work-items","work-ledger"],"created_at":"2026-04-20T21:02:10.108Z","updated_at":"2026-05-11T21:01:54.132Z","avatar_url":"https://github.com/motus-os.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Motus\n\n\u003e Motus is a local event-backed work ledger with a reference CLI.\n\u003e It records work as Store runs and append-only events, then derives packets,\n\u003e evidence, decisions, and receipts as projections you can trust later.\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/motusos)](https://pypi.org/project/motusos/)\n[![Downloads](https://img.shields.io/pypi/dm/motusos)](https://pypi.org/project/motusos/)\n[![Quality Gates](https://github.com/motus-os/motus/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/motus-os/motus/actions/workflows/quality-gates.yml)\n\n## What Motus Solves\n\nImportant work usually disappears into chat, tickets, logs, and memory. That\nmakes it hard to answer basic questions later:\n\n- What was the work?\n- Who owned it?\n- What proof exists?\n- What was accepted?\n- What should happen next?\n\nMotus makes those answers durable.\n\nIt records work as a **Store run**, appends useful **events**, and projects those\nfacts into operator-facing **packets**, **evidence**, **decisions**, and\n**receipts**. Existing `motus work` commands use a lease-backed compatibility\npath for active custody. The 0.4 kernel direction keeps that user-facing path\nwhile making Store runs and append-only events the deepest durable truth.\nOptional locks are for protected mutable resources, not the primary meaning of\nwork.\n\nMotus is useful with one person in one environment. It is also composable\nacross environments that share the packet format. Neither mode requires the\nother.\n\nThe practical asymmetry is simple: if reconstructing a handoff costs more than\nrecording it once, Motus is worth using.\n\n## What Motus Is\n\nMotus defines the local work-truth surfaces that a work loop depends on:\n\n1. records work as a bounded Store run,\n2. appends structured proof while the work happens,\n3. closes the run with an explicit outcome,\n4. derives receipts and packets from durable facts,\n5. preserves the result as deterministic lineage.\n\nThe shipped CLI is the reference implementation. Motus should not require a\nsecond implementation to be useful, but the kernel boundary is kept small enough\nthat another implementation could preserve the same run, event, projection, and\nreceipt truth.\n\n## What Motus Is Not\n\nMotus is not:\n\n1. a replacement for Git, CI, ticketing, or your runtime,\n2. a scheduler or orchestration product,\n3. a hosted control tower,\n4. a chat transcript archive.\n\nThose systems still run work. Motus defines how work becomes reviewable,\nreceiptable, and reusable.\n\n## Good First Use Cases\n\nStart where reconstruction is already painful:\n\n- AI-assisted code changes that need evidence and reviewable closeout,\n- release decisions that need explicit scope, verification, and approval,\n- CI validation handoffs where the next actor must inherit proof,\n- exception approvals that need rationale, approver identity, and expiry,\n- review or approval workflows where the accepted outcome must stay durable.\n\nDo not start by trying to model every task, every transcript, or every agent\nmemory surface. Start with one workflow where losing the contract, custody,\nevidence, or accepted outcome is already expensive.\n\n## Start Light With The Store\n\nWhen command execution is the useful evidence, start with the Store-backed\n`motus wrap` adapter. It records one Store run and terminal outcome without\nmanual evidence authoring.\n\nRoutine compatibility work can still use the light path. It writes a\nproject-local Store run/event record by default while preserving the lease ID\nas a compatibility custody alias:\n\n```bash\nmotus work claim ...\nmotus work evidence ...\nmotus work release ...\n```\n\nSet `MOTUS_KERNEL_STORE_PATH` or `MOTUS_STORE_PATH` only when you need to\noverride the default `.motus/kernel-store.db` location. Set\n`MOTUS_WORK_STORE_BRIDGE=disabled` only for compatibility recovery; normal work\nshould leave the bridge in `auto` mode.\n\nUse governed packet workflows only when the consequence of the work justifies\nthe extra structure. Typical reasons:\n\n- another actor must inherit the evidence and decision,\n- the work changes a release, approval, or policy boundary,\n- the closeout needs a stricter final receipt than the light loop provides.\n\n## Auto-Capture: Wrap A Command\n\nWhen the useful evidence is command execution, use the Store-backed adapter\ninstead of hand-authoring output evidence:\n\n```bash\nmotus wrap -- pytest\n```\n\n`motus wrap` runs the command normally, streams stdout/stderr back to your\nterminal, and records one Store run with start, metadata-only output, and\nterminal outcome events. Raw stdout/stderr content is not persisted by default;\nthe Store payload records byte counts, line counts, truncation state, and the\nterminal outcome. It is an adapter over the Store, not a workflow engine or\nscheduler.\n\n## GitHub Actions\n\nUse the GitHub Action when CI command evidence should produce the same Store\ntruth and receipt projection:\n\n```yaml\n- uses: motus-os/motus@v0.4.10\n  with:\n    command: \"pytest\"\n    export-path: \"motus-run-export.json\"\n    receipt-path: \"motus-receipt.json\"\n```\n\nThe Action writes a Store run, a deterministic Store export, and a receipt\nprojection. Upload those files with your normal artifact policy if another\nreviewer or job needs them. Use `if: always()` on the artifact upload step if\nyou want receipts from failing commands. The Action is a thin adapter over the\nStore path; it does not own workflow routing, approvals, or orchestration.\n\n## Install\n\n```bash\npip install motusos\nmotus --help\n```\n\n## Quickstart: First Store Run\n\n```bash\nmotus wrap -- python3 -c \"print('motus store run')\"\n```\n\nThis proves the Store-backed adapter path without hand-authoring evidence or\nusing the legacy lease custody loop.\n\n## Compatibility Quickstart: First Work Item\n\n```bash\nmotus install\nmotus init --empty --path .\nmotus doctor\nLEASE_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\"])')\nmotus work evidence \"$LEASE_ID\" test_result --passed 1 --failed 0\nmotus work release \"$LEASE_ID\" success\nmotus work receipt \"$LEASE_ID\"\n```\n\nThe compatibility loop records linked Store run/event truth by default in\n`.motus/kernel-store.db`. Set `MOTUS_KERNEL_STORE_PATH` or `MOTUS_STORE_PATH`\nonly when you need a different Store location.\n\nPowerShell:\n\n```powershell\n$LEASE_ID = (motus work claim ADHOC-QUICKSTART-001 --intent \"First local work item\" --json | ConvertFrom-Json).lease_id\nmotus work evidence $LEASE_ID test_result --passed 1 --failed 0\nmotus work release $LEASE_ID success\nmotus work receipt $LEASE_ID\n```\n\nThe shell pipeline extracts the `lease_id` from JSON output so you can reuse it\nin the next two commands. If you prefer, run `motus work claim ... --json`\nfirst, copy the returned `lease_id`, and paste it into the evidence and release\ncommands manually. `motus work release` prints the `receipt_id`; `motus work\nreceipt` lets you inspect that close record directly.\n\nWhat each command does:\n\n- `motus install` applies local defaults Motus expects.\n- `motus init --empty --path .` creates the minimum neutral workspace layout.\n- `motus doctor` checks that the environment is healthy before execution.\n- `motus work claim ...` opens a compatibility lease for one bounded work item.\n- `motus work evidence ...` attaches proof to that active lease and appends a\n  Store evidence event.\n- `motus work release ...` closes the lease and closes the linked Store run.\n- `motus work receipt ...` inspects the durable close record and prefers the\n  Store receipt projection when one exists.\n- `success`, `failure`, and `partial` close as released attempts.\n- `aborted` and `expired` remain distinct terminal states rather than accepted\n  closeout.\n\nWhat success looks like:\n\n- `motus doctor` reports healthy.\n- `claim` returns a `lease_id`.\n- `evidence` succeeds against that lease.\n- `release` returns a `receipt_id`.\n- `receipt` shows the durable close record for that lease, or the Store receipt\n  projection when the bridge is configured.\n\n## Core Ideas\n\n- **Store run**: the kernel lifecycle container.\n- **Event**: append-only durable fact recorded for a run.\n- **Work packet**: operator-facing projection over a run and its events.\n- **Evidence**: proof-bearing events and references.\n- **Receipt**: deterministic close projection for accepted work.\n- **Lease**: current compatibility custody for `motus work`; not the long-term\n  kernel lifecycle primitive.\n- **Lock**: optional fenced protection for Motus-controlled mutable resources.\n- **Adapter**: CLI, wrapper, hook, CI, or MCP surface that writes through the\n  Store path.\n\n## Runtime Boundary\n\nMotus is intentionally runtime-agnostic.\n\nYou can use it with:\n\n- local scripts,\n- CI jobs,\n- agent workflows,\n- N8N or other orchestrators,\n- your own server/runtime stack.\n\nMotus owns the local run/event truth and deterministic projections. You choose\nthe downstream execution stack.\n\n## Public Boundary\n\nMotus keeps three public layers distinct:\n\n- **Core**: the invariant Store path plus the compatibility work-item loop:\n  claims, evidence, receipts, declared routes, and durable ledger truth.\n- **Adapters**: runtime- or vendor-specific observation and integration\n  surfaces.\n- **Userland**: governed workspace conventions, review packets, and operating\n  opinions layered on top of the core loop.\n\nThe package is strongest when those boundaries stay explicit.\n\nThe 0.4 migration target makes that boundary smaller: Store runs and events are\nthe durable kernel truth, while work packets, evidence lists, decisions,\nreceipts, handoffs, and route summaries are deterministic projections over that\ntruth. Existing `motus work claim/evidence/release/receipt` commands remain the\ncurrent compatibility path while that target proves itself.\n\nIf you want a reviewable, file-backed governed workflow on top of that core\nloop, use the optional\n[Governed Workspace Layout](packages/cli/docs/implementation/governed-workspace.md).\n\n## Start Here\n\n1. [Quickstart](packages/cli/docs/implementation/README.md)\n2. [First Real Workflow](packages/cli/docs/implementation/first-real-workflow.md)\n3. [Evidence and Receipts](packages/cli/docs/implementation/evidence-and-receipts.md)\n4. [Using the Work Ledger](packages/cli/docs/implementation/work-ledger.md)\n5. [Kernel Concepts](packages/cli/docs/implementation/kernel.md)\n6. [Kernel Boundary](packages/cli/docs/implementation/kernel-boundary.md)\n7. [GitHub Actions](packages/cli/docs/github-actions.md)\n8. [Governed Workspace Layout](packages/cli/docs/implementation/governed-workspace.md)\n9. [Architecture](ARCHITECTURE.md)\n10. [Docs Index](packages/cli/docs/README.md)\n\n## Links\n\n- PyPI: https://pypi.org/project/motusos/\n- GitHub: https://github.com/motus-os/motus\n- Contributing: CONTRIBUTING.md\n- Security Policy: SECURITY.md\n\n## License\n\nApache License 2.0. See LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmotus-os%2Fmotus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmotus-os%2Fmotus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmotus-os%2Fmotus/lists"}