Local Setup

HQ is split across several independently versioned repos. There is no single clone — pick the repo for the surface you’re working on. See the Ecosystem & Repo Map for the full list.

Prerequisites

• Node.js 20+ (the hq-cli repo requires Node ≥22)
• npm 9+ (ships with Node) or pnpm 10 (used by hq-console / hq-pro)
• Git and the GitHub CLI (gh)
• Claude Code CLI — for scaffold/worker development
• Rust toolchain — only if you’re building the hq-sync desktop app
• AWS CLI v2 — only for the cloud apps (hq-pro, hq-deploy)
• qmd — for search testing (brew install tobi/tap/qmd)

Clone the repo you need

Each repo stands alone — clone just the one you’re working on.

# the hq CLI
gh repo clone indigoai-us/hq-cli && cd hq-cli && npm ci

# the sync engine
gh repo clone indigoai-us/hq-cloud && cd hq-cloud && npm ci

# the scaffold / starter kit
gh repo clone indigoai-us/hq-core && cd hq-core

# the menubar app
gh repo clone indigoai-us/hq-sync && cd hq-sync && npm ci

Build & typecheck

Inside a TypeScript package repo (e.g. hq-cli, hq-cloud):

npm run build       # tsc → dist/
npm run typecheck   # tsc --noEmit
npm test            # Vitest

hq-cli depends on the published @indigoai-us/hq-cloud. To develop the two together, use npm link (or an overrides/file: reference) to point hq-cli at your local hq-cloud checkout rather than the npm version.

Run individual surfaces

hq-cli (the hq command)

cd hq-cli
npm run build
node dist/index.js modules list

hq-cloud (library — no standalone run)

Build only; consumed by hq-cli and driven by the hq-sync app via its hq-sync-runner binary.

hq-core (test the scaffold)

# from anywhere, scaffold a throwaway HQ instance
npx create-hq ~/test-hq

hq-sync (desktop dev)

cd hq-sync
npm run tauri dev   # launches the menubar app with HMR

hq-console / hq-pro / hq-deploy (cloud apps)

cd hq-console && pnpm dev      # Next.js admin UI on :3400
cd hq-pro && pnpm sst dev      # SST dev against your AWS stage
cd hq-deploy && npm run dev    # Hono API via tsx watch

This docs site (indigo-docs)

gh repo clone indigoai-us/indigo-docs && cd indigo-docs && npm ci
npm run dev   # Starlight on http://localhost:4321

Environment variables

Each repo declares its own config. The cloud apps read AWS + Cognito settings; the desktop and CLI tools read sync credentials provisioned by hq-pro. Create .env files locally (they are gitignored), or use hq run / hq secrets exec to inject schema-defined secrets without printing them.

Variable	Repo	Description
AWS_PROFILE	hq-pro, hq-deploy	AWS credentials profile
AWS_REGION	hq-pro, hq-deploy	AWS region (default: us-east-1)
NEXTAUTH_* / Cognito IDs	hq-console	OIDC against the shared identity pool

Repo reference

Repo	Ships as	Dev command	Build output
hq-core	npx create-hq scaffold	—	scaffold seed
hq-cli	@indigoai-us/hq-cli	npm run build	dist/
hq-cloud	@indigoai-us/hq-cloud	npm run build	dist/
hq-sync	macOS app	npm run tauri dev	DMG / latest.json
hq-console	Next.js app	pnpm dev	.next/
hq-pro	SST app	pnpm sst dev	SST stack
hq-deploy	AWS data plane	npm run dev	Lambda bundle
indigo-docs	this site	npm run dev	dist/ (Astro)