Open Lagrange

The stable point between cognition and execution.

Open Lagrange is a TypeScript control plane for reconciled work. Models can propose typed artifacts, but the platform owns durable state, policy, capability boundaries, approvals, retries, resume, verification, telemetry, and outputs.

It is built for workflows where “the model said so” is not enough.

Core Model

Open Lagrange is organized around Durable Runs:

Planfiles describe reviewable work as typed, validated plans.
Durable Runs execute Planfiles and are the canonical visible execution surface.
RunEvents record execution progress, approvals, artifacts, policy decisions, model calls, verification, repair, retry, resume, and completion.
RunSnapshots are UI/query projections for CLI, TUI, and web.
Capability Packs expose bounded operations through PackRegistry and CapabilityStepRunner.
Artifacts are durable outputs, evidence, telemetry, and final exports.
Profiles and Providers configure local or remote runtime access, model providers, search providers, secrets, and runtime services.

Hatchet owns durable workflow/task execution when available. Local projection state exists for query and UI continuity; it is not the execution authority.

What Works Now

Compose, validate, reconcile, and apply Planfiles.
Create Durable Runs from Planfiles and inspect them through CLI, TUI, or web.
See active nodes, timelines, approvals, artifacts, model calls, policy decisions, errors, next actions, and final outputs.
Resume yielded runs and retry failed nodes with an explicit replay mode.
Apply repository Planfiles in isolated git worktrees, verify results, review output, and export final patches.
Run research workflows through bounded search/fetch/extract/brief capabilities with artifact lineage.
Validate, install, inspect, and health-check reviewed local Capability Packs.
Store provider secrets through OS keychain references or environment-backed profiles.
Operate local or remote runtime profiles through the CLI, TUI, Next.js API, and web Run Console.

Quickstart

git clone git@github.com:supernovae/open-lagrange.git
cd open-lagrange
npm install
npm run build

The snippets below use the installed or linked open-lagrange binary. From a source checkout, use npm run cli -- <command> as the local equivalent.

Bootstrap a local runtime profile, compose stack, Hatchet token, API, worker, and web UI:

open-lagrange bootstrap --runtime podman

Docker works too:

open-lagrange bootstrap --runtime docker

Check runtime health:

open-lagrange status
open-lagrange doctor

Configure the local Control Plane bearer token before using the TUI or API:

TOKEN="$(openssl rand -hex 32)"
printf '%s' "$TOKEN" | open-lagrange auth login --from-stdin
open-lagrange restart --runtime podman

Configure provider credentials without writing secrets to project config:

open-lagrange secrets set openai
open-lagrange secrets status

Run A Planfile

Run the included URL summary Planfile:

open-lagrange plan run examples/planfiles/research-url-summary.plan.md

Author a new Planfile and write it to .open-lagrange/plans/:

open-lagrange plan compose "Create a release readiness checklist for this repository" --write

Validate and inspect the Planfile:

open-lagrange plan check .open-lagrange/plans/<plan_id>.plan.md
open-lagrange plan explain .open-lagrange/plans/<plan_id>.plan.md

Save it for reuse:

open-lagrange plan save .open-lagrange/plans/<plan_id>.plan.md \
  --library workspace \
  --path research/release-readiness.plan.md
open-lagrange plan library list
open-lagrange plan library plans workspace

Create a Durable Run from the authored Planfile:

open-lagrange plan run .open-lagrange/plans/<plan_id>.plan.md

The command returns a run_id. Use that ID as the primary handle for status, events, artifacts, approvals, model calls, retries, resume, and export.

open-lagrange run status <run_id>
open-lagrange run explain <run_id>
open-lagrange run events <run_id>
open-lagrange run artifacts <run_id>

If a run yields, the snapshot includes required next actions:

open-lagrange run resume <run_id>
open-lagrange run retry <run_id> <node_id> --mode reuse-artifacts
open-lagrange run retry <run_id> <node_id> --mode refresh-artifacts
open-lagrange run retry <run_id> <node_id> --mode force-new-idempotency-key
open-lagrange run cancel <run_id>

Retry always requires an explicit replay mode. Side-effecting work remains behind policy and approval gates.

Web Run Console

Start the web runtime with bootstrap, then open the Run Console:

http://localhost:3000/runs/<run_id>

The web console shows:

run status and active node
step list
timeline
artifacts and artifact viewer
approvals
model calls
logs and structured errors
next actions
Planfile projection

Plan Builder creates Durable Runs and navigates directly to /runs/<run_id>. The web UI renders RunSnapshot and RunEvent projections; it does not execute plan nodes directly.

Browse saved Planfiles in the web Plan Library:

http://localhost:3000/plans

From there, Check, Run Now, Schedule, Save, and open the Run Console for the new run.

Terminal Console

Open the terminal workbench:

open-lagrange tui

The TUI can open the same Durable Run state as the web console. It shows active steps, timeline, artifacts, approvals, model calls, logs, and next actions.

Useful keys in Run Console mode:

a approvals
f artifacts
m model calls
l logs
p plan
r resume or retry
e explain
q back

Repository Runs

Repository work compiles to a Planfile and executes as a Durable Run. Apply mode uses an isolated git worktree, records evidence, generates a PatchPlan, applies approved changes, verifies output, records model-call telemetry, and exports a reviewable patch artifact.

open-lagrange repo run \
  --repo . \
  --goal "Add JSON output to the status command" \
  --apply \
  --planning-mode model

Inspect the resulting run:

open-lagrange repo status <plan_id_or_run_id>
open-lagrange repo explain <plan_id_or_run_id>
open-lagrange repo evidence <plan_id_or_run_id>
open-lagrange repo diff <plan_id_or_run_id>
open-lagrange repo verify <plan_id_or_run_id>
open-lagrange run status <run_id>
open-lagrange run watch <run_id>

Export the final patch artifact:

open-lagrange repo worktree <plan_id_or_run_id>
open-lagrange repo patch <plan_id_or_run_id> --output final.patch
git apply final.patch
open-lagrange repo cleanup <plan_id_or_run_id>

Repository runs show phases such as planning, evidence collection, PatchPlan generation, worktree application, verification, repair, review, and final patch export.

The web Repository Workbench is available at:

http://localhost:3000/runs/<run_id>/repository

It shows the understood goal, isolated worktree, inspected files, evidence, PatchPlans, diffs, verification output, repair attempts, scope expansion requests, model-call telemetry, review notes, and final patch export.

Research Runs

Research work also runs through Planfiles, Capability Packs, policy gates, and artifact lineage.

open-lagrange research plan "open source container security" --provider local-searxng --write
open-lagrange research brief "open source container security" --provider local-searxng
open-lagrange run status <run_id>
open-lagrange research explain <run_id>
open-lagrange research sources <run_id>
open-lagrange research export <brief_artifact_id> --format markdown --output brief.md

Research runs show phases such as search, source selection, source fetch, content extraction, brief creation, citations, and Markdown export.

The web Research Workbench is available at:

http://localhost:3000/research

It composes a research Planfile from a natural language topic, runs Plan Check, creates a Durable Run, and opens a research-specific Run Console at /research/runs/<run_id>. That view shows live status, source counts, selected/rejected sources, citations, the Markdown brief, exports, and next actions. The generic Run Console remains available at /runs/<run_id>.

Save or schedule reusable research flows:

open-lagrange plan save .open-lagrange/plans/research/<plan>.plan.md \
  --library workspace \
  --path research/container-security.plan.md
open-lagrange research schedule "open source container security" \
  --provider local-searxng \
  --daily \
  --at 08:00

Output Pack

Runs can produce many artifacts. The trusted local Output Pack turns selected artifact graphs into useful final deliverables while preserving lineage and redaction boundaries.

open-lagrange output select --run <run_id> --preset final_outputs
open-lagrange output digest --run <run_id> --style developer
open-lagrange output packet --run <run_id> --type research
open-lagrange output render-html <brief_artifact_id>
open-lagrange output render-pdf <brief_artifact_id>
open-lagrange output export \
  --run <run_id> \
  --preset research_packet \
  --format directory \
  --output ./brief

PDF export is optional and capability-gated. If a sandboxed PDF renderer is not configured, the command returns an unsupported result with Markdown, HTML, and ZIP alternatives instead of failing the run.

The web Run Console includes an Output tab for recommended final outputs, packets, digests, HTML/PDF rendering, and export results. The TUI exposes the same flow through the Output pane and delegates export work to the Output Pack.

Capability Packs

Capability Packs are the bounded execution surface. Packs declare capabilities, schemas, risk, approval requirements, and runtime behavior.

Inspect installed packs:

open-lagrange pack list
open-lagrange pack inspect open-lagrange.repository
open-lagrange pack health open-lagrange.repository

Validate and install a reviewed local pack directory:

open-lagrange pack validate ./path/to/local-pack
open-lagrange pack install ./path/to/local-pack
open-lagrange restart
open-lagrange pack health <pack_id>

Installed workspace-local packs live under the active runtime profile unless --workspace-local is specified.

Architecture

The execution boundary is deliberate:

Plan Builder creates or reconciles Planfiles.
PlanRunner creates Durable Runs and emits RunEvents.
CapabilityStepRunner executes PackRegistry capabilities behind policy gates.
Approvals are explicit state transitions.
Model calls produce telemetry artifacts.
Verification and repair emit durable events.
Hatchet owns workflow/task durability where available.
RunEvent and RunSnapshot are projections for query, CLI, TUI, and web.

The control plane owns validation, policy, approvals, retries, resume, artifacts, telemetry, and observability. Models produce typed artifacts; they do not own runtime state.

Packages

packages/core: Planfiles, reconciliation, runs, policy, approvals, artifacts, packs, repository flows, research flows, and state stores.
packages/capability-sdk: interfaces and primitives for bounded Capability Packs.
packages/runtime-manager: profiles, local runtime supervision, doctor, and logs.
packages/platform-client: fetch client for the Control Plane API.
apps/cli: native command line entrypoint.
apps/tui: Ink terminal Run Console and workbench.
apps/web: Next.js Control Plane API and web Run Console.

Core Docs

Operator Notes

Durable Run is the visible execution surface. Prefer run status, run explain, run events, and run artifacts for active work instead of domain-specific status shortcuts. Domain commands are convenience entrypoints that should return or lead to a run_id.

The local state under .open-lagrange/ is projection and artifact state. Do not treat it as workflow authority when Hatchet-backed runtime is available.

Development

npm run typecheck
npm test
npm run build

Image: NASA illustration of JWST near L2, public domain via Wikimedia Commons.

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.github/workflows		.github/workflows
apps		apps
containers		containers
docs		docs
examples		examples
packages		packages
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
compose.yaml		compose.yaml
open-cot-alignment.md		open-cot-alignment.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Open Lagrange

The stable point between cognition and execution.

Core Model

What Works Now

Quickstart

Run A Planfile

Web Run Console

Terminal Console

Repository Runs

Research Runs

Output Pack

Capability Packs

Architecture

Packages

Core Docs

Operator Notes

Development

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Open Lagrange

The stable point between cognition and execution.

Core Model

What Works Now

Quickstart

Run A Planfile

Web Run Console

Terminal Console

Repository Runs

Research Runs

Output Pack

Capability Packs

Architecture

Packages

Core Docs

Operator Notes

Development

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages