Using Nisa from a coding agent

Nisa integrates as a subprocess CLI plus a skill file (nisa-cli). There is no MCP server. This page is the working contract once the skill is installed; the per-agent setup is on the Install page.

Install the CLI and the skill

One download into your agent’s skills folder — the per-agent paths for Claude Code, Codex, Cursor, Copilot CLI, Gemini CLI, Qwen Code, OpenCode, Kilo Code, Hermes Agent, OpenHands, and Replit Agent are on the Install page. For Claude Code:

curl -sSL https://api.rapidreview.io/cli/install | bash
mkdir -p ~/.claude/skills/nisa-cli
curl -sSL https://api.rapidreview.io/cli/skill -o ~/.claude/skills/nisa-cli/SKILL.md

The skill is public and edge-cached (~5 min) — safe to refetch on every start; it also carries the local-tool write contract (read before edit, error codes) and the recipes. Downloads: SKILL.md · install.sh. A self-healing guard the skill itself uses:

command -v nisa >/dev/null 2>&1 || { curl -sSL https://api.rapidreview.io/cli/install | bash; export PATH="$HOME/.local/bin:$PATH"; }

Give it a key

On the machine where you signed in through the chat’s browser flow, nothing to do: that flow stored a long-lived key in ~/.nisa/credentials.json and agents pick it up. Anywhere else, mint a named key and export it:

nisa login                          # once, as a human; OAuth must be the credential in use
nisa keys create "claude-code"      # prints rr_sk_… exactly once
export RAPIDREVIEW_KEY="rr_sk_..."

Or create it in the web app under Settings → API Keys — the path that always works (a key can’t manage keys: 403 API key management requires browser login). Keys are the only supported agent-mode auth: no refresh, no rotation, parallel-safe. Don’t share your OAuth credentials file with parallel agents — refresh tokens are one-shot. (The Python SDK reads RAPIDREVIEW_API_KEY, a different variable.)

Run headless

nisa --headless --envelope search --query "state space models" --query "Mamba" --max-results 20
nisa --headless ask --timeout 120 "Find recent work on retrieval reranking."

--headless disables every prompt; --envelope wraps direct-command JSON as {meta, data}.

Contract for the agent

Rule	Detail
Output	stdout = payload; stderr = session id, usage, errors. Parse stdout only
Chat-backed JSON	Always `ok`, `session_id`, `answer`, `arxiv_ids`, `tokens.cost_usd`, `duration_ms` — on failure too. Check the exit code, then `ok`
Order of preference	Direct first (`search`, `paper`, `related`, `excerpts`, `cite`); `ask` for judgment. Multi-query `search` beats one clever query
Concurrency	Direct: fan out freely. Chat-backed: 10/min · 100/hr per machine, and the backend can’t yet serve many concurrent turns — `ask-batch`, not a loop
Structured answers	`ask --schema '{"relevant":"boolean","reason":"string"}'`
Not for	General web search, non-arXiv sources, editing the user’s own paper
Diagnose	`nisa doctor --json`

Code	Meaning
`0`	success
`1`	error — bad input, rate-limit trip, or no credential in headless mode
`124`	`--timeout` reached; a partial answer is still returned and the session kept
`130`	interrupted with Ctrl-C
`141`	broken pipe (e.g. `\| head`); exits silently

Give it your files

nisa exec --workspace ./papers "Summarize the three PDFs here against arXiv:2401.12345"
nisa exec --workspace ./papers --allow-writes "Write notes.md with the comparison"

Read tools by default; --allow-writes adds file edits; --allow-exec adds shell.exec (60 s default, credential-shaped env scrubbed, cwd clamped — not a sandbox). For a browser-driven session use the bridge: Local folder access. Registering what you find in Merv: Using Nisa with Merv.

Start

Guides

Reference

Using Nisa from a coding agent

Contract for the agent

Give it your files

​Contract for the agent

​Give it your files

Contract for the agent

Give it your files