{"id":50320687,"url":"https://github.com/witchdaddylabs/cauldron-os","last_synced_at":"2026-05-29T03:04:53.151Z","repository":{"id":354087544,"uuid":"1222082347","full_name":"witchdaddylabs/cauldron-os","owner":"witchdaddylabs","description":"Local-first, design-aware blueprint generator for AI-assisted app \u0026 web development","archived":false,"fork":false,"pushed_at":"2026-05-16T03:40:50.000Z","size":9331,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T05:40:45.700Z","etag":null,"topics":["ai","blueprint","cauldron","code-generation","design-system","llm","local-first","ollama","witch-daddy-labs"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/witchdaddylabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"witchdaddylabs"}},"created_at":"2026-04-27T02:57:24.000Z","updated_at":"2026-05-16T03:40:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/witchdaddylabs/cauldron-os","commit_stats":null,"previous_names":["witchdaddylabs/cauldron-os"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/witchdaddylabs/cauldron-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/witchdaddylabs%2Fcauldron-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/witchdaddylabs%2Fcauldron-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/witchdaddylabs%2Fcauldron-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/witchdaddylabs%2Fcauldron-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/witchdaddylabs","download_url":"https://codeload.github.com/witchdaddylabs/cauldron-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/witchdaddylabs%2Fcauldron-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33634615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","blueprint","cauldron","code-generation","design-system","llm","local-first","ollama","witch-daddy-labs"],"created_at":"2026-05-29T03:04:52.904Z","updated_at":"2026-05-29T03:04:53.145Z","avatar_url":"https://github.com/witchdaddylabs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/witchdaddylabs"],"categories":[],"sub_categories":[],"readme":"# Cauldron OS\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.250-blue.svg)](CHANGELOG.md)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n[![GitHub](https://img.shields.io/badge/github-witchdaddylabs-181717.svg)](https://github.com/witchdaddylabs)\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/hero-header.png\" alt=\"Cauldron OS Hero\" width=\"100%\"/\u003e\n\n\u003c/div\u003e\n\n\u003e **Bring the messy idea. Cauldron OS 0.250 brings the structure, taste, and next steps.**\n\nCauldron OS 0.250 is a local-first workshop for AI-assisted builders. Drop in a rough app or website idea, choose a model or design reference, and Cauldron turns the mess into a structured product blueprint with architecture notes, schema ideas, exportable docs, and a live HTML + AlpineJS prototype preview.\n\nNew in **0.250** (Sprint 4): Rebranded and polished — 7-stage pipeline with Build mode, sandboxed workspace, and fully rewritten docs. \n\nIt is built for hobbyists, indie builders, designers, enthusiasts, and developers who want better AI output than “make me a nice dashboard”.\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/witchdaddylabs/cauldron-os.git\ncd cauldron-os\nnpm install\nnpm start\n# → Open http://localhost:3000\n```\n\n### Non-technical start\n\n**Windows:** double-click `start-cauldron.bat` or run `start-cauldron.ps1` in PowerShell.\u003cbr\u003e\n**macOS / Linux:** open Terminal in the repo folder, then run `npm install` and `npm start`.\n\nYou will need Node.js 18+. For local AI generation, install Ollama and pull at least one model. You can also use OpenAI or Google AI Studio with your own API key.\n\n---\n\n## What Cauldron does\n\n1. **You brain-dump the idea**\u003cbr\u003e\n   Write naturally. Messy is fine. Paste reference URLs if you have them.\n\n2. **Optional: Annoying PM Mode / Interrogate Idea**\u003cbr\u003e\n   Cauldron can pop up a short set of annoying project-manager questions before generation. Answer what you can; the Q\u0026A gets folded into the final blueprint prompt so the model has firmer scope, risks, users, and assumptions before it starts pretending to be useful.\n\n3. **Cauldron adds taste and context**\u003cbr\u003e\n   It injects design rules, optional brand/design references, and URL research before the model sees your prompt.\n\n4. **The model creates a blueprint**\u003cbr\u003e\n   You get product notes, architecture direction, schema ideas, security considerations, and implementation guidance.\n\n5. **You get a live preview**\u003cbr\u003e\n   Cauldron asks the model for an HTML + AlpineJS prototype preview so you can see and click through the shape of the idea, not just read about it.\n\n6. **You save, export, or hand it off**\u003cbr\u003e\n   Drafts and history are stored locally. You can export Markdown/JSON or hand the blueprint to a coding agent such as OpenCode.\n\n---\n\n## Screenshots\n\n**Walkthrough demo** — Rude Boy Coffee Co rewards app generated from a Brain Dump plus the live cloner/reference URL research flow.\u003cbr\u003e\n![Rude Boy Coffee walkthrough](assets/demo/cauldron-rude-boy-coffee-walkthrough.gif)\n\n**Full three-panel interface** — Brain Dump, Blueprint Output, HTML + AlpineJS Preview using a Rude Boy Coffee Co rewards-app prompt.\u003cbr\u003e\n![Main UI](assets/screenshots/01-main-ui.png)\n\n**Design Reference selector** — fuse brand DNA from Cursor, Vercel, Lovable, Raycast, Linear, Stripe, Notion, Apple, Figma, Supabase, Resend, Webflow, or OpenCode.\u003cbr\u003e\n![Design Reference Dropdown](assets/screenshots/02-design-dropdown.png)\n\n**Generated prototype preview** — cropped HTML + AlpineJS output with typography and palette inspired by the supplied reference site.\u003cbr\u003e\n![Generated Rude Boy Coffee rewards preview](assets/screenshots/04-rude-boy-preview.png)\n\nA browser-recorded `.webm` walkthrough is also included at [`assets/demo/cauldron-rude-boy-coffee-walkthrough.webm`](assets/demo/cauldron-rude-boy-coffee-walkthrough.webm).\n\n---\n\n## Features\n\n### For hobbyists and solo builders\n\n- Turn rough ideas into structured build blueprints\n- **Annoying PM Mode**: interrogate rough ideas with a product-manager question pass before generation, then fold the answers into the final blueprint prompt\n- **Iterative Refinement**: Tweak generated blueprints with conversational prompts instead of starting from scratch\n- Run locally with Ollama — no API costs and no data leaving your machine\n- Optional cloud fallback using your own OpenAI or Google AI Studio API key\n- Save/load drafts locally with searchable history\n- Export blueprints as Markdown or JSON\n- Save and download blueprints with one click\n- **One-Click Downloads**: Download the generated raw HTML + AlpineJS `prototype.html` directly to your machine\n- Create project folders with blueprint + OpenCode stub for your preferred coding tool\n\n### For design-conscious builders\n\n- Expanded Design Reference dropdown for Cursor, Vercel, Lovable, Raycast, Linear, Stripe, Notion, Apple, Figma, Supabase, Resend, Webflow, and OpenCode-style visual direction\n- Dedicated one-URL cloner target field plus Brain Dump URL detection\n- URL research mode that extracts CSS variables, fonts, colours, and layout hints from reference sites\n- Taste guardrails that avoid generic AI UI sludge: default Inter/Roboto, pure black, nested cards, and tired blue gradients\n- Prompts for stronger spacing, typography, component states, and micro-interactions\n\n### For power users\n\n- **XML Tool Agent System** — Multi-turn build agent that writes, edits, and runs code in a sandboxed workspace\n- **Workspace preview** — Live HTML preview of built files via `/workspace-preview/`\n- **7-stage pipeline** — Brain Dump → Interrogate → Design System → Blueprint → Prototype → Build → Export\n- **Build mode** — Sandboxed workspace with file listing and agent-driven project generation\n- Public-safe local records layer using `sql.js`\n- Clear extension points for prompts, design systems, URL research, templates, and exporters\n- MIT licensed and intentionally local-first\n\n---\n\n## First Blueprint\n\n1. Enter an idea, for example: `A tiny CRM for freelance designers who hate spreadsheets`.\n2. Pick **Local Router** or **Cloud Cauldron**.\n3. Choose **App** or **Static Site**.\n4. Pick a detected local Ollama model, or switch to Cloud Cauldron.\n5. Optionally choose a design reference.\n6. Optionally add one reference URL in the cloner target field, or paste a URL like `https://raycast.com` into Brain Dump to trigger research mode.\n7. Optional but recommended: click **Interrogate Idea** to make Cauldron ask the annoying product-manager questions first.\n8. Answer what you can in the pop-up. Blank answers are allowed and treated as unresolved assumptions.\n9. Click **Generate Blueprint** or press **Cmd/Ctrl + Enter**.\n10. Review the blueprint and HTML + AlpineJS preview.\n11. Save/download, export, or click **Save Prototype \u0026 Blueprint** to save a blueprint + OpenCode stub for your preferred tool.\n\n---\n\n## Model Routing\n\n### Local models\n\nCauldron auto-detects local Ollama models from `/api/tags` on startup and fills the Local Ollama Model dropdown. Defaults remain available as fallbacks for **blueprint generation**:\n\n| Project Type | Default Local Model | Best For |\n|--------------|---------------------|----------|\n| App / product blueprint | `qwen3.5:9b` | Architecture, state, schema, full-stack planning |\n| Static site / landing page | `gemma4:e4b` | Layout, visual hierarchy, static markup |\n\nThese small models (9b–E4B) produce solid blueprints and prototypes, making them viable for generation-only workflows. However, if you want **strong Annoying PM / Interrogate Idea questions** from a local model, you will want a larger model such as **Gemma 4:26b** or **Qwen 3.5/3.6:27b**. Smaller models tend to ask very basic questions during the clarify phase. For the best interrogate experience, use cloud models (OpenAI, Gemini) which produce sharp, specific, jaded-PM-tier questions in seconds.\n\nYou can change the selected model in the UI. This makes cloned installs portable across machines with different Ollama model libraries, including Windows desktops with heavier models.\n\n### Cloud models\n\nCloud Cauldron supports user-provided API keys stored in your browser localStorage.\n\n| Provider | Default / Available Models |\n|----------|----------------------------|\n| OpenAI | `gpt-5.4` |\n| Google AI Studio | `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview` |\n\nGoogle routing now follows the currently available 3.1 choices. Flash Lite is the preferred lightweight architecture model; Pro Preview is available as the heavier fallback.\n\n---\n\n## The Master Brain layer\n\nCauldron’s prompt builder adds three design-aware upgrades before generation:\n\n| Module | What it does |\n|--------|--------------|\n| Impeccable Taste | Adds design anti-patterns and premium UI mandates |\n| Design Reference Selector | Pulls brand DNA from `awesome-design-md` style references |\n| URL Research Sweep | Scrapes the dedicated reference URL or first Brain Dump URL for CSS variables, fonts, colours, and layout patterns |\n\nThis means the model gets more than “build me an app”. It gets taste, constraints, references, and context.\n\n---\n\n## Project Structure\n\n```text\ncauldron-os/\n├── server.js               # Express backend, model proxy, prompt builder, research scraper\n├── db/                     # Local sql.js records backend\n├── public/\n│   └── index.html          # Frontend cockpit with HTML + AlpineJS preview\n├── projects/               # Generated handoff projects (gitignored)\n├── data/                   # Local runtime DB/drafts (gitignored)\n├── docs/                   # Architecture, install, contributing, and upgrade notes\n├── examples/               # Example blueprints/design references\n├── scripts/                # Validation/support scripts\n├── assets/                 # Branding and screenshots\n├── start-cauldron.bat      # Windows launcher\n├── start-cauldron.ps1      # PowerShell launcher\n├── LICENSE                 # MIT License\n└── README.md\n```\n\n---\n\n## Configuration\n\n### Port\n\nDefault: `3000`.\n\n```bash\nPORT=4000 npm start\n```\n\n### Local data\n\nDrafts, sessions, and local runtime data are stored under `data/` and are gitignored by default.\n\n### API keys\n\nCloud API keys are entered in the browser and stored locally in browser localStorage. They are not committed to the repo.\n\n---\n\n## Contributing\n\nPull requests are welcome. Useful areas:\n\n- Add new design references\n- Improve URL research, especially for SPAs\n- Add template/scaffold options such as React + Vite, Next.js, FastAPI, or SwiftUI\n- Improve exports and blueprint diffing\n- Improve accessibility\n- Add tests and docs\n- Clean up install paths for different operating systems\n\nPlease read [CONTRIBUTING.md](docs/CONTRIBUTING.md) before opening a PR.\n\n---\n\n## Roadmap ideas\n\nNear-term public roadmap candidates:\n\n- Templates library\n- Blueprint diffing\n- Blueprint gallery\n- Basic scaffold generator\n\nThe private Witch Daddy Labs build has more experimental automation, build-status, and coding-agent orchestration. Public Cauldron will get the stable, broadly useful pieces as they mature.\n\n---\n\n## Acknowledgments \u0026 Inspirations\n\n- [impeccable.style](https://impeccable.style) — design taste manifesto inspiration\n- [taste-skill](https://github.com/Leonxlnx/taste-skill) by Leonxlnx — high-agency frontend taste patterns\n- [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template) by JCodesMore — reconnaissance inspiration for URL research\n- [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) — DESIGN.md concept and design-system references\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with 💜 by [Witch Daddy Labs](https://witchdaddylabs.com)**\n\n**Happy cooking. 🔥**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwitchdaddylabs%2Fcauldron-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwitchdaddylabs%2Fcauldron-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwitchdaddylabs%2Fcauldron-os/lists"}