Lossless Codex Orchestrator

Give your main agent a memory and command layer for all your Codex projects and threads.

Codex is excellent at doing work. The hard part is managing all the work after you have dozens or hundreds of threads across repos, customer projects, fixes, reviews, and follow-ups.

LCO turns that scattered local Codex history into an operating layer your Hermes agent, MCP client, OpenClaw agent, or custom agent can use. Your agent can find the right project, understand what happened, see what is blocked, prepare the next action, and keep moving without rereading huge transcripts every time.

npm install -g lossless-codex-orchestrator@latest
lco doctor
lco find "billing bridge"

If this helps your main agent stay on top of Codex work, a star helps other agent builders find it. ⭐

Setup · OpenClaw Plugin · Agent Skill · Vision · Privacy · Hermes Boundary · Contributing · AGENTS.md · Security · Code of Conduct · Release Notes · License

Why It Exists

When you use Codex heavily, the problem stops being "can an agent code?" and becomes "can my main agent understand all the work already in motion?"

LCO gives that main agent a local memory and command surface:

| Without LCO | With LCO | | --- | --- | | Threads are scattered across many sessions and projects. | Your agent can search and triage them from one local index. | | Every handoff starts with rediscovery. | Prepared cards show the objective, blocker, status, and next action. | | Big transcripts eat context. | Summary leaves and bounded expansion let agents read the right slice. | | OpenClaw or another orchestrator has to guess what Codex did. | MCP/OpenClaw tools expose Codex state directly to the orchestrator. | | "Continue this work" is risky because the target may be unclear. | Dry-run command packets show the exact thread and action before anything runs. |

The goal is simple: your orchestration agent should manage Codex work the way a good technical operator would. It should know the projects, the active threads, the stale work, the blocked work, the finished work, and the right next move.

What It Does ✨

LCO is more than a transcript index. It builds an agent-readable operating picture over local Codex work.

Project and thread memory

• Indexes local Codex sessions into a local SQLite database.
• Uses field-weighted FTS5 search for session-card discovery over titles, summaries, proposed plans, final messages, touched files, tool metadata, and prepared safe text. For remembered content phrases, use lco grep or lco expand-query.
• Blends relevance, recency, identifier matching, and query fallback so agents can find "the billing bridge plan" or "the PR that touched auth" without the exact thread id.
• Detects Codex JSONL format drift in lco doctor so broken imports are visible instead of silently missing work.

Prepared state for agents

• Creates prepared cards for Codex threads: objective, blocker, lifecycle state, next action, freshness, confidence, and source refs.
• Builds a prepared inbox so your main agent can start from "what needs my attention?" instead of raw search.
• Tracks lifecycle states such as completed, waiting for approval, watching an external check, needs resume, dirty worktree handoff, ready for review, stale/partial, and unknown.
• Keeps completed work visible, so finished lanes can still be found and cited.

Summary leaves and bounded expansion

• Splits large sessions into source ranges and deterministic summary leaves.
• Creates leaf refs for user prompts, plans, final messages, closeouts, touched files, tool metadata, and compaction markers.
• Lets an agent expand a small 1k-token brief or a deeper 4k-token evidence bundle instead of loading an entire transcript.
• Reports omissions when a brief is intentionally smaller than the underlying session.

Operating picture tools

• lco_recent_sessions shows recent or active Codex work as compact cards.
• lco_attention_inbox lists threads that need action, review, approval, watch, or blocker triage.
• lco_project_digest creates a project-level handoff brief from Codex cards, optional GitHub items, plan pins, and source coverage.
• lco_operating_picture powers cockpit-style views such as session maps, collaboration next steps, active-thread state, autonomy tick planning, GitHub operating items, and business pulse cards.

Command layer for orchestrators

• Exposes the same local registry through CLI commands, a Hermes-compatible MCP server, and an OpenClaw compatibility plugin.
• Gives normal agents a compact facade: prepared inbox, recent sessions, project digest, attention inbox, bounded expansion, describe, and Codex control dry run.
• Creates dry-run command packets for Codex start/resume/send/steer/interrupt actions so the target and action can be reviewed before live execution.
• For live Codex actions, the packet can include the exact target, action, message hash, and approval id your main agent should show before it moves.
• Pins the currently supported live Codex control path to approvalPolicy=never and a read-only, no-network sandbox; LCO does not inherit or widen a thread's ambient runtime permissions. Active-turn steer and interrupt fail closed unless the same-connection resume response proves that posture is already in effect.
• Adds hook-sidecar commands for closeout capture, state prep, compaction marker capture, and thread title aliases.

Who It Is For

Use LCO if you:

• run Codex across many repos, customer projects, or product lanes
• use Hermes as your main local agent/operator
• want an MCP or OpenClaw orchestrator to manage Codex work
• need agents to hand off work without rereading massive transcripts
• want one place to ask "what is active, blocked, stale, finished, or ready?"
• want project digests and next-action briefs your agents can actually use

If you only run one short Codex session at a time, LCO may be more system than you need. If Codex is becoming your day-to-day engineering workforce, this is the memory layer that helps a main agent manage it.

Install 🚀

Requirements:

• Node.js 22.5 or newer
• npm
• local Codex session files, usually under ~/.codex/sessions
• Hermes if you want the primary supported agent path over stdio MCP
• OpenClaw Desktop/CLI if you want the compatibility plugin

Stable install:

npm install -g lossless-codex-orchestrator@latest
lco doctor

lossless-codex-orchestrator is the current published npm package name. The deprecated compat package lossless-openclaw-orchestrator remains maintained for existing automation and points at the same lco CLI and lco-mcp-server. The historical loo, loo-mcp-server, and LOO_* env names remain maintained compatibility aliases for at least two minor releases.

loo index codex "$HOME/.codex/sessions"
loo-mcp-server

Beta train, when you explicitly want the newest prerelease:

npm install -g lossless-codex-orchestrator@beta

Package channels:

• npm latest and GitHub Releases are the stable publication authorities.
• A version in the source tree is a candidate until those publication authorities show the same version; merged source alone is not release proof.
• latest is the stable public channel.
• beta is the active prerelease train.
• next is reserved for release candidates.
• npm dist-tags and GitHub Releases are the publication authorities; source version metadata, merged code, and local package smoke are not release proof.

If npm shows a version or dist-tag but install fails with a selector cutoff error such as ENOVERSIONS or ETARGET, use the npm selector-drift tarball fallback with raw npm commands a fresh shell can run:

tarball_url="$(npm view lossless-codex-orchestrator@latest dist.tarball)"
test -n "$tarball_url" && npm install -g "$tarball_url"

If the ETARGET message says the requested package version must have a publish date before a specific time, check for a local npm min-release-age or before pin before treating it as registry drift.

Full setup 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 LCO_DB_PATH="$HOME/.openclaw/lossless-openclaw-orchestrator/orchestrator.sqlite"

Index local Codex sessions:

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

The importer applies a 256 MB / 200,000-event per-file index cap so one oversized JSONL cannot dominate a first run. If lco index codex reports codex_index_limited_files_skipped, use --max-bytes-per-file <bytes> and --max-events-per-file <events> only when you intentionally want to widen that local indexing window.

The per-event content cache is local derived data used for deeper recall. If you need to pause that cache or reclaim space, use:

export LCO_EVENT_CONTENT=disabled
lco maintenance --drop-event-content

Re-enable by unsetting LCO_EVENT_CONTENT and running lco index codex again.

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

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

Configured peers stay read-only. lco index codex and lco find materialize public-safe advisory cards and inbox items from their summary DAGs without copying peer rows into LCO source tables. Inspect peer readiness and integrity with lco doctor --peers; peers are classified as ready, degraded, or unavailable with omission reasons for missing tables, empty summaries, and stale DAG links.

Check local readiness:

lco doctor --peers
lco onboard status --strict

First Workflow 🧭

Find the work you remember. lco find runs a local incremental index pass on first use, then searches titles, metadata, prepared cards, summaries, and event-level content snippets:

lco find "billing bridge proposed plan"

Use JSON when you want the same result shape in scripts or agent harnesses:

lco find --json "billing bridge proposed plan"

For lower-level recall, use lco search for title/session-card discovery and lco grep or lco expand-query for content-oriented recall.

Before preparing a drive plan, ask what changed since a public-safe cursor:

lco session-diff --cursor <cursor>

Build a bounded review-then-drive packet without running live control:

lco drive --dry-run --reviewer codex --driver claude --max-turns 3

When LCM peers are configured, inspect their read-only integrity posture with lco doctor --peers. Claude targeting in 1.6 validates availability and dry-run policy only; it does not provide Claude live control.

Describe a result:

lco describe codex_thread:<thread-id>

Expand a small brief:

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

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

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

For an agent or MCP client, start with the normal operator path:

| Step | Tool | What your agent gets | | --- | --- | --- | | 1 | lco_find | Fast public-safe session/content matches from the existing index; pass index:true only for an explicit synchronous refresh. | | 2 | lco_prepared_inbox | The best starting view of work that needs attention. | | 3 | lco_describe_ref | Details for a selected thread, card, leaf, or source ref. | | 4 | lco_expand_query | A bounded brief when the exact ref is unknown. | | 5 | lco_recent_sessions | Recent and active Codex work as compact cards. | | 6 | lco_attention_inbox | Blocked, waiting, stale, approval-needed, or ready-for-review work. | | 7 | lco_project_digest | A project-level handoff brief. | | 8 | lco_codex_control_route | An expiring opaque reference for one daemon-owned Codex task, or an explicit Desktop-observation blocker. | | 9 | lco_codex_deliver | A dry-run-first delivery that sends when idle or steers the matching active turn. | | 10 | lco_codex_control_dry_run | A preview packet for a lower-level exact Codex action. | | 11 | lco_codex_resume_thread | Resume a Codex thread after the dry-run packet is approved. |

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

Naming note: LCO is the public product abbreviation. New user-facing examples use lco, lco-mcp-server, and canonical lco_* tools. The historical loo, loo-mcp-server, and loo_* names remain maintained compatibility aliases for at least two minor releases.

Works With 🔌

| Surface | Status | What to use today | | --- | --- | --- | | Codex local sessions | Stable | lco index codex, lco search, lco describe, and bounded expansion. | | MCP clients | Stable | lco-mcp-server exposes the local tool registry over stdio. | | Hermes | Primary supported agent path over stdio MCP; native adapter deferred | Mount lco-mcp-server, use the canonical lco_* tools, and run the Hermes smoke before release. | | OpenClaw | Compatibility supported | Install the plugin and let your OpenClaw agent call the same lco_* tools. | | Other MCP agents | Supported | Mount the standards-compliant stdio server; see docs/HERMES_ADAPTER_BOUNDARY.md. |

LCO is Hermes-first. Hermes uses the standards-compliant stdio MCP surface as the primary supported agent path; OpenClaw remains a maintained compatibility surface over the same runtime-neutral core. A native Hermes adapter is still a separate, deferred claim.

Claude Code users who already run codex-plugin-cc can add LCO as a separate recall companion:

/plugin marketplace add 100yenadmin/Lossless-Codex-Orchestrator-LCO
/plugin install lco-recall@lco

The companion provides a user-invocable find skill for local recall and leaves Codex command ownership with codex-plugin-cc.

OpenClaw And MCP

Run the MCP server directly:

lco-mcp-server

Typical MCP client entry:

{
  "mcpServers": {
    "lco": {
      "command": "lco-mcp-server"
    }
  }
}

Hermes configuration (config.yaml) is credential-free because LCO is a local stdio server:

mcp_servers:
  lco:
    command: lco-mcp-server
    enabled: true
    env:
      LCO_TOOL_PROFILE: standard
      LCO_CODEX_TRANSPORT: daemon

Omitting LCO_DB_PATH uses LCO's home-based default. If you set it explicitly, use an expanded absolute path because Hermes does not shell-expand ~ inside an environment-variable value.

LCO_CODEX_TRANSPORT defaults to stdio for compatibility. The opt-in daemon mode connects only to the already-running local Codex managed daemon through its Unix socket. LCO does not start or restart the daemon and does not enable Codex Remote Control. Set LCO_CODEX_DAEMON_SOCKET only for an explicit absolute local override; LCO_CODEX_APP_SERVER_ARGS remains stdio-only.

For remote operation, Eva should call lco_codex_control_route first. A selected app_server route is safe for LCO daemon/CLI task control. A desktop_observation_required result means Hermes must use its own computer_use integration to identify and operate the Codex Desktop task; LCO must not silently redirect that task to the managed daemon. Telegram direction is user to Eva for instructions and Eva to the same user for results. An operator should not type a bot message into Telegram as though it came from Eva.

Before a release, verify the candidate without changing a Hermes profile:

lco qa-lab cli-mcp-smoke --evidence-dir /tmp/lco-package-smoke --package-version <package-version> --candidate-sha <candidate-sha> --cli-bin <candidate-prefix>/node_modules/.bin/lco --mcp-bin <candidate-prefix>/node_modules/.bin/lco-mcp-server --strict
lco hermes smoke --evidence-dir /tmp/lco-hermes-smoke --package-version <package-version> --candidate-sha <candidate-sha> --cli-bin <candidate-prefix>/node_modules/.bin/lco --mcp-bin <candidate-prefix>/node_modules/.bin/lco-mcp-server --strict
lco release hermes-readiness --evidence-dir /tmp/lco-hermes-readiness --package-version <package-version> --candidate-sha <candidate-sha> --hermes-smoke /tmp/lco-hermes-smoke/hermes-smoke.json --package-smoke /tmp/lco-package-smoke/cli-mcp-product-smoke.json --strict

The reports are public-safe candidate evidence. They do not prove publication, an active Hermes profile install, or Eva runtime safety.

Install the OpenClaw plugin from npm:

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

Smoke the OpenClaw path:

lco openclaw dogfood --profile lco-dogfood --install-source lossless-codex-orchestrator@latest --required-tool lco_doctor --required-tool lco_search_sessions --strict
lco openclaw tool-smoke --profile lco-dogfood --required-tool lco_doctor --required-tool lco_search_sessions --strict

Tool exposure can be narrowed with LCO_TOOL_PROFILE=facade|standard|all. The default is all, preserving the full catalog. facade exposes the compact operator path (lco_*) plus loo_* compatibility aliases; standard adds workflow-detail tools. Profile filtering affects tool listing and OpenClaw declarations only.

See docs/OPENCLAW_PLUGIN.md for the full OpenClaw setup path.

Privacy And Local Data

LCO reads local Codex session files and writes a local SQLite index. It is built so agents can work from source refs, cards, summaries, and bounded briefs instead of opening enormous raw transcript files by default.

For details, read docs/PRIVACY.md and docs/SAFE_SUMMARIES.md.

Community And Contributing

LCO is meant to be easy to try and straightforward 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 command-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, command path, and sanitized evidence 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: local SQLite index, field-weighted search, source refs, summary leaves, prepared cards, inboxes, session descriptions, and bounded expansion
• packages/mcp-server: stdio MCP server exposing lco_* operator tools and loo_* compatibility aliases
• packages/openclaw-plugin: OpenClaw plugin entry and manifest surface
• .codex-plugin/ and hooks/: Codex plugin manifest, Stop hook config, and wrapper for local thread title aliases
• packages/cli: lco CLI for setup, indexing, recall, smoke, eval, and release checks, with loo retained as a compatibility alias
• packages/adapters: Codex transport, audit, redaction, desktop-readiness, and adapter contracts
• skills/: packaged agent-facing OpenClaw playbook
• evals/: scenario and scorecard contracts
• docs/: setup, privacy, source authority, adapter docs, and maintainer guides

Roadmap

Stable today: local Codex indexing, field-weighted search, prepared cards, prepared inboxes, summary leaves, bounded expansion, project digests, OpenClaw/MCP tools, and the dry-run command layer.

Since 1.2.x, the 1.2 prepared-state and summary-leaves lane has remained shipped as part of the stable product line. That work added source-ref-backed ranges, deterministic summary leaves, prepared cards, prepared inbox items, watcher observations, attention queue items, and hook capture so an OpenClaw or main orchestration agent can start from compact prepared state instead of rereading huge Codex transcripts. The historical architecture handoff remains in docs/sprints/brief-lco-1.2-prepared-state-summary-leaves-2026-07-03.md.

The 1.4 identity work makes lco, lco-mcp-server, lco_*, and LCO_* the canonical command and tool names, with loo, loo-mcp-server, loo_*, and LOO_* retained as compatibility aliases for at least two minor releases. The current npm package is lossless-codex-orchestrator; the deprecated compat package lossless-openclaw-orchestrator remains maintained for existing automation.

For the full product direction, read VISION.md.

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.

Using LCO yourself — including at work — is fine and encouraged. Embedding LCO inside a product or service that you sell requires a commercial license (standard terms: 5% of the embedding product's pricing, or negotiated). Plain-language guide: docs/COMMERCIAL_LICENSING.md — or just email [email protected].