_refs
GitHub ↗
Free · Open source · MIT macOS, Linux, Windows

Design references your agent can read.

_refs is a local library for design references. You collect images onto boards and write down what each board is for. Your coding agent reads the same boards, as plain files on your machine.

View on GitHub ↗

Copies an install prompt. Paste it into Claude Code, Codex, Cursor or any coding agent.

  • Plain files on your machine
  • No account, no database
  • Tagging optional, off by default

01 — How it works

Collect. Brief. Hand off.

A moodboard shows an agent what you like, but not why. On _refs every board carries a short brief and every image a note: what it is for, what to take from it, what to ignore. That is the part an agent can act on.

  1. Step 1

    Collect

    Drop or paste images and links into the app, or add them from the command line. Each image is stored once, however many boards it sits on.

  2. Step 2

    Brief

    Say what the board is for. Give any image a note for this board only: take the grid, not the red. Mark the ones that matter most as key.

  3. Step 3

    Hand off

    Press Agent on a board. It copies a prompt with the folder's path and how to read it. Paste it into your agent, then say what you want designed.

out/acme-rebrand/editorial-grid/refs.yaml + 7 images 
board: acme-rebrand/editorial-grid
brief: Grid and type hierarchy only. Ignore the colour.
parent_briefs:
  - board: acme-rebrand
    brief: The client is a bank. Sober.
refs:
  - id: 3fa9c1d2e4b7
    file: grid-poster-3fa9c1.jpg
    key: true
    note: Strong six-column rhythm.
    board_note: Take the column rhythm, not the red.
    tags: [poster, grid]
    machine_tags: [typographic, two-colour, asymmetric]
    source: https://example.com/poster

Every board is also written out as a folder: the images, plus one refs.yaml. The agent reads the lines in ink first. The parent board's brief comes along, key refs come first, and a note for this board outranks the general one.

02 — What you get

Plain files. Nothing to rent.

No account, no database, no server. Your library is a folder you can back up, sync or put under version control, and it stays out of the repository: references are other people's work.

  • Boards that nest

    acme-rebrand/editorial-grid is a board inside a board. The agent gets the parent's brief too.

  • One image, many boards

    Stored once and named by its content, with a different note on each board. Dropping it twice never duplicates it.

  • A grid for looking

    Three, four or six columns, tag filters, light and dark, and a popover for notes.

  • An Agent button

    On every board and every image. It copies a prompt with the right paths, ready to paste.

  • Optional tagging

    A vision model you choose tags each image in the background: Ollama, LM Studio, oMLX, Claude, Codex or your own adapter. Off until you set it up.

  • A CLI for agents

    Add, move, show and export from the command line, with --json, so an agent can file the references it finds while it works.

03 — Install

Give this to your agent.

Paste this into Claude Code, Codex, Cursor or whichever agent you use. It clones the repository, follows its AGENTS.md, and asks you before anything optional. You paste one thing.

Install prompt 
Install _refs for me. It is a local library for design references: https://github.com/ccmdesign/refs

1. Ask me which folder to put it in, unless I already said. Clone https://github.com/ccmdesign/refs there.
2. Open AGENTS.md in the repository and follow it step by step. It is the source of truth: if anything here disagrees with it, AGENTS.md wins.
3. It needs Node 22.18 or newer, and pnpm through `corepack enable`. If my Node is older, stop and tell me. Don't install Node yourself.
4. Ask me before anything optional: image tagging (and which tagger) and the agent skill. Never choose a paid, hosted tagger unless I ask for one. Never invent an API key, write one into a file, or ask me to paste one into the chat.
5. If a step fails, run `pnpm refs doctor` in the app folder, fix what it reports, and run it again.
6. When it works, start the app with `pnpm dev` and tell me the URL (http://localhost:3210 unless REFS_PORT is set).

Or by hand

git clone https://github.com/ccmdesign/refs
cd refs/app
corepack enable
pnpm install
pnpm refs setup
pnpm dev

Needs Node 22.18 or newer. Then open localhost:3210. If something is off, pnpm refs doctor says what and how to fix it.

Good to know

  • It runs on your own machine. There is no login, so don't expose its port to a network.
  • Your library is ignored by git. Keep references private unless you have the right to share them.
  • Not there yet: a browser extension, video and PDF references, and ordering refs by hand.