Commands
Workspace Commands
Run from the repository root with pnpm <command>.
Develop
| Command | Description |
|---|---|
pnpm dev | Build the SDK package, then start the showcase app on port 3000 (Next.js dev server). |
pnpm dev:coolaid | Build the SDK package, then start the AGI Coolaid Stand demo on port 3001 with Turbopack. |
pnpm dev:applied | Build the SDK package, then start the Applied AI Retail demo on port 3002 with Turbopack. |
pnpm dev:studio | Build the SDK package, then start the Start Studio onboarding wizard on port 3003 with Turbopack. |
pnpm --filter dashboard-reference dev | Start the reference dashboard server. |
Test
| Command | Description |
|---|---|
pnpm test | Build the SDK package, then run all unit tests with Vitest (single run). |
pnpm test:watch | Run Vitest in watch mode. |
pnpm test:coverage | Run tests with coverage thresholds (70/60/65/70). |
pnpm e2e | Build the SDK package, then run Playwright end-to-end tests for the showcase app. |
pnpm e2e:coolaid | Build the SDK package, then run Playwright end-to-end tests for the AGI Coolaid Stand demo. |
pnpm e2e:applied | Build the SDK package, then run Playwright end-to-end tests for the Applied AI Retail demo. |
pnpm e2e:studio | Build the SDK package, then run the Start Studio Playwright suite (~1.1s end-to-end). |
pnpm agent-evals | Run agent evaluation suite across CC / Codex / Antigravity providers. --report emits HTML cross-agent comparison. |
pnpm eval:showcase | Run gecx eval against the 22 reference scenarios with the committed baseline. |
STUDIO_FULL_TESTS=1 pnpm --filter start-studio test | Run the slow generated-repo-compiles suite: compose files for a representative matrix, write to tmpdir, pnpm install against the bundled tarball, pnpm typecheck, assert exit 0. Requires pnpm --filter start-studio pack-sdk first. |
Build
| Command | Description |
|---|---|
pnpm build:packages | Build the gecx-chat package only. |
pnpm build | Build gecx-chat then the showcase app. |
pnpm build:coolaid | Build gecx-chat then the AGI Coolaid Stand demo. |
pnpm build:applied | Build gecx-chat then the Applied AI Retail demo. |
pnpm build:studio | Build gecx-chat then the Start Studio wizard (Next.js standalone output for Cloud Run). |
Lint and Type Check
| Command | Description |
|---|---|
pnpm lint | Run ESLint across the entire workspace (zero warnings allowed). |
pnpm typecheck | Build the SDK package, then run tsc --noEmit across all packages. |
Size and Quality
| Command | Description |
|---|---|
pnpm size | Run size-limit on the gecx-chat package to check bundle size. |
pnpm quickstart-stopwatch | Verify the PRD quickstart snippet compiles against the built tarball. |
gecx CLI Commands
After installing gecx-chat, the package exposes a gecx binary. Run it with npx gecx <command> or from npm scripts.
doctor
npx gecx doctor [--token-endpoint <url>]
Diagnoses common integration issues: checks transport reachability, token endpoint health, CORS headers, and registered tool consistency. Surfaces ChatSdkError codes with remediation hints and docsUrl links. Run this when an integration starts misbehaving — it's the fastest way to convert a vague failure into a known error code.
verify
npx gecx verify [--cwd <dir>]
One-shot pre-flight check: runs tsc --noEmit, your test suite, and gecx doctor in sequence and returns a single non-zero exit code if anything fails. Use this in scaffolded apps and as the final step in CI for downstream integrations.
scaffold
npx gecx scaffold
Scaffolds a new integration project with the recommended file structure, ChatProvider setup, and a working proxy stub.
agent-pack
npx gecx agent-pack init --out .
Installs the agent-facing asset pack (CLAUDE.md, llms.txt, agent prompts) into a downstream project so coding agents can integrate the SDK without reading the full documentation tree. See docs/agent/agent-pack.md for details.
add/list/search
npx gecx list [--category <name>] [--json]
npx gecx search <query> [--json]
npx gecx add <recipe> [--out <dir>] [--json]
Lists, searches, and copies first-party recipes from the packaged recipes/ registry.
A2UI catalog: add ui:<name>, ui:doctor
npx gecx add ui:<name> [--out <dir>] [--no-telemetry]
npx gecx ui:doctor [--cwd <dir>]
npx gecx doctor --include-ui-catalog
Install one of 20 vetted composite A2UI surface presets (eta-promise, appointment-picker, confirmation-receipt, etc.). ui:doctor recomputes the sha256 integrity hash against the installed copy and reports ok, integrity_drift, outdated, or deprecated. doctor --include-ui-catalog rolls catalog checks into the global doctor pass.
eval
npx gecx eval <dir> [--baseline <file>] [--fail-on-regress] [--json] [--output <file>]
Runs scenario-replay tests against a ChatSession, scores them with deterministic and LLM-judge scorers, and emits a JSON report plus an optional regression gate. Sixteen scorers ship — thirteen deterministic + three LLM-judge (Anthropic / OpenAI / Gemini). See Evaluation and Eval CLI.
scaffold --with-voice
npx gecx scaffold --with-voice [--out <dir>]
Scaffolds a project with a voice page, a voice config block, and an app/api/voice-token/route.ts adapted from the proxy reference.
lab init
npx gecx lab init [--template commerce|support] [--out <dir>]
Generates a /lab route powered by the @gecx/lab package — agent-target picker (Claude Code / Codex / Antigravity), per-agent prompt variants, copy/verify/walkthrough buttons.
walkthrough capture / verify
npx gecx walkthrough capture --task=<task-id> [--driver=stub|playwright]
npx gecx walkthrough verify <manifest-path>
The cross-agent "show your work" artifact protocol. capture emits a PNG + manifest pair conforming to schemas/walkthrough.schema.json; verify round-trips the manifest. The stub driver works offline; the Playwright driver hook is ready for real browser captures.
validate
npx gecx validate [--path <glob>]
Static PCI/PII lint over the source tree. Flags Luhn-valid card literals, CVV literals, and unguarded payment-method fields. Comment-aware. Wire it into CI for commerce surfaces.
agent-pack (v2)
npx gecx agent-pack init [--all | --target claude-code|codex|antigravity | --mcp] [--out <dir>]
Installs agent-facing assets. --all writes pointer files (AGENTS.md, CLAUDE.md, GEMINI.md) plus skill copies under .claude/skills/, .agents/skills/, .agent/skills/. --target <agent> writes the subset for one agent. --mcp writes the MCP server config for each detected agent.
MCP server install
pnpm dlx gecx-chat-mcp-server --install
Registers the MCP server with whichever agents are detected on the machine, writing the right config file for each (.mcp.json, .codex/config.toml, mcp_servers.json) and merging non-destructively.
CI Pipeline
CI runs the following commands in order. All must pass before a PR can merge:
pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build:packages
pnpm size
pnpm e2e
pnpm e2e:coolaid
pnpm e2e:applied
docs/reference/commands.md