---

PinFlow verbindet dein laufendes Frontend mit deinem Coding Agenten.

Du klickst im Browser auf ein Element, beschreibst die gewünschte Änderung und PinFlow legt daraus eine präzise Aufgabe an: mit Source-Datei, Zeile, Komponente, Props, State, DOM-Kontext und deiner Anweisung. Codex, Claude oder jeder MCP-kompatible Agent kann den Kontext anschließend direkt verwenden, statt im Code zu raten.

PinFlow ist bewusst ein Developer-Tool für die lokale Arbeit: sichtbar im Browser, nachvollziehbar im Repository, anschlussfähig für Agenten. Doom-Script / Domscribe bildet dafür die starke technische Grundlage, auf der PinFlow als fokussierter, produktisierter Agent-Workflow weiterbaut.

Schnellstart

PinFlow ist als npm-Paket pinflow veroeffentlicht. Voraussetzung: Node.js 20 oder neuer.

Direkt aus npm starten:

npx pinflow init

Oder dauerhaft installieren und danach starten:

npm install -g pinflow
pinflow init

Der Wizard läuft standardmäßig als Smart Setup:

1. Agents verbinden - einen oder mehrere MCP-Clients auswählen, z. B. Codex und Claude.
2. Frontend-App wählen - PinFlow erkennt App-Kandidaten und zeigt, ob sie bereits vollständig, teilweise oder noch nicht eingerichtet sind.
3. Framework und Package Manager bestätigen - erkannte Werte werden mit Grund angezeigt; bei Unsicherheit kannst du manuell wählen.
4. Setup-Plan prüfen - PinFlow fasst App, Package, Package Manager und Config-Snippet vor der Installation zusammen.

Danach startest du deinen Dev-Server und öffnest die App im Browser. Das PinFlow-Overlay ist dann bereit für Markierungen, Aufgaben und Live-Kontext. Die Agent-Auswahl ist nicht exklusiv: Du kannst mehrere Agents direkt im selben Init-Lauf auswählen oder später mit pinflow init --agent <name> ergänzen. PinFlow richtet pro Init-Lauf genau eine Frontend-App ein. Wenn mehrere Apps im Repo liegen, wählst du eine aus; für weitere Apps startest du pinflow init danach erneut. Für Sonderfälle gibt es pinflow init --manual, für sichere Defaults ohne Nachfragen pinflow init --yes.

Kurz gesagt: npx pinflow init ist der No-Install-Weg über npm, npm install -g pinflow ist der installierte Weg.

Wie PinFlow lokal läuft

PinFlow ist kein separates Cloud-Dashboard und keine VS-Code-only Extension. Es läuft in deinem normalen lokalen Entwicklungs-Setup: dein Repo liegt in der IDE, dein Frontend läuft auf localhost, PinFlow hängt sich über Framework- und Bundler-Integration in die App ein und dein Coding Agent verbindet sich über MCP mit dem lokalen Relay.

Der wichtige Punkt: Der Browser liefert den sichtbaren UI-Kontext, das Repo liefert Source-Dateien und lokale Aufgaben, und der Agent fragt beides über PinFlow ab. Dadurch bleibt der Workflow nah an deiner echten App, ohne dass du Screenshots, DOM-Details oder Datei-Vermutungen manuell in den Chat tragen musst.

Der Dev-Server darf ganz normal manuell laufen. Er muss nicht von einem Agenten gestartet werden. Wichtig ist nur, dass deine App mit der PinFlow-Integration auf localhost läuft, das Overlay im Browser verbunden ist und der Agent den PinFlow-MCP-Server erreichen kann. Wenn ein Agent den Dev-Server startet, ist das nur Komfort, keine Voraussetzung.

Was PinFlow löst

• UI-Wünsche werden konkrete Code-Aufgaben. Nicht "irgendwo ist ein Button falsch", sondern PricingCard.tsx:118 plus Laufzeitkontext.
• Agenten sehen den Browser-Kontext. Mit pinflow.query.bySource kann ein Agent prüfen, was eine Source-Zeile gerade live rendert.
• Der Arbeitsstand bleibt lokal. Annotationen liegen in .pinflow/annotations/, Statuswechsel laufen über Relay, REST, WebSocket und MCP.
• Production bleibt sauber. Die Instrumentierung ist development-only und wird aus Production Builds entfernt.

PinFlow ist dabei bewusst nicht als weitere Browser-Preview positioniert. Claude, Codex und andere Tools können deine App bereits sehen und bedienen. PinFlow ergänzt diese Agenten um die fehlende Tiefenschicht: source-exakte Zuordnung, Runtime-Kontext, lokale Queue und MCP-Werkzeuge für echte Frontend-Änderungen.

Der tägliche Loop

Der Kern ist kein riesiger Prozess, sondern ein kurzer Kreislauf: im Browser sehen, Kontext sichern, Agenten arbeiten lassen, Ergebnis wieder im Browser prüfen.

Zwei Arbeitsrichtungen

UI -> Code

Du markierst im laufenden UI ein Element oder einen Bereich. PinFlow sammelt Source-Position, Komponente, DOM, Props, State und deine Anweisung. Daraus wird eine Aufgabe, die ein Agent claimen, bearbeiten und beantworten kann.

Code -> UI

Der Agent kann auch andersherum arbeiten: Er fragt zu einer Datei und Zeile den Live-Zustand im Browser ab, bevor er editiert.

Tip

Agenten nutzen Runtime-Kontext nicht automatisch. Formuliere es ausdrücklich: "Ändere den CTA. Nutze vorher pinflow.query.bySource, um den Live-Kontext im Browser zu prüfen." Die Zielseite sollte im Browser geöffnet bleiben.

Features

• Stabile Build-Time IDs - deterministische data-ds Attribute per AST, stabil über HMR und Fast Refresh hinweg
• Runtime Capture - Props, State, Komponenten-Metadaten und DOM-Snapshots über React Fiber Walking und Vue VNode Inspection; Next.js 16/Turbopack ist für Element-, Source- und Props-Kontext verifiziert, Hook-State bleibt dort aktuell best-effort
• Framework Support - React 18-19, Vue 3, Next.js 15-16, Nuxt 3+ und ein Adapter-Interface
• Bundler Support - Vite 5-7, Webpack 5 und Turbopack
• Agent Workflow - Queue, Claim, Process, Respond, Retry, Undo und Failure-Status für Overlay und MCP
• PII Redaction - E-Mails, Tokens und sensible Muster werden vor dem Verlassen des Browsers bereinigt
• Live Feedback - WebSocket-Events streamen Antworten und Statuswechsel ins Overlay

Workflow und Einstellungen

Bereich	Bedeutung
Picker-Modus	Einzelnes Element, Region oder Multi-Select markieren
Dispatch	Direkt an Codex/Claude senden oder erst nur sammeln
Queue	Aufgaben von queued über claimed bis processed verfolgen
Undo	Lokale Auswahl zurücknehmen oder Follow-up-Aufgabe erzeugen
Session	Agent, Dispatch-Verhalten und Defaults sichtbar einstellen

Wenn Relay oder MCP nicht laufen, soll PinFlow das klar zeigen: Kontext kann weiter gesammelt werden, Agent Processing braucht aber die lokale Verbindung.

Architektur

1. Inject - der Bundler injiziert stabile data-ds IDs und schreibt das Manifest nach .pinflow/manifest.jsonl.
2. Capture - Runtime Adapter sammeln DOM, Props, State und Komponenteninfos aus der laufenden App.
3. Relay - ein lokaler Fastify-Daemon verbindet Browser, Repository und MCP.
4. Agent - Codex, Claude oder andere MCP-Clients fragen Live-Kontext ab oder bearbeiten Annotationen.

Installation im Detail

Note

npx pinflow init erledigt die Setup-Schritte automatisch. Die manuelle Einrichtung ist vor allem für Monorepos oder bewusst kontrollierte Setups gedacht.

App-Seite

Next.js 15/16 - npm install -D @pinflow/next

// next.config.ts
import type { NextConfig } from 'next';
import { withPinFlow } from '@pinflow/next';

const nextConfig: NextConfig = {};

export default withPinFlow()(nextConfig);

Nuxt 3+ - npm install -D @pinflow/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinflow/nuxt'],
});

React 18/19 mit Vite - npm install -D @pinflow/react

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { pinflow } from '@pinflow/react/vite';

export default defineConfig({
  plugins: [react(), pinflow()],
});

React 18/19 mit Webpack - npm install -D @pinflow/react

// webpack.config.js
const { PinFlowWebpackPlugin } = require('@pinflow/react/webpack');

module.exports = {
  plugins: [new PinFlowWebpackPlugin()],
};

Vue 3 mit Vite - npm install -D @pinflow/vue

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { pinflow } from '@pinflow/vue/vite';

export default defineConfig({
  plugins: [vue(), pinflow()],
});

Vue 3 mit Webpack - npm install -D @pinflow/vue

// webpack.config.js
const { PinFlowWebpackPlugin } = require('@pinflow/vue/webpack');

module.exports = {
  plugins: [new PinFlowWebpackPlugin()],
};

Framework-unabhängig - npm install -D @pinflow/transform

// vite.config.ts
import { defineConfig } from 'vite';
import { pinflow } from '@pinflow/transform/plugins/vite';

export default defineConfig({
  plugins: [pinflow()],
});

Diese Variante liefert DOM-zu-Source-Mapping, aber keine tiefen Framework-Props oder State-Daten.

Framework-unabhängig mit Webpack - npm install -D @pinflow/transform

// webpack.config.js
const { PinFlowWebpackPlugin } = require('@pinflow/transform/plugins/webpack');

module.exports = {
  plugins: [new PinFlowWebpackPlugin()],
};

Monorepos

npx pinflow init --app-root apps/web

Smart Setup erkennt typische App-Pfade wie apps/web oder apps/admin und zeigt den aktuellen Status pro App. PinFlow schreibt weiterhin eine einfache pinflow.config.json mit genau einem appRoot; es gibt keine Multi-App-Config. Wenn du eine weitere App verbinden willst, startest du danach einen neuen Init-Lauf und wählst diese App aus.

Agent-Seite

Claude Code

claude plugin marketplace add Dom-303/pinflow
claude plugin install pinflow@pinflow

Codex

codex marketplace add Dom-303/pinflow
codex mcp add pinflow -- npx -y --package @pinflow/mcp pinflow-mcp

Codex Support liegt zusätzlich im Repo über .codex-plugin/plugin.json und AGENTS.md. Wenn du mehrere Agents nutzt, konfiguriere denselben MCP-Server-Key pinflow in jedem Client. Die Overlay-Session kann danach weiterhin auf Aktueller Agent, Codex, Claude oder Nur sammeln stehen.

Jeder MCP-Client

Bevorzugtes installiertes MCP-Binary: pinflow-mcp. Bevorzugter MCP-Server-Key: pinflow. Kompatibilitaets-Aliasse bleiben fuer aeltere pinflow.*-MCP-Clients verfuegbar.

{
  "mcpServers": {
    "pinflow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--package", "@pinflow/mcp", "pinflow-mcp"]
    }
  }
}

Herkunft und Einordnung

PinFlow ist aus der Idee entstanden, Frontend-Arbeit für Agenten sichtbarer und präziser zu machen. Domscribe, das ursprüngliche DOM-Skript, war dabei die technische Grundlage: stark als Konzept und Experiment, aber noch nicht als rundes, friend-ready Repository. PinFlow führt diese Richtung weiter und verbindet sie mit einer source-genauen Runtime-Grundlage.

Bereich	Domscribe / Grundlage	Source-Mapping-Grundlage	PinFlow heute
Ziel	Agenten näher an UI-Arbeit bringen	DOM-Elemente auf Source abbilden	Voller UI-zu-Agent Workflow
Oberfläche	Konzeptuell, noch roh	Technische Primitive	Overlay, Picker, Queue, Settings
Agenten	Gedacht als Workflow	MCP-nahe Bausteine	Codex/Claude-ready MCP Flow
Repo-Eindruck	Noch nicht fertig zum Teilen	Technisch erklärbar	Deutsche README, Visuals, Setup
Fokus	Idee und Richtung	Präzision der Zuordnung	Produktisierte Entwickler-Erfahrung

Vergleich

Legende: ✅ klar vorhanden · ◐ teilweise/anderer Fokus · ✕ nicht erkennbar

Feature	PinFlow	Domscribe	stagewise	DevInsp.	React Grab	Frontman
Stable IDs	✅ AST data-ds	✅ AST data-ds	✕ Runtime/CDP	◐ AST, unstabil	✕ _debugSource	✕ Runtime APIs
DOM→Source	✅ JSONL	✅ JSONL	✕	✕	✕	✕
Code→Live UI	✅ Source→Runtime	✅ Source→Runtime	✕	✕	✕	✕
Runtime ctx	✅ Props · State · DOM	✅ Props · State · DOM	◐ flach	◐ DOM + JS eval	✕ HTML + Namen	◐ Props
Frameworks	✅ React · Vue · Next · Nuxt	✅ React · Vue · Next · Nuxt	◐ React	✅ React · Vue · Svelte · Solid	✕ React	◐ Next · Astro · Vite
Bundler	✅ Vite · Webpack · Turbo	✅ Vite · Webpack · Turbo	✕ N/A	✅ Vite · Webpack · Turbo	✕ N/A	◐ Middleware
MCP	✅ 12 Tools · 4 Prompts	✅ 12 Tools · 4 Prompts	✕ Karton	✅ 9 Tools	◐ Add-on	✕ intern
Agent-neutral	✅ jeder MCP-Client	✅ jeder MCP-Client	✕ bundled	✅	✅	✕ bundled
Picker	✅ Shadow DOM	✅ Shadow DOM	✅ Browser selector	✅ Inspector bar	✅ Hover	✅ Chat
Picker-Modi	✅ Element · Region · Multi	◐ Element	◐ Element	◐ Inspector	◐ Hover	◐ Chat
Dispatch	✅ Auto · Codex · Claude · Queue	◐ Queue + MCP	✕	◐ MCP/ACP	✕	✕
Regeln	✅ Manual · Immediate · Threshold	✕	✕	✕	✕	✕
Fortsetzung	✅ Manual · Confirm · Automatic	✕	✕	✕	✕	✕
Session	✅ Defaults + Overrides	✕	✕	✕	✕	✕
Queue	✅ Queue + Batch-Status	✅ Queue	✕	◐ Tooling	✕	✕
Lizenz	✅ MIT	✅ MIT	◐ AGPL	✅ MIT	✅ MIT	◐ Apache + AGPL

PinFlows Stärke ist die Kombination: stabile Source-Zuordnung, Live-Kontext, visuelles Markieren, lokale Queue und MCP-Werkzeuge in einem zusammenhängenden Workflow.

Quellen und Einordnung:

• Domscribe ist die ursprüngliche Grundlage: Build-time IDs, DOM→Source Manifest, Code→Live DOM Query, Runtime-Kontext, MCP Tools sowie React/Vue/Next/Nuxt, Vite/Webpack/Turbopack.
• stagewise positioniert sich als Browser-Agent für laufende Web-Apps mit DOM-Kontext, kompatiblen Frameworks und eigenem Agentenflow; das GitHub-Repo nennt AGPL-3.0.
• DevInspector MCP beschreibt MCP/ACP-Flows mit Source Location, DOM, Styles, Network, Console, Screenshots und Framework-Support für React, Vue, Svelte, SolidJS, Preact und Next.js.
• React Grab fokussiert React: Element auswählen, Kontext kopieren, darunter HTML, React-Komponente, File-Source und Hierarchie.
• Frontman läuft browserbasiert über Framework-Plugins, nutzt einen browserseitigen MCP-Server für DOM, Screenshots und computed CSS und editiert Source-Dateien mit Hot Reload.

PinFlow vs. Doom-Script / Domscribe

Bereich	PinFlow	Domscribe	Was PinFlow darauf aufbaut
Build-time IDs	✅	✅	unverändert starke Source-Zuordnung
DOM→Source Manifest	✅	✅	PinFlow behält JSONL/Manifest-Basis
Code→Live-UI Query	✅	✅	Agenten können weiter Source-Stellen live abfragen
Runtime Props/State/DOM	✅	✅	React/Vue Runtime-Kontext bleibt erhalten
MCP Tools	✅	✅	PinFlow nutzt die Tool-Basis weiter
Annotation Lifecycle	✅	✅	Queue/Claim/Respond bleibt Kern des Workflows
WebSocket Feedback	✅	✅	Statuswechsel bleiben live im Overlay sichtbar
Framework-/Bundler-Basis	✅	✅	React, Vue, Next, Nuxt, Vite, Webpack, Turbopack
Picker: Element	✅	✅	bestehender UI→Code-Pfad
Picker: Region	✅	✕	Bereichsauswahl für breitere UI-Kontexte
Picker: Multi-Select	✅	✕	mehrere Elemente als gemeinsame Aufgabe
Provider-Kanal	✅	✕	Auto, Codex, Claude oder Queue-only
Dispatch-Modus	✅	✕	Manual, Immediate oder Threshold
Fortsetzung	✅	✕	Manual, Confirm oder Automatic
Projektdefaults	✅	✕	dauerhafte Dispatch-Standards
Session-Overrides	✅	✕	temporäre Regeln nur für die laufende Sitzung
Batch-/Run-Status	✅	✕	sichtbarer Fortschritt für freigegebene Aufgaben
Undo-/Follow-up-Fluss	✅	✕	Auswahl zurücknehmen oder Anschlussaufgabe erzeugen
README-Produktauftritt	✅	◐	deutsche README, PinFlow-Visuals, lokales Setup-Bild, CTA

Kurz gesagt: Domscribe ist die profunde Grundlage. PinFlow übernimmt diese starke technische Basis und legt darüber eine stärker geführte Produkt-, Settings- und Dispatch-Erfahrung für Codex-, Claude- und MCP-Workflows.

MCP Tools

Tool	Zweck
pinflow.query.bySource	Source-Datei und Zeile im Live-Browser abfragen
pinflow.manifest.query	Manifest nach Datei, Komponente oder Element-ID durchsuchen
pinflow.manifest.stats	Manifest-Statistiken abrufen
pinflow.resolve	data-ds ID zu Source-Position auflösen
pinflow.resolve.batch	Mehrere IDs auf einmal auflösen
pinflow.annotation.process	Nächste Queue-Aufgabe claimen
pinflow.annotation.respond	Agent-Antwort speichern und Aufgabe abschließen
pinflow.annotation.updateStatus	Status manuell ändern
pinflow.annotation.get	Annotation per ID laden
pinflow.annotation.list	Annotationen filtern und listen
pinflow.annotation.search	Volltextsuche über Annotationen
pinflow.status	Relay-, Manifest- und Queue-Status abrufen

Details stehen im @pinflow/mcp README.

Annotation Lifecycle

Von	Nach	Auslöser
queued	processing	Agent claimt die nächste Aufgabe per MCP
processing	processed	Agent speichert Antwort und schließt die Aufgabe
processing	failed	Agent-Fehler, Abbruch oder Timeout
processed	archived	Entwickler räumt erledigte Aufgaben im Overlay auf

Der praktische Ablauf: Du markierst ein Element im Browser, PinFlow speichert die Aufgabe lokal in .pinflow/annotations, der Agent claimt sie atomar, ändert die passende Datei und schreibt seine Antwort zurück. Das Overlay erhält Statuswechsel über WebSocket.

Packages

Package	Inhalt
@pinflow/core	Schemas, Fehlerformat, IDs, PII Redaction
@pinflow/manifest	JSONL Manifest, IDStabilizer, BatchWriter
@pinflow/relay	Fastify HTTP/WS Server, MCP stdio Adapter
@pinflow/transform	AST Injection, Vite/Webpack/Turbopack Plugins
@pinflow/runtime	ElementTracker, ContextCapturer, BridgeDispatch
@pinflow/overlay	Lit Web Components, Picker, Annotation UI
@pinflow/react	React Fiber Adapter, Vite/Webpack Plugins
@pinflow/vue	Vue VNode Adapter, Vite/Webpack Plugins
@pinflow/next	withPinFlow() für Next.js
@pinflow/nuxt	Nuxt Modul mit Runtime Plugin
pinflow	CLI für init, serve, status, stop, mcp
@pinflow/mcp	Standalone MCP Server

Lokale Prüfung

pnpm run pinflow:preview:vite-react

Der wiederholbare Golden-Path-Democheck laeuft separat:

corepack pnpm nx demo-e2e pinflow-test-fixtures

Für den vollständigen Repo-Check:

pnpm run release:check

Der Release-Check validiert README-Assets, wichtige Package-Metadaten, Formatierung, Lint, Tests, Build und Typecheck. Der ausführliche Ablauf steht in RELEASE.md; lokale Sicherheits- und Datenhinweise stehen in SECURITY.md.

Produktfokus

Die aktuelle strategische Einordnung steht in PinFlow Positioning and Build Focus. Kurz: PinFlow soll enger und tiefer werden, nicht breiter. Release-relevant ist der Golden Path aus stabilem DOM→Source Mapping, Runtime-Kontext, pinflow.query.bySource, lokaler Annotation-Queue und Agent-Integration. Dinge wie eigener Browser, Desktop-App, großes Chat-UI oder generische Artifact-Plattform bleiben bewusst außerhalb dieses Release-Fokus.

Contributing

pnpm install
pnpm run build:all

Konventionen liegen in .claude/rules/. PRs sind willkommen.

---

Pin it. Flow it. Ship it.

Starte in deinem Frontend-Repo, öffne die App lokal im Browser und gib deinem Coding Agenten den Kontext, den er wirklich braucht.

Besonderer Dank an Doom-Script / Domscribe: eine außergewöhnlich starke Grundlage, auf der PinFlow weiterbauen konnte.

npx pinflow init

License

MIT