This document provides a high-level introduction to gstack: its purpose, architecture, and design philosophy. It explains how gstack transforms AI agents from generalist assistants into a coordinated team of specialists through a structured skill system, backed by a persistent headless browser infrastructure and a semantic memory layer.
gstack is designed for technical founders, CEOs, and staff engineers who want to ship code at an accelerated scale—leveraging agentic workflows to move faster than a traditional team README.md29-33
gstack is an "open source software factory" README.md23 It provides specialized cognitive modes for different engineering activities, invoked via slash commands. The system consists of three primary layers:
/office-hours, /plan-ceo-review, /review, /ship) that define persona-driven prompts and workflows README.md23-24 These are generated from templates in .tmpl files using a resolution pipeline involving scripts/gen-skill-docs.ts CLAUDE.md101/browse and /qa skills to interact with web applications with sub-second latency ARCHITECTURE.md7-10| Skill | Specialist Persona | Primary Function |
|---|---|---|
/office-hours | YC Partner | Reframes product ideas via 6 forcing questions; pushes back on framing docs/skills.md7 |
/plan-ceo-review | CEO / Founder | Rethinks the problem; finds the "10-star product" docs/skills.md9 |
/plan-eng-review | Eng Manager | Locks architecture, data flow, and edge cases docs/skills.md10 |
/review | Staff Engineer | Finds bugs that pass CI but fail in production docs/skills.md13 |
/qa | QA Lead | Tests apps, finds bugs, and verifies via browser docs/skills.md18 |
/ship | Release Engineer | Automates PR creation, test runs, and doc syncing docs/skills.md22 |
/browse | QA Engineer | Provides the agent "eyes" via a persistent browser docs/skills.md30 |
/investigate | Debugger | Systematic root-cause debugging with an "Iron Law" of no fixes without investigation docs/skills.md14 |
/autoplan | Review Pipeline | Runs CEO → design → eng → DX review automatically docs/skills.md32 |
Sources: README.md23-24 docs/skills.md5-50 CLAUDE.md86-131 CONTRIBUTING.md27-32
Standard AI agents often suffer from "blank prompt" syndrome or inconsistent depth. gstack solves several specific bottlenecks:
/office-hours to push back on premises docs/skills.md7This diagram bridges the Natural Language Space (user commands and agent invocation) to the Code Entity Space (implementation files and classes).
Skill Markdown Files: gstack comprises specialized skills expressed in Markdown (SKILL.md) that encode prompt templates and shell preambles. These skills are generated from typed .tmpl templates driven by host-specific resolvers (scripts/resolvers/) and managed by scripts/gen-skill-docs.ts CLAUDE.md101-105
Multi-Host Support: Skills adapt to various AI hosts (Claude, Codex, Gemini, Cursor, OpenClaw, Hermes, gbrain) through host config files in the hosts/ directory. This system changes prompt format, tool availability, and request routing dynamically per host CLAUDE.md94-105 README.md94-99
Browser Daemon: The browse binary supports fast browser automation by acting as a persistent headless Chromium daemon. Commands go through an HTTP server (browse/src/server.ts) which schedules them with BrowserManager (browse/src/browser-manager.ts), which manages Playwright tabs and state ARCHITECTURE.md36-40
Snapshot and Ref System: Physical page element references (@e1, @c2) are managed by the snapshot system that parses ARIA accessibility trees and assigns stable tokens for command targeting ARCHITECTURE.md112-121
State File Management: The .gstack/browse.json file coordinates client-server state sharing (port, token, PID) and persists session information like cookies, console logs, and network requests across commands ARCHITECTURE.md58-62
Operational Learnings & gbrain: Projects accumulate learnings from AI agent sessions in structured logs (learnings.jsonl), which the gbrain layer uses to provide semantic recall and improve subsequent sessions' context CONTRIBUTING.md27-32
When a user issues a browser skill command, e.g. $B click @e1:
This persistent daemon architecture achieves:
gstack tailors the skill experience for different AI hosts via a host config abstraction:
hosts/*.ts) provides:
Specialized Cognitive Modes
By giving each slash command skill a distinct persona and purpose (e.g., CEO planning, staff engineer review), gstack forces Claude Code into specialized reasoning modes, avoiding shallow or inconsistent outputs docs/skills.md7-19
Operational Self-Improvement
Each session logs errors, missteps, and fixes as operational learnings. These accumulate into project-specific memory files automatically surfaced by /learn skill, allowing gstack to self-improve over time CONTRIBUTING.md27-32
Latency and Persistence
The persistent browser daemon ensures sub-second command liveness and state retention across commands, critical for efficient "eyes and hands" automation with reliable session continuity ARCHITECTURE.md36-40
Template-Driven Multi-Host Flexibility
Instead of monolithic prompts, gstack uses a template and host config pipeline to generate skill files tailored to specific AI agent models, promoting maintainability and extending support for different AI providers CLAUDE.md101-105
End-to-End Test Oriented
The system integrates static validation, E2E interaction tests (bun run test:e2e), and LLM-based quality scoring (bun run test:evals) for high confidence in correctness and robustness CLAUDE.md144-147
Open Source, One-Repo, One-Install
gstack ships all skills, browser tooling, and integrations in a single repo with a straightforward install script (./setup) that generates all artifacts and registers skills in Claude Code package.json12-18 setup
gstack converts a general-purpose Claude Code AI into a specialized, persistent, full-stack engineering assistant team by combining:
This design enables AI-accelerated software production workflows at unprecedented scale.
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.