IdeaClyst

★Step-by-step guide

The fastest path from a fresh clone to a finished planning packet. Mock mode is the default, so you need no CLIs to try it end to end.

01What it is

IdeaClyst is a local-first Next.js app that turns one rough product idea into a complete founder planning packet. It does this not with a single prompt, but by orchestrating a structured council — a five-step deliberation between two AI command-line tools that take opposing roles and critique each other before reaching a verdict.

Think of it as a tiny boardroom: a skeptical SaaS founder (Claude) and a pragmatic CTO (Codex) argue your idea into shape. The output is split into Summary, MVP Backlog, Risks, Validation Tests, and ready-to-paste Next Prompts.

02Features at a glance

03Architecture

IdeaClyst has four layers, and the design discipline is that only one of them knows whether you're in mock or real-CLI mode.

// the only branch that knows the mode — agents/index.ts
export async function runAgent(agent, prompt, ctx) {
  if (agentMode() === "mock")
    return runMock(ctx.run, ctx.stepKey);   // ignores prompt, uses structured run
  return agent === "claude"
    ? runClaude(prompt, runDir)            // real `claude` (no -p), in run dir
    : runCodex(prompt);                    // real `codex exec`
}

04The 5-step council

This is the heart of the app. The two agents alternate, and the crucial detail is in the "sees" line of each step — every agent reads specific prior outputs, which is what makes it a deliberation rather than five isolated prompts.

◆Idea Discovery

Most of IdeaClyst evaluates an idea you bring. Idea Discovery (the /discover route) does the opposite — it finds ideas for you, grounded in what people are actually struggling with on the web. The blank page is the hardest part of building; Discovery replaces it with real demand signals.

Discoveries persist on disk under .ideaclyst/discoveries/<id>/ (a discovery.json, MARKET_READ.md, OPPORTUNITY_MAP.md, CANDIDATES.md, and report/version artifacts), and the discovery page polls live, just like a run. Trend radar writes .ideaclyst/trends; insights, monitors, decisions, exports, source lanes, validation imports, and interviews write to their own local folders under .ideaclyst/. The app header stays lean: Explore opens /discover, /today, and /trends; Workspace opens sessions, library, and validation. Compare, evidence, decisions, insights, monitors, interviews, clusters, and research settings are linked contextually from those pages.

◆Roadmap Intelligence

IdeaClyst can read the roadmap of a Threlmark project — a separate local-first roadmap manager — and turn it into grounded growth suggestions. Point it at a project (the /roadmap route) and it proposes new features, spin-off products, and services, each scored like a roadmap card and backed by real web evidence. Review them, then send the best ones back into Threlmark's Inbox.

Analyses persist under .ideaclyst/roadmap/<id>/ and the page polls live, just like a run. The data source and any REST base URL are set at /settings; see the new variables in Configuration. Roadmap intelligence is mode-gated like the rest of research — it runs live + strict and shows real data only.

05Request lifecycle

From the moment you hit submit, here is the exact path — note that the server responds before the council finishes:

// api/runs/route.ts — the fire-and-forget hand-off
const run = await createRun(input);
void startRun(run.id);              // NOT awaited — runs in background
return NextResponse.json({ runId: run.id }, { status: 201 });

06Mock vs. CLI mode

One environment variable, IDEACLYST_AGENT_MODE, selects the backend. The orchestrator and UI are identical in both modes — only agents/ behaves differently.

07How CLI calls work

In CLI mode each council step spawns a real process. Both backends use array args + stdin (never a shell string), so a prompt can't break escaping or inject shell syntax, and both enforce a per-call timeout (default 180s).

Claude backend

No -p / --print. When claude's stdout is not a TTY (here it's a pipe), the CLI runs non-interactively and prints a single response, then exits. So IdeaClyst just pipes the prompt on stdin and reads stdout — no print flag needed. --tools "" keeps it a pure text completion (no agentic file actions), and it runs inside the idea's own run directory (spawn cwd):

// agents/claude.ts — runs in the run's own directory
claude --tools ""                  // prompt on stdin, stdout piped (non-TTY)
       [--model <model>]            // optional IDEACLYST_CLAUDE_MODEL

Returns trimmed stdout. A missing binary (ENOENT), non-zero exit with no output, or empty output each reject with a clear "fall back to mock mode" message.

Codex backend

Runs Codex non-interactively, read-only, inside a throwaway temp working directory so it can't touch your filesystem — we only want the 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 on stdin

The clean final message is read from the -o output file; the --json event stream is parsed as a fallback (and to surface a clean API error). The temp dir is always removed afterward. An optional IDEACLYST_CODEX_MODEL adds -m <model>, otherwise it defers to ~/.codex/config.toml.

08Data model & storage

IdeaClyst is local-first: there is no database and no in-memory state. Each run is a directory, and run.json is the single source of truth — the orchestrator rewrites it after each step, the polling API just reads it back.

On-disk layout

The run record

A run carries the brief (title, idea, goal, optional target customer / constraints / preferred stack), a status of queued → running → completed | failed, a human-readable currentStep label for the UI, and an outputs object that starts empty and fills in. Run IDs are timestamp-prefixed slugs, so a reverse string-sort yields newest-first for free.

09API reference

Lists all runs, newest first. Returns { runs: Run[] }.

Validates the brief, creates a queued run, fires the council in the background, and returns { runId } (201). Validation: title required; idea ≥ 10 chars; goal ∈ validate · plan · build · pitch · refine.

// request body
{
  "title": "...",            // required
  "idea": "...",             // required, 10+ chars
  "goal": "validate",        // required, one of the five
  "targetCustomer": "...",   // optional
  "constraints": "...",      // optional
  "preferredStack": "..."    // optional
}

Returns a single run as { run: Run } — this is what the detail page polls every 1.5s.

Drive a run from the terminal

The UI is just a client of this API — anything you can do in the browser you can do from a script. Create a run, poll until it completes, then read the packet off disk:

# 1. Create a run → returns { "runId": "..." }
curl -s -X POST http://localhost:5417/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"title":"StandupScribe","idea":"A Slack bot that posts a daily standup digest.","goal":"plan"}'

# 2. Poll status until completed (every few seconds)
curl -s http://localhost:5417/api/runs/<runId> | jq '.run.status, .run.currentStep'

# 3. Read the finished packet
cat .ideaclyst/runs/<runId>/FINAL_PLAN.md

10File map

11Configuration

All configuration lives in .env.local (copy from .env.example). No secrets are required.

Research & discovery

All best-effort; the live path needs a Chrome/Chromium install. Research follows the agent mode unless overridden.

Roadmap intelligence (Threlmark)

Where IdeaClyst reads Threlmark projects from. The /settings page edits these too; environment variables take precedence.

12Running it

# quick start — mock mode, no CLIs needed
npm install
cp .env.example .env.local
npm run dev          # → http://localhost:5417

# then: open the app → "Start an Idea Session" → submit → watch it assemble

13Limits & troubleshooting