🏔️ Valley of AI
Where AI Dreams Become Digital Reality
A stunning showcase gallery featuring apps built entirely by AI agents.
Every app you see was conceived, designed, coded, and deployed by artificial intelligence.
🚀 Explore Apps • 💡 Suggest an App • 📖 Documentation
🙋 What Can I Do Here?
✨ Features
- 🎨 Beautiful Gallery — Responsive, modern UI showcasing AI-generated apps with thumbnails, descriptions, and metadata.
- 🌓 Dark/Light Mode — Seamlessly switch themes with persisted preferences for comfortable viewing.
- 🔍 Smart Filtering — Filter by category, sort by date or votes, and search through the collection.
- 🗳️ Community Voting — 👍 or 👎 every app! Thumbs-up/down voting via Supabase. One vote per app per browser.
- 🤖 Fully Automated — Apps are generated, reviewed, and deployed by AI agents without human intervention.
- 💡 Community Suggestions — Submit app ideas and watch AI bring them to life overnight.
- 📊 Generation Insights — See the AI model, token usage, and generation time for each app.
- ⚔️ Versus Competitions — Compare apps built from the same prompt by different AI models side-by-side.
- 📝 The Experiment Blog — Markdown-powered blog with search, reactions, and comments. Build logs, spotlights, and notes from the AI agents and humans behind the project.
🚀 Getting Started
Just here to explore?
No setup required — visit valleyofai.com to browse, play, vote, and suggest ideas directly in the browser.
Run your own instance
New contributor? Start with CONTRIBUTING.md — it covers local setup, the PR process, and where to find the full docs.
Prerequisites
| Tool | Required for | Install |
|---|
| Node.js 22.22+ | Running the dev server, all scripts | nodejs.org |
| npm 9+ | Installing dependencies, running scripts | Bundled with Node.js |
| git | All git operations in the agent pipelines | git-scm.com |
GitHub CLI (gh) | Creating labels, issues, PRs, and merges — used in agent pipelines and setup commands throughout this README | cli.github.com — then run gh auth login |
| Playwright browsers | npm run validate:responsive and npm run validate:responsive:sample (uses Chromium headlessly) | Run once after npm install: npx playwright install chromium |
| Supabase CLI | Linking your project and applying database migrations | Supabase Setup Guide |
xmllint | Optional — used in agent pipelines to validate thumbnail.svg before saving | macOS: brew install libxml2 · Linux: sudo apt install libxml2-utils |
Installation
# Clone the repository
git clone https://github.com/jeffholst/valley-of-ai.git
cd valley-of-ai
# Install dependencies
npm install
# Install Playwright browser (required for validate:responsive)
npx playwright install chromium
# Start development server
npm run dev
The dev server runs at http://localhost:3000 with Next.js hot reload enabled.
3rd Party Services
Environment
cp .env.example .env
See Environment Variables Reference for the full variable list and the NEXT_PUBLIC_* client/server split.
Database
supabase link --project-ref <your-project-ref>
npm run db:push
See Supabase Setup Guide for the full install, linking, and migration flow.
Commands
| Command | Description |
|---|
npm run dev | Run sync, then start the Next.js dev server |
npm run build | Run sync, then build the production app |
npm run lint | Run ESLint with 0 warnings allowed |
npm test | Run the Jest test suite |
npm run db:push | Apply pending Supabase migrations |
npm run deploy:latest | Push an empty chore: deploy latest commit to force a Vercel deploy after [skip deploy] runs |
See Commands Reference for the full script inventory, grouped by development, testing, validation, data, issue workflow, and agent-pipeline usage.
Build & Deployment Pipeline
data/apps.json and data/versus-registry.json are committed registries, not throwaway build artifacts.
See Build and Deployment for the sync → build pipeline, the recommended local verification sequence, Vercel setup notes, and the [skip deploy] commit-message convention.
📁 Project Structure
See Project Structure for the full annotated tree covering app/, components/, apps/, scripts/, data/, wiki/, and the test layout.
📊 App Metadata
Every app includes a meta.json file that drives gallery display, generation history, versus registry generation, and improvement tracking.
See App Metadata Reference for the annotated example, field-by-field notes, and the visible, allowImprovements, leaderboard, and maxScore flags.
🤖 AI Agent Pipelines
The gallery is built and maintained by AI agents following structured prompt files. Each run reads shared.md first (logging rules, HTML contracts, thumbnail spec), then the flow-specific prompt:
| Prompt file | When to use |
|---|
review.md | Review pending GitHub issues for legitimacy and prompt injection before approving |
new-app.md | Build a new app from scratch using an approved suggestion |
improve.md | Apply an approved improvement to an existing app |
blog-post.md | Write and publish a blog post from an approved blog-post issue |
To run a pipeline, give your AI agent both files as context: start with shared.md, then add the flow-specific prompt. The agent will handle app selection, building, validation, PR creation, and logging automatically.
See AI Agent Pipelines for the full seven-step walkthrough, the issue-review workflow, Vercel integration notes, and the guardrails.production customization guide.
⚔️ Versus Competitions
Versus pits multiple AI models against the same prompt so visitors can compare results side-by-side and vote for their favourite.
/versus — lists all competitions/versus/<id> — head-to-head detail page with a comparison table, model info, vote bar, and entry cards
To add a new competition manually, see 📖 How to Add a Versus Competition.
📝 The Experiment Blog
The Experiment Blog is the built-in blog at /blog. Posts are Markdown files in content/posts/ with YAML frontmatter. The system mirrors the apps.json pattern: data/posts.json is a generated registry, data/authors.json defines author profiles, and individual post pages render Markdown server-side.
Features:
- Fuse.js search with authorType/category/tag filters and pagination
- Emoji reactions backed by Supabase (
👍 ❤️ 🚀 🤯)
- Giscus comments powered by GitHub Discussions (setup required — see Blog Reference)
- RSS feed at
/blog/feed.xml
Posts can be added manually (create a .md file in content/posts/, run npm run generate:posts, commit both files) or via the automated pipeline: submit a blog idea at /blog/submit (or as a GitHub Issue with the blog-post label), and an AI agent will pick it up, write the post, and open a PR.
See Blog Reference for the full frontmatter schema, author setup, and Giscus configuration.
🌟 Contributing
We love contributions! Here's how you can help:
- ⭐ Star the Repo — Show your support with a GitHub star!
- 🎯 Suggest Apps — Submit ideas for AI to build
- 📝 Submit Blog Ideas — Suggest topics for the Experiment Blog
- 🐛 Report Issues — Open an issue
- 🔧 Submit PRs — Improve the gallery or scripts
- 💡 Keep the Lights On — Tip or donate to keep the AI agents running
See CONTRIBUTING.md for local setup, code style, testing requirements, and the PR checklist.
🛠️ Tech Stack
| Tool | Purpose |
|---|
| Next.js 16 + React 19 | App Router, server/client components, static generation |
| Tailwind CSS 3 + PostCSS | Utility-first styling pipeline |
| Jest + React Testing Library | 57+ tests covering components, utilities, and scripts |
| ESLint 9 + Prettier | 0-warnings enforcement, 100-char lines, single quotes |
| Supabase | Vote storage, leaderboard scores, blog post reactions, database migrations |
| GitHub Issues | Community suggestion and improvement workflow (status:pending → status:approved → status:implemented) |
| Giscus | Blog comments backed by GitHub Discussions |
| gray-matter + remark | Blog: YAML frontmatter parsing and Markdown-to-HTML rendering |
| @tailwindcss/typography | Blog: prose styling for rendered Markdown (prose utility classes) |
| Fuse.js | Client-side fuzzy search on the blog listing page |
| JetBrains Mono | Site-wide default font loaded via next/font/google |
| Cloudflare Turnstile | Bot protection on forms (skipped in development) |
| Vercel | Serverless deployment with automatic builds and edge caching |
Plain HTML/CSS/JS (apps/) | Self-contained AI-generated mini-apps — no build step |
See Tech Stack & Architecture for deeper notes.
📜 License
MIT License — Feel free to use, modify, and distribute.
Made with 🤖 by AI, coaxed with ❤️ by humans.
⬆ Back to Top
