Project Forge

An autonomous project idea generator. It runs an in-process scheduler inside the FastAPI app, calls an LLM (or falls back to deterministic heuristics), scores ideas on three orthogonal axes — feasibility (can we build it), fundability (can we sell it), and ambition (does it push the frontier) — deduplicates aggressively, and stores everything in SQLite. A web dashboard lets a human review, approve, and — with a single click — promote ideas into GitHub issues with full MVP specs. Promotion is human-gated: the engine ranks and surfaces, you approve.

Two themed surfaces frame the corpus:

• /money-bots — top ideas in money-friendly categories (automation-income, creator-tools, consumer-app, productivity), sorted by fundability_score DESC. Money is the goal.
• /claude-lab (v0.15) — top ideas in the Claude / agent ecosystem categories (claude-skills-agents, ai-marketplace), sorted by ambition_score DESC. Frontier capability is the goal — new skills, sub-agents, MCP servers, hooks, slash commands, marketplaces, attribution and provenance systems.

Each page has its own Churn Now button that fires the LLM-first generator on demand against the right category family and the right scoring axis. On /claude-lab, Churn additionally rotates through 8 artifact shapes (skill, sub-agent, MCP server, hook, slash command, workflow, protocol, ability) so each click produces a meaningfully different starting frame.

Operating philosophy: autonomous, human-driven. The engine generates, scores, dedups, sweeps, and audits itself on a schedule. Anything that touches external state (GitHub issues, repos) is one click away — never autonomous. The v0.14 weekly auto-promote cadence was removed in v0.14b after a uvicorn-reload bug fired it three times. Today, the Money Bots and Claude Lab pages each expose a Promote ➤ button per card; nothing else can flip an idea to approved without an operator.

This is a personal project that's been running for several months. It's open-sourced because some of the patterns (LLM backend abstraction, multi-stage dedup, persona-driven generation, three-axis scoring, in-process multi-cadence scheduling, artifact-shape rotation) might be useful to others. It is not a product — there's no support, no roadmap commitment, and no SLA.

[!NOTE] No API key required. The LLM backend resolver picks the best path automatically: 1. Anthropic API when ANTHROPIC_API_KEY is set 2. Claude Code CLI when claude is on $PATH (uses your Claude subscription) 3. Static heuristics when neither

>

Override via FORGE_LLM_BACKEND={api|claude_code|static} and FORGE_LLM_MODEL={sonnet|opus|haiku} (default: sonnet).

>

v0.15a — CLI defaults to Opus. When the resolved backend is the Claude Code CLI, the cheap-path resolver (resolve_cheap_backend()) now returns Opus rather than Haiku. There's no per-call cost on a Claude subscription, so the strongest model wins for the LLM-first generator, fundability/ambition tie-breaks, and semantic-dedup verification. API-path users still get Haiku 4.5 there for cost discipline. Override via FORGE_CLI_MODEL={sonnet|opus|haiku} for the speed/quality tradeoff. Set FORGE_HAIKU_API_KEY if you want to use a dedicated cheap key for the API path without exposing your Sonnet/Opus key.

>

GET /api/backend-info (v0.15a) returns which backend is in use plus a censored view of the API-key env vars visible to the running process — useful when /money-bots looks suspiciously like the static generator wrote it.

What it actually does

Quick Start

git clone https://github.com/rayketcham-lab/project-forge.git
cd project-forge
pip install -e ".[dev,test]"

# Run tests (~1290+ tests, ~50s)
pytest tests/ -v

# Start dashboard — the in-process scheduler boots with it
forge-serve     # http://localhost:55443

# Generate one idea (uses whatever backend resolves)
forge-generate

# Check which LLM backend is wired up right now
curl -s http://localhost:55443/api/backend-info | jq .

# Trim an over-saturated database one-shot (e.g. archive the long tail
# below a feasibility cutoff, then run uniqueness gates retroactively)
python scripts/trim-now.py

The dashboard is plain HTML + a small amount of vanilla JS. No build step. Every cadence kicks in once forge-serve is running — there's no separate cron daemon to manage.

Dashboard

The "Add Idea" tab has three independent paths:

• From URL — paste a link, the tool fetches the page (with SSRF guard), sends content + metadata to the LLM, gets an idea back.
• Text — Quick — paste a fragment, one LLM call, get an idea.
• 5-Phase Wizard — Discover → Differentiate → Audience → Constraints → Synthesize. Each phase asks 2–3 follow-up questions based on prior answers. Final phase produces a draft you can edit before saving.

Navigation (v0.15)

The nav bar was rebuilt in v0.15. Three redundant tabs were dropped (Approved and Challenged were duplicates of /explore filters; API was a duplicate of the footer link), and emoji prefixes were removed (they rendered inconsistently across systems). The remaining six items:

Dashboard · Explore · Money Bots · Claude Lab · Projects · Think Tank

Money Bots and Claude Lab carry a subtle 6px colored dot and a colored bottom-underline-on-active — small visual hooks that say "this is a themed surface" without the loud gradient backgrounds of the v0.14 nav.

Card UX (v0.14c)

Every idea card across the dashboard, money-bots, claude-lab, super-ideas, and explore pages carries the same triage UX:

• Hover tooltip — 220 ms after mouse-over, a floating panel shows name + tagline + feasibility / fundability / ambition / mode pills + the first 280 chars of the description. Reads from data-* attributes for an instant first paint, then lazy-fetches /api/ideas/{id} to fill the description. Move off the card and it disappears.
• In-window modal — click anywhere on a card (not on a link/button) and the full idea opens in place: description, market, MVP scope, tech-stack chips, the GitHub issue if promoted, a Reject button, and a "Full page ↗" escape hatch. Backdrop / × / ESC all close. No more page navigations for just-peek-at-an-idea.
• Per-card Reject button — a small red × top-right of every card, invisible until you hover. Confirms via dialog, posts to /ideas/{id}/reject, removes the card from the DOM.
• Churn Now button (on /money-bots and /claude-lab) — fires /api/churn for the current category filter and lab. New idea appears in the grid after a 1.5 s reload.
• Artifact-type badge (on /claude-lab) — small colored pill on each card showing which of the 8 artifact shapes the LLM was asked to produce. Lets a triager see at a glance "this is a slash command" vs "this is an MCP server" without opening the card.
• Promote ➤ button (on /money-bots and /claude-lab, only for un-promoted ideas) — confirms, posts to /api/promote/{id}, files the GitHub issue, flips status to approved. The only path that touches GitHub state.

API

A subset of the routes exposed by web/routes.py. There are more — see the @router.get/post decorators in that file for the full list, or hit /docs for the auto-generated OpenAPI page.

Non-read methods require a Bearer token when FORGE_API_TOKEN is set. The dashboard uses an ephemeral per-process token rendered into the page meta tag — see web/auth.py.

Configuration

Core

Scheduler cadences (v0.11)

All in hours. The in-process scheduler owns these — no systemd timers required. See web/lifespan_scheduler.py.

Promote button (v0.14b — manual)

These knobs gate the manual Promote ➤ button on /money-bots and /claude-lab and the underlying /api/promote/{id} endpoint. The cadence that used to read them autonomously was removed in v0.14b.

Architecture

src/project_forge/
  config.py                  Pydantic-settings
  models.py                  Idea, FilteredIdea, GenerationRun, IdeaCategory, etc.
                             v0.13+ columns: generation_mode, fundability_score
                             v0.14 column:   auto_promoted_at
                             v0.15 columns:  ambition_score, artifact_type
  engine/
    generator.py             API path (IdeaGenerator + LLMBackendIdeaGenerator)
    llm_generator.py         v0.13. LLM-first generator with 5 modes + persona rotation + anti-similarity.
                             v0.15a: ARTIFACT_TYPES + _ARTIFACT_PROMPTS + pick_least_used_artifact()
    llm_backend.py           Backend resolver: AnthropicAPI | ClaudeCode | static.
                             v0.15a: resolve_cheap_backend() returns Opus on CLI, Haiku on API.
    prompts.py               Generation, URL-ingest, text-ingest prompts
    diversity_prompts.py     Combinatoric / contrarian / persona templates
    categories.py            CATEGORY_SEEDS dict (19 categories). Claude Lab categories carry
                             22 seeds + 12 personas each.
    scorer.py                novelty + specificity + scope_realism → composite (feasibility)
    fundability.py           v0.13. Heuristic + Haiku/Opus tie-break in [0.35, 0.70]
    ambition.py              v0.15. Frontier-bias score for the Claude Lab corpus.
                             Heuristic (category + frontier keywords + Anthropic stack +
                             description depth) + tie-break in [0.40, 0.75].
    dedup.py                 INSERT-time gates: content-hash + tagline + name-Jaccard + vertical-cap
    super_ideas.py           Clustering + slot-fill or LLM-reasoned naming
    super_reasoning.py       Cluster signature + LLM cluster naming.
                             v0.15: DAILY_ROTATION slot 8 = "Claude Frontier".
    static_introspect.py     No-LLM SI proposals (Decompose / Add tests for)
    introspect.py            LLM-driven self-improvement prompt builder
    idea_builder.py          5-phase wizard prompts + step orchestration
    text_ingest.py           Free-form text → Idea
    url_ingest.py            URL → Idea (with SSRF guard)
    verticals.py             Industry inference (keyword-based, cached)
    telemetry.py             filter_rate, saturation, novelty_trend, coverage_gaps
    shadow.py                Patch validation (parse target metric, compare snapshots)
    compare.py               Idea-to-repo overlap
    quality_review.py        Reject low-quality / off-topic ideas
    approval_check.py        v0.11. Approval-time think-tank coherence checker
    siphon.py / audit.py / bulk.py / repo_registry.py / router.py
  feeds/
    nvd.py / arxiv.py / ietf.py    Parser + fetcher per source
    cache.py / health.py / _http.py
  storage/
    db.py                    SQLite (WAL), schema, dedup queries.
                             v0.11 tables: approval_checks, verdict_audits.
                             v0.15 ideas columns: ambition_score REAL, artifact_type TEXT.
                             v0.15 hardening: asyncio write-lock, busy_timeout=60s.
  web/
    app.py                   FastAPI factory, lifespan, dashboard token, CSP middleware
    lifespan_scheduler.py    In-process multi-cadence scheduler (replaces systemd timers)
    auth.py                  Bearer token middleware
    routes.py                All page + API routes (incl. /money-bots, /claude-lab, /api/churn, /api/backend-info)
    templates/               Jinja2 (dashboard, explore, idea_detail, money_bots, claude_lab, thinktank, thinktank_audit, projects)
    static/                  app.js, style.css
  cron/
    runner.py                Single-shot entry (used by forge-generate)
    scheduler.py             Full-cycle orchestration (generate → score → dedup → save → route)
    auto_scan.py             No-LLM generation
    horizontal.py            Super-idea generation
    expand_runner.py / introspect_runner.py / self_improve_runner.py
    review_runner.py / challenge_runner.py / verdict_audit_runner.py
    auto_promote_runner.py   v0.14. Promote logic, invoked by POST /api/promote/{id} only
                             (the autonomous weekly cadence was removed in v0.14b).
    issue_sync_runner.py     v0.14c. Pulls live GH issue state for promoted ideas → DB.
  scaffold/
    builder.py               Project structure
    github.py                gh CLI wrapper
    templates/               Per-language scaffold templates

The in-process multi-cadence scheduler

There's no systemd. The original deployment shipped one timer per cron-driven cycle in /etc/systemd/system/, but the runtime sandbox doesn't have access to systemd at all (no DBus, no sudo, no /etc/systemd/ writes). v0.11 moved every cadence into the FastAPI lifespan as a single supervisor task that owns N async loops, one per Cadence. A child failing once is logged and retried; a child crashing repeatedly does not stop its siblings; cancelling the supervisor cancels every child.

The defaults are tuned so a single host can run the full engine on roughly $2–3/month of LLM spend at API-path Haiku 4.5 prices — and essentially $0 on a Claude subscription (the CLI path):

expand            1h    cross-category + super idea generation (LLM-first)
issue_sync        1h    pull live GH state for promoted ideas → DB
review            12h   auto-archive sweeps over aged ideas
self_improve      6h    GitHub ci-queue → PR loop
introspect        24h   self-improvement idea proposals
verdict_audit     24h   "who watches the watcher" — samples recent LLM verdicts
feed_refresh      24h   NVD / arXiv / IETF cache refresh
fundability       24h   score recent ideas for monetization viability
ambition          24h   score Claude Lab category ideas for frontier-bias (v0.15)
challenge         168h  autonomous adversarial pass on top unchallenged ideas

There is no auto_promote cadence anymore. The weekly money-flipper was removed in v0.14b after a uvicorn-reload bug fired it three times in one session. The runner code at cron/auto_promote_runner.py stays — it's invoked by the manual /api/promote/{id} endpoint that the Promote ➤ buttons on /money-bots and /claude-lab POST to.

Each cadence is overridable via env (see the table above). The scheduler honours per-cadence watermarks (e.g. expand consults MAX(generated_at) so a manual forge-generate resets the clock), so frequent restarts don't double-fire.

Self-improvement loop

There's a pipeline that proposes patches to the codebase itself:

• Static introspector (no LLM): walks src/, finds files >300 lines and modules without tests. Emits Decompose X and Add tests for X proposals with concrete suggestions (longest functions, public symbols).
• LLM introspector (with API key or Claude Code CLI): builds a prompt with file tree, recent commits, lint status, telemetry signals (saturation, filter rate, coverage gaps), asks for one targeted patch with a named target metric.
• Shadow validation: parses target metric from the proposal, snapshots telemetry before/after, only allows merge if the metric moved correctly.

Promoted proposals appear in the Think Tank dashboard. Whether they auto-merge depends on the self_improve_runner config — by default it opens a PR and waits for review.

Data model

class Idea(BaseModel):
    id: str                          # 12-char hex, generated
    name: str
    tagline: str
    description: str
    category: IdeaCategory           # 19-value StrEnum (v0.15)
    market_analysis: str
    feasibility_score: float         # 0.0-1.0 composite from scorer — "can we build it?"
    mvp_scope: str
    tech_stack: list[str]
    generated_at: datetime
    status: IdeaStatus               # new | approved | scaffolded | rejected
                                     # | archived | contributed | implemented
    github_issue_url: str | None
    project_repo_url: str | None
    content_hash: str | None         # for dedup
    source_url: str | None           # for URL-ingest provenance
    generation_mode: str | None      # v0.13. Which of the 5 LLM-first modes
                                     # produced this idea (or None for template)
    fundability_score: float | None  # v0.13. 0.0-1.0 monetization viability —
                                     # "can we sell it?" Sorts /money-bots DESC.
    ambition_score: float | None     # v0.15. 0.0-1.0 frontier-bias —
                                     # "does it push the frontier?" Sorts /claude-lab DESC.
    artifact_type: str | None        # v0.15a. One of skill / sub-agent / mcp-server /
                                     # hook / slash-command / workflow / protocol / ability
                                     # for Claude Lab ideas; None elsewhere.
    auto_promoted_at: datetime | None # v0.14. Stamped when a Promote ➤ click
                                     # filed the issue — idempotency guard

SuperIdea extends with vision, component_idea_ids, mvp_phases. Filtered ideas (FilteredIdea) live in their own table with filter_reason and similar_to_id so saturation telemetry can read them. Approval-check results land in approval_checks; verdict-audit results land in verdict_audits.

Categories

19 of them as of v0.15. The original 13 lean security / infrastructure (it's what the project was built for); v0.12 added 4 money-friendly categories so the engine has fresh idea space once the IT seeds saturate; v0.15 added 2 Claude / agent frontier categories to anchor the /claude-lab surface. They're a dict[IdeaCategory, dict] in engine/categories.py:

# Original 13 (IT / security)
security-tool · vulnerability-research · pqc-cryptography · nist-standards
rfc-security · crypto-infrastructure · privacy · compliance · observability
devops-tooling · automation · market-gap · self-improvement

# v0.12 scope expansion — money-friendly
automation-income · consumer-app · productivity · creator-tools

# v0.15 scope expansion — Claude / agent frontier
claude-skills-agents · ai-marketplace

/money-bots reads from the four money-friendly ones; /claude-lab reads from the two Claude-ecosystem ones. The other 13 still flow through /explore and the dashboard top-ideas grid.

Each entry has description, seed_concepts (list of strings — the two Claude Lab categories carry 22 seeds each), personas (the two Claude Lab categories carry 12 personas each in engine/llm_generator.py), and domains_to_cross (unrelated domains for cross-pollination prompts). Replace the dict to retarget the engine at any portfolio.

A parallel vertical axis is inferred at query time from idea text: government, healthcare, education, finance, retail, hospitality, manufacturing, energy, telco. Inferred via keyword matching; cached per idea ID. Used by the explore page filter and the dashboard "Browse by Industry" panel.

The 5 generation modes (v0.13)

engine/llm_generator.py rotates through these. The picker prefers under-represented modes so the rotation self-balances.

Each call also picks a category-specific persona (indie hackers for money-bots, CISOs for security tools, parents for consumer apps, agent authors / MCP integrators / prompt-eng leads / marketplace founders for Claude Lab, …) and injects the 30 most-recent active names from the same category as anti-similarity hints: "do NOT produce anything resembling these." This pre-empts the regrowth pattern that the INSERT-time dedup gates would otherwise catch reactively.

The 8 artifact shapes (v0.15a — Claude Lab only)

On Claude Lab Churn clicks, the LLM-first generator additionally picks one of 8 artifact shapes and injects a per-shape prompt section (~150 words) that pins down what the LLM should produce. The picker prefers under-represented shapes via pick_least_used_artifact(db, category) — same rotation discipline as pick_least_used_mode.

The artifact shape is stored on the idea row (artifact_type column) and surfaced on the Claude Lab card as a colored badge. The /api/churn response carries it alongside the idea fields so the operator can see how the dice landed.

Combinatorics for one Claude Lab Churn click: 2 categories × 5 modes × 8 artifacts × 12 personas = 960 distinct starting frames, before the anti-similarity injection narrows further. Money Bots Churn at 4 × 5 × 12 = 240 frames remains the same — no artifact rotation there because the shape on those categories is always "product."

v0.15 / v0.15a bug fixes worth calling out

A few quiet correctness fixes that landed alongside the bigger features:

• `app.js` here-doc escaping: ten \! sequences had crept into the JS source and broke every JS-driven handler (Reject button, modal open/close, hover tooltip, issue-reporter form). Fixed in v0.14c. The same pattern then bit style.css — four \!important declarations were silently invalid — and was fixed in v0.15.
• Stale "✓ promoted" badge on /money-bots: the template gated on auto_promoted_at IS NOT NULL, which left the badge stuck on ideas that had been rejected after promotion. Now gates on status='approved' AND auto_promoted_at IS NOT NULL.
• "database is locked" on /reject: an asyncio write-lock was added to the SQLite layer, busy_timeout was bumped to 60s, and the fundability rescore batch was reduced from 50 → 5 per cycle. Backend latency is now 4–13ms across all paths.

Deployment notes

The project runs on a single host as one long-lived FastAPI service (forge-serve). The in-process multi-cadence scheduler boots with the app — no systemd timers, no cron daemon. File writes deploy instantly via uvicorn --reload. The unit files under scripts/ (project-forge-*.service/.timer) are kept for reference but are not the active path; the in-process scheduler supersedes them.

The project assumes a normal Python environment with gh CLI and (optionally) claude CLI on PATH. There's no Docker image checked in.

Testing

pytest tests/ -v                                  # ~1290+ tests, ~50s
pytest tests/ -k "ambition or claude_lab" -v      # subset — v0.15 surface area
pytest tests/ -k "artifact_type" -v               # subset — v0.15a artifact rotation
pytest tests/ -k "telemetry or super" -v          # subset
pytest tests/ --cov=project_forge --cov-report=term-missing
ruff check src/ tests/

CI runs the same on a self-hosted runner.

Status

Active. The in-process scheduler fires generation hourly, issue-sync hourly, fundability + ambition scoring + verdict audits + feed refresh daily, and the autonomous challenge cadence weekly. Promotion to GitHub is human-gated via the Promote ➤ button on /money-bots and /claude-lab. Issues / PRs welcome but not necessarily merged on any timeline — see CONTRIBUTING.md and SECURITY.md.

See ROADMAP.md for the v0.16+ plan — top three: Stripe revenue webhook (so the engine learns which money categories actually convert), an MCP-registry pull (so the engine learns which Claude Lab artifact shapes are over- or under-represented in the wild and biases generation accordingly), and auto-scaffold of the promoted idea into a real starter repo (close the loop from "approved" → "running MVP" without an operator click).

License

MIT. See LICENSE (or the [project] license field in pyproject.toml).