OVERVIEW

What is HQ?

HQ is a filesystem-based operating system that gives Claude Code persistent memory, specialized workers, and multi-company orchestration. One terminal. Every business. Full autonomy.

01

Companies

Each business gets isolated context — credentials, knowledge, workers, and projects never cross-contaminate.

02

Workers

Specialized AI agents with domain knowledge, tools, and learned rules. Route tasks to the right expert.

03

Commands

Slash commands that encode complex workflows. /prd plans projects, /run dispatches workers, /handoff preserves context.

04

Ralph Loop

Plan → Execute → Review → Learn. Every project runs through this cycle until acceptance criteria pass.

GET STARTED

Install in 30 Seconds

One command to create your HQ. Two more to keep it synced and updated.

npx create-hq

create-hq

One-command installer. Creates your HQ with commands, workers, knowledge bases, and project scaffolding.

npm i -g @indigoai/hq-cli

@indigoai/hq-cli

Module management. Sync external knowledge, workers, and tools into your HQ with merge, link, or copy strategies.

hq sync start

@indigoai/hq-cloud

Cloud sync engine. Access your HQ from any device. S3-backed with real-time file watching.

01 — Create your HQ

terminal

shell

$ npx create-hq

  ╭─────────────────────────────────────╮
  │                                     │
  │   HQ — Personal OS for AI Workers   │
  │                                     │
  ╰─────────────────────────────────────╯

✓ Created .claude/commands/ (17 slash commands)
✓ Created workers/ (26 AI workers)
✓ Created knowledge/ (5 knowledge bases)
✓ Created workspace/ (threads, checkpoints)
✓ Created starter-projects/ (3 templates)

  Next steps:
    cd hq
    claude
    /setup

02 — Manage modules

terminal

shell

$ npm install -g @indigoai/hq-cli

$ hq modules list
  hq-core       v5.0.0  merge   ✓ synced
  ralph-method  v2.1.0  link    ✓ synced
  dev-patterns  v1.4.0  link    ✓ synced

$ hq modules sync
  Syncing hq-core... ✓ 3 files updated
  Syncing ralph-method... ✓ up to date
  Syncing dev-patterns... ✓ up to date

03 — Sync to cloud

terminal

shell

$ hq sync init
  Authenticating with IndigoAI...
  ✓ Connected to hq.indigoai.com

$ hq sync start
  ✓ Background sync active
  ✓ Watching 847 files across 16 companies
  ✓ Access your HQ at hq.indigoai.com

indigoai-us/hq — View on GitHub

IN ACTION

How It Works

HQ runs inside Claude Code. You type commands, workers execute, and the system learns.

01 — Define workers with domain knowledge

worker.yaml

yaml

# workers/public/backend-dev/worker.yaml
name: backend-dev
type: CodeWorker
team: dev-team
description: Endpoints, business logic, APIs

skills:
  - name: implement-endpoint
    description: Build a REST or GraphQL endpoint
    steps:
      - Read the PRD acceptance criteria
      - Check existing route patterns
      - Implement with tests
      - Run quality gates

instructions: |
  Always use existing auth middleware.
  Follow repository naming conventions.
  Include error handling for all edge cases.

03 — Dispatch workers to execute

terminal

shell

> /run backend-dev implement-endpoint

Worker: backend-dev
Skill: implement-endpoint
Company: acme (auto-detected from cwd)

Reading PRD... US-003 "Update API middleware"
Reading knowledge... companies/acme/knowledge/auth.md
Checking patterns... repos/private/acme-api/src/middleware/

Implementing...
✓ Created src/middleware/clerk-auth.ts
✓ Updated src/routes/index.ts
✓ Added tests in __tests__/clerk-auth.test.ts
✓ All 14 tests passing

Quality gates:
  ✓ TypeScript — no errors
  ✓ Lint — clean
  ✓ Tests — 14/14 passed

02 — Plan projects with /prd

terminal

shell

> /prd
Planning project: user-auth-migration

Generated 5 stories:
  US-001  Set up Clerk provider       P0  ■■■■■
  US-002  Migrate session handling     P0  ■■■■■
  US-003  Update API middleware        P0  ■■■■■
  US-004  Add role-based access        P1  ■■■□□
  US-005  Integration tests            P1  ■■■□□

PRD saved → companies/acme/projects/user-auth-migration/prd.json
Branch created → feature/user-auth-migration

04 — CLAUDE.md governs behavior

CLAUDE.md

markdown

# .claude/CLAUDE.md (excerpt)

## Company Isolation
- Infer active company from cwd, worker, or repo
- NEVER read credentials from another company
- NEVER mix company knowledge in outputs

## Workers
Worker-first rule: Before specialized tasks,
check workers/registry.yaml for a match.
Use /run {worker} {skill} — workers carry
domain instructions + learned rules.

## Ralph Loop
Plan → Execute → Review → Learn
Every project runs through this cycle
until acceptance criteria pass.

WHO IT'S FOR

Built for Operators

Whether you're a solo founder, an agency, or an enterprise team — HQ scales with your complexity.

Solo Founder

You're running 3 businesses from one laptop. Context-switching kills your output.

HQ isolates each company — credentials, knowledge, and workers stay separate. Switch context in one command.

Agency / Studio

10+ clients, each with their own repos, brand guidelines, and deploy targets. AI keeps mixing them up.

Company isolation enforces boundaries. Workers inherit the right company context automatically. No cross-contamination.

Enterprise Team

Your AI toolchain is fragmented — ChatGPT for writing, Copilot for code, custom scripts for everything else.

HQ unifies everything under one orchestrator. Workers handle code, content, design, and ops. PRDs drive execution end-to-end.

STRUCTURE

Directory Architecture

Everything has a place. Companies, workers, knowledge, and projects — all isolated yet interconnected.

tree

shell

hq/
├── .claude/
│   ├── commands/          # 35 slash commands (/prd, /run, /handoff...)
│   ├── hooks/             # PreToolUse, PostToolUse, PreCompact
│   ├── policies/          # Hard/soft enforcement rules
│   └── skills/            # Reusable skill definitions
├── companies/
│   ├── manifest.yaml      # Source of truth: company → resources
│   ├── liverecover/
│   │   ├── knowledge/     # Embedded git repo
│   │   ├── settings/      # Credentials by service (aws/, linear/, stripe/...)
│   │   ├── policies/      # Company-scoped rules
│   │   ├── projects/      # PRDs + execution state
│   │   ├── workers/       # Company-scoped AI workers
│   │   └── data/          # Exports, reports, checkpoints
│   ├── indigo/
│   ├── personal/
│   └── ...                # 16 companies, fully isolated
├── knowledge/
│   ├── public/            # Symlinks → repos/public/knowledge-*
│   └── private/           # Internal knowledge bases
├── repos/
│   ├── public/            # Open-source repos (hq, slack-mcp, ralph...)
│   └── private/           # Client repos (vyg, indigo-nx, moonflow...)
├── workers/
│   └── public/            # Shared workers (dev-team, content-team, qa...)
├── workspace/
│   ├── threads/           # Session continuity (handoff.json, thread files)
│   ├── orchestrator/      # Project execution state
│   ├── reports/           # Generated reports
│   └── social-drafts/     # Content queue
├── settings/              # Shared config (orchestrator.yaml)
└── CLAUDE.md              # System prompt — all rules live here

NAVIGATION

INDEX.md System

Hierarchical INDEX.md files provide a navigable map of HQ. Commands auto-update them so the map stays current.

projects/INDEX.md

All project PRDs and status

workspace/orchestrator/INDEX.md

Ralph loop workflow state

companies/*/knowledge/INDEX.md

Company knowledge maps

workers/*/INDEX.md

Worker directories

knowledge/public/INDEX.md

Public knowledge bases

workspace/reports/INDEX.md

Generated reports

Auto-Updated By

/checkpoint/handoff/reanchor/prd/run-project/newworker/cleanup --reindex

COMPANIES

Company Isolation

Each company owns its own settings, data, and knowledge — fully isolated contexts with dedicated credentials.

Company A

Each company is an isolated context with its own credentials, data, and knowledge.

settings/data/knowledge/

Company B

Workers and commands can be scoped to a specific company.

settings/data/knowledge/

Personal

Personal context for individual workflows and social presence.

settings/knowledge/

WORKERS

Worker Hierarchy

Specialized AI workers organized into teams. Each has a YAML definition, skills, verification, and state machine lifecycle.

CodeWorkerContentWorkerSocialWorkerOpsWorkerResearchWorker

Dev Team (12)

project-managerCodeWorker

task-executorCodeWorker

architectCodeWorker

backend-devCodeWorker

database-devCodeWorker

frontend-devCodeWorker

infra-devCodeWorker

motion-designerCodeWorker

code-reviewerCodeWorker

knowledge-curatorCodeWorker

product-plannerCodeWorker

dev-qa-testerCodeWorker

Content Team (5)

content-brandContentWorker

content-salesContentWorker

content-productContentWorker

content-legalContentWorker

content-sharedContentWorker

Utility (3)

frontend-designerOpsWorker

qa-testerOpsWorker

security-scannerOpsWorker

Custom (You Create) (4)

your-cfoOpsWorker

your-cmoOpsWorker

your-analystResearchWorker

your-socialSocialWorker

COMMANDS

Slash Commands

Organized into categories — from session management to deployment. Each command maps to a Claude skill.

Session

6

/

reanchor

Context reanchoring

/

checkpoint

Save thread state

/

handoff

Hand off to fresh session

/

nexttask

Scan and suggest next tasks

/

remember

Capture learnings

/

learn

Auto-capture learnings

Workers

3

/

run

Execute worker skills

/

newworker

Scaffold new worker

/

metrics

View worker metrics

Projects

3

/

prd

Plan project, generate PRD

/

run-project

Execute project (Ralph loop)

/

execute-task

Execute single task

Content

6

/

contentidea

Build content idea into posts

/

suggestposts

Research and suggest posts

/

scheduleposts

Choose what to post

/

preview-post

Preview, select images, approve

/

post-now

Post to social platforms

/

humanize

Remove AI writing patterns

Design

3

/

generateimage

Generate images

/

svg

Generate SVG graphics

/

design-iterate

A/B design iterations with git

System

6

/

hq-sync

Sync modules from manifest

/

cleanup

Audit and enforce policies

/

search

Search HQ (qmd-powered)

/

search-reindex

Reindex (semantic + full-text)

/

setup

Interactive setup wizard

/

exit-plan

Force exit plan mode

Deploy

2

/

deploy

Deploy to production

/

publish-kit

Publish content kit

KNOWLEDGE

Knowledge System

Three-tier knowledge architecture with semantic search. Workers load relevant knowledge automatically from their context.base paths.

qmd searchFast

BM25 keyword

Fast exact-match keyword search across all HQ content

qmd vsearchMedium

Semantic vector

Conceptual/meaning-based search using embeddings

qmd queryBest quality

Hybrid + re-ranking

BM25 + vector search combined with result re-ranking

Public (8)

Ralph/Coding methodology

workers/Worker framework

hq-core/Thread schema, HQ patterns

dev-team/Dev team patterns

design-styles/Image generation styles

loom/Agent patterns & architecture

projects/Project templates

ai-security/Security practices

Private (2)

your-tools/Your tool integrations

your-domain/Your domain knowledge

Company-Level (3)

company-a/

metricsschemaintegrations

company-b/

brandproductsmessaging

personal/

voicestyle

ARCHITECTURE

Knowledge Repos

Every knowledge folder is its own git repo, symlinked into HQ. Independent versioning, sharing, and publishing per knowledge base.

Transparent Reading

qmd, Glob, Grep, and Read all follow symlinks. No special handling needed — knowledge is accessed like any file.

Independent Versioning

Each knowledge base is its own git repo. Commit, push, and share independently from HQ.

Module Sync

modules/modules.yaml manages the repo inventory. /hq-sync keeps symlinks current.

Repo Mapping

knowledge/public/Ralph→repos/public/ralph-methodology/docs·public

knowledge/public/workers→repos/public/knowledge-workers·public

knowledge/public/hq-core→repos/public/knowledge-hq-core·public

companies/company-a/knowledge→repos/private/knowledge-company-a·private

companies/company-b/knowledge→repos/private/knowledge-company-b·private

ORCHESTRATION

The Ralph Loop

Simple for-loop orchestration: read PRD, pick task, spawn fresh agent, execute, verify, checkpoint, repeat.

One task at a time

No context overload. Each agent handles exactly one user story.

Fresh context per task

Sub-agent spawns with 100% clean context. Orchestrator stays lean (<30%).

Back pressure

Every task must pass typecheck, build, and tests before completion.

Simple loops

for-loop orchestration over complex frameworks. PRD is the source of truth.

Feature branches

All work on feature/{project-name}. Never commit to main. PR when done.

Auto-checkpoint

Thread state saved after every task — git context, worker state, files touched.

LIFECYCLE

Worker State Machine

Every worker follows the same lifecycle: load context, plan, execute, verify, checkpoint.

idle

Worker registered, awaiting invocation

loading

Loading context from knowledge bases and worker.yaml

planning

Analyzing task, determining approach

executing

Performing the skill — writing code, generating reports

verifying

Running typecheck, build, tests — back pressure gate

post_hook

Auto-checkpoint, metrics logging, thread save

completed

Task done, output delivered, state persisted

error

Failure caught — can retry or escalate

SKILLS

Skill Execution Flow

Skills are atomic, verifiable operations with typed inputs and outputs. Mutating skills trigger automatic state management.

Skill Schema

Field	Type	Description
id	string	Unique skill identifier
interface.inputs	array	Typed parameters: name, type, required, default
interface.outputs	array	Result types with destination paths
verification	array	Shell commands that must pass before completion
mutating	boolean	If true, triggers auto-checkpoint + metrics logging

PERSISTENCE

Thread Lifecycle

Sessions are captured as thread JSON files with full git context, worker state, and continuation hints.

Thread Schema

thread_id·T-20260123-143052-slug·Unique timestamped identifier

git.branch·feature/my-project·Active branch at time of save

git.commits_made·["abc1234: feat: ..."]·Commits made during session

worker.id·backend-dev·Worker that executed the skill

files_touched·["workspace/reports/..."]·All files modified during session

next_steps·["Run tests", "Deploy"]·Continuation hints for next session

LEARNING

Learning System

Rules are captured from task execution and injected directly into the files they govern. The system gets smarter with every session.

Tier 1

Highest

/remember (user correction)

Immediate injection into governing file

Tier 2

High

/learn (auto-capture post-task)

Classified and injected into relevant file

Tier 3

Normal

Event log append

workspace/learnings/*.json (analysis/dedup)

Injection Targets

Worker→worker.yaml instructions: block

Command→command .md ## Rules section

Knowledge→Relevant knowledge file (committed to repo)

Global→CLAUDE.md ## Learned Rules

READY?

Build your HQ today

One command to install. Open source. Free forever. Or work with Indigo to get a custom HQ for your team.

FOR DEVELOPERS

Install & Customize

npx create-hq

17 commands, 26 workers, 5 knowledge bases — ready in 30 seconds. Customize your workers, add companies, and start orchestrating.

View on GitHub

FOR TEAMS & ENTERPRISES

Build With Indigo

Get a custom HQ built, configured, and handed off — worker architecture, knowledge bases, and orchestration pipelines your team actually uses.

HQ Advisory Services