pc-style/librarian/librarian

Librarian

Use the hosted Librarian service to get fast, source-backed findings about GitHub repositories and public web pages.

Service domain: https://librarian.pcstyle.dev

Librarian is modeled after Amp's librarian subagent: a constrained research worker with no local shell, filesystem, or secret access. In Amp, callers invoke librarian({ query: string }); this eve service accepts the same research task as the session message field.

The reverse-engineered Amp client exposes the Librarian tool names and client-side activity metadata, but not the server-side Librarian prompt text. Treat this service as a behavior-compatible research worker, not as a verbatim copy of Amp's private prompt.

Research tools

The service exposes the same GitHub and web tool surface Amp's Librarian uses internally:

• GitHub: read_github, search_github, commit_search, list_directory_github, list_repositories, glob_github, diff
• Web: web_search, read_web_page

Librarian runs those tools silently and returns a concise, source-backed answer with citations.

Authentication

Production requests require a valid, unexpired Vercel OIDC token authorized for the Librarian deployment's project and environment. Arbitrary bearer strings are rejected. Send the token on every request:

Authorization: Bearer <token>

Use LIBRARIAN_AUTH_TOKEN:

export LIBRARIAN_AUTH_TOKEN="<short-lived-vercel-oidc-token>"

LIBRARIAN_API_KEY remains a deprecated alias in the script, but it must contain the same valid OIDC token. The script fails closed when neither variable is set.

Quick usage

Prefer the bundled script when shell access is available. Librarian performs live repo/web research, so the command may run for 5+ minutes on broad or tool-heavy questions. Use a generous command timeout and do not assume it is stuck just because it is quiet while the remote agent works.

skills/librarian/scripts/ask-librarian.mjs "In the GitHub repo vercel/ai, where is createOpenAICompatible documented or implemented? Summarize with source paths."

Or from inside this skill directory:

./scripts/ask-librarian.mjs "What is Amp's TypeScript SDK for? Use https://ampcode.com/manual/sdk/typescript"

The script reads LIBRARIAN_AUTH_TOKEN (or the deprecated LIBRARIAN_API_KEY alias) and fails when no token is configured.

When to use Librarian

Use Librarian for:

• Questions about public GitHub repositories: files, directories, symbols, docs, package setup, examples, tests, commits, and diffs.
• Public web research where the answer should cite pages or docs.
• Repo-plus-web questions, such as whether a public SDK can plausibly integrate into a public project.
• Requests where a user wants a direct answer with evidence, not a browsing transcript.

Do not use Librarian for:

• Local filesystem inspection. Librarian cannot see your local checkout.
• Secret or environment-variable inspection.
• Private GitHub data unless the deployed service has been configured with an authorized connector for that user/session.
• Tasks that require making changes to a repository; Librarian researches and answers.

How to ask good questions

Include exact identifiers when possible:

• GitHub repo: owner/repo or a GitHub repository URL.
• File paths, symbols, package names, error strings, branch/ref names, or docs URLs.
• The answer shape you want: “summarize with source paths,” “return concise evidence,” “compare these two refs,” etc.

Good examples:

In the GitHub repo charmbracelet/skate, what is the project and where are the CLI entrypoint or main command files? Give source-backed paths.

What is Amp's TypeScript SDK for, and what are the main integration surfaces? Use these sources: https://ampcode.com/manual/sdk/typescript https://ampcode.com/manual/sdk https://ampcode.com/news/typescript-sdk

In vercel/next.js, what files at the repository root indicate package manager and TypeScript setup? Return concise evidence.

API contract

The script uses eve's HTTP session API. Map Amp's librarian({ query }) call to { "message": "<query>" }:

1. POST /eve/v1/session with JSON { "message": "..." }.
2. Read sessionId from the response.
3. GET /eve/v1/session/:sessionId/stream and collect message.completed events.

Set these headers:

Content-Type: application/json
Authorization: Bearer ${LIBRARIAN_AUTH_TOKEN}

If implementing your own client, stream events are newline-delimited JSON. Return the last completed assistant message as Librarian's answer.