Product Git

Version control for product behavior, not code.

Product Git is a project-local product-behavior layer for coding agents. Code Git records which files changed; Product Git records what the product is meant to do, what the agent says it implemented, what a human accepted or rejected, and which decisions later turns must preserve.

Each agent run can submit a Product Graph snapshot or patch. A successful sync advances Implementation Head and its Preview bindings atomically, so the local Web workbench immediately renders the newest working graph and requests its mapped product state while New, Changed, and Removed behavior is still pending PM Review. If the exact state cannot be confirmed, the real mapped page stays visible with an honest non-blocking status. Accept, Edit, Reject, Lock, and Save remain human decisions. A saved Edit or Reject becomes Product Head intent that differs from Implementation Head, so Product Git derives the Required Product Changes supplied to a later run.

What is implemented

• Separate Product Head, Implementation Head, Pending Product Changes, and Required Product Changes state.
• A generic Product Graph of modules, screens/actions/decisions/systems, flow edges, product logic, edge cases, locks, and code anchors.
• Reviewable add, update, and remove behavior changes.
• A localhost Web workbench with a real-project Preview, Product Graph, review controls, and version saving.
• A project-scoped stdio MCP server with a two-call default lifecycle and legacy v0 tool names retained for migration; v0.5 legacy submissions require component_assessment.
• Bootstrap snapshots for new projects and scoped incremental context for later turns.
• Diff-seeded incremental impact analysis with pluggable framework adapters, a reverse mapping index, bounded dependency/Graph expansion, mapping reconciliation, deterministic state presets, and at most one scoped inference request.
• Five high-level Product Intents (update_behavior, add_state_branch, add_transition, remove_product_element, and update_preview_state) compiled server-side into Graph and Preview patches.
• A transient Change DAG that orders large implementation changes without replacing the PM-facing Component User Flow Graph.
• An explicit Product Component boundary judgment on every sync, with deterministic validation and compact per-run auditing.
• Delta context and compacted run audits, so later turns do not inherit an ever-growing history payload.
• Deterministic revision, locked-logic, reported-diff, required-diff, and declared-file-scope checks.

Product Git does not independently prove that agent-declared behavior matches the code. It makes the declaration explicit, validates its structure and lifecycle, and gives the human a review surface.

Local-only architecture and privacy

Codex or another MCP client
        │ stdio
        ▼
one Product Git process
  ├─ MCP lifecycle tools
  ├─ local state engine
  └─ Web/API on 127.0.0.1
        ├─ .product-git/ files
        └─ iframe → the project's real localhost Web app

Product Git has no hosted backend, Product Git account, cloud database, or telemetry service. Its HTTP service binds to 127.0.0.1; mutation requests from other browser origins are rejected. Product state, run records, and saved versions stay under the target project's .product-git/ directory.

Important privacy details:

• Run files include the user request and product-state declarations. Review .product-git/ before committing it.
• Runtime metadata, logs, indexes, and run audits are ignored by .product-git/.gitignore; saved Product Graph state and Product Versions remain visible for teams to commit deliberately.
• Product Git does not retrieve past-session memory or user preferences. Each run receives only current project state, the exact request, focused Graph context, locks, and Required Product Changes.
• Installing from npm or GitHub uses those distribution networks. Codex and model providers have their own data-handling behavior outside Product Git.

Requirements

• Node.js 20 or newer.
• An existing Web project that can run on localhost if you want an interactive Preview.
• Codex for the automated project-scoped connection in this release. Other MCP clients can use the printed stdio configuration.

Install

Product Git is published on npm as product-git. Pin a version in project configuration so every agent run uses the same release.

From npm — recommended

npm install --save-dev [email protected]
npx product-git --help

You can also run the pinned package without adding it to the project:

npx --yes [email protected] --help

From GitHub — available now

export PRODUCT_GIT_PACKAGE='github:Luciayuanzhu/product-git'
npm install --save-dev "$PRODUCT_GIT_PACKAGE"
npx product-git --help

Keep PRODUCT_GIT_PACKAGE set when connecting Codex so the generated MCP entry continues to use the same GitHub source rather than switching to the npm release:

PRODUCT_GIT_PACKAGE='github:Luciayuanzhu/product-git' \
  npx product-git connect codex --project "$PWD"

If an execution environment disables npm Git dependencies with EALLOWGIT or EALLOWREMOTE, clone once and use the checkout directly:

gh repo clone Luciayuanzhu/product-git "$HOME/.local/share/product-git"
export PRODUCT_GIT_SOURCE="$HOME/.local/share/product-git"
npm --prefix "$PRODUCT_GIT_SOURCE" install
npx --yes "$PRODUCT_GIT_SOURCE" --help

Then initialize and connect from the target Web project:

cd /absolute/path/to/your-web-project
npx --yes "$PRODUCT_GIT_SOURCE" init --preview-mode unconnected

PRODUCT_GIT_PACKAGE="$PRODUCT_GIT_SOURCE" \
  npx --yes "$PRODUCT_GIT_SOURCE" connect codex --project "$PWD"

Direct source — works now

From an existing Product Git checkout:

export PRODUCT_GIT_SOURCE="$(cd /absolute/path/to/product-git && pwd)"
npm --prefix "$PRODUCT_GIT_SOURCE" install
npx --yes "$PRODUCT_GIT_SOURCE" --help

Then run Product Git from the target Web project. PRODUCT_GIT_PACKAGE is important: it makes the Codex MCP entry continue to use this exact source checkout.

cd /absolute/path/to/your-web-project

npx --yes "$PRODUCT_GIT_SOURCE" init \
  --preview-url http://127.0.0.1:3000

PRODUCT_GIT_PACKAGE="$PRODUCT_GIT_SOURCE" \
  npx --yes "$PRODUCT_GIT_SOURCE" connect codex --project "$PWD"

Quick start with Codex

The examples below use the pinned npm release form. GitHub and direct-source installations remain available above.

1. Start the target project's real Web app and note its localhost URL.

2. Initialize Product Git in the target project:

   npx --yes [email protected] init \
     --preview-url http://127.0.0.1:3000

3. Register Product Git in that project's Codex configuration:

   npx --yes [email protected] connect codex --project "$PWD"

   This preserves existing settings and writes one managed MCP block to .codex/config.toml. It is project-scoped and runs:

   npx --yes [email protected] mcp --project <absolute-project-path>

4. Restart or reload Codex so it reads the updated project configuration.

5. Ask Codex to change the product. Product Git cannot read the host chat directly, so the agent must pass the exact request to pg_begin_turn. That first tool call starts the local Product Git Web/API service and returns its web_url.

6. Open the workbench from the returned URL, or while that MCP runtime is alive:

   npx --yes [email protected] open --project "$PWD"

   product-git open reuses a running MCP-owned workbench or starts a standalone local workbench when needed.

Before the first valid agent snapshot, the workspace has no invented Product Graph. The first snapshot bootstraps the reviewable product state and must identify every Product Component represented by that snapshot. A Product Component is a stable user capability or journey, such as Generate Content or Manage Billing—not a React, Vue, or other code component. Pending PM Review never blocks another coding run: pg_begin_turn reports pending_review_count, while the Web workbench keeps every still-relevant item available for Accept, Edit, or Reject. Later implementation changes are folded into the cumulative Product Head → latest Implementation Head diff, so superseded proposals do not accumulate as stale history.

Every pg_sync_turn includes component_assessment: the first snapshot reports boundary: "established" with all of its Product Component IDs; later runs report "unchanged", or "changed" when a component is added, removed, merged, split, or a node moves across component boundaries. The current coding agent supplies the affected IDs and a short rationale. Product Git validates that declaration with local deterministic rules, stores it only in the completed run audit, and does not trigger another model call or inject the assessment into future turns.

Incremental impact: start from the diff, not the graph root

For an initialized project, the recommended lifecycle is pg_begin_turn → optional pg_expand_context → pg_sync_turn. The deterministic path inside sync is:

typed Git diff
  → generic + framework adapters extract certain route facts
  → file / route / component / test seed facts
  → reverse-index lookup and bounded code-dependency / Product Graph expansion
  → rename, copy, move, and delete mapping reconciliation
  → per-hunk result: mapping only | deterministic state preset | needs inference
  → zero or one scoped inference over all unresolved hunks + ranked targets
  → server compiles high-level Product Intents into Graph + Preview changes
  → conflict-aware merge with presets and legacy patches
  → transient Change DAG for dependency order
  → Implementation patch, anchors, Preview bindings, and server-grounded evidence

Expansion begins at facts from changed files and hunks. It does not traverse from every Product Graph root for every turn. Product Git may separately build or refresh its reverse mapping/import index, but impact scope remains bounded around the diff seeds. Every hunk receives one ledger disposition:

• mapping_only updates anchors/bindings without inventing a behavior change.
• deterministic_preset_patch may add one known state rule when a single mapped node and unambiguous code signal match a built-in preset.
• needs_inference returns only unresolved hunk evidence and at most 12 ranked candidate_details per hunk. The current coding agent makes one batched judgment and returns high-level Product Intents; target ambiguity is never handed to the PM.

Framework adapters are pure, model-free translators for certain route conventions. The built-ins cover Next.js, Remix, SvelteKit, and Nuxt; the generic adapter handles explicit route literals used by React Router and other routers, plus conservative fallback. A route rename requests interpretation only when the resolved URL semantics may have changed.

The Intent Compiler owns the low-level mechanics: it reads before values from the current Graph, creates deterministic IDs, adds conditioned state branches and Preview bindings, cleans removals in reverse dependency order, and rejects conflicting writes. Legacy graph_changes remain available as an escape hatch for structures the five MVP intents cannot express.

The Change DAG contains only change IDs, operations, dependencies, and completion state. It is derived from the two Graph revisions and discarded after the run; it never becomes a second product model or a PM-facing view.

The turn is complete only when pg_sync_turn returns synced. That single atomic operation validates scope, locks, evidence, Required Product Changes, and Graph quality; then it updates Implementation Head, Preview, and the review candidate and closes the run. A failed sync changes none of those heads. PM Review happens afterward in the Component User Flow Graph.

The Preview must be real

Product Git does not generate a substitute product, and a screenshot is not an interactive Preview. Start the target app separately, then give init its actual loopback URL. Non-loopback Preview URLs are rejected.

npx --yes [email protected] init \
  --preview-url http://localhost:5173

Preview orchestration is bridge-first and has no technical mode selector in the workbench:

• On the route already shown, Workbench sends APPLY_STATE and waits for the matching APPLIED_ACK; it does not reload the iframe.
• For another route, Workbench sends NAVIGATE, waits for that route's READY, sends APPLY_STATE, and waits for APPLIED_ACK.
• If no development bridge becomes ready or an acknowledgement times out, Workbench falls back to the binding's real route. Cross-route fallback navigates the iframe; same-route fallback keeps the current page and reports, without blocking review, that the exact internal state could not be confirmed.
• The legacy product-git/navigate-v0 and product-git/preview-state-v0 messages remain accepted for existing integrations.
• Without a Preview URL or binding, Product Graph, review, versioning, storage, and MCP remain usable. The UI does not claim exact Preview state.

bridge is the default when a Preview URL is configured. Explicit route mode bypasses state injection and opens only deterministic URLs; unconnected leaves Preview disabled. In default bridge mode, a missing READY or ACK automatically degrades to route behavior.

The included Creator Studio pages are repository-only test/demo fixtures. They demonstrate the Preview Bridge; they are not shipped in the npm runtime and are never used as fallback data for another project.

Add the development-only Preview Bridge to an external project

Install Product Git as a development dependency, then import its browser runtime only behind your framework's build-time development gate:

npm install --save-dev [email protected]

export async function installProductGitPreview(adapter) {
  // Vite example. Use the equivalent compile-time DEV guard in Next, Nuxt, etc.
  if (!import.meta.env.DEV || window.parent === window) return () => {};

  const { createPreviewGuestBridge } = await import("product-git/preview-runtime");
  const bridge = createPreviewGuestBridge({
    window,
    getRoute: adapter.getRoute,
    navigate: async (route) => {
      await adapter.navigate(route);
      return { route: adapter.getRoute() };
    },
    applyState: async ({ preview_binding_id, preview_state, route, freeze }) => {
      const applied = await adapter.applyPreviewState({
        preview_binding_id,
        preview_state,
        route,
        freeze
      });
      return { applied: applied !== false, route: adapter.getRoute() };
    },
    reset: async ({ route }) => {
      await adapter.resetPreview(route);
      return { route: adapter.getRoute() };
    },
    onFreezeChange: adapter.setPreviewFrozen
  });

  bridge.start();
  return () => bridge.dispose();
}

The adapter is project-specific: navigate must wait until the SPA is on the requested same-origin route; applyPreviewState must render the exact state for preview_binding_id or return false; resetPreview must clear transient preview-only state. A frozen preview should stop timers, random data, and automatic transitions until reset or user interaction releases it.

Do not use "*" as a parent origin or hard-code a session. Product Git supplies an exact parent origin and per-workbench session in the iframe URL; createPreviewGuestBridge validates origin, source, session, localhost development context, and message schemas. The runtime also accepts v0 navigation for compatibility. Keep the dynamic import out of production builds even though the runtime disables itself outside local development.

CLI reference

product-git init [--project PATH] [--preview-url URL] [--preview-mode bridge|route|unconnected]
product-git connect codex [--project PATH]
product-git connect --print-mcp [--project PATH]
product-git mcp [--project PATH]
product-git open [--project PATH] [--no-browser]
product-git doctor [--project PATH]
product-git print-mcp [--project PATH]

• init creates project identity, empty workspace state, Preview configuration, and local storage. It does not create a sample Product Graph. Preview options apply when the project is first initialized.
• connect codex adds or replaces Product Git's managed project-scoped block in .codex/config.toml and reports that a restart is required.
• connect --print-mcp and print-mcp print a standard JSON stdio configuration without editing another client's files.
• mcp starts the stdio server. Its loopback Web/API service starts lazily on the first pg_begin_turn.
• open opens the currently running project's workbench; --no-browser only returns its URL.
• doctor checks initialization, workspace validity, runtime and Preview reachability, and bridge state.

MCP tools

The recommended lifecycle uses two required tools and one optional tool:

| Tool | Current behavior | |---|---| | pg_begin_turn | Starts a run with the exact request and compact focus_refs. Returns a small component index, only the focused Graph/lock/target delta, and an informational pending_review_count. Existing Review never blocks the run. | | pg_expand_context | Optional. Adds newly discovered file, route, component, test, or entity references and returns only the newly relevant context slice. | | pg_sync_turn | Requires a per-run component_assessment, then reads the actual Git diff, extracts framework facts, finds affected Graph scope, applies deterministic updates, returns ranked targets only for unresolved semantics, compiles Product Intents, and commits Implementation Head, Preview, and the PM review candidate atomically. |

Six legacy v0 tool names and their flow—pg_declare_impact, pg_extend_impact, pg_pull_web_updates, pg_analyze_code_changes, pg_submit_product_state, and pg_finish_turn—remain registered for migration. This is not full wire compatibility: starting in v0.5, every pg_submit_product_state submission must include component_assessment. New clients should use the compact lifecycle and must not mix both paths in one run.

The MCP server returns structured product-git/mcp-v0 envelopes. It does not perform a hidden model call: adapters, indexing, target ranking, compilation, DAG ordering, and validation are local deterministic code. needs_interpretation asks the current host coding agent for at most one scoped semantic pass. Product Git cannot make human review decisions; Accept, Edit, Reject, Lock, Unlock, and Save are Web actions.

After a successful sync, the workbench shows the latest Implementation Graph and requests its Preview state. Accept aligns Product Head with the implementation when saved. Edit records the PM's revised target; Reject preserves the prior target. Saving either divergence recomputes Product Head − Implementation Head as Required Product Changes for the next run.

Local storage

product-git init creates .product-git/ in the target project:

.product-git/
  config.json                 project ID and Preview settings
  workspace.json              current heads, pending review, queue, run, Preview
  product-head.json           user-approved product-state projection
  implementation-head.json    agent-declared implementation projection
  implementation-queue.json   Required Product Changes projection
  preview-map.json            Preview bindings
  impact-index.json           ignored, rebuildable reverse mapping/import index
  versions/product-v*.json    saved Product Versions
  runs/run_*.json             active detail; completed runs become compact audit records
  runtime/                    ignored process metadata/lock/logs
  .gitignore

The three head/queue projection files appear after state transactions. JSON writes use a temporary file and atomic rename, and Web mutations require the expected workspace revision. Product Head advances only when the user chooses Save Changes. Runtime data, the impact index, and run audits are ignored by the generated .gitignore; only the newest 20 completed run audits are retained.

Product Git does not decide which non-runtime files your team should commit. Product Graph versions can be useful in Git; run files can contain request text. Choose deliberately.

Current hackathon boundaries

This repository is a functional local prototype, not a production product. In the current release:

• Localhost Web projects are supported; native apps, desktop apps, pure backend projects, and remote Preview URLs are not.
• Codex is the only automated host connection. Other MCP clients receive a configuration snippet only.
• The lifecycle depends on the host agent following the MCP server instructions. Product Git cannot force a model to call a tool before it has entered the Product Git lifecycle.
• The first Product Graph and later implementation patches are agent-declared and schema-validated. Product Git does not fully reverse-engineer an arbitrary repository or independently verify every UI behavior.
• Full two-way Preview synchronization requires a project-specific development bridge. Auth, CSP, iframe restrictions, and complex app state may leave Preview unconnected.
• Natural-language instruction placement is a simple deterministic prototype, not a general model-backed product parser.
• One project has at most one active run. There are no Product Graph branches, merges, cherry-picks, cloud sync, accounts, team permissions, or real-time collaboration.
• npm and GitHub distribute the CLI; Product Git itself remains local-only and has no hosted application backend.

See PRODUCT_GIT_PRD.md for the intended product contract.

Development

From the Product Git source checkout:

npm install
npm run check
npm test

Useful commands:

npm run dev              # local Web/API development server on port 4173
npm run demo             # repository-only Creator Studio demo for recording
npm run mcp              # stdio MCP entry point for this checkout
npm run test:mcp         # recommended + compatibility MCP smoke test
npm run generate:fixture # refresh the checked-in offline Web fixture
npm pack --dry-run       # run prepack validation and inspect package contents

npm run check performs syntax checks and fixture-parity validation. npm test runs schema, state reconciliation, storage, incremental-impact, Preview runtime, Codex-connect, and MCP lifecycle tests.

For a local recording session, run npm run demo and open the printed ?demo=creator-studio URL. This path is available only from the source repository; installed npm consumers always load their own .product-git workspace and localhost Preview.

License

MIT