oracle

A Claude Code subagent that answers "how does library X work" questions from a curated reference list instead of blind web searches. It comes with an MCP server that stores, per library, its docs domains, GitHub repo and your own notes. The agent looks the library up there first, then reads the docs or the cloned source.

Install

Install the oracle binary with mise:

mise use -g github:fdarian/oracle

Then copy the agent into place:

curl -fsSL https://raw.githubusercontent.com/fdarian/oracle/main/agents/oracle.md -o ~/.claude/agents/oracle.md

Edit ~/.claude/agents/oracle.md and replace the placeholder ORACLE_DB_PATH in the mcpServers frontmatter with an absolute path, where your reference list is stored. It's a SQLite file created on first run.

Restart Claude Code.

Related MCP server: Context7 MCP Clone

Use

Ask Claude a library question and it delegates to the oracle agent, or call it directly: "ask oracle how drizzle's pgTable options work". Unknown libraries are added to the list (domains, repo, an index note) after the first lookup, so the next one is instant.

Sync across machines

The database is local-only by default. To share it between machines, point it at a libSQL server: Turso Cloud (free tier is plenty) or a self-hosted sqld.

1. Add the server to the agent's env, next to ORACLE_DB_PATH:

   ORACLE_SYNC_URL: "libsql://<db>.turso.io"
   ORACLE_SYNC_TOKEN: "<token>"   # omit if the server has no auth

2. On the machine that already has data, copy it to the server once, with the same three variables set in your shell:

   oracle sync enable

   This uploads every reference, moves the local file to oracle.db.bak, and replaces it with a synced replica.

3. On other machines, set the same variables with any ORACLE_DB_PATH. The replica fills itself from the server on first start.

Reads are local and each agent run pulls the latest state on start. Writes go to the server, so two agents never overwrite each other's file.

• A synced database needs its server to open. Offline, the oracle tools return an error instead of stale data.

• The token sits in plain text in ~/.claude/agents/oracle.md.

• Unsetting ORACLE_SYNC_URL on a replica is refused, since local writes would fork it from the server. To go back to local-only, restore oracle.db.bak; it lacks anything written since sync was enabled.

Earlier versions stored the list in a JSON file. Import it once:

ORACLE_DB_PATH=/path/to/oracle.db oracle import /path/to/references.json

Existing references with the same name are replaced.

Development

Needs bun and pnpm.

pnpm install
pnpm format        # biome
pnpm check:type
pnpm check:lint
pnpm build         # compiles dist/oracle for the current platform

See AGENTS.md for the layout.

License

MIT