Foldweave

Inspiration

A shared project folder rarely stays shared in the literal sense. Sofia may keep the final report under approved/, while Martin keeps the same report under ready/. Their notes may link to the same images and documents through different relative paths. Both copies can contain the same underlying project while looking completely different on disk.

That creates a practical problem. A good reorganization is hard to repeat safely. Asking an AI model to reorganize both copies independently can produce two different answers. Sending a replacement folder transfers project files. Sending a list of paths only works when everyone already has the same layout. A batch rename can also omit files, collide paths, or break the links that make the folder useful.

I built Foldweave to separate the creative decision from the mechanical proof.

What it does

Foldweave lets a person describe a connected-folder reorganization in plain English, review the complete proposed structure before execution, refine it, and create a separate verified copy only after accepting the exact proposal.

The result can include a Foldweave Change File. It contains no project payload bytes. Instead, it carries a verified structural transformation plus the hashes, sizes, supported link relationships, lineage, and proof identifiers needed to recognize a strictly equivalent project.

That is the central idea: the same project does not need to start with the same paths.

Sofia can create and verify a new structure. Martin can combine Sofia's Change File with his differently arranged equivalent copy. Foldweave matches the underlying members deterministically, shows Martin his own current folder against Sofia's shared proposal, and lets him either:

1. accept the shared proposal without any model call; or
2. use GPT-5.6, ChatGPT, or Codex to build a complete next proposal from it.

If Martin creates a derivative change, Foldweave produces a new self-contained Change File. Sofia can then apply that change to her equivalent copy. The participants exchange a verified structural pattern, not the project payload.

How it works

1. Plan

The user chooses a folder and describes the desired result. Foldweave supports four honest execution modes:

• Direct API: exact gpt-5.6 through the OpenAI Responses API with a user-supplied key.
• ChatGPT-hosted: the user's normal ChatGPT session supplies model inference through the Foldweave app and paired local companion. Foldweave makes no hidden direct API call.
• Recorded replay: a keyless, clearly labelled replay of a real GPT planning run.
• Unchanged Change File application: deterministic and model-free.

Codex is also supported through the same bounded MCP tools and deterministic engine.

2. Compile

The model may propose a complete plan or a strict revision. It cannot move files, approve its own proposal, bypass checks, create a receipt, or declare a result verified.

One Python engine performs the authoritative work:

• scan and hash every in-scope member;
• account for every file exactly once;
• preserve protected members;
• validate every destination;
• detect collisions and stale input;
• derive supported relative Markdown link rewrites;
• build one immutable review preview;
• bind acceptance to the exact preview fingerprint;
• create a separate copy;
• verify the result independently; and
• retain transaction-specific reconstruction authority.

Nothing is created while the job is merely under review.

3. Review and revise

The native macOS application, browser fallback, ChatGPT widget, Codex integration, and CLI all use the same preview contract.

The review shows:

• the current and proposed trees;
• every moved or renamed member;
• protected files and empty directories;
• supported link effects;
• complete file and change counts;
• why a path was proposed;
• whether output exists; and
• the exact proposal revision being accepted.

A user may request a bounded revision. A failed revision leaves the previous valid proposal intact. Stale tabs, duplicate acceptance, changed sources, changed destinations, and concurrent revise-versus-accept races fail closed.

4. Carry the change to a different layout

For ordinary files, Foldweave matches exact size, SHA-256, suffix, and protection status. For supported Markdown files, it commits to all bytes outside relative link destinations and refines the match using ordered incoming and outgoing link relationships. Protected members require exact path and bytes.

The matcher never guesses from the origin path, receiver path, directory order, or filename similarity. Extra, missing, changed, or irreducibly ambiguous members block.

This is why Martin can begin with a different local organization and still receive the exact reviewed structure.

5. Prove and reconstruct

Each accepted transaction produces a receiver-specific result and receipt. The verifier checks source-free proof and can also compare against the selected source. The organized-tree commitment includes files, directories, and supported rewritten links.

Reconstruction means: recreate the exact source selected when this transaction began. Martin reconstructs Martin's source, not Sofia's earlier layout.

Why the Change File matters

The Foldweave Change File is deliberately payload-free, but it is not metadata-free. It discloses project names and structure, sizes, hashes, supported link relationships, the original instruction, target names, lineage, and proof identifiers.

This contract makes several useful workflows possible:

• a consultant can send a reviewed handoff structure without redistributing client payloads;
• a research group can apply one verified organization to equivalent local copies;
• a collaborator can inspect a shared proposal against their own layout before accepting it;
• a team can iterate serially through self-contained Change Files;
• an archivist can prove that every admitted member survived the transformation; and
• any participant can recreate the source used for their own transaction.

Foldweave does not claim semantic correctness, support for independently edited copies, arbitrary file-format understanding, arbitrary reference rewriting, sender authentication, or universal reversibility. This release supports connected local project folders and relative Markdown links.

How I built it with Codex

I began with a constrained project-selection tournament. Candidate ideas were challenged against user value, Build Week fit, feasibility, differentiation, and whether a complete trustworthy transaction could be demonstrated. That process led to Foldweave's authority split: the model proposes, deterministic code compiles and proves, and the person decides.

Codex was my primary implementation and integration environment. I used it to develop and continuously integrate:

• the deterministic folder engine and matcher;
• versioned jobs, immutable previews, exact acceptance, and restart recovery;
• sparse plan revisions and parent-child lineage;
• Change Files, receipts, verification, and reconstruction;
• the native macOS shell and secure Keychain boundary;
• the focused React review tree and ChatGPT widget;
• the shared local and public MCP services;
• the Codex plugin;
• the Cloudflare gateway and paired outbound companion;
• packaging, clean-clone reproduction, browser and native visual QA; and
• adversarial regression and refusal coverage.

Codex also helped force early end-to-end transactions instead of allowing isolated subsystems to remain unintegrated.

How GPT-5.6 is used

In direct mode, Foldweave calls the exact gpt-5.6 alias through the Responses API with strict tool and response schemas, bounded eligible evidence, store=false, no fallback model, and no provider retry.

GPT-5.6 contributes the part that benefits from language understanding: turning a plain-English request and bounded folder evidence into one complete structural proposal, or turning a focused user instruction into one strict revision.

Everything after model output is deterministic. Fixed code validates the proposal, derives link rewrites, renders the review, executes only the accepted fingerprint, verifies the result, and constructs proof.

In ChatGPT-hosted and Codex-hosted modes, the host supplies inference through the same bounded planning tools. ChatGPT subscription access and API billing remain separate. Recorded replay and unchanged Change File application use no model.

What I am proud of

The Sofia → Martin → Sofia demonstration proves more than a folder rename:

• two source layouts represent one strictly equivalent connected project;
• Sofia reviews and revises a GPT-5.6 proposal;
• Martin sees his own original tree beside the shared proposal;
• Martin can accept unchanged with no GPT call;
• Martin can build a derivative proposal through a live host;
• the child Change File is complete and does not require its parent;
• Sofia can apply Martin's derivative change;
• every accepted result converges to one organized-tree commitment;
• each participant reconstructs the source selected for that transaction; and
• no source folder is modified in place.

Try it

Repository: https://github.com/ModernBlueprints/Foldweave

The README begins with a keyless replay that requires no API key, ChatGPT login, Cloudflare account, or native-app rebuild. It also documents the unsigned/ad-hoc macOS Apple-Silicon judge build, browser and CLI paths, direct GPT-5.6 mode, ChatGPT integration, and the Foldweave Codex plugin.

The native release is tested on macOS Apple Silicon. The ChatGPT integration is technically ready for review, but I do not claim that it is approved, publicly listed, or generally available.

Built With

• bagit
• blueprintjs
• cloudflare-workers
• codex
• durable-objects
• fastapi
• gpt-5.6
• macos-keychain
• mcp
• oauth-2.1
• openai-apps-sdk
• openai-responses-api
• pydantic
• pyinstaller
• pytest
• python-3.11
• pywebview
• react
• ruff
• typescript
• vite