IdeaClyst

★Schritt-für-Schritt-Anleitung

Der schnellste Weg von einem frischen Clone zu einem fertigen Planungspaket. Der Mock-Modus ist die Voreinstellung — du brauchst also keine CLIs, um alles durchzuspielen.

01Was es ist

IdeaClyst ist eine local-first Next.js-App, die eine grobe Produktidee in ein vollständiges Founder-Planungspaket verwandelt. Das geschieht nicht mit einem einzigen Prompt, sondern über einen strukturierten Council — eine fünfstufige Beratung zwischen zwei KI-Kommandozeilen-Tools, die gegensätzliche Rollen einnehmen und sich gegenseitig kritisieren, bevor sie zu einem Urteil kommen.

Stell es dir wie einen winzigen Vorstand vor: ein skeptischer SaaS-Gründer (Claude) und ein pragmatischer CTO (Codex) argumentieren deine Idee in Form. Die Ausgabe wird in Summary, MVP Backlog, Risks, Validation Tests und gebrauchsfertige Next Prompts aufgeteilt.

02Funktionen im Überblick

03Architektur

IdeaClyst hat vier Schichten, und die Design-Disziplin ist: Nur eine davon weiß, ob du im Mock- oder echten CLI-Modus bist.

// der einzige Zweig, der den Modus kennt — agents/index.ts
export async function runAgent(agent, prompt, ctx) {
  if (agentMode() === "mock")
    return runMock(ctx.run, ctx.stepKey);   // ignoriert Prompt, nutzt strukturierten Run
  return agent === "claude"
    ? runClaude(prompt, runDir)            // echtes `claude` (ohne -p), im Run-Verzeichnis
    : runCodex(prompt);                    // echtes `codex exec`
}

04Der 5-Schritte-Council

Das ist das Herz der App. Die beiden Agenten wechseln sich ab, und das Entscheidende steht in der „Sieht“-Zeile jedes Schritts — jeder Agent liest bestimmte vorherige Ergebnisse, und genau das macht es zu einer Beratung statt zu fünf isolierten Prompts.

◆Idea Discovery

Der größte Teil von IdeaClyst bewertet eine Idee, die du mitbringst. Idea Discovery (die Route /discover) macht das Gegenteil — es findet Ideen für dich, geerdet in dem, womit Menschen im Web tatsächlich kämpfen. Das leere Blatt ist der schwerste Teil; Discovery ersetzt es durch echte Nachfrage-Signale.

Discoveries werden auf Platte unter .ideaclyst/discoveries/<id>/ gespeichert (discovery.json, MARKET_READ.md, OPPORTUNITY_MAP.md, CANDIDATES.md sowie Report-/Versions-Artefakte), und die Discovery-Seite pollt live, genau wie ein Run. Trend Radar schreibt nach .ideaclyst/trends; Insights, Monitors, Entscheidungen, Exporte, Source Lanes, Validation-Imports und Interviews schreiben jeweils in eigene lokale Ordner unter .ideaclyst/. Der Header bleibt schlank: Explore öffnet /discover, /today und /trends; Workspace öffnet Sessions, Library und Validation. Compare, Evidence, Decisions, Insights, Monitors, Interviews, Clusters und Research Settings sind kontextuell verlinkt.

◆Roadmap-Intelligenz

IdeaClyst kann die Roadmap eines Threlmark-Projekts (ein separater lokal-first Roadmap-Manager) lesen und daraus belegte Wachstums-Vorschläge machen. Über die Route /roadmap schlägt es neue Features, Spin-off-Produkte und Services vor — jeweils wie eine Roadmap-Karte bewertet und mit echten Web-Quellen belegt. Prüfen, dann die besten zurück in Threlmarks Inbox senden.

Analysen liegen unter .ideaclyst/roadmap/<id>/ und die Seite pollt live wie ein Run. Datenquelle und REST-Basis-URL werden unter /settings gesetzt; siehe die neuen Variablen in der Konfiguration. Roadmap-Intelligenz ist mode-gated wie die übrige Recherche — sie läuft live + strict und zeigt nur echte Daten.

05Ablauf einer Anfrage

Vom Moment des Absendens an — der genaue Pfad. Beachte: Der Server antwortet, bevor der Council fertig ist.

// api/runs/route.ts — die Fire-and-forget-Übergabe
const run = await createRun(input);
void startRun(run.id);              // NICHT awaited — läuft im Hintergrund
return NextResponse.json({ runId: run.id }, { status: 201 });

06Mock- vs. CLI-Modus

Eine Umgebungsvariable, IDEACLYST_AGENT_MODE, wählt das Backend. Orchestrator und UI sind in beiden Modi identisch — nur agents/ verhält sich anders.

07Wie CLI-Aufrufe laufen

Im CLI-Modus startet jeder Council-Schritt einen echten Prozess. Beide Backends nutzen Array-Args + stdin (nie einen Shell-String), damit ein Prompt das Escaping nicht brechen oder Shell-Syntax einschleusen kann, und beide erzwingen einen Timeout pro Aufruf (Default 180 s).

Claude-Backend

Kein -p / --print. Wenn der stdout von claude kein TTY ist (hier eine Pipe), läuft die CLI non-interaktiv, gibt eine einzelne Antwort aus und beendet sich. IdeaClyst pipet also nur den Prompt auf stdin und liest stdout — kein Print-Flag nötig. --tools "" hält es bei einer reinen Text-Completion (keine agentischen Datei-Aktionen), und es läuft im eigenen Run-Verzeichnis der Idee (spawn-cwd):

// agents/claude.ts — läuft im Run-Verzeichnis
claude --tools ""                  // Prompt auf stdin, stdout gepiped (non-TTY)
       [--model <model>]            // optional IDEACLYST_CLAUDE_MODEL

Gibt getrimmtes stdout zurück. Ein fehlendes Binary (ENOENT), ein Exit ungleich null ohne Ausgabe oder leere Ausgabe werden jeweils mit einer klaren „zurück zum Mock-Modus“-Meldung abgelehnt.

Codex-Backend

Führt Codex non-interaktiv, read-only, in einem Wegwerf-Temp-Verzeichnis aus, damit es dein Dateisystem nicht anfassen kann — wir wollen nur die Text-Completion:

// agents/codex.ts
codex exec --json --skip-git-repo-check --ephemeral \
  -s read-only --color never \
  -C <temp-dir> -o last-message.txt -    // Prompt auf stdin

Die saubere finale Nachricht wird aus der -o-Ausgabedatei gelesen; der --json-Event-Stream wird als Fallback geparst (und um einen sauberen API-Fehler sichtbar zu machen). Das Temp-Verzeichnis wird danach immer entfernt. Ein optionales IDEACLYST_CODEX_MODEL ergänzt -m <model>, sonst greift ~/.codex/config.toml.

08Datenmodell & Speicherung

IdeaClyst ist local-first: es gibt keine Datenbank und keinen In-Memory-State. Jeder Run ist ein Verzeichnis, und run.json ist die Single Source of Truth — der Orchestrator schreibt sie nach jedem Schritt neu, die Polling-API liest sie einfach zurück.

Layout auf Platte

Der Run-Datensatz

Ein Run trägt den Brief (Titel, Idee, Ziel, optional Zielkunde / Constraints / bevorzugter Stack), einen status von queued → running → completed | failed, ein menschenlesbares currentStep-Label für die UI und ein outputs-Objekt, das leer beginnt und sich füllt. Run-IDs haben ein Zeitstempel-Präfix, sodass ein umgekehrter String-Sort gratis „neueste zuerst“ liefert.

09API-Referenz

Listet alle Runs, neueste zuerst. Gibt { runs: Run[] } zurück.

Validiert den Brief, legt einen queued-Run an, feuert den Council im Hintergrund und gibt { runId } (201) zurück. Validierung: Titel erforderlich; Idee ≥ 10 Zeichen; Ziel ∈ validate · plan · build · pitch · refine.

// Request-Body
{
  "title": "...",            // erforderlich
  "idea": "...",             // erforderlich, 10+ Zeichen
  "goal": "validate",        // erforderlich, eins der fünf
  "targetCustomer": "...",   // optional
  "constraints": "...",      // optional
  "preferredStack": "..."    // optional
}

Gibt einen einzelnen Run als { run: Run } zurück — genau das pollt die Detailseite alle 1,5 s.

Einen Run vom Terminal aus steuern

Die UI ist nur ein Client dieser API — alles, was du im Browser tun kannst, geht auch per Skript. Run anlegen, bis zum Abschluss pollen, dann das Paket von der Platte lesen:

# 1. Run anlegen → liefert { "runId": "..." }
curl -s -X POST http://localhost:5417/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"title":"StandupScribe","idea":"Ein Slack-Bot, der einen täglichen Standup-Digest postet.","goal":"plan"}'

# 2. Status pollen, bis completed (alle paar Sekunden)
curl -s http://localhost:5417/api/runs/<runId> | jq '.run.status, .run.currentStep'

# 3. Das fertige Paket lesen
cat .ideaclyst/runs/<runId>/FINAL_PLAN.md

10Dateiübersicht

11Konfiguration

Die gesamte Konfiguration liegt in .env.local (Kopie von .env.example). Es sind keine Secrets erforderlich.

Recherche & Discovery

Alles best-effort; der Live-Pfad braucht eine Chrome/Chromium-Installation. Research folgt dem Agent-Modus, sofern nicht überschrieben.

Roadmap-Intelligenz (Threlmark)

Woher IdeaClyst Threlmark-Projekte liest. Die /settings-Seite bearbeitet diese ebenfalls; Umgebungsvariablen haben Vorrang.

12Ausführen

# Schnellstart — Mock-Modus, keine CLIs nötig
npm install
cp .env.example .env.local
npm run dev          # → http://localhost:5417

# dann: App öffnen → "Start an Idea Session" → absenden → beim Zusammenbauen zusehen

13Grenzen & Fehlerbehebung