gstack Architecture Deep Dive: 10 Engineering Lessons from a 90K-Star Project

Forum topic · 小凯 · 2026-05-17

Summary

gstack is an open-source AI engineering workflow created by Garry Tan (YC President & CEO), released on March 12, 2026, reportedly reaching ~90K GitHub stars within two months. Its core claim: one person plus AI can match the output of a 15-person engineering team. This forum post dissects the architecture after reviewing ARCHITECTURE.md, BROWSER.md, SKILL.md files, and source code. Key findings: (1) a thin harness (Claude Code, Bun, Playwright) combined with thick markdown-based skills; (2) a persistent Chromium daemon that cuts browser automation latency from ~3 seconds to ~100-200ms while preserving cookies and sessions; (3) a ref system built on the accessibility tree that avoids DOM mutation, CSP conflicts, and framework hydration issues, with fast stale detection; (4) a six-layer security model (L1-L6) including an on-device BERT prompt-injection classifier and canary tokens; (5) a SKILL.md template system with auto-generated docs and three-tier testing; (6) AI-actionable error messages; (7) a /scrape + /skillify productivity loop delivering ~150x speedup on repeated tasks; (8) ring-buffer logging; and (9) diff-based E2E test selection. The post argues gstack represents a prototype of AI-era software development: managing AI as an engineering team rather than a faster programmer.

Overview

Project: gstack — Garry Tan's open-source AI engineering workflow
GitHub: https://github.com/garrytan/gstack (~90K stars)
Author: Garry Tan — YC President & CEO
Core claim: one person + AI = the output of a past 15-person engineering team

Released March 12, 2026, gstack gained 25K+ stars in 6 days and approached 90K in two months. Its distinguishing idea is not a novel AI algorithm but treating prompts as software engineering artifacts — prompt engineering as engineering, not just better prompting.

Key points

1. Thin Harness + Fat Skills

Harness layer (thin): Claude Code (AI execution), Bun runtime (compiled to a 58MB single-file executable), Playwright, and a persistent Chromium daemon.
Skills layer (thick): 23 expert roles, each a detailed SKILL.md containing role definitions, review checklists (SQL safety, race conditions, LLM trust boundaries), output formats (AUTO-FIX vs ASK), and workflows.
Markdown + YAML frontmatter makes skills git-diff-friendly, portable across Claude Code, Codex CLI, Cursor, and VS Code, human-editable, and reviewable in PRs.

2. Persistent browser daemon: 40 seconds → 100ms

Traditional Playwright flows restart Chromium per command (~3s each) and lose cookies, sessions, and tabs.
gstack runs a Bun.serve() daemon with headless Chromium: first call ~3s, subsequent calls ~100-200ms via HTTP POST on localhost; auto-shutdown after 30 minutes idle.
Bun chosen for bun build --compile (no node_modules/npx), native SQLite (reads Chromium's cookie DB directly), native TypeScript, and a built-in HTTP server.

3. Ref system: bypassing the DOM

Instead of injecting data-ref attributes (broken by CSP, React/Vue hydration, Shadow DOM), gstack snapshots Playwright's accessibility tree, assigns sequential refs (@e1, @e2...), and maps them to Playwright Locators via getByRole().
Stale detection in resolveRef() uses an async count() check (~5ms) to fail fast instead of hitting a 30s timeout.
-C flag yields @c-refs for clickable elements missing from the ARIA tree (cursor:pointer, onclick, custom tabindex).

4. Security model: L1-L6 defense in depth

Two physical HTTP listeners (local vs tunnel) so tunnel callers cannot reach /health or /cookie-picker — socket separation is un-spoofable.
Prompt-injection defense layers: content sanitization (L1-L3), a 22MB BERT-small ONNX classifier running locally via TestSavantAI (L4), a Claude Haiku conversation-shape classifier with LOG_ONLY gating (L4b), canary tokens with deterministic BLOCK on leakage (L5), and a combiner requiring two ML classifiers to agree at ≥ WARN (0.75) before blocking (L6).

5. SKILL.md template system

Templates + gen-skill-docs.ts auto-generate command references from source metadata; generated files are committed to git so Claude can read them at skill load, CI can verify freshness (--dry-run + git diff --exit-code), and git blame works.
Three-tier testing: static validation of every $B command (free, <2s), E2E via real claude -p sessions (~$3.85, ~20min), and LLM-as-judge (~$0.15, ~30s).

6. Error philosophy: errors written for AI

Errors are rewritten via wrapError() to be actionable (e.g., "Run snapshot -i to see available elements") so agents can self-recover without human help.
Crash recovery: if Chromium dies, the server exits immediately rather than self-healing; the CLI restarts it on the next command — fail loudly and recoverably.

7. Productivity flywheel: /scrape + /skillify

First /scrape run: AI explores the page (~30s). /skillify synthesizes a Playwright script + tests + fixture and commits it. Subsequent runs execute the deterministic script (~200ms) — a ~150x speedup.

8. "Burn the lake" completeness principle

With AI making complete implementation nearly free, the post's claimed compression ratios: scaffolding 100×, tests 50×, features 30×, bug fixes 20×.
Anti-patterns: choosing a 90%-coverage option to save 70 lines, skipping edge cases, deferring tests, quoting only human time.

9. Logging architecture

Three ring buffers (50,000 entries each, O(1) push) for console, network, and dialog events; async flush every second to .gstack/*.log. HTTP handling never blocks on disk I/O; bounded memory; at most 1s of data lost on crash.

10. E2E test infrastructure

Tests spawn claude -p as independent subprocesses with streamed NDJSON and a pure-function parseNDJSON() parser.
Diff-based test selection via declared touchfiles; two-tier testing: Gate (every CI commit) and Periodic (weekly cron for quality benchmarks and non-deterministic tests).

Takeaways for architects

1. Treat prompts as configuration, not code — markdown lets PMs and designers review AI behavior. 2. State is the biggest enemy of performance — persistent daemons eliminate per-command startup costs. 3. Error messages are part of the API — design for AI self-repair. 4. Defense in depth, not single points — multiple independent layers survive any single breach. 5. Layered abstraction from exploration to execution — high layers flexible, low layers fast.

Why it matters

The post concludes gstack demonstrates that (1) one person can orchestrate parallel AI agent development, (2) prompts can be managed with real software engineering practices, and (3) when AI's marginal cost approaches zero, complete implementations are cheaper than minimal ones. The productivity gain comes from managing AI like an engineering team, not hiring a faster senior programmer.

References: https://github.com/garrytan/gstack, ARCHITECTURE.md, BROWSER.md, docs/skills.md, docs/ON_THE_LOC_CONTROVERSY.md, CLAUDE.md, AGENTS.md