Real source code for coding agents.

Ask a coding agent how a library works and it answers from training data that is months
old. Tell it to go look, and the best it finds is a minified bundle in node_modules.
Private repositories are worse still. The model has never seen that code at all.

refs hands it the source. It keeps read-only git checkouts of the repositories you care
about, so your agent reads the code that actually ships.

How it works

You say "add zod as a ref". refs resolves the npm package to its git repository, clones
it, and works out how the project tags its releases.

After that the agent has zod's own files on disk. "How does zod implement codecs" is
answered by reading them. For "what changed between v4.0.1 and v4.1.0", the agent resolves
both versions to their tags and diffs them in the same clone.

https and ssh URLs both work, including the git@host:path form, so a private repo or
a self-hosted forge is no different from a public one. Private ones use the credentials
your git already has, since refs refuses to take any in the URL. npm is just a convenient
way to name a repository you would otherwise paste a URL for.

The CLI and the skill

refs is two pieces: a command-line tool, and a skill for your agent. It is written for
Claude Code and Codex, and skills add installs it into other agents' directories too.

The CLI does the deterministic work of cloning, syncing, and resolving a question to the
right path or tag. The skill teaches your agent when to reach for the CLI and how to use
what comes back.

The skill runs only when you ask for it, in both agents. In Claude Code that also keeps
its description out of the context window until then, so the questions that need no source
code cost you nothing.

Using it

Invoke the skill explicitly. It will not activate by itself.

/refs add zod as a ref
/refs how does zod implement codecs

Use /refs in Claude Code and $refs in Codex. Adding a ref pauses for your approval
before it enters your configuration. The clone happens first, so what the agent shows you
is filled in from the real repository rather than guessed. From then on it finds the right
checkout, reads the source, and runs refs sync when one has gone stale.

Its answers name the file and line they came from, so you can check a claim instead of
trusting it. Where your terminal or app opens file links, they are clickable; where it
restricts access to the working directory, they stay plain text.

The agent route comes first because the agent can search the source, follow what it finds,
and talk with you about it. Driving the CLI by hand is still worth knowing, for scripting
or for checking what the agent did. docs/commands.md has every
command.

Install

1. The CLI

You need Node.js 24.2 or newer, and git. On Windows use
Git for Windows, because the read-only guards are sh scripts
and need the shell it ships with. The CLI behaves the same on all three platforms, and its
full test suite runs on each of them.

npm i -g @kaisers-io/refs
refs init       # seeds the refs home directory and the git hooks guard

2. The agent skill

npx skills add kaisers-io/refs

This installs into the current project. Pass -g to install once for every project, which
also prints a failure line for the few agents that have no global location. The install
itself still succeeds.

To install without skills add, copy the directory yourself:

mkdir -p ~/.claude/skills                                     # or ~/.codex/skills
cp -r <path-to-this-repo>/skills/refs ~/.claude/skills/refs

Now check the whole setup:

refs doctor

Read-only is a promise, not a sandbox

Every checkout under sources/ is reference material. Agents are instructed never to edit,
commit or push inside one, and refs installs git hooks that reject both. When a checkout
gets dirty anyway, refs sync restores it.

The hooks are a backstop against mistakes, not a security boundary. A determined local
process can still write into a checkout.

Documentation

docs/commands.md covers every command, its flags, its --json
output and its exit codes.
docs/configuration.md explains config.toml, state.json,
the per-ref settings and REFS_HOME.
CONTRIBUTING.md has the toolchain, the local development loop and
what a pull request has to pass.
SECURITY.md is what to read before reporting a vulnerability.

MIT licensed. See LICENSE.