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: hq-cli needs ≥20; create-hq needs ≥22.13. Node 22.13+ covers every repo.
pnpm 10 for hq-cli, hq-cloud, hq-desktop-app, hq-console, and hq-pro. create-hq, hq-deploy, and this docs site use npm.
Git. The GitHub CLI (gh) is optional but used in the examples below.
An agent runtime (Claude Code, Codex, or Grok; Cursor gets a rules file only) for scaffold and worker development. Optional for CLI and app work.
Rust toolchain, only for hq-desktop-app.
AWS CLI v2, only for the cloud apps (hq-pro, hq-deploy).
qmd, optional, for search testing: npm install -g @tobilu/qmd.

Clone the repo you need

# the hq CLI
gh repo clone indigoai-us/hq-cli && cd hq-cli && pnpm install

# the sync engine
gh repo clone indigoai-us/hq-cloud && cd hq-cloud && pnpm install

# the installer
gh repo clone indigoai-us/create-hq && cd create-hq && npm ci

# the desktop app
gh repo clone indigoai-us/hq-desktop-app && cd hq-desktop-app && pnpm install

hq-core changes are made in indigoai-us/hq-core-staging, not in hq-core directly. See Contributing.

Build & typecheck

In a TypeScript package repo (hq-cli, hq-cloud, create-hq):

pnpm run build       # (npm run build in create-hq)
pnpm run typecheck
pnpm test            # Vitest

hq-cli depends on the published @indigoai-us/hq-cloud. To develop the two together, point hq-cli at your local hq-cloud checkout (for example with pnpm link) instead of the npm version.

Run individual surfaces

hq-cli (the `hq` command)

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

hq-cloud (library)

Build only. It is consumed by hq-cli, and the desktop app runs it through the hq-sync-runner binary.

create-hq (test the installer)

cd create-hq
npm run build
node dist/index.js ~/test-hq --local-template ../hq-core-staging

--local-template scaffolds from a local hq-core checkout instead of downloading the latest release. Without it, npx create-hq ~/test-hq installs the published scaffold.

hq-desktop-app

cd hq-desktop-app/apps/sync
pnpm tauri dev

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

cd hq-console && pnpm dev      # Next.js on :3400
cd hq-pro && pnpm 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 and Cognito settings; the CLI and desktop app use the Cognito session created by hq login or the desktop sign-in. Create .env files locally (they are gitignored), or use hq run / hq secrets exec to inject 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-staging` → `hq-core`	scaffold release	—	GitHub release
`create-hq`	`npx create-hq`	`npm run build`	`dist/`
`hq-cli`	`@indigoai-us/hq-cli`	`pnpm run build`	`dist/`
`hq-cloud`	`@indigoai-us/hq-cloud`	`pnpm run build`	`dist/`
`hq-desktop-app`	macOS and Windows app	`pnpm tauri dev` (in `apps/sync`)	installers + updater manifests
`hq-console`	Next.js app	`pnpm dev`	`.next/`
`hq-pro`	SST app	`pnpm dev`	SST stack
`hq-deploy`	AWS data plane	`npm run dev`	Lambda bundle
`indigo-docs`	this site	`npm run dev`	`dist/` (Astro)