Tuesday, 13 October 2026
Monday, 12 October 2026
yoyo-evolve， 能够自我演化的coding agent
A coding agent that evolves its own source, in public — 200 lines of Rust on day one, every commit since agent-written and tests-gated.
https://yoyo.yolog.dev/
Website · GASP · Journal · Documentation · GitHub · DeepWiki · Issues · Follow on X
200 lines of Rust. Zero human code. One rule: evolve or die. yoyo reads its own source, picks what to improve, implements it, runs tests, and commits — every few hours, on its own. 180 days later: 158,000+ lines, 5,400+ tests, 94 source files.
A free, open-source coding agent for your terminal. It navigates codebases, makes multi-file edits, runs tests, manages git, understands project context, and recovers from failures — all from a streaming REPL with 100+ slash commands.
No human writes its code. No roadmap tells it what to do. It decides for itself.
Every 3 hours, yoyo wakes up and:
→ Reads its own source code
→ Checks GitHub issues for community input
→ Plans what to improve
→ Makes changes, runs tests
→ If tests pass → commit. If not → revert.
→ Replies to issues as 🐙 yoyo-evolve[bot]
→ Pushes and goes back to sleep
Every 4 hours (offset), yoyo runs a social session:
→ Reads GitHub Discussions
→ Replies to conversations it's part of
→ Joins new discussions if it has something real to say
→ Occasionally starts its own discussion
→ Learns from interacting with humans
Daily, a synthesis job regenerates active memory:
→ Reads JSONL archives (learnings + social learnings)
→ Applies time-weighted compression (recent=full, old=themed)
→ Writes active context files loaded into every prompt
The entire history is in the git log and the journal.
Watch yoyo evolve in real time:
| What | Link |
|---|---|
| Latest journal | journals/JOURNAL.md |
| What it's learned | memory/active_learnings.md |
| Family lineage | LINEAGE.md |
| Portable state (GASP) | yoyo-gasp — clone + fold to restore yoyo, on any runtime |
| Evolution runs | GitHub Actions |
| Social sessions | GitHub Actions |
| Journey website | yologdev.github.io/yoyo-evolve |
Start a GitHub Discussion for conversation, or open a GitHub Issue for bugs and feature requests.
| Label | What it does |
|---|---|
agent-input |
Community suggestions, bug reports, feature requests — yoyo reads these every session |
agent-self |
Issues yoyo filed for itself as future TODOs |
agent-help-wanted |
Issues where yoyo is stuck and asking humans for help |
- Open a new issue
- Add the
agent-inputlabel - Describe what you want — be specific about the problem or idea
- Add a thumbs-up reaction to other issues you care about (higher votes = higher priority)
- Suggestions — tell it what to learn or build
- Bugs — tell it what's broken (include steps to reproduce)
- Challenges — give it a task and see if it can do it
- UX feedback — tell it what felt awkward or confusing
- Fixed: yoyo comments on the issue and closes it automatically
- Partial: yoyo comments with progress and keeps the issue open
- Won't fix: yoyo explains its reasoning and closes the issue All responses come with yoyo's personality — look for the 🐙.
yoyo's growth isn't just autonomous — you can influence it.
Every issue is scored by net votes: thumbs up minus thumbs down. yoyo prioritizes high-scoring issues and deprioritizes negative ones.
- See a great suggestion? Thumbs-up it to push it up the queue.
- See a bad idea, spam, or prompt injection attempt? Thumbs-down it to protect yoyo.
You're the immune system. Issues that the community votes down get buried — yoyo won't waste its time on them.
Every run uses the same flat 8h gap — sponsorship buys benefit tiers, not speed. And every sponsor, any amount, is listed in this README permanently. Recognition doesn't expire here.
Monthly sponsors:
| Amount | Benefits |
|---|---|
| $5/mo | Issue priority (💖) |
| $10/mo | Priority + shoutout issue |
One-time sponsors:
| Amount | Benefits |
|---|---|
| $5 | Issue priority (14 days) |
| $10 | Above + shoutout issue (30 days) |
| $1,000 💎 | Genesis — permanent priority + top billing |
- Streaming output — tokens arrive as they're generated, not after completion
- Multi-turn conversation with full history tracking
- Extended thinking — adjustable reasoning depth (off / minimal / low / medium / high)
- Subagent spawning —
/spawndelegates focused tasks to a child agent, now with parallel (--parallel) and background (--bg+/spawn collect) execution and an optional per-subagent--model; the model can also delegate subtasks automatically via a built-in sub-agent tool - Parallel tool execution — multiple tool calls run simultaneously
- Automatic retry with exponential backoff and rate-limit awareness
- Auto-continue — detects when the model stops mid-work and automatically sends follow-up prompts (up to 5 per user turn, configurable)
- Provider failover —
--fallbackflag switches to backup provider on API failure with configurable priority - Rate-limit aware retry — reads the provider's own reset time instead of guessing, and reports when the door reopens rather than burning attempts against it;
--wait-for-reset(opt-in) waits out a long reset instead of giving up
| Tool | What it does |
|---|---|
bash |
Run shell commands with interactive confirmation, optional RTK token compression |
read_file |
Read files with optional offset/limit |
write_file |
Create or overwrite files with content preview |
edit_file |
Surgical text replacement with colored inline diffs |
search |
Regex-powered grep across files |
list_files |
Directory listing with glob filtering |
rename_symbol |
Project-wide symbol rename across all git-tracked files |
ask_user |
Ask the user questions mid-task for clarification (interactive mode only) |
web_search |
Search the web and read result snippets |
Sub-agents also auto-receive sub_agent and shared_state tools for delegating subtasks and sharing memory across a multi-agent run.
Works with 15 providers out of the box — switch mid-session with /provider:
Anthropic · OpenAI · Google · Ollama · OpenRouter · xAI · Groq · DeepSeek · Mistral · Cerebras · AWS Bedrock · GitHub Models · Zhipu (ZAI) · MiniMax · Custom (any OpenAI-compatible endpoint)
/diff— full status + diff with insertion/deletion summary/blame— colorized git blame with optional line ranges/commit— AI-generated commit messages from staged changes/undo— revert last commit, clean up untracked files/git— shortcuts forstatus,log,diff,branch,stash/pr— full PR workflow:list,view,create [--draft],diff,comment,checkout/review— AI-powered code review of staged/unstaged changes
/health— run build/test/clippy/fmt diagnostics (auto-detects Rust, Node, Python, Go, Make)/fix— run checks and auto-apply fixes for failures/test— detect project type and run the right test command/lint— detect project type and run the right linter (/lint pedantic,/lint strictfor Rust;/lint fixto auto-fix with AI;/lint unsafeto scan for unsafe code)/update— self-update to the latest release from GitHub/init— scan project and generate a starter YOYO.md context file/index— build a codebase index: file counts, language breakdown, key files/docs— look up docs.rs documentation for any Rust crate/tree— project structure visualization/find— fuzzy file search with scoring and ranked results/ast— structural code search using ast-grep (optional)/map— structural repo map showing file symbols and relationships with ast-grep backend/architect— dual-model mode: plan with a strong model, implement with a cheaper one/risk— per-file risk scoring from git-history signals (/risk accuracygrades past predictions)
/saveand/load— persist and restore sessions as JSON--continue/-c— resume last session on startup- Auto-save on exit — sessions saved automatically, including crash recovery
- Auto-compaction at 80% context usage, plus manual
/compact --context-strategy checkpoint— exit with code 2 when context is high (for pipeline restarts)/tokens— visual token usage bar with per-category context breakdown (system, user, assistant, tool calls, tool results, thinking)/cost— per-model input/output/cache pricing breakdown, with fleet pricing (Opus 4.8 / Sonnet 5 / Fable 5 / Haiku 4.5) read live from yoagent presets
- Project context files — auto-loads YOYO.md, CLAUDE.md, or
.yoyo/instructions.md - Git-aware context — recently changed files injected into system prompt
- Project memories —
/remember,/memories,/forgetfor persistent cross-session notes
- Interactive tool approval — confirm prompts for bash, write_file, and edit_file with preview
- "Always" option — approve once per session
--yes/-y— auto-approve all executions--allow/--deny— glob-based allowlist/blocklist for commands--allow-dir/--deny-dir— directory restrictions with path traversal prevention- Config file support via
[permissions]and[directories]sections;[directories]entries support*wildcards - Project-config trust boundary — a repo's own
.yoyo.tomlcannot silently grant itself privileges. MCP servers,permissions.allow, shell hooks and.yoyo/goal_verify.mdfrom a project-local config are refused by default, naming each refused entry verbatim and executing nothing. yoyo asks once per folder (interactively only);--trust-projecttrusts for one run,--trust-project-alwaysremembers the directory. A non-interactive run always takes the safe answer.
- Custom slash commands — drop
.mdfiles in.yoyo/commands/(project) or~/.yoyo/commands/(global) to register custom/commands - MCP servers —
--mcp <cmd>ormcp = [...]in.yoyo.tomlconnects to MCP servers via stdio transport./mcp listmarks any server that failed to connect, so2 of 3 failednever renders like3 of 3 failed - OpenAPI tools —
--openapi <spec>registers tools from OpenAPI specifications - Skills system —
--skills <dir>loads markdown skill files with YAML frontmatter; search GitHub for community skills (/skill search), install from local paths or GitHub repos (/skill install gh:user/repo) - RTK integration — auto-detects RTK and uses it to compress tool output by 60-90% (
--no-rtkto disable)
- Rustyline — arrow keys, Ctrl-A/E/K/W, persistent history
- Tab completion — slash commands with descriptions, file paths, model names, git subcommands, inline hints
- Multi-line input — backslash continuation and fenced code blocks
- Markdown rendering — headers, bold, italic, code blocks with syntax-labeled headers
- Syntax highlighting — Rust, Python, JS/TS, Go, Shell, C/C++, JSON, YAML, TOML
- Braille spinner while waiting for responses
- Conversation bookmarks —
/mark,/jump,/marks - Conversation search —
/searchwith highlighted matches - Shell escape —
/run <cmd>and!<cmd>bypass the AI entirely
curl -fsSL https://raw.githubusercontent.com/yologdev/yoyo-evolve/main/install.sh | bashirm https://raw.githubusercontent.com/yologdev/yoyo-evolve/main/install.ps1 | iexcargo install yoyo-agentgit clone https://github.com/yologdev/yoyo-evolve && cd yoyo-evolve && cargo install --path .# Interactive REPL (default)
ANTHROPIC_API_KEY=sk-... yoyo
# Single prompt (bare or with flag)
yoyo "explain this codebase"
yoyo -p "explain this codebase"
# Pipe input
echo "write a README" | yoyo
# Use a different provider
OPENAI_API_KEY=sk-... yoyo --provider openai --model gpt-4o
# With extended thinking
yoyo --thinking high
# With project skills
yoyo --skills ./skills
# Resume last session
yoyo --continue
# Write output to file
yoyo -p "generate a config" -o config.toml
# Auto-approve all tool use
yoyo --yesCreate .yoyo.toml in your project root, ~/.yoyo.toml in your home directory, or ~/.config/yoyo/config.toml globally:
model = "claude-sonnet-4-6"
provider = "anthropic"
thinking = "medium"
mcp = ["npx open-websearch@latest"]
[permissions]
allow = ["cargo *", "npm *"]
deny = ["rm -rf *"]
[directories]
allow = ["."]
deny = ["../secrets"]Create a YOYO.md (or CLAUDE.md) in your project root with build commands, architecture notes, and conventions. yoyo loads it automatically as system context. Or run /init to generate one.
| Command | Description |
|---|---|
/add <file|url> |
Add file or URL contents to the conversation |
/apply <patch> |
Apply a diff or patch file |
/architect |
Toggle architect mode — plan with a strong model, implement with a cheap one |
/ast <pattern> |
Structural code search via ast-grep (optional) |
/bg [subcmd] |
Manage background shell processes: run, list, output, kill |
/blame <file> |
Git blame with colored output (/blame file:10-20 for ranges) |
/cd [dir] |
Change the working directory (~ and relative paths supported) |
/changelog [N] |
Show recent git commit history (default: 15) |
/changes |
Show files modified during this session |
/checkpoint [sub] |
Named file-state snapshots (save, list, restore, diff, delete) |
/clear |
Clear conversation history |
/clear! |
Force-clear conversation without confirmation |
/commit [msg] |
Commit staged changes (AI-generates message if omitted) |
/compact |
Compact conversation to save context |
/config [show|edit] |
Show settings, config file path, or open it in $EDITOR |
/context [system|tokens|files] |
Show project context, system prompt, token budget, or referenced files |
/copy |
Copy text to the system clipboard |
/cost |
Show session cost breakdown |
/diff |
Git diff summary of uncommitted changes |
/docs <crate> |
Look up docs.rs documentation |
/doctor |
Run environment diagnostics |
/evolution [N] |
Show evolution history, session stats, and CI run status |
/exit, /quit |
Exit yoyo |
/explain <file> |
Ask the agent to explain code from a file |
/export |
Export the conversation as markdown |
/extended <task> |
Run the agent autonomously on a long task |
/extract |
Extract a function or block to a new file |
/find <pattern> |
Fuzzy-search project files by name |
/fix |
Auto-fix build/lint errors |
/forget <n> |
Remove a saved memory by index |
/fork [subcmd] |
Branch conversations and switch between them |
/git <subcmd> |
Quick git: status, log, add, diff, branch, stash |
/goal [subcmd] |
Set, view, or check progress on a session goal |
/grep <pattern> |
Search file contents |
/health |
Run project health checks |
/help |
Grouped command reference |
/history [detail] |
Conversation summary (detail for a per-turn breakdown) |
/hooks |
Show active hooks (pre/post tool execution) |
/index |
Build a lightweight codebase index |
/init |
Generate a starter YOYO.md |
/jump <name> |
Jump to a conversation bookmark |
/lint [pedantic|strict|fix|unsafe] |
Auto-detect and run project linter (strictness levels for Rust) |
/load [path] |
Load session from file |
/loop <N|until-pass> <prompt> |
Repeat a prompt in a polling loop |
/map |
Structural repo map of file symbols (ast-grep backend) |
/mark <name> |
Bookmark current point in conversation |
/marks |
List all conversation bookmarks |
/mcp |
List and manage MCP server connections (a failed connect is named inline) |
/memories |
List or search project memories |
/model <name|list|info> |
Switch, list, or inspect models |
/move |
Move a method between files |
/open <file> |
Open a file in your editor |
/outline [symbol] |
Search for symbols or show file structure |
/permissions |
Show active security and permission configuration |
/plan [subcmd] |
Plan mode toggle, one-shot plan, show/apply/clear |
/pr [subcmd] |
PR workflow: list, view, create, diff, comment, checkout |
/profile |
Session statistics (tokens, cost, time, turns) |
/provider <name> |
Switch or show the current provider |
/quick <question> |
Fast answer without tools (single-turn, no agent loop) |
/read |
Toggle read-only oracle mode — analyze but not modify |
/refactor |
Refactoring tools (extract, rename, move) |
/remember <note> |
Save a persistent project memory |
/rename <old> <new> |
Rename a symbol across the project |
/retry |
Re-send the last input (--with "..." to refine) |
/review [path] |
AI code review (--quick, --thorough) |
/revisit |
Review closed/shelved issues that may now be feasible |
/rewind |
Restore the conversation auto-stashed by /clear |
/risk [subcmd] |
Per-file risk scoring from git history (/risk accuracy) |
/run <cmd> |
Run a shell command directly (no AI, no tokens) |
/save [path] |
Save session to file |
/search <query> |
Search conversation history |
/security |
Run a dependency vulnerability scan |
/side <question> |
Ask a quick question without affecting the conversation |
/skill [subcmd] |
List, inspect, install, and search for skills |
/spawn <task> |
Run a task in a sub-agent (--parallel, --bg, --model) |
/stash |
Stash conversation and start fresh |
/status |
Show session dashboard (model, modes, goal, watch, changes) |
/teach [on|off] |
Toggle teach mode — explains reasoning as it works |
/test |
Auto-detect and run project tests |
/think [level] |
Show or change thinking level |
/tips |
Context-sensitive feature suggestions |
/todo [subcmd] |
Track tasks (add, done, remove, clear, board) |
/tokens |
Show token usage, context window, and per-category breakdown |
/tree [depth] |
Show project directory tree |
/undo |
Undo last turn's changes, all uncommitted, or last commit |
/update |
Self-update to the latest release |
/version |
Show version, build metadata, and target |
/watch |
Auto-run lint + test after file changes |
/web <url|search> |
Fetch a web page or search the web |
Want your own self-evolving agent? Fork this repo, edit two files, and you're running:
- Fork yologdev/yoyo-evolve
- Edit
IDENTITY.md(goals, rules) andPERSONALITY.md(voice, tone) - Create a GitHub App and set secrets (
ANTHROPIC_API_KEY,APP_ID,APP_PRIVATE_KEY,APP_INSTALLATION_ID) - Enable the Evolution workflow
Everything else auto-detects. See the full guide for details.
src/ 77 modules, ~115,000 lines of Rust
main.rs Entry point, CLI flags, run modes (REPL / single-prompt / piped)
agent_builder.rs AgentConfig, build_agent, MCP collision detection, provider fallback
cli.rs · cli_config.rs CLI parsing, Config, constants, system prompt
dispatch.rs · dispatch_sub.rs REPL /command routing + bare `yoyo <subcmd>` routing
commands*.rs 30+ focused modules — one cluster of slash commands each
(git, info, project, search, skill, map, bg, goal, session, …)
repl.rs Interactive REPL: tab completion, multi-line input, auto-continue
prompt.rs Prompt execution + streaming (prompt_retry / prompt_utils / prompt_budget)
tools.rs Builtin tools; tool_wrappers.rs decorators; smart_edit.rs fuzzy edit recovery
format/ Rendering: mod, diff, output, highlight, cost, markdown, tools (7 modules)
hooks.rs Hook trait, registry, AuditHook, tool wrapping
context.rs · memory.rs Project context loading; cross-session project memory
watch.rs Watch mode (lint → fix → test → fix) + post-prompt auto-fix loop
rtk.rs · safety.rs · update.rs · providers.rs · config.rs RTK, bash safety, self-update, providers, config
tests/
integration.rs 89 subprocess-based integration tests
docs/ mdbook source (book.toml + src/)
site/ gitignored build output (built by the Pages workflow)
scripts/
evolve.sh Evolution pipeline (plan → implement → respond)
skill_evolve.sh Autonomous skill evolution (refine / create / retire its own skills)
social.sh Social session (discussions → reply → learn)
extract_trajectory.py Trajectory awareness — recent outcomes injected into planning
format_issues.py · format_discussions.py · yoyo_context.sh · refresh_sponsors.py · build_site.py
memory/
learnings.jsonl · social_learnings.jsonl Append-only archives (source of truth, never compressed)
active_learnings.md · active_social_learnings.md Synthesized prompt context (regenerated daily)
skills/ 14 skills — 7 core (immutable): self-assess, evolve, communicate, research,
skill-evolve, skill-creator, analyze-trajectory
+ social, family, release, blindspot, synthesis, explore-codebase, yopedia
5,400+ tests (unit + integration) covering CLI flags, command parsing, error quality, exit codes, output formatting, edge cases, project detection, fuzzy scoring, git operations, session management, markdown rendering, cost calculation, permission logic, streaming behavior, and more.
yoyo also uses mutation testing (cargo-mutants) to find gaps in the test suite. Every surviving mutant is a line of code that isn't truly tested.
cargo install cargo-mutants
cargo mutantsSee mutants.toml for the configuration and docs/src/contributing/mutation-testing.md for the full guide.
Built On
yoagent — minimal agent loop in Rust. The library that makes this possible.
from https://github.com/yologdev/yoyo-evolve
StreamDiffusion
StreamDiffusion: A Pipeline-Level Solution for Real-Time Interactive Generation
Authors: Akio Kodaira*, Chenfeng Xu*, Toshiki Hazama*, Takanori Yoshimoto, Kohei Ohno, Shogo Mitsuhori, Soichi Sugano, Hanying Cho, Zhijian Liu, Masayoshi Tomizuka, Kurt Keutzer
StreamDiffusion is an innovative diffusion pipeline designed for real-time interactive generation. It introduces significant performance enhancements to current diffusion-based image generation techniques.
We sincerely thank Taku Fujimoto and Radamés Ajna and Hugging Face team for their invaluable feedback, courteous support, and insightful discussions.
-
Stream Batch
- Streamlined data processing through efficient batch operations.
-
Residual Classifier-Free Guidance - Learn More
- Improved guidance mechanism that minimizes computational redundancy.
-
Stochastic Similarity Filter - Learn More
- Improves GPU utilization efficiency through advanced filtering techniques.
-
IO Queues
- Efficiently manages input and output operations for smoother execution.
-
Pre-Computation for KV-Caches
- Optimizes caching strategies for accelerated processing.
-
Model Acceleration Tools
- Utilizes various tools for model optimization and performance boost.
When images are produced using our proposed StreamDiffusion pipeline in an environment with GPU: RTX 4090, CPU: Core i9-13900K, and OS: Ubuntu 22.04.3 LTS.
| model | Denoising Step | fps on Txt2Img | fps on Img2Img |
|---|---|---|---|
| SD-turbo | 1 | 106.16 | 93.897 |
| LCM-LoRA + KohakuV2 |
4 | 38.023 | 37.133 |
Feel free to explore each feature by following the provided links to learn more about StreamDiffusion's capabilities. If you find it helpful, please consider citing our work:
@article{kodaira2023streamdiffusion,
title={StreamDiffusion: A Pipeline-level Solution for Real-time Interactive Generation},
author={Akio Kodaira and Chenfeng Xu and Toshiki Hazama and Takanori Yoshimoto and Kohei Ohno and Shogo Mitsuhori and Soichi Sugano and Hanying Cho and Zhijian Liu and Kurt Keutzer},
year={2023},
eprint={2312.12491},
archivePrefix={arXiv},
primaryClass={cs.CV}
}git clone https://github.com/cumulo-autumn/StreamDiffusion.gitYou can install StreamDiffusion via pip, conda, or Docker(explanation below).
conda create -n streamdiffusion python=3.10
conda activate streamdiffusionOR
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Linux
source .venv/bin/activateSelect the appropriate version for your system.
CUDA 11.8
pip3 install torch==2.1.0 torchvision==0.16.0 xformers --index-url https://download.pytorch.org/whl/cu118CUDA 12.1
pip3 install torch==2.1.0 torchvision==0.16.0 xformers --index-url https://download.pytorch.org/whl/cu121details: https://pytorch.org/
Install StreamDiffusion
#for Latest Version (recommended)
pip install git+https://github.com/cumulo-autumn/StreamDiffusion.git@main#egg=streamdiffusion[tensorrt]
#or
#for Stable Version
pip install streamdiffusion[tensorrt]Install TensorRT extension
python -m streamdiffusion.tools.install-tensorrt(Only for Windows) You may need to install pywin32 additionally, if you installed Stable Version(pip install streamdiffusion[tensorrt]).
pip install --force-reinstall pywin32python setup.py develop easy_install streamdiffusion[tensorrt]
python -m streamdiffusion.tools.install-tensorrtgit clone https://github.com/cumulo-autumn/StreamDiffusion.git
cd StreamDiffusion
docker build -t stream-diffusion:latest -f Dockerfile .
docker run --gpus all -it -v $(pwd):/home/ubuntu/streamdiffusion stream-diffusion:latestYou can try StreamDiffusion in examples directory.
|
|
|---|---|
|
|
There is an interactive txt2img demo in demo/realtime-txt2img directory!
There is a real time img2img demo with a live webcam feed or screen capture on a web browser in demo/realtime-img2img directory!
We provide a simple example of how to use StreamDiffusion. For more detailed examples, please refer to examples directory.
from https://github.com/cumulo-autumn/StreamDiffusion
react-starter-kit
Modern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.
https://reactstarter.com/
A full-stack monorepo template for building SaaS applications with React 19, tRPC, and Cloudflare Workers. Type-safe from database to UI, deployable to the edge in minutes.
- Type-safe full stack – TypeScript, tRPC, and Drizzle ORM create a single type contract from database to UI
- Edge-native – Three Cloudflare Workers (web, app, api) connected via service bindings
- Auth + billing included – Better Auth with email OTP, passkey, Google OAuth, organizations, and Stripe subscriptions
- Modern React – React 19, TanStack Router (file-based), TanStack Query, Jotai, Tailwind CSS v4, shadcn/ui
- Database ready – Drizzle ORM with Neon PostgreSQL, migrations, and seed data
- Fast DX – Bun toolchain, Vite, Vitest, Oxlint, Oxfmt, and pre-configured VS Code settings
React Starter Kit is proudly supported by these amazing sponsors:
| Layer | Technologies |
|---|---|
| Runtime | Cloudflare Workers |
| Frontend | React 19, TanStack Router, Tailwind CSS v4, shadcn/ui, Jotai |
| Marketing | Astro |
| Backend | Hono, tRPC, Better Auth, Stripe |
| Database | Drizzle ORM, Neon PostgreSQL |
| Toolchain | Bun, TypeScript 7.0, Vite, Vitest, Oxlint, Oxfmt |
├── apps/
│ ├── web/ Astro marketing site (edge router, serves static + proxies to app/api)
│ ├── app/ React 19 SPA (TanStack Router, Jotai, Tailwind CSS v4)
│ ├── api/ Hono + tRPC API server (Better Auth, Cloudflare Workers)
│ └── email/ React Email templates
├── packages/
│ ├── ui/ shadcn/ui components (new-york style)
│ ├── core/ Shared types and utilities
│ └── ws-protocol/ WebSocket protocol with type-safe messaging
├── db/ Drizzle ORM schemas, migrations, and seed data
├── infra/ Terraform (Hyperdrive connection pools, R2 storage)
├── docs/ VitePress documentation
└── scripts/ Build automation and dev tools
Each app deploys independently to Cloudflare Workers. The web worker routes /api/* to the API worker and app routes to the app worker via service bindings.
- Bun v1.4+ (replaces Node.js and npm)
- VS Code with our recommended extensions
- React Developer Tools browser extension (recommended)
- Cloudflare account for deployment
Generate a new repository from this template, then clone it locally:
git clone https://github.com/your-username/your-project-name.git
cd your-project-namebun installThis project follows Vite env conventions:
.envis committed and contains shared defaults/placeholders only (no real secrets).env.localis git-ignored and should contain your real credentials.env.localvalues override.env
cp .env .env.local # then replace placeholder values with real onesAlso check wrangler.jsonc for Worker configuration and bindings.
# Launch all apps in development mode (web, api, and app)
bun dev
# Or, start specific apps individually
bun web:dev # Marketing site
bun app:dev # Main application
bun api:dev # API serverEnsure DATABASE_URL is configured in your .env.local file, then set up the schema:
bun db:push # Push schema directly (quick dev setup)
bun db:seed # Seed with sample data (optional)
bun db:studio # Open database GUIdb:push is for local prototyping only. Staging and production apply migrations instead: bun db:migrate:staging, bun db:migrate:production.
| App | URL |
|---|---|
| React app | http://localhost:5173 |
| Marketing site | http://localhost:4321 |
| API server | http://localhost:8787 |
When you want to bring in newer React Starter Kit changes, ask your coding agent to run the merge-seed skill (/merge-seed in Claude Code or $merge-seed in Codex). It merges upstream changes while preserving your project's identity and configuration. Start with a clean working tree; the Quick Start guide explains the workflow and its safety boundary.
The short version. The deployment guide covers each step in full.
Terraform creates the Hyperdrive configurations the API worker connects through:
bun infra:production applyPaste the two IDs it prints into the hyperdrive block of apps/api/wrangler.jsonc.
Configure your production secrets in Cloudflare Workers:
# Required – the API refuses to deploy without these
bun wrangler secret put BETTER_AUTH_SECRET --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put RESEND_API_KEY --config apps/api/wrangler.jsonc --env=""
# Google sign-in (optional – email OTP and passkeys work without it)
bun wrangler secret put GOOGLE_CLIENT_ID --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put GOOGLE_CLIENT_SECRET --config apps/api/wrangler.jsonc --env=""
# Stripe billing (optional – set all four to enable, or none; annual is extra)
bun wrangler secret put STRIPE_SECRET_KEY --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put STRIPE_WEBHOOK_SECRET --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put STRIPE_STARTER_PRICE_ID --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put STRIPE_PRO_PRICE_ID --config apps/api/wrangler.jsonc --env=""
bun wrangler secret put STRIPE_PRO_ANNUAL_PRICE_ID --config apps/api/wrangler.jsonc --env="" # optionalAll of these belong to the API worker, which is what --config selects – without it Wrangler has no worker to attach the secret to. Use --env staging for staging; production is the top-level config, selected explicitly with --env="". Non-sensitive vars like RESEND_EMAIL_FROM go in wrangler.jsonc directly.
Set RESEND_EMAIL_FROM to an address on a domain you have verified with Resend. The default onboarding@resend.dev only delivers to your own inbox, and sign-in is email OTP – leave it and no one else can sign in.
bun db:migrate:production # reads .env.production.local, and only that file# Builds, then deploys api -> app -> web (service-binding targets first)
bun deploy:staging
bun deploy:productionCI runs the same script, so a release from your machine and one from GitHub Actions cannot drift.
Need Help?
Documentation covers auth, database, billing, deployment, and more.
Our AI assistant is trained on this codebase – ask it anything on ChatGPT or Gemini. Try these questions:
- How do I add a new tRPC endpoint?
- Help me create a database table
- How does authentication work?
- Explain the project structure
- How do I deploy to Cloudflare?
- Add a new page with routing
- How do I send emails?
from https://github.com/kriasoft/react-starter-kit
