Build your AI team. Ship projects autonomously. Never lose context.
Quick Start • What's New • Core Concepts • Commands • Workers
HQ is infrastructure for orchestrating AI workers — autonomous agents that code, write content, research, and automate tasks.
Not just files. Active systems that:
- Execute — Workers do real work autonomously
- Learn — Rules get injected into the files they govern
- Scale — Build workers for any domain with
/newworker - Survive — Threads persist across sessions, auto-handoff at context limits
┌─────────────────────────────────────────────────────────────────┐
│ YOUR HQ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ WORKERS │ │ KNOWLEDGE │ │ COMMANDS │ │
│ │ Do things │ │ Learn & │ │ Orchestrate │ │
│ │ autonomously│ │ remember │ │ workflows │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ THREADS │ │
│ │ Survive │ │
│ │ sessions │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
| Tool | Required | Install |
|---|---|---|
| Claude Code | Yes | npm install -g @anthropic-ai/claude-code |
| GitHub CLI | Yes | brew install gh then gh auth login |
| qmd | Recommended | brew install tobi/tap/qmd |
| OpenAI Codex | Optional | npm install -g @openai/codex then codex login |
| Vercel CLI | Optional | npm install -g vercel then vercel login |
/setup checks for these automatically and guides you through anything missing.
# 1. Clone
git clone https://github.com/coreyepstein/hq-starter-kit.git my-hq
cd my-hq
# 2. Open in Claude Code
claude
# 3. Run setup wizard (checks deps, creates profile, scaffolds knowledge repos)
/setup
# 4. Build your profile (optional but recommended)
/personal-interviewSetup asks your name, work, and goals. It also scaffolds your first knowledge repo as a symlinked git repo (see Knowledge Repos below). The personal interview goes deeper — 18 questions to build your voice, preferences, and working style.
Three production-ready workers powered by OpenAI Codex SDK via MCP:
/run codex-coder generate-code --task "Create a rate limiter"
/run codex-reviewer review-code --files src/auth/*.ts --focus security
/run codex-debugger fix-bug --issue "Session not persisting"Workers connect to external AI via Model Context Protocol — a shared codex-engine MCP server wraps the Codex SDK and exposes tools (codex_generate, codex_review, codex_debug, codex_improve). The sample-worker template now includes MCP, reporting, and verification patterns.
Sessions no longer pre-load INDEX.md or agents.md. Lazy-loading rules in CLAUDE.md tell Claude to load only what the task needs:
Writing task → loads agents.md + voice-style.md
Coding task → goes straight to the repo
Worker task → loads just worker.yaml
Resuming work → reads handoff.json (7 lines)
Rules get injected directly into the files they govern:
/learn # Auto-capture learnings after task execution
/remember # Manual correction → injects rule into source fileWorker rules → worker.yaml. Command rules → command .md. Global rules → CLAUDE.md.
Start from sample-worker or the bundled codex workers:
/newworker # Interactive scaffold from sample-worker templateCopy workers/sample-worker/ (or any codex worker), customize the YAML, and you have a production worker.
Deep conversational interview builds your profile and voice:
/personal-interview # ~18 questions → agents.md, voice-style.md, profile.mdqmd-powered search across all HQ content:
/search "auth middleware" # BM25 keyword search
/search "how billing works" -v # Semantic/conceptual search
/search-reindex # Rebuild search indexClaude auto-runs /handoff when context hits 70%. Threads capture full git state, worker progress, and next steps. Fresh sessions resume seamlessly.
Autonomous agents with defined skills. They do things.
| Type | Purpose | Examples |
|---|---|---|
| CodeWorker | Implement features, fix bugs | codex-coder, backend-dev |
| ContentWorker | Draft content, maintain voice | brand-writer, copywriter |
| SocialWorker | Post to platforms | x-worker, linkedin-poster |
| ResearchWorker | Analyze data, markets | analyst, researcher |
| OpsWorker | Reports, automation | cfo-worker, monitor |
Workers learn from and contribute to shared knowledge:
knowledge/Ralph/— Autonomous coding methodologyknowledge/workers/— Worker patterns & templatesknowledge/ai-security-framework/— Security best practicesknowledge/dev-team/— Development patternsknowledge/design-styles/— Design guidelines
Slash commands orchestrate everything:
/run worker-name skill # Execute a worker skill
/checkpoint my-work # Save session state
/handoff # Prepare for fresh sessionWork survives context limits:
/checkpoint feature-x # Save state
# ... context fills up → auto-handoff triggers ...
/nexttask # Finds thread, continues work| Command | What it does |
|---|---|
/checkpoint |
Save progress to thread |
/handoff |
Prepare handoff for fresh session |
/reanchor |
Pause, show state, realign |
/nexttask |
Find next thing to work on |
| Command | What it does |
|---|---|
/learn |
Auto-capture learnings from task execution |
/remember |
Manual correction → injects rule into source file |
| Command | What it does |
|---|---|
/run |
List all workers |
/run {worker} {skill} |
Execute a skill |
/newworker |
Create a new worker |
/metrics |
View worker execution metrics |
| Command | What it does |
|---|---|
/prd |
Generate PRD through discovery |
/run-project |
Execute project via Ralph loop |
/execute-task |
Run single task with workers |
| Command | What it does |
|---|---|
/search |
Semantic + full-text search across HQ |
/search-reindex |
Rebuild search index |
/cleanup |
Audit and clean HQ |
/setup |
Interactive setup wizard |
/personal-interview |
Deep interview to build profile + voice |
/exit-plan |
Force exit from plan mode |
Three production workers that use OpenAI Codex SDK via MCP:
| Worker | Skills | Purpose |
|---|---|---|
| codex-coder | generate-code, implement-feature, scaffold-component | Code generation in Codex sandbox |
| codex-reviewer | review-code, improve-code, apply-best-practices | Second-opinion review + automated improvements |
| codex-debugger | debug-issue, root-cause-analysis, fix-bug | Auto-escalation on back-pressure failure |
# Generate code
/run codex-coder generate-code --task "Create a rate limiter middleware"
# Review for security issues
/run codex-reviewer review-code --files src/auth/*.ts --focus security
# Debug a failing test
/run codex-debugger debug-issue --issue "TS2345 type error" --error-output "$(cat errors.txt)"These workers share a codex-engine MCP server. To use them, you'll need a Codex API key (CODEX_API_KEY env var). See workers/dev-team/codex-coder/worker.yaml for the full pattern.
Start from the included sample worker:
# Option 1: Interactive scaffold
/newworker
# Option 2: Manual
cp -r workers/sample-worker workers/my-worker
# Edit workers/my-worker/worker.yamlWorker YAML structure (with modern patterns):
worker:
id: my-worker
name: "My Worker"
type: CodeWorker
version: "1.0"
execution:
mode: on-demand
max_runtime: 15m
retry_attempts: 1
spawn_method: task_tool
skills:
- id: do-thing
file: skills/do-thing.md
verification:
post_execute:
- check: typescript
command: npm run typecheck
- check: test
command: npm test
approval_required: true
# MCP Integration (optional)
# mcp:
# server:
# command: node
# args: [path/to/mcp-server.js]
# tools:
# - tool_name
state_machine:
enabled: true
max_retries: 1
hooks:
post_execute: [auto_checkpoint, log_metrics]
on_error: [log_error, checkpoint_error_state]| Type | Purpose |
|---|---|
| CodeWorker | Features, bugs, refactors |
| ContentWorker | Writing, voice, messaging |
| SocialWorker | Platform posting |
| ResearchWorker | Analysis, data, markets |
| OpsWorker | Reports, automation, ops |
| Library | Shared utilities (no skills) |
See knowledge/workers/ for the full framework, templates, and patterns.
HQ uses the Ralph Methodology for autonomous coding.
1. Pick task from PRD (passes: false)
2. Execute in fresh context
3. Run back pressure (tests, lint, typecheck)
4. If passing → commit, mark complete
5. Repeat until done
- Fresh context per task — No accumulated confusion
- Back pressure validates — Code that doesn't pass isn't done
- Atomic commits — One task = one commit
- PRD is truth — Simple JSON, easy to inspect
# 1. Create PRD
/prd "Build user authentication"
# 2. Execute via Ralph loop
/run-project auth-system
# 3. Monitor progress
/run-project auth-system --statusKnowledge bases in HQ are independent git repos, symlinked into the knowledge/ directory. This lets you version, share, and publish each knowledge base separately from HQ itself.
repos/private/knowledge-personal/ ← actual git repo
└── README.md, notes.md, ...
knowledge/personal → ../../repos/private/knowledge-personal ← symlink
HQ git tracks the symlink. The repo contents are tracked by their own git. Tools (qmd, Glob, Read) follow symlinks transparently.
# 1. Create and init the repo
mkdir -p repos/public/knowledge-my-topic
cd repos/public/knowledge-my-topic
git init
echo "# My Topic" > README.md
git add . && git commit -m "init knowledge repo"
cd -
# 2. Symlink into HQ
ln -s ../../repos/public/knowledge-my-topic knowledge/my-topicFor company-scoped knowledge:
ln -s ../../../repos/private/knowledge-acme companies/acme/knowledge/acmeChanges appear in git status of the target repo, not HQ:
cd repos/public/knowledge-my-topic
git add . && git commit -m "update notes" && git pushThe starter kit ships Ralph, workers, security framework, etc. as plain directories. These work as-is. To convert one to a versioned repo later:
mv knowledge/Ralph repos/public/knowledge-ralph
cd repos/public/knowledge-ralph && git init && git add . && git commit -m "init"
cd -
ln -s ../../repos/public/knowledge-ralph knowledge/Ralphmy-hq/
├── .claude/
│ ├── CLAUDE.md # Session protocol + Context Diet
│ └── commands/ # 18 slash commands
├── agents.md # Your profile
├── knowledge/ # Symlinks → repos/ (or plain dirs)
│ ├── Ralph/ # Coding methodology
│ ├── workers/ # Worker framework + templates
│ ├── ai-security-framework/ # Security practices
│ ├── dev-team/ # Development patterns
│ ├── design-styles/ # Design guidelines
│ ├── hq-core/ # Thread schema, INDEX spec
│ ├── loom/ # Agent patterns
│ └── projects/ # Project guidelines
├── repos/
│ ├── public/ # Public repos + knowledge repos
│ └── private/ # Private repos + knowledge repos
├── workers/
│ ├── registry.yaml # Worker index
│ ├── sample-worker/ # Example (copy + customize)
│ └── dev-team/ # Codex workers (coder, reviewer, debugger)
├── projects/ # Your PRDs
├── workspace/
│ ├── threads/ # Auto-saved sessions
│ │ └── recent.md # Recent thread index
│ ├── orchestrator/ # Project state
│ └── learnings/ # Captured insights
└── companies/ # Multi-company setup (optional)
| Component | Purpose |
|---|---|
| hq-starter-kit | This repo — personal OS template |
| hq-cli | Module management CLI |
This is a template. Make it yours:
- Build workers for your workflows (
/newworker) - Create knowledge bases for your domains
- Add commands for your patterns
- Connect tools via MCP
- Run
/personal-interviewto teach it your voice
- Ralph Methodology by Geoffrey Huntley
- Loom Agent Architecture by Geoffrey Huntley — Thread system, state machine, and agent patterns
- Inspired by personal knowledge systems and AI workflow patterns
MIT — Do whatever you want with it.