Lossless OpenClaw Orchestrator

LCO turns local Codex sessions into searchable, bounded, approval-aware
work objects for OpenClaw.

Use it when an agent or user needs to answer: what sessions are active, what did
they plan, what did they finish, what files did they touch, and what is the next
safe action without rereading raw transcripts.

Setup · Contributing · Agent Instructions · Agent Skill · OpenClaw Plugin · Security · Code of Conduct · Vision · Privacy · Claude Boundary · Claim Audit · Release Notes · 1.1.4 Notes · 1.0 Notes · License

Why It Matters

Codex is powerful, but long-running local work can become hard to supervise
once you have dozens or hundreds of threads. LCO gives your orchestrator agent a
safe operating picture: search first, inspect compact session cards, expand only
bounded evidence, and dry-run the next action before anything live happens.

If you are here to contribute, start with CONTRIBUTING.md.
If you are an agent working in this repository, read AGENTS.md
before editing files.

What It Does

LCO is a local-first orchestration layer for Codex-heavy work:

• indexes local Codex session stores into a local SQLite database
• searches sessions by safe summaries, plans, finals, touched files, and refs
• describes one session without exposing the whole transcript
• expands only the evidence an agent needs, with token-budgeted profiles
• exposes loo_* tools through MCP and the OpenClaw plugin
• creates dry-run approval packets before Codex resume/send/steer/interrupt
• reports Codex Desktop visibility and fallback readiness without GUI mutation
• validates exact action-bound Desktop collaboration proof packets without executing them
• summarizes runtime Desktop visibility coverage and next read-only proof steps
• classifies active threads as running, blocked, needs-nudge, stale, waiting,
  approval-needed, idle, or unknown from public-safe read-only signals,
  including attention coverage, non-executed read-only probe recommendations,
  and non-executed control dry-run recommendations for safe nudge handoff
• plans one deterministic read-only autonomy loop tick with execute:false
  tool calls so an agent can probe before dry-run handoff without mutation

The result is a staged recall loop:

1. Search broadly.
2. Describe the likely session.
3. Expand a small evidence bundle.
4. Dry-run the next action.
5. Execute only after the user approves the exact target/action.

Install

Requirements:

• Node.js 22 or newer
• npm
• local Codex session files, usually under ~/.codex/sessions
• OpenClaw Desktop/CLI if you want installed loo_* tools through OpenClaw

Stable install:

npm install -g lossless-openclaw-orchestrator@latest
loo doctor

Beta train, when you explicitly want the newest prerelease:

npm install -g lossless-openclaw-orchestrator@beta

Package channels:

• latest is the stable public channel.
• beta is the active prerelease train.
• next is reserved for release candidates.

Full first-run instructions live in docs/SETUP.md.

Set Up

Choose where LCO stores its local index. The default is already under
~/.openclaw, but setting it explicitly makes setup easier to inspect:

export LOO_DB_PATH="$HOME/.openclaw/lossless-openclaw-orchestrator/orchestrator.sqlite"

Index local Codex sessions:

loo index codex --max-files 500 "$HOME/.codex/sessions" "$HOME/.codex/archived_sessions"

Optional: allow read-only recall from one or more OpenClaw LCM peer databases:

export LOO_LCM_DB_PATHS="$HOME/.openclaw/lcm.db"

Check local readiness:

loo doctor
loo onboard status --strict

If agents will author PRs, issue comments, or closeouts in the repo, also copy
the provenance snippets from docs/SETUP.md
into the repo's AGENTS.md and CLAUDE.md files.

First Workflow

Search for a session:

loo search "billing bridge proposed plan"

Describe a result:

loo describe codex_thread:<thread-id>

Expand a bounded brief:

loo expand-ref --profile brief --token-budget 1000 codex_thread:<thread-id>

Expand from a query when you do not know the ref yet:

loo expand-query --profile brief --token-budget 1000 "billing bridge"

For normal agent workflows, start with the compact public/operator facade
instead of treating every loo_* tool as a peer:

Other declared tools remain available as workflow_detail, proof_debug, or
internal_low_level surfaces for setup, diagnosis, proof, and recovery. Their
existence is deliberate: normal agents should start from the facade, then drop
to the lower tiers only when the compact path returns a specific next step or
blocker.

loo_codex_control_dry_run returns the audit id and hashes an agent should show
before any live start/resume/send/steer/interrupt call. Live control requires
the matching approval_audit_id.

Live Codex control results include proof_state fields for
accepted_by_transport, started, completed, persisted, and
unverified_pending. Transport acceptance is not durable execution: when
unverified_pending is true, run the returned next_proof read-only tool call
before claiming the turn or thread completed, persisted, or is safe to build on.

The packaged agent playbook is
skills/lossless-openclaw-orchestrator/SKILL.md.

Naming policy: LCO is the public product abbreviation and lco_* is the
forward public alias target for new user-facing tool names. The currently
callable OpenClaw/MCP tools still use the historical loo_* runtime prefix, so
examples that must run today continue to show loo_* until #434 lands a tested
alias layer. Do not delete or silently rename the loo_* tools; keep them as
backward-compatible aliases when lco_* aliases are added.

OpenClaw And MCP

Run the MCP server directly:

loo-mcp-server

Typical MCP client entry:

{
  "mcpServers": {
    "lossless-openclaw-orchestrator": {
      "command": "loo-mcp-server"
    }
  }
}

Install the OpenClaw plugin from npm:

openclaw plugins install lossless-openclaw-orchestrator@latest
openclaw plugins list --json

Verify the package and OpenClaw gateway path:

loo openclaw dogfood --profile lco-dogfood --install-source lossless-openclaw-orchestrator@latest --required-tool loo_doctor --required-tool loo_search_sessions --strict
loo openclaw tool-smoke --profile lco-dogfood --required-tool loo_doctor --required-tool loo_search_sessions --strict

OpenClaw gateway setup may require local credential, device-pairing, token, or
scope approval steps before tool smoke can pass. LCO reports those as setup
blockers, not package failures. See docs/SETUP.md and
docs/OPENCLAW_PLUGIN.md.

Safety Boundaries

LCO is Codex-first and local-first.

Default behavior:

• local SQLite index
• public-safe summaries before raw expansion
• source refs instead of raw transcript paths
• bounded expansion profiles
• read-only OpenClaw LCM peer DB access
• direct Codex protocol before desktop fallback
• CUA Driver as the preferred/default desktop fallback backend when desktop
  fallback is needed; CUA is externally installed, not bundled by LCO, and
  Peekaboo remains a secondary visible fallback
• dry-run plus matching approval_audit_id before live Codex control,
  including new-thread creation
• explicit mutation classes: pure reads use empty mutationClasses, and
  LCO-owned indexing/audit/prepared-state writes use mode: "local_cache_write"
  with derived_cache instead of mutating Codex source stores, external
  systems, live control, or GUI state

Not claimed:

• full Claude Code parity
• cloud sync
• unattended desktop takeover
• permission bypass
• enterprise or customer-ready security claim
• generic GUI mutation is not supported
• Codex GUI mutation is not a stable public claim

Claude Code support is an adapter stub and redacted fixture inventory until its
storage and control paths are proven. Desktop fallback surfaces report
readiness, blockers, and proof states; they do not authorize prompt typing,
clicking, refresh/restart automation, or arbitrary app control.

Desktop fallback readiness is optional for normal read/search/describe
workflows. Operators who need fallback control should install CUA Driver
separately, verify the launch entrypoint with cua-driver mcp --help, then use
loo doctor --json or loo desktop see cua-driver only for LCO readiness and
blocker reporting. Treat missing CUA as a desktop-fallback readiness blocker
rather than a package install failure.

Claude adapter proof boundaries live in
docs/CLAUDE_ADAPTER_BOUNDARY.md. Public
claim details live in docs/CLAIM_AUDIT.md.
Privacy details live in docs/PRIVACY.md and
docs/SAFE_SUMMARIES.md.

Community And Contributing

LCO is meant to be easy to try and safe to improve. The public contribution
path is:

1. Read CONTRIBUTING.md for issue routing, validation,
   evidence, and agent-authored PR expectations.
2. Follow docs/SETUP.md for local install and first-run setup.
3. Use AGENTS.md when a coding agent is making or reviewing the
   change.
4. File a bug, docs bug, feature request, adapter request, protocol drift
   report, or unsafe-control report through the GitHub issue forms.

Good first issue candidates are docs gaps, redacted fixture coverage, setup
diagnostics, issue-template improvements, and narrow CLI help fixes. Use the
adapter request form to request an adapter; describe the target app/runtime,
read/index path, control boundary, and redacted proof available to test it.

Never paste raw Codex transcripts, private SQLite databases, tokens, cookies,
connector URLs, or customer data into public issues or PRs. Use
SECURITY.md for private vulnerability reports and
CODE_OF_CONDUCT.md for community expectations.

Architecture

• packages/core: SQLite index, Codex import, safe summaries, source refs,
  extraction, search, and expansion
• packages/mcp-server: stdio MCP server exposing loo_* tools
• packages/openclaw-plugin: OpenClaw plugin entry and manifest surface
• packages/cli: loo CLI for setup, indexing, recall, smoke, eval, and
  release gates
• packages/adapters: Codex transport, audit, redaction, CUA/Peekaboo
  readiness, and adapter boundaries
• skills/: packaged agent-facing OpenClaw playbook
• evals/: scenario and scorecard contracts
• docs/: setup, privacy, release proof, source authority, adapter boundaries,
  and deeper operator guides

Roadmap And Proof Status

The stable public product is Codex-first local orchestration: index, search,
describe, expand, OpenClaw/MCP tools, and approval-gated dry-run/live-control
boundaries.

Current deeper product work is the 1.2 prepared-state and summary-leaves lane.
It is tracked in GitHub issues, summarized in VISION.md, and
handed off in
docs/sprints/brief-lco-1.2-prepared-state-summary-leaves-2026-07-03.md.
Keep sprint and agent-operator details there, in AGENTS.md, and in
the packaged agent skill, not
in this public landing page.

The 1.2 lane is local, deterministic, and opt-in. It is building
source-ref-backed ranges, summary leaves, prepared cards, persisted watcher
observations, execute-false local attention queue items, and hook capture so an
OpenClaw/Eva agent can start from compact prepared state rather than rereading
huge Codex transcripts. Summary leaves are advisory
routing/evidence cards over prepared ranges; they are not authority, hidden
autonomy, GUI mutation, Claude parity, or true Codex compaction-summary capture.
When a specific Codex thread id is requested, prepared-state status reports
thread-level targetCoverage with opaque source refs, freshness, coverage, and
reason codes such as source_present_not_indexed instead of hiding a miss
behind healthy global cache counts.
The hook sidecar CLI lives under loo hook closeout-capture,
loo hook state-prep, and loo hook compaction-capture --mode marker; those
commands write only LCO-owned derived cache and treat transcript paths as
hash/redact-only inputs.

Maintainer Proof

Release and readiness proof lives in the runbooks, not in the first-run setup
path:

• Release Checklist
• Release Runbook
• Claim Audit
• QA Demo

For 1.0, the general release checklist requires fresh npm clean-profile
evidence, agent dogfood evidence through gateway tools, CI, scorecards, and
claim-audit proof before latest promotion.

Versioned proof contracts live in evals/scorecards/v1.0 and
evals/scenarios/v1; runtime-required scenario contracts live in
evals/scenarios/v1.1.

Core proof commands:

loo scorecards sweep --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-scorecard-sweep --strict
loo eval scenarios --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-qa-lab --strict
loo release preflight --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-preflight --strict
loo release demo-status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/demo --strict
loo release status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status --candidate-sha <release-candidate-sha> --npm-publish-approval-evidence npm-publish-approval.json --github-release-approval-evidence github-release-approval.json --github-ci-evidence github-ci.json --codeql-evidence codeql.json --strict
loo release general-readiness --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/general-readiness --fresh-npm-evidence published-package-smoke.json --agent-dogfood-evidence openclaw-tool-smoke.json --strict

Development

npm install
npm run build
npm test
npm run check

The test suite uses redacted fixtures and Node's built-in test runner. Heavy
validation is expected to run in CI; local development should use focused tests
first.

For contributor workflow details, use CONTRIBUTING.md.

License

Current source and current npm-published versions are source-available under the
PolyForm Noncommercial License 1.0.0. Noncommercial use is permitted
under those terms.

Commercial, internal-business, hosted-service, or product use requires a
separate commercial license from the project owner.

Earlier prerelease artifacts that previously carried MIT metadata are no longer
published on npm. Any copies already downloaded remain governed by the license
terms distributed with those copies.