> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# agentsearch

> Turn any documentation site into a filesystem your agent can navigate with bash. One command, zero install.

**agentsearch** mounts any documentation site as a filesystem your agent can navigate with the tools it already knows: `tree`, `grep`, `cat`, `find`. No API key, no account, no install — one `npx` command and the docs are a directory you (or your agent) can `cd` into.

<Info>
  **Why a filesystem?** Agents were pre-trained on Unix. They already know `cat README.md` and `grep -r "auth" .`. Giving them a filesystem instead of yet another MCP tool means zero schema overhead, zero context tax, and no new abstractions to learn.
</Info>

***

## Quick start

### Browse any docs site

```bash theme={null}
npx nia-docs https://docs.trynia.ai
```

That's the entire interface. The first call indexes the site (cold index \~30–120s, then \~2s on subsequent visits and \~100ms when locally cached). You're dropped into a bash shell scoped to that site:

```text theme={null}
indexed 47 pages from docs.trynia.ai
type 'help' for commands, or try: tree, cat welcome.md, grep oracle

trynia $ tree -L 1
trynia $ cat welcome.md
trynia $ grep -rl "oracle" .
```

All standard Unix tools work in-process: `tree`, `ls`, `cat`, `grep`, `find`, `head`, `tail`, `wc`, `cd`, pipes, aliases. The shell starts in the docs root — use `.` for relative paths.

### One-shot mode (for agents and scripts)

Use `-c` to run a single command and exit. This is the mode most agents use:

```bash theme={null}
# Find pages mentioning a topic
npx nia-docs https://docs.stripe.com -c "grep -rl 'webhook signature' ."

# Read a specific page
npx nia-docs https://docs.stripe.com -c "cat api/charges/create.md"

# Find all markdown files
npx nia-docs https://docs.stripe.com -c "find . -name '*.md'"

# List top-level structure
npx nia-docs https://docs.stripe.com -c "tree -L 1"
```

***

## Wire it into your agent

agentsearch ships with two helpers — `setup` and `agents` — that generate an agent-ready instruction snippet for any URL. Pipe the snippet into your agent or append it to its rules file.

### Claude Code

```bash theme={null}
npx nia-docs setup https://docs.stripe.com | claude
```

### Codex / OpenAI

```bash theme={null}
codex "$(npx nia-docs setup https://docs.stripe.com)"
```

### Append to AGENTS.md / CLAUDE.md / .cursorrules

```bash theme={null}
npx nia-docs agents https://docs.stripe.com >> AGENTS.md
```

### OpenCode

```bash theme={null}
opencode --prompt "$(npx nia-docs setup https://docs.stripe.com)"
```

### Gemini CLI

```bash theme={null}
gemini "$(npx nia-docs setup https://docs.stripe.com)"
```

### GitHub Copilot CLI

```bash theme={null}
copilot -i "$(npx nia-docs setup https://docs.stripe.com)"
```

Works with anything that reads an instructions file or supports skills — Claude Code, Cursor, Copilot, Codex, Gemini CLI, OpenCode, and more.

After setup, the agent receives a short snippet like this:

```markdown theme={null}
## Stripe Docs

Before working on a Stripe feature, check the docs via `npx nia-docs https://docs.stripe.com`.

    # Search for a topic
    npx nia-docs https://docs.stripe.com -c "grep -rl 'webhook' ."

    # Read a specific page
    npx nia-docs https://docs.stripe.com -c "cat getting-started.md"
```

When the agent needs to verify how something works, it runs the command, gets the actual current documentation, and writes code against *that* — not against whatever was in its training data.

***

## How it works

Three pieces, no magic.

### 1. Index

The backend crawls the site once. It respects `llms.txt`, auto-detects OpenAPI specs (which appear under `/api-spec/` in the filesystem), and normalizes URL paths so the filesystem mirrors how you *think* about the docs, not how the URLs are structured. For example, `https://better-auth.com/docs/installation` becomes `/installation.md`, not `/docs/installation.md`.

Indexes are namespaced by canonical site ID and **shared across all users** — index `docs.stripe.com` once, everyone benefits. Public docs only, unauthenticated by design.

### 2. Serve

The backend exposes filesystem operations as HTTP endpoints (`load`, `read`, `grep`, `ls`, `tree`, `find`). Everything is gzip-compressed. The CLI maintains a disk cache at `~/.cache/nia-docs/` keyed by namespace and `indexed_at` timestamp. Backend cache TTL is 5 days.

### 3. Shell

The shell runs **on the client**, not in a container or VM. agentsearch uses `just-bash` — a TypeScript bash reimplementation that supports `grep`, `cat`, `ls`, `find`, `cd`, `tree`, pipes, and aliases. The whole filesystem is an in-memory JavaScript object, so a `grep -r "webhook" .` over 500 pages completes in milliseconds because it's pure string matching in memory.

Result:

* **\~100ms** to boot when locally cached
* **\~2s** when the site is already indexed on the backend
* **\~30–120s** for a cold index of a brand-new site
* **Zero per-session compute** on the server

***

## Telemetry

Every command run inside a shell session is logged: command name, success/failure, duration, file count for greps. Not the content — just the patterns. We use this to understand how agents navigate docs so we can keep making the filesystem better.

Opt out:

```bash theme={null}
NIA_DOCS_TELEMETRY=off npx nia-docs https://docs.example.com
```

***

## When to use agentsearch vs. other Nia products

| Use this                                            | If you want                                                                                                             |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **agentsearch**                                     | Zero-install, public docs only, no account. Best for ad-hoc lookups and dropping any agent into fresh docs in one line. |
| **[Nia CLI](/integrations/installation/cli)**       | Persistent indexes, private repos and folders, oracle/tracer research, full platform access.                            |
| **[MCP Server](/integrations/installation/mcp)**    | IDE-native integration via the Model Context Protocol. Best for in-editor agents.                                       |
| **[Agent Skill](/integrations/installation/skill)** | Single-file skill that calls the Nia API directly. Best for lightweight setups.                                         |

agentsearch is the lightest possible front door to Nia — public docs, zero state. Graduate to the full platform when you need persistent indexes, private sources, or research workflows.

***

## Links

<CardGroup cols={2}>
  <Card title="agentsearch.sh" icon="globe" href="https://www.agentsearch.sh/">
    Manifesto, live demo, and source
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/nozomio-labs">
    nia-docs source code
  </Card>
</CardGroup>

***

<Warning>
  **Need help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) for support.
</Warning>