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 <key> --clue-api-base-url <url> --project-key <key> --environment dev
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 <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,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
• writes .env.clue when environment guidance is ready, after protecting it in .gitignore

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 the four setup hops: customer frontend to customer backend /api/v1/clue/browser-tokens, customer backend to Clue /api/v1/ingest/browser-tokens, customer frontend to Clue /api/v1/ingest/browser, and customer backend to Clue /api/v1/ingest/backend. It does not replace setup-watch because it does not exercise real login, account, 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-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,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 Clue values from the setup screen flags, detects local services, writes .clue/setup-manifest.json, and prints service-specific env blocks. Do not hand-write CLUE_SERVICE_KEY; use the value printed for each detected service.

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.