Hey Hey CLI

Development

From this directory:

pnpm dev

This runs the internal agent tool bridge from source (tsx src/index.tsx). By default (heyhey with no command), the CLI starts the loopback bridge and waits until Ctrl+C.

Other useful dev scripts:

• pnpm dev:build - TypeScript watch build to dist/
• pnpm dev:run - run the CLI directly from source
• pnpm openapi:context - print the Git worktree identity and resolved OpenAPI source

OpenAPI generation follows the current CLI worktree into the same-named OpenAPI worktree when one exists. From the main checkout, or when no matching OpenAPI worktree exists, it uses the main OpenAPI checkout. Set HEY_HEY_OPENAPI_ROOT to pin an explicit source; that override is authoritative. Generation and freshness checks print the selected source with an [openapi] diagnostic line.

Register heyhey command

From this directory:

pnpm run register

This builds dist/ and globally links the package so heyhey is available in your shell.

Verify

heyhey --help

Example invocation:

heyhey

Provider credential refresh:

heyhey credential refresh --provider codex --account default

Agent Auth Mode

Agent runs can authenticate in two ways:

• Stored credential mode: if a credential exists for the selected provider/account, Hey Hey binds it and injects auth env vars for the provider CLI.
• Native CLI auth mode: if no stored credential exists, Hey Hey launches the provider CLI without injected auth tokens so the CLI uses its own signed-in state (for example OAuth/login done directly in codex or claude).
• Codex invocation compatibility: Hey Hey uses codex exec --full-auto --json ... (and codex exec resume --full-auto --json ...) so orchestrated runs avoid interactive approval gates while staying sandboxed.
• Credential refresh command: use heyhey credential refresh --provider <claude|codex> [--account <accountId>] to store/replace provider API keys used by agent runs.

Agent Invocation Recovery Config

The CLI reads agent invocation recovery settings from:

• HEYHEY_AGENT_INVOCATION_CONFIG_PATH (explicit file path), or
• HEYHEY_CONFIG_DIR/agent-invocation.json, or
• default config location:
  • macOS: ~/Library/Application Support/heyhey/agent-invocation.json
  • Linux: ~/.config/heyhey/agent-invocation.json
  • Windows: %APPDATA%\\heyhey\\agent-invocation.json

Example:

{
  "agentInvocation": {
    "errorVerbosity": "compact",
    "model": "claude-sonnet-4-6",
    "reasoningEffort": "medium",
    "retryPolicies": {
      "claude": {
        "maxAttempts": 4,
        "initialDelayMs": 300,
        "maxDelayMs": 5000,
        "multiplier": 2,
        "jitterRatio": 0.2
      },
      "codex": {
        "maxAttempts": 3,
        "initialDelayMs": 250
      }
    }
  }
}

• model — default Claude model ID (e.g. claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001). Overridden per-run via the model field on LocalCreateRunRequest.
• reasoningEffort — default reasoning effort (low, medium, high). Overridden per-run via reasoningEffort on LocalCreateRunRequest.

Internal agent tool bridge

The loopback listener is an internal bridge for the local agent process. Its only HTTP paths are /mcp/submission-tools and /mcp/platform; browser REST routes, browser CORS, and browser-local WebSocket connections are not part of the CLI.

The bridge carries submission-tool actions and platform channel operations. Run output, lifecycle events, repository bindings, and provider identity remain process-local or platform-owned and are not exposed as a browser transport.

Unregister

From this directory:

pnpm run unregister