REPL

The Omega REPL is the interactive interface — and the primary surface for sessions, snapshots, and replay. Two binaries ship: omega (the production CLI in bin/omega.mjs) and omega-repl (dist/omega-repl.mjs, also exported as omega-fast).

Starting it

bash

# From projects/omega-lisp/
pnpm omega-fast                                        # interactive
pnpm omega-fast -- --cmd "(+ 1 2)"                     # one-shot
pnpm omega-fast -- --session mywork --cmd "(define x 42)"
pnpm omega-fast -- --session mywork --cmd "x"         # → 42
pnpm omega-fast -- --file demo/lisp/ch00-instant-showcase.lisp

Sessions are stored under ~/.omega-sessions/repl-<name>.json.

Public API: `OmegaRepl`

The REPL itself is also a library:

import { OmegaRepl } from 'omega-lisp';

const repl = new OmegaRepl(/* opts */);
const result = await repl.eval('(+ 1 2)');
// result.value === { tag: 'Num', n: 3 }

Types: IReplExecutor, ReplCoreState, ReplEvalOpts, ReplEvalResult, SerializedReplState (all exported from omega-lisp/repl and re-exported from the package root).

The colon commands

REPL meta-commands (those starting with :) cover four buckets:

Bucket	Examples	What they do
Help	`:help`, `:doc <fn>`, `:apropos <pat>`, `:packages`, `:primitives`	discovery
Session	`:session save <name>`, `:session load <name>`, `:session goto <n>`	persist, resume, time-travel
Snapshot	`:save <name>`, `:restore <name>`	checkpoint and restore evaluator state
Debugger	`:debug`, `:step`, `:break`, `:state`, `:back`, `:trace`	step through, set breakpoints

The full set is enumerated in the help output and documented in CLI / REPL reference.

Agentic mode

:ask "question" switches the REPL into agentic mode: the LLM is given the REPL as a tool. It can write Lisp, evaluate it, see the result, and iterate up to 20 turns. This is the co-recursive tower in user-facing form — the model calls omega_eval, the result comes back, the model decides what to do next.

The reentry path is gated by tools omega_eval, omega_apply, omega_observe, omega_return (see src/core/oracle/plugins/openai.ts for the reference loop).

Sessions are deterministic replay logs

Every command is appended to the session log with: timestamp, source text, evaluation result, any LLM receipts. Replaying a session is deterministic — the same inputs produce the same outputs as long as you use the same provider/model. This is why the language goal of "auditable reasoning" is more than a slogan: the trace IS the audit.

Snapshots vs sessions

	Session	Snapshot
What's saved	the full event log	a single point-in-time `State`
File	`~/.omega-sessions/repl-<name>.json`	`~/.omega-sessions/snapshot-<name>.json`
Restoring	replay events to reach a given index	hydrate the saved State directly
Use case	"pick up where I left off"	"checkpoint before risky exploration"

REPL ​

Starting it ​

Public API: OmegaRepl ​

The colon commands ​

Agentic mode ​

Sessions are deterministic replay logs ​

Snapshots vs sessions ​

See also ​