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 OpenClaw agent, MCP client, Hermes-style orchestration 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:

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, an MCP server, and an OpenClaw 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 OpenClaw as your main local agent/operator
• want a Hermes-style or custom orchestrator to manage Codex work through MCP
• 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
• OpenClaw Desktop/CLI if you want OpenClaw to call the installed lco_* tools

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:

• Current stable: 1.6.0 shipped on latest as the Control Plane release for bounded session-diff cursors, review-then-drive dry-runs with budgets and audit binding, Codex scratch-thread control verification, LCM prepared cards and peer diagnostics, and a Claude adapter validation lane that remains dry-run only.
• latest is the stable public channel.
• beta is the active prerelease train.
• next is reserved for release candidates.

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 `