Parallax.
A secure, extensible agent-runtime CLI for terminal workflows, with deterministic permissions, human approvals, file tools, shell execution, and durable sessions. Built at Singularity and published under MIT as @singularitycolabs/parallax. The model proposes actions; deterministic code validates, authorizes, and executes them. Currently v0.1 beta — a working single-agent loop — with a macOS desktop app and an iOS companion app in progress.
TypeScript ESM package on Node 22.18+, using the built-in node:sqlite for session persistence, Zod for tool input validation, Vitest for tests, and ESLint import-boundary rules to keep the runtime, tools, policy, and provider layers separated. Model providers are swap-in ModelProvider implementations: a scripted fake provider for demos and tests, and an OpenAI-compatible provider that works against NVIDIA NIM or any endpoint you repoint the base URL at.
Deterministic turn loop
An event-driven runtime with a strict cycle — model, validate, policy, approval, execute, persist, model — so every side effect passes the same checks in the same order.
Typed tool registry
Tool inputs are validated with Zod before anything runs, so a malformed or hallucinated tool call is rejected at the boundary instead of reaching the filesystem or shell.
Workspace-scoped file tools
read_file, list_directory, search_files, write_file, and edit_file are scoped to the workspace, deny symlink escapes, and stale-check files before writing over them.
Guarded shell execution
The shell tool runs with a timeout, output caps, cancellation support, and process-group cleanup so a runaway command cannot outlive or wedge the turn that started it.
ALLOW / ASK / DENY policy
Permissions are resolved by deterministic code rather than model judgment, with read-only and workspace modes, and diff previews shown before any edit is approved.
Durable sessions
Sessions persist to SQLite at ~/.parallax/sessions.sqlite, so work can be listed and resumed later instead of dying with the terminal that started it.
CLI surface
run executes a one-shot goal, chat opens an interactive REPL, demo plays scripted scenarios, and sessions and resume manage prior work.
Desktop and mobile apps
A macOS desktop app and an iOS companion app are in progress, targeting approval prompts and session review away from the terminal.
Problem
Agent CLIs are trusted with real filesystems and real shells, but many of them let the model decide what is safe to run. When authorization lives in the prompt, a single bad tool call can overwrite files or execute a destructive command, and there is usually no durable record of what happened or why it was allowed.
Solution
Parallax moves every security decision out of the model and into deterministic code. The model may only propose a tool call; a typed registry validates it, a policy engine resolves it to ALLOW, ASK, or DENY, a human approves side effects with a diff preview, and only then does an executor run it. Each step is persisted, so a session is an auditable record rather than a transcript.
Runtime and Policy
- Event-driven turn loop enforcing model, validate, policy, approval, execute, persist ordering on every iteration.
- Deterministic ALLOW/ASK/DENY policy engine with read-only and workspace modes, evaluated in code rather than inferred by the model.
- Human approval gate for every side effect, rendering diff previews before an edit is written.
Tools and Execution
- Zod-validated tool registry where invalid calls are rejected before execution.
- Filesystem tools with workspace scoping, symlink-escape denial, and stale-check protection against clobbering concurrent edits.
- Shell executor with timeouts, output caps, cancellation, and process-group cleanup.
Persistence and Providers
- SQLite session store using Node's built-in node:sqlite, supporting session listing and resume.
- Swap-in ModelProvider interface with a scripted fake provider for tests and an OpenAI-compatible provider for NVIDIA NIM or any compatible endpoint.
- ModelProvider, Executor, ToolRegistry, and SessionStore interfaces designed as extension points for compaction, TUI, MCP, subagents, and sandboxed executors.
- 01Designed the runtime around a strict turn loop so validation, authorization, approval, execution, and persistence always happen in the same order.
- 02Built the typed tool registry with Zod schemas, making invalid tool calls unrunnable rather than merely discouraged.
- 03Implemented workspace-scoped filesystem tools with symlink-escape denial and stale-check writes.
- 04Wrote the shell executor with timeout, output cap, cancellation, and process-group cleanup semantics.
- 05Implemented SQLite-backed session persistence and resume on Node's built-in node:sqlite driver.
- 06Published the package to npm as @singularitycolabs/parallax under MIT, with CI, contribution guide, code of conduct, and security policy.
- Authorization is deterministic code, never model judgment — the model can propose an action but cannot grant itself permission.
- Tool inputs are schema-validated at the boundary, so invalid calls never reach the filesystem or shell.
- File tools refuse symlink escapes out of the workspace and stale-check before overwriting.
- Shell commands are bounded by timeouts and output caps, with process-group cleanup to avoid orphaned processes.
- Every side effect requires explicit human approval, with a diff preview for edits.
- Architectural import boundaries are enforced by ESLint so the policy layer cannot be bypassed by a careless import.
- Why authorization belongs in deterministic code rather than in the model's prompt.
- How a strict turn loop makes an agent's side effects auditable instead of emergent.
- Why Zod validation at the tool boundary is a security control, not just ergonomics.
- How workspace scoping and symlink-escape denial contain filesystem access.
- Why durable SQLite sessions matter more than longer context windows for resumable work.
- How a ModelProvider seam keeps the runtime independent of any single model vendor.