ParallaX

Turn AI conversations into an evidence-backed, git-versioned, repo-local "project brain".

Comment

Project name

ParallaX

Tagline

Turn AI conversations into an evidence-backed, repo-local project brain.

Category

Developer Tools

Short description

ParallaX gives coding assistants one approved source of project context. It imports chat exports, extracts decisions, tasks, questions, glossary terms, and specification changes, verifies every proposal against exact source evidence, and asks a human to approve what becomes project memory.

Approved records live in a plain-file .parallax store that can be reviewed, edited, and versioned with the repository. ParallaX can then compile concise context into AGENTS.md, CLAUDE.md, and Cursor rules so another coding tool can continue from the same evidence-backed state.

Inspiration

Important engineering context is often trapped inside individual AI conversations. One session contains an architectural decision, another captures a privacy constraint, and a third leaves behind an unresolved task. Moving to a new assistant usually means pasting an oversized transcript, trusting a summary, or reconstructing decisions from memory.

I wanted a workflow where models could propose useful project knowledge without being allowed to declare that knowledge true. The repository should remain the durable source of truth, and every accepted record should be traceable to the conversation that supported it.

What it does

ParallaX implements a deliberate loop:

chat export -> validated proposal -> explicit apply -> .parallax -> compile

It accepts generic Markdown transcripts and extracted ChatGPT conversation exports. A configured distiller proposes five record types: decisions, tasks, questions, glossary terms, and specification changes. ParallaX validates the structured response locally, verifies exact contiguous evidence against the normalized transcript, and presents the result without writing anything.

The CLI supports full noninteractive apply for scripts and selectable TTY review for people. The local browser UI exposes the same shared application services, keeps proposals in server memory, and requires a final selected-item confirmation. Rejected, empty, stale, or replayed proposals write nothing.

Applied records are readable Markdown and YAML rather than database rows. The store can be browsed through the CLI, a read-only MCP server, the local UI, or a self-contained static snapshot. Sensitive imports can retain only source metadata, and compiled context is written only inside protected managed regions of supported agent instruction files.

How I built it

ParallaX is a strict TypeScript and ESM application targeting Node.js 24. The CLI, local UI, MCP server, and static explorer share one application-service layer for parsing, provider resolution, verification, snapshot reads, selected apply, compilation, and the plain-file store writer.

The OpenAI provider uses the Responses API with strict structured output and can select GPT-5.6 for live distillation. Gemini, Claude, and OpenAI-compatible adapters use the same portable proposal contract, followed by the same local Zod validation and evidence verification. The recorded walkthrough uses a deterministic mock distiller so it performs zero network requests and requires no API key.

The local UI is a dependency-free Node loopback service bound only to 127.0.0.1. It keeps API keys server-side, uses a per-launch capability token for authenticated requests, requires same-origin mutations, applies restrictive security headers, and renders imported content with DOM text APIs. The public demo is generated deterministically from tracked mock fixtures and deployed by GitHub Pages.

How I used Codex and GPT-5.6

I built ParallaX through a primary Plan-Execute thread with Codex and GPT-5.6. Initially, I had established the codebase structure, mapping repository elements such as the the .parallax store, TypeScript source code (delegating modules for application, contract, ui, web, etc.), before guiding GPT-5.6 with my established structure. Before each milestone, Codex inspected the repository and helped turn a feature idea into a reviewable implementation plan. After implementation, I used Codex to refactor the TypeScript code, add regression coverage, diagnose test and GitHub Actions failures, review generated artifacts, and checked each final working-tree diff before I committed it.

Several product decisions came directly from that collaboration: model output remains an untrusted proposal, review and approval happen in one distillation session, the local UI reuses application services instead of shelling out to the CLI, mutation access is protected by a fragment-only launch capability, and the public demo is generated from deterministic fixtures.

GPT-5.6 therefore contributed both as the reasoning model behind the primary Codex build workflow and as a supported OpenAI distillation model in the finished project. The deterministic submission demo intentionally avoids a paid call while exercising the same parsing, verification, selection, and store pipeline.

Challenges I ran into

The hardest problem was making extracted evidence trustworthy. A proposal is accepted only when its quote is exact, contiguous, and uniquely matched to the claimed transcript turn. The system rejects invalid or ambiguous evidence rather than attempting fuzzy repair.

The second challenge was keeping behavior identical across the CLI and browser without creating a second data path. Extracting shared services made provider resolution, verification, selected apply, compiler safety, and store behavior consistent across every surface.

The third challenge was balancing a convenient local UI with the privacy model of a repo-local developer tool. The final design binds only to loopback, keeps credentials out of the browser, authenticates every API request, prevents cross-origin mutations, and never persists pending proposals.

Accomplishments that I am proud of

  • A complete import, verify, review, apply, and compile loop with exact evidence.
  • One human-editable and git-diffable source of approved project truth.
  • Shared behavior across CLI, local UI, MCP reads, and static snapshots.
  • Deterministic mock mode with no key requirement or network access.
  • Full proposal replay protection and no-write failure paths.
  • A reproducible synthetic store and public explorer guarded by drift checks.
  • Offline CI covering formatting, type checking, tests, build, and demo determinism.

What I learned

Reliable AI handoff needs a stronger boundary than a generated summary. The model is best used to propose structure, while deterministic application code owns identifiers, timestamps, evidence validation, persistence, and compiler safety. That separation made the system easier to test and easier to trust.

I also learned that a local browser interface can remain lightweight and private when it reuses domain services and treats the browser as an authenticated view, not a second application database. Originally, I'd planned to accomodate the CLI-based implementation with a local application; realistically, the web-based interface proved more than enough for the requirements of ParallaX, simultaneously serving as a simple medium for demoing, without having to factor in additional development time and support across host platforms within the limited hackathon timeframe.

What's next for ParallaX

The next product milestone is lifecycle editing for decisions, tasks, and questions while preserving the existing evidence and store invariants. Persisted proposal drafts, cloud synchronization, and desktop packaging remain deferred until the local workflow proves that they solve a real need without weakening the repository-local privacy boundary. For now, lifecycle features are targeted within the scope of a potential V2 release.

Built With

Share this project:

Updates