Causalist

Causalist — typed graph queries for any repo

You have a CLI named causalist on PATH that queries a typed causal graph for the active project, and creates new projects on the user's Causalist account. Every command returns structured JSON in one round-trip — faster and cheaper than re-grepping the repo.

Setup (one time)

The user mints an API key in causalist.xyz/app/settings and runs:

causalist login --api-key cspl_live_…

After that, every causalist command on this machine is authenticated to their account. No pair codes, no browser tab, no 6-char dance. The key is stored at ~/.causalist/session.json. You can also export CAUSALIST_API_KEY=cspl_live_… for shell-wide use.

If causalist login hasn't been run, tell the user:

"Mint an API key at https://causalist.xyz/app/settings (sign in with GitHub first), then run causalist login --api-key <KEY>."

Creating a new project — full local build

When the user wants Causalist to map a new repo, you build it yourself, right here in the terminal:

causalist project create <github-url-or-owner/repo>

This runs the full 4-agent pipeline (Structure / Dependency / Semantic / Oracle) locally using $ANTHROPIC_API_KEY from the environment, then uploads the finished graph to the user's account via the API key. The user's /app tab (if open) saves the entry to their library on receipt.

You will see live progress: "Structure agent — classifying nodes ✓", "Dependency agent — extracting edges ✓", etc. The whole thing takes 20–60 seconds depending on repo size. The build completes before this command returns. Once it's done, the graph is real and queryable — you can immediately follow up with causalist blast, causalist tests, etc.

Required env

• ANTHROPIC_API_KEY — for the four agent calls
• CAUSALIST_API_KEY — auth to the user's Causalist account (auto-loaded from ~/.causalist/session.json after causalist login)
• GITHUB_TOKEN — only needed for private repos. The user's PAT or OAuth token. Public repos work without it.

When to use --no-build

causalist project create <repo> --no-build

If ANTHROPIC_API_KEY isn't set or the user explicitly wants the build to run in their browser (so the cost is on their browser-side key, not the terminal env), pass --no-build. The command returns immediately with a viewer URL the user opens to trigger the in-browser build.

Private repos

Both paths handle private repos. For the local-build path, set GITHUB_TOKEN to a PAT with repo scope. For the browser-build path, the user's GitHub OAuth cookie already has repo scope.

Don't lie about state

If you just ran causalist project create <repo>, the build has already happened — say so. If you ran it with --no-build, the build hasn't started — tell the user to open the URL.

Decision tree (which graph-query command for which question)

Every command:

• Defaults to JSON when stdout is piped (--json to force).
• Returns { ok: bool, summary: string, data?: ... }.
• Exits 0 on success, 1 on ok: false, 2 on fatal errors.

Composing

Pipe through jq to extract just the fields you need — don't dump whole results into context. Examples:

# Blast radius → just the affected file ids
causalist blast src/auth/login.ts --json | jq -r '.data.affected[].id'

# Affected tests for every file in the api layer
causalist layer api --json \
  | jq -r '.data.nodes[].id' \
  | xargs causalist tests --json \
  | jq '.data.affected'

# Verify an edge before trusting it
causalist verify src/auth/login.ts src/db/users.ts --json \
  | jq '.data[].verified'

Edge verification — important

Edges in the graph carry a verified flag:

• verified: true — confirmed by a real AST parse (Babel for JS/TS, import scan for Python). Treat as ground truth.
• verified: false — LLM-inferred. May be wrong. If it matters, confirm via causalist verify or a quick Read of the source.

Always check verified on edges that drive your decisions.

When the CLI fails

If causalist exits with code 2, surface the stderr message to the user and stop. Don't retry. Common causes:

• No API key → tell them to run causalist login --api-key <KEY> (mint at causalist.xyz/app/settings).
• Network error → confirm causalist.xyz is reachable.
• Node id not found → list candidates with causalist layer <best-guess>.

Legacy: pair-code path (rarely needed)

The 6-char causalist pair <code> flow still works, but it only covers the live browser-tab streaming case. For everything an agent does — querying the graph, creating projects — the API key is the better path. Don't suggest the pair-code dance unless the user explicitly asks for live browser-tab streaming.