Vistracta

Vistracta (visualize + abstract) turns local repositories and software ideas into a visual intent graph that Codex can analyze, verify, plan, and safely implement - without giving up local control.

Comment

Vistracta is a local-first visual specification and execution layer for AI-assisted software development. It connects an explicit local Git repository to a durable graph of Goals, Features, Components, Constraints, Acceptance Criteria, Modules, Files, Symbols, Tests, and Dependencies.

Instead of asking an agent to change code from one large prompt, a developer can see and edit the intent first. Repository analysis produces a preview. A second intelligent reconciliation compares that analysis with the current graph Job, preserves manual decisions and layout, and requires an explicit merge. Graph changes then become a read-only implementation plan. Only a separate Approve & implement action allows Codex to work in an isolated Git worktree, after which Vistracta validates the diff and controlled tests before safe write-back.

The application supports multiple repositories, multiple named graph Jobs, implementation checks, provider-assisted Job merging, encrypted local Job vaults, visual Areas, deterministic Smart Arrange, a real activity feed, and explicit Git commit/stash/push controls. Users can choose an OpenAI API provider or a signed-in Codex CLI workflow that needs no personal API key.

Inspiration

AI coding sessions often lose the reasoning behind a feature: what the user wanted, which constraints mattered, and how acceptance should be verified. That context remains fragmented across prompts, issues, and code. Vistracta was inspired by the idea that product intent should be visible, versioned, and reviewable before it becomes a diff.

What it does

  • Safely indexes local Git repositories with AST and Tree-sitter analysis.
  • Visualizes both product intent and concrete code structure.
  • Reconciles fresh repository evidence with existing graph Jobs instead of overwriting them.
  • Checks whether complete Jobs are already implemented.
  • Generates read-only Feature, batch, or multi-Job plans.
  • Implements only explicitly approved plans in an isolated worktree.
  • Streams real Codex activity without exposing hidden reasoning or secrets.
  • Keeps graph data, repository paths, and vault contents local.

How it was built

The frontend uses React, strict TypeScript, Vite, XYFlow, Zustand, TanStack Query, Tailwind CSS, and ELK for local graph layout. The backend uses Python, FastAPI, Pydantic, GitPython, Tree-sitter, the OpenAI SDK, and atomic JSON persistence. Versioned JSON contracts are shared with a repo-local Codex plugin containing six focused skills for analysis, reconciliation, checking, job merging, planning, and approved implementation.

Static indexing and semantic interpretation are separated. Python symbols come from ast; TypeScript and JavaScript use Tree-sitter; other safe text files receive a structured fallback. Provider output is schema-validated before it can affect graph state. Write runs share one bounded worktree, test, diff, and write-back path.

How Codex and GPT-5.6 were used

Codex served as the primary engineering collaborator: it inspected the repository, converted requirements into plans, implemented backend and frontend changes, built schemas and plugin skills, ran tests, diagnosed failures, and iterated on the interface from screenshots. GPT-5.6 is also part of the product itself, powering repository interpretation, reconciliation, implementation checks, semantic Job merging, planning, and approved worktree changes through explicit model and reasoning settings.

Codex accelerated the architectural decisions that matter most: separating indexing from semantic interpretation, requiring two review gates before graph merge, separating planning from approval, using a single validated worktree path for all providers, and ensuring visual organization never silently becomes code intent.

Challenges

The hardest challenge was designing an agent workflow that remained useful without becoming autonomous. Repository text, model output, graph changes, Git state, and local UI actions all needed different trust boundaries. Another challenge was preserving stable graph identity and manual intent while bringing in changing code evidence. The two-stage reconciliation and explicit conflict decisions emerged from that work.

Large graph interaction was also demanding. Areas, collapsed groups, deterministic layout, orthogonal relations, manual routes, and presentation-only state had to coexist without creating semantic diffs or accidental implementation requests.

Accomplishments

  • A complete local-first repository-to-graph-to-code loop.
  • Two interchangeable but explicit provider modes with no silent fallback.
  • A repo-local Codex plugin with six validated skills and shared schemas.
  • Encrypted multi-Job workspaces and provider-assisted implementation checks.
  • Plan-gated worktree implementation with controlled tests and atomic write-back.
  • A judge fixture and one-command launcher for reproducible local evaluation.

What was learned

Agent safety becomes clearer when product states map to explicit permissions: index, analyze, preview, reconcile, plan, approve, validate, and write back. A graph is most useful when it preserves the developer's intent but can still attach evidence from code. Live activity also matters: users need truthful phases and concrete artifacts, not invented percentages or hidden reasoning.

What's next

Next steps include Windows desktop support, richer language indexers, configurable test policies, graph review history, signed release packages, accessibility refinement, and broader evaluation of the same graph contracts across multiple providers. Remote collaboration and autonomous destructive Git actions remain deliberately outside the current scope.

Built With

  • 5.6sol
  • codex
  • ultra
  • veryhigh
Share this project:

Updates