OpenLoop

OpenLoop keeps agent-assisted engineering work recoverable across sessions. It is a file-backed CLI state kernel: external agents and scripts use it to store signals, loop items, lifecycle state, evidence, artifacts, agenda views, and handoff context in deterministic project state.

OpenLoop does not run agents, call models, generate prompts, or decide whether a fix is correct. It gives your agents durable state they can inspect, validate, and resume from when chat history is gone.

The npm package is @lijingda/openloop; the published binary is openloop.

Why OpenLoop?

Use OpenLoop when AI-assisted work needs memory outside a single conversation:

• A signal, bug, drift risk, or quality concern should survive context resets.
• Multiple agents or sessions need to hand off the same work safely.
• You need an auditable path from input signal to item, stage result, evidence, verification, and closure.
• Some loop items explicitly depend on, supersede, or contextualize other loop items, and that graph should survive handoff.
• Automation needs JSON output, retry-safe mutations, and deterministic recovery guidance instead of fuzzy chat memory.

See It In Action

openloop init --backend workspace
openloop signal add --file signal.json --idempotency-key ingest-001 --json
openloop item create --from-signal signal-20260615-reply-drift \
  --file item.json --idempotency-key create-001 --json
openloop item transition loop-20260615-reply-drift \
  --to diagnosing --reason "ready to understand the failure mode" --json
openloop stage prepare loop-20260615-reply-drift \
  --stage diagnosing --out context-pack.md --json
openloop stage result submit loop-20260615-reply-drift \
  --data-json '{"stage":"diagnosing","outcome":"completed","summary":"Diagnosed enough to choose the next step.","recommendations":[{"kind":"transition","to":"fixing_or_codifying"}]}' \
  --idempotency-key diagnosis-001 --json
openloop agenda list --json

The complete copy-paste walkthrough, including the input JSON files, is in docs/getting-started.md.

Install

Install globally when you want openloop on your PATH:

npm install -g @lijingda/openloop@latest
openloop --help

Run once without a global install:

npm exec --package @lijingda/openloop@latest -- openloop --help

For a project-pinned install, add @lijingda/openloop to the project and invoke openloop from npm scripts.

Common Workflows

| Need | Start here | | ------------------------------------------- | -------------------------------------------------------------------------------------- | | Try OpenLoop for the first time | docs/getting-started.md | | Understand the nouns | docs/concepts.md | | Resume work after a context reset | docs/workflows/resume-agent-work.md | | Turn an incoming signal into tracked work | docs/workflows/process-new-signal.md | | Hand off an item between agents or sessions | docs/workflows/handoff-between-agents.md | | Validate state and recover from bad input | docs/workflows/validate-and-recover.md | | Look up every command | docs/reference/commands.md | | Prepare input JSON files | docs/reference/schemas.md | | Choose workspace vs user state | docs/reference/backends.md |

What OpenLoop Stores

• Signals: raw or normalized inputs that may deserve tracking.
• Loop items: long-lived concerns that move through a lifecycle.
• Item relations: explicit loop-to-loop edges such as depends_on, part_of, relates_to, and supersedes.
• Evidence and artifacts: durable support records attached to an item.
• Stage results: structured output from an external agent or harness.
• Agenda entries: deterministic next-work views derived from stored state.
• Context packs: generated handoff documents for zero-background recovery.

Everything is file-backed JSON/JSONL, protected by atomic writes and locking. --json output is a stable agent API, not an afterthought.

What OpenLoop Is Not

OpenLoop is not an intelligent agent, task manager, hosted service, model runtime, prompt library, or execution planner. It does not make semantic truth decisions such as whether a root cause is correct or a loop is truly solved. Those decisions belong to external agents and humans.

Item relations do not create tasks, subtasks, owners, deadlines, priorities, or automatic lifecycle rollups. They are caller-declared structural edges that OpenLoop stores, validates, and renders for recovery.

The current implementation supports workspace and user backends. git, custom backends, sync commands, and explicit import --replace restore mode are later scope.

Documentation

User-facing documentation starts at docs/index.md.

The existing product and implementation design notes remain part of the repository because they are useful for development:

• docs/product/index.md is the product design map.
• docs/product/principles.md defines product boundaries and red lines.
• docs/technical/implementation-plan.md describes the implementation plan.

Development From Source

npm install
npm run build
npm run typecheck
npm test
npm run lint
npm pack --dry-run