Clue Tool

This repository owns the Codex / Claude Code SDK init tool and the client-side CI semantic generation runner.

The Clue product repository keeps SDKs, shared schemas, and API contracts. Tool implementation lives here so client repositories do not receive tool source code and the product repository does not become the tool runtime.

Commands

The public npm package is @clue-ai/cli. The binary exposed by that package is clue-ai, but first-run setup should not assume a global clue-ai install. Use npx -y @clue-ai/cli <command> unless .clue/setup-manifest.json explicitly provides a different invocation.

/clue-init
npx -y @clue-ai/cli setup --clue-api-key <ak_dev_or_prod_key> --clue-api-base-url <clue-api-base-url> --project-key <pk_dev_or_prod_key>
npx -y @clue-ai/cli setup-detect --repo .
npx -y @clue-ai/cli semantic-inventory --framework fastapi --backend-root-path backend --repo .
npx -y @clue-ai/cli semantic-workflow --framework fastapi --backend-root-path backend --repo .
npx -y @clue-ai/cli lifecycle-apply --plan clue-lifecycle-plan.json --repo .
npx -y @clue-ai/cli setup-check --framework fastapi --backend-root-path backend --repo . --require-sdk-lifecycle
npx -y @clue-ai/cli setup-doctor --local
npx -y @clue-ai/cli setup-watch --project-key <pk_dev_or_prod_key> --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-organization,event-sent]=<frontend-url>,backend:api[init,identify,set-organization,logout,event-sent]=<backend-url>
npx -y @clue-ai/cli init --request clue-init-request.json --repo .
npx -y @clue-ai/cli semantic-gen --request clue-semantic-request.json --repo .

/clue-init is the standard user-facing command for Codex and Claude Code wrappers. The command collects structured setup inputs and invokes the same tool request/report contract as clue-ai init.

npx -y @clue-ai/cli semantic-workflow mechanically writes the GitHub Actions workflow that passes the semantic generation request through CLUE_SEMANTIC_REQUEST_JSON at CI runtime and then runs npx -y @clue-ai/cli semantic-gen. Do not commit runtime semantic request files to client repositories.

npx -y @clue-ai/cli setup installs the target AI-tool skills and, when backend routes are detectable, also runs the machine-owned setup preparation:

• detects the FastAPI backend root
• writes .github/workflows/clue-semantic-snapshot.yml
• writes .clue/setup-manifest.json
• defers service-specific runtime env guidance to the Clue setup screen Step 2; the CLI does not write .env.clue

Route inventory is computed mechanically on demand and returned in stdout; it is not written to .clue/semantic-routes.json. The AI prompt should use generated manifest/workflow artifacts as inputs and should not hand-edit route inventory or semantic CI workflow files.

npx -y @clue-ai/cli setup-detect mechanically detects FastAPI route candidates and returns the framework, backend root path, service key candidate, route files, and route count before any AI interpretation.

npx -y @clue-ai/cli lifecycle-apply mechanically applies an AI-produced exact replacement plan after validating edit paths, lifecycle API names, blocked-plan status, canonical SDK usage, no broad tracking, no DOM clue tags, and claimed lifecycle insertion evidence.

npx -y @clue-ai/cli setup-check mechanically verifies installed setup skills, route inventory, semantic workflow shape, runtime request absence, obvious secret leaks, and SDK lifecycle presence when requested. With --require-sdk-lifecycle, a passing result is still static only; dependency installation, SDK imports in the target environments, app startup, and event delivery remain required before setup can be called complete.

npx -y @clue-ai/cli setup-doctor --local checks API connectivity before user-operated lifecycle verification. It verifies three setup hops:

1. frontend SDK to Clue /api/v1/ingest/browser-tokens (short-lived token issuance — the frontend SDK calls the Clue backend directly using the public project key and request Origin, no customer-backend proxy in between).
2. customer frontend to Clue canonical browser observation batch ingest with the short-lived token.
3. customer backend to Clue /api/v1/ingest/backend (server-side ingest with CLUE_API_KEY).

It also scans the customer backend for /api/v1/clue/* proxy routes and emits a blocking error requiring removal (customer_backend_clue_route_forbidden). Setup-doctor does not replace setup-watch because it does not exercise real login, organization, or logout flows.

npx -y @clue-ai/cli setup-watch polls the Clue API setup-check endpoint in remote mode while you operate the service. --clue-api-base-url is the Clue API URL, not the customer frontend URL. Use --watch-targets to list every frontend/backend producer by service key and the lifecycle checks expected for that service, for example frontend:web[init,identify,set-organization,event-sent]=<frontend-url>,backend:api[init,identify,set-organization,logout,event-sent]=<backend-url>. Do not assume localhost ports; use the actual URLs printed by the repository's dev scripts or configured in its local env. In --local mode, the watcher stays open until the expected lifecycle checks pass or you stop it with Ctrl+C. The frontend/backend endpoint URLs printed by the command are local Clue receiver endpoints; configure the customer's Clue SDK ingest endpoint to those receiver URLs while testing. Local mode does not ask for or health-check customer service URLs. It prints a per-service Clue lifecycle checklist and only prints a new snapshot when the observed state changes.

npx -y @clue-ai/cli setup reads the Clue API base URL, project key, and API key from setup screen flags, detects local services, writes .clue/setup-manifest.json, and points runtime env setup to the Clue setup screen Step 2.

Required Environment

• CLUE_API_KEY: Clue setup screen issues this value.
• CLUE_AI_PROVIDER_API_KEY: the customer's OpenAI API key for the semantic generation CI run. Create one at https://platform.openai.com/api-keys.
• CLUE_AI_PROVIDER: always openai. semantic-gen is OpenAI-only.
• CLUE_AI_MODEL: defaults to gpt-5.4-mini. Other supported OpenAI models: gpt-5.5 (accuracy), gpt-5.4-nano (cost).

npx -y @clue-ai/cli semantic-gen runs semantic AI inside the customer repository CI with the customer-configured AI provider key. Clue receives only the final privacy-safe semantic snapshot.

Boundaries

• The tool may read allowed source paths in the client repository.
• The tool must not read .env, secrets, logs, dumps, build output, or vendor directories.
• Semantic generation calls the configured AI provider from customer CI.
• Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs are not sent to Clue.
• clue-layer.yaml and clue-semantic.yaml are not committed to client repositories.