Atlas Research

atlas-research

Run a deep-research query via this repo's atlas CLI and return the cited markdown report.

Atlas runs a fixed research lifecycle: it scopes the question into search angles, fetches sources through Steel, extracts verbatim-quoted claims, chases gaps with a lead agent, adversarially verifies every claim with independent voters, and synthesizes a cited Markdown report from the claims that survive. The harness provides web/search/browser tools, runtime limits, caching, and progress events.

Step 1 — Get the question

If the user's invocation includes text after /atlas-research, that's the question — use it verbatim.

If the invocation is empty, output this usage line and stop:

Usage: /atlas-research <your question>

Example: /atlas-research What changed when Cloudflare Durable Objects added SQLite?

Step 2 — Verify keys are in the shell env

if { [ -n "$ANTHROPIC_API_KEY" ] || [ -n "$ATLAS_ANTHROPIC_API_KEY" ] || \
     [ -n "$OPENAI_API_KEY" ] || [ -n "$ATLAS_OPENAI_API_KEY" ]; } && \
   { [ -n "$STEEL_API_KEY" ] || [ -n "$ATLAS_STEEL_API_KEY" ]; }; then
  echo ok
else
  echo missing
fi

If missing, stop and tell the user:

Atlas needs Steel plus one model-provider API key set in your shell:

export ANTHROPIC_API_KEY=sk-ant-...   # https://console.anthropic.com
# or:
export ATLAS_PROVIDER=openai
export OPENAI_API_KEY=sk-...          # https://platform.openai.com
export STEEL_API_KEY=sk_...           # https://app.steel.dev

Restart this Claude Code session after exporting them, then re-run /atlas-research.

Never ask the user to paste API keys into the chat — keys do not belong in transcripts. The env-var path is the only supported way.

Step 3 — Confirm we're in the atlas repo

test -f src/cli.ts && test -f package.json && echo ok || echo not-atlas

If not-atlas, tell the user to cd into the atlas repo and re-run. Don't try to install or locate it.

Step 4 — Run atlas

Use tsx so no build step is required. Capture stderr to a log file and write the markdown to a temp file via --out:

REPORT=$(mktemp -t atlas-XXXXXX).md
ATLAS_LOG=$(mktemp -t atlas-events-XXXXXX).log
npx tsx src/cli.ts '<QUESTION>' [extra flags] --out "$REPORT" 2> "$ATLAS_LOG"
echo "REPORT=$REPORT"
echo "LOG=$ATLAS_LOG"

Bash tool timeout: 600000 (10 min — the max). Typical runs land in 1–4 min.

Quoting: wrap <QUESTION> in single quotes. If the question itself contains a single quote, escape it with the ''' dance: it'''s great.

Defaults are fine. Only add flags that the current CLI supports and the user clearly asked for:

If atlas exits non-zero, the user-facing message is the last atlas: ... line in $ATLAS_LOG. Show that and stop — don't retry blindly.

Step 5 — Return the report

tail -5 "$ATLAS_LOG"   # includes the ✓ done — N verified claims from M cited sources line, token usage, and wrote path

Then Read $REPORT and present it to the user as:

Atlas summary: <the ✓ done line, and token usage line if present, stripped of ANSI color codes>

If the report is very long (>20k chars), still include it fully — the user asked for it. Don't truncate.

Clean up afterward:

rm -f "$REPORT" "$ATLAS_LOG"

Boundaries

• Only runs from the atlas repo root (where src/cli.ts lives).
• One atlas job at a time — they share model-provider / Steel rate limits.
• Never log or echo API keys back to chat.
• Report only the stats Atlas actually prints — the ✓ done line gives verified-claim and cited-source counts plus token usage. Quote those; never invent or inflate them.