Feature matrix
A complete, practical list of the shipped M8Shift capabilities and what each one does.
Scope rule
This table describes available behavior: the local relay, generated files, validation, automation hooks, and the optional worktree companion. Planned protocol work stays in the roadmap until it ships.
Token adapters: RTK and Headroom
Optional token-usage optimizers, not requirements.
RTK is an external open-source shell-output compression tool. M8Shift can use it through the RFC 034 identity-pinned argv runner for shell and tool output, primarily to reduce the amount of command output agents need to read.
Headroom / headroom-ai is an external open-source context-compression library and CLI. M8Shift can plug an adapter-compatible local headroom_ext command into the same identity-pinned runner for broad context records.
Both are local, optional, and fail closed to builtin behavior when absent, unpinned, invalid, or errored. They exist to optimize token usage, not to change the core relay. M8Shift measurements recorded ~97% savings on referenced context packs and ~54–68% on real shell output with RTK; Headroom is treated as a near-lossless broad-context experiment. See the context-pack measurements.
| Area | Feature | What it does |
|---|---|---|
| Core relay | Exclusive pen | Allows exactly one roster agent to write in the shared repository at a time. An agent must claim the pen before changing files. |
| Core relay | Agent roster | Defines which agents may participate, for example claude,codex,gemini,vibe. Any listed agent can receive the pen. |
| Core relay | Lock block | Stores holder, state, roster, turn number, timestamps, TTL, note, and language in plain text at the top of M8SHIFT.md. |
| Core relay | State machine | Tracks IDLE, WORKING_<agent>, AWAITING_<agent>, PAUSED, and DONE so every participant knows the safe next action. |
| Core relay | Manual heartbeat | Refreshes a long WORKING_<agent> turn by re-running claim <agent>, extending the 30-minute TTL without a daemon. |
| Core relay | Stale recovery | Lets another agent recover with claim --force only after the current lock has expired. |
| Core relay | Release | Hands the pen to another agent without recording a numbered turn and without incrementing turn. |
| Core relay | Done state | Marks the relay finished with done, allowing humans and automation to stop cleanly. |
| Core relay | Pause / resume | Parks an open session with PAUSED and holder=none, then resumes only on explicit new user scope. |
| Handoffs | Numbered turns | Appends each completed handoff as an immutable, numbered block in M8SHIFT.md. |
| Handoffs | append --to | Closes the current agent turn, records what was done, and routes the next turn to another roster member. |
| Handoffs | append --wait | Keeps the sender blocked after handoff until its next turn or DONE, reducing premature exits in shells or automation. |
| Handoffs | Free-text body | Accepts longer handoff notes from a file or stdin with --body PATH|-, while protecting reserved relay markers. |
| Handoffs | Work metadata | Records fields such as ask, done, files, branch, commit, tests, next, and blocked_on. |
| Handoffs | Stage-4 contract fields | Adds structured advisory fields such as role, relation, requirements, expected output, evidence, decision, waiver reason, and permissions. |
| Handoffs | Relation vocabulary | Labels the handoff as handoff, review_request, review_result, or escalation. |
| Handoffs | Review decisions | Records review outcomes with approve, revise, reject, or waive. |
| Handoffs | Custom fields | Accepts namespaced advisory metadata through --field key=value, including x_* fields for local conventions. |
| Read views | Status | Prints the current holder, state, turn, roster, session, UTC timestamps, and human-facing local time. |
| Read views | Safe next action | Uses status --for <agent> to tell an agent whether to claim, wait, resume, recover, or stop. |
| Read views | JSON status | Emits machine-readable state with status --json for scripts, tools, dashboards, and headless wrappers. |
| Read views | Watch | Continuously displays relay state without writing, claiming, or mutating anything. |
| Read views | Project identity | Shows the project name, working directory, and relay root in status, status --json, and the watch banner so multiple open terminals or tabs stay distinguishable. The label prefers init --name and falls back to the folder name, and the generated protocol now carries the status-guard rule: never claim the pen or DONE from memory — re-run status before ending a turn. |
| Read views | Wait | Blocks a process until it is an agent's turn, with --once for non-blocking readiness checks. |
| Read views | Next | Combines wait, claim, and latest handoff output so an agent can resume safely from one command. |
| Read views | Peek | Reads the latest handoff addressed to an agent without claiming the pen. |
| Read views | Log | Shows the relay timeline, including an oneline mode and optional archived turns. |
| Read views | Recap | Builds a current-session briefing from the lock, recent turns, memory headlines, and open tasks. |
| Read views | History | Reads prior session start, reset, and done events from M8SHIFT.sessions.jsonl. |
| Audit | Archive | Moves older turns to M8SHIFT.archive.md while keeping the lock and recent turns in the main relay file. |
| Audit | Memory notes | Appends durable shared-memory notes with remember without requiring the pen. |
| Audit | Task ledger | Adds, lists, shows, completes, or drops task events in an append-only ledger without requiring the pen. |
| Audit | Generated files | Keeps relay state, protocol, archive, memory, tasks, sessions, and temporary lock files in the repository or local workspace. |
| Adoption | Agent pack | init generates M8SHIFT.agent-pack.md, a first-read discipline pack for agents with claim-before-write, no-parking, prompt-security, stale-lock, delivery-complete, raw-proof (compressed views are orientation, not proof), and shared-checkout (destructive git needs explicit human authorization) rules. |
| Adoption | Compact anchor floor | Agent anchors keep a compact inline safety floor and point to the generated pack plus the protocol, reducing repeated prompt weight without dropping critical guardrails. |
| Adoption | Source-driven update | update --target DIR --source DIR refreshes an adopted project from a newer local source copy while preserving live relay state and writing the core last. |
| Validation | Doctor | Runs read-only health and lint checks, with JSON output and severity filtering. |
| Validation | Adoption health | doctor reports missing, stale, or invalid agent packs and stale anchor floors. Pre-v3.49 projects receive informational adoption findings until init refreshes them. |
| Validation | doctor --lint | Adds core-safe lint findings for relay/LOCK validity, anchors, protocol drift, sessions, duplicate open sessions, and livelock indicators. |
| Validation | Security checks | Adds local security-oriented checks with doctor --security. It reports findings; it is not a sandbox. |
| Validation | Contract validation | Validates schema=stage4.v1 handoff fields with contract validate or doctor --contracts. |
| Validation | Strict mode | Lets validation commands exit non-zero when findings meet the selected severity threshold. |
| Setup | Init kit | Generates or regenerates M8SHIFT.md, M8SHIFT.protocol.md, and agent-facing anchor files. |
| Setup | Companion kit install | Copies selected companion scripts into the kit, version-locked to the core, with init --companions runtime,context,..., --with-runtime and friends, or --full: idempotent, no-clobber (never downgrades, refuses edited or newer files), atomic, and preflighted before any mutation. Records a merged .m8shift/kit.json manifest checked by read-only doctor kit findings; --companion-source <dir> copies from a release or checkout directory. |
| Setup | EN/FR generation | Writes generated protocol and anchor content in English or French with init --lang en|fr. |
| Setup | Agent anchors | Injects idempotent protocol stanzas into files such as CLAUDE.md, AGENTS.md, and GEMINI.md. |
| Setup | Single-file core | Runs as m8shift.py, a Python 3.8+ script using the standard library only. |
| Setup | Install scripts | Provides shell and PowerShell installers for macOS, Linux, WSL, Git Bash, and Windows, with checksum verification, dry-run planning, explicit optional RTK setup from same-tag-checksummed release assets, and experimental Headroom setup. |
| Setup | Checksum verification | Verifies downloaded scripts against checksums.sha256 during installer-based adoption. |
| Automation | Exit codes | Returns distinct codes for success, refusal/runtime error, argument error, and not-ready states. |
| Automation | Headless runner | Ships a reference loop for unattended CLI agents that claims, launches one agent turn, observes crashes, writes immutable run plans, verifies the post-run LOCK, and stops on DONE. |
| Automation | Runtime run IDs | Sets M8SHIFT_RUN_ID and writes .m8shift/runtime/runs.jsonl so process runs can be correlated with turns. |
| Automation | Runtime companion | Adds advisory local sidecars for presence, runs, progress, operator inbox, idempotency, approvals, reports, runtime status, and diagnostics. |
| Automation | Context compression records | m8shift-context.py compress/retrieve stores redacted raw references, compact digests, backend metadata, and bounded retrieval paths without touching the core relay. |
| Automation | Optional compression backends | --backend auto uses identity-pinned RTK for shell/tool output; broad context records stay on builtin unless backends.headroom_ext.auto_enabled explicitly opts into the optional headroom_ext experiment. |
| Automation | Lane ownership | Allows one fresh managed runtime per agent identity and requires explicit stale takeover before a second runtime uses the same lane. |
| Automation | No-progress detection | Reports runtime no-progress findings when a companion loop stops seeing newer run or progress events. |
| Automation | Sidecar retention | Prunes runtime JSONL sidecars to a fixed row cap and archives older rows under .m8shift/runtime/archive/ by default. |
| Automation | VS Code workflow | Documents a practical loop for interactive Claude, Codex, Gemini, Vibe, or other agent panels inside an editor. |
| Automation | Worktree toolbox | Adds optional isolated parallel feature work with one git worktree per task. |
| Automation | Serialized integration | Merges worktree results through one integration pen so two integrations cannot run at the same time. |
| Boundary | Provider neutrality | Coordinates any cooperative CLI-capable agent. M8Shift does not call models, host a runtime, or require a project API key. |
| Boundary | Companion advisory boundary | Runtime companions never own the pen, never edit M8SHIFT.md directly, never require network access, and never auto-force. |
| Boundary | Permission vocabulary | Records advisory permission intent while making clear that real enforcement belongs to the OS, IDE, repository, or provider host. |