open-agent-glossary

Tool-agnostic glossary management for coding agents.

What it is

open-agent-glossary gives your agents a shared, authoritative vocabulary. You define project terms once in a glossary file, and the package makes those terms available across:

• Pi via extension — lazy-loads definitions into the system prompt when terms are mentioned
• Claude Code via hooks — injects matching definitions on every prompt
• Any MCP-capable agent via stdio MCP server — explicit lookup, add, edit, remove tools
• CLI scripts directly

Why it exists

Project acronyms and domain language drift fast. Agents either guess, ask again, or use the wrong meaning. open-agent-glossary fixes that by loading glossary terms from local files and making them available automatically or on demand, without bloating every turn's prompt.

Definitions are only injected when the current prompt references a matching glossary handle.

The goal is fast setup, one shared source of truth, and a great local UI for understanding what the glossary is doing.

Local UI

The local UI is the easiest way to understand what the glossary is doing and to manage entries without editing JSON by hand.

What the UI gives you

• Overview

  • glossary file discovery
  • merge order / precedence visualization
  • current session state
  • top-level lookup and injection metrics

• Glossary

  • searchable entries browser
  • list / split / cards layouts
  • inline add / edit / delete
  • alias and tag chip editors
  • live regex / pattern tester against sample text
  • provenance for where a term came from

• Usage

  • all-time vs current-session analytics
  • activity timeline
  • top terms by lookups or injections
  • detection of “looked up often, rarely injected” terms

• Config

  • config resolution stack
  • effective values with origin tracking
  • inline edits written back to the active config file

Start it

open-agent-glossary init
open-agent-glossary ui

Or:

open-agent-glossary ui --port 4319
open-agent-glossary ui --no-open
open-agent-glossary mcp-serve --open   # UI starts by default
open-agent-glossary mcp-serve --no-ui  # disable UI auto-start

By default it runs at:

http://127.0.0.1:7337

---

Background

This project is built on top of the schema and concepts from pi-glossary by @ruliana — an excellent Pi extension for glossary injection.

The goal here is to take the same idea further and make it tool-agnostic: one shared glossary file that works seamlessly across Pi, Claude Code, GitHub Copilot, and any MCP-capable agent. Your team maintains a single .agents/glossary.jsonl in the repo, and every agent — regardless of which tool a developer uses — picks it up automatically.

Existing glossary.json files from pi-glossary are 100% schema-compatible and can be dropped in without changes.

---

Install

npm install -g open-agent-glossary
# or use directly with
npx open-agent-glossary --help

---

60-second setup

1) Initialize the project

The fastest way to get started is now:

open-agent-glossary init

This scaffolds:

.open-agent-glossary/
  config.json
  glossary.json

• config.json contains sensible defaults
• glossary.json starts as an empty glossary ready to edit in the UI or via CLI

You can also initialize globally:

open-agent-glossary init --global

And overwrite existing files if needed:

open-agent-glossary init --force

2) Add glossary terms

You can now either:

• edit .open-agent-glossary/glossary.json directly
• use the local UI: open-agent-glossary ui
• or use the CLI:

open-agent-glossary add "BFF" "Backend For Frontend" --scope project --cwd .

You can still place glossaries in any supported path:

• .agents/glossary.json / .agents/glossary.jsonl ← recommended for shared team glossaries
• .pi/glossary.json / .pi/glossary.jsonl ← Pi-only
• .open-agent-glossary/glossary.json ← package-scoped project glossary created by init

Example:

[
  {
    "term": "BFF",
    "definition": "Backend For Frontend — a dedicated backend service tailored to a specific frontend application.",
    "aliases": ["backend for frontend", "bff-pattern"]
  },
  {
    "term": "DRY",
    "definition": "Don't Repeat Yourself — reduce repetition of information across a codebase.",
    "aliases": ["dont repeat yourself"]
  }
]

Or JSONL (preferred for team repos — easier diffs, fewer merge conflicts):

{"term":"BFF","definition":"Backend For Frontend — a dedicated backend service tailored to a specific frontend application.","aliases":["backend for frontend"]}
{"term":"DRY","definition":"Don't Repeat Yourself — reduce repetition of information across a codebase.","aliases":["dont repeat yourself"]}

3) Pick your integration

Pi

pi install npm:open-agent-glossary

Claude Code hook

Add to .claude/settings.json:

{
  "hooks": {
    "UserPrompt": [
      {
        "matcher": ".*",
        "command": "npx open-agent-glossary inject --prompt \"$USER_PROMPT\" --cwd \"$CWD\""
      }
    ]
  }
}

MCP (GitHub Copilot, Cursor, any MCP client)

Add to your MCP config:

{
  "mcpServers": {
    "glossary": {
      "command": "npx",
      "args": ["open-agent-glossary", "mcp-serve"]
    }
  }
}

That is enough to start.

---

Pi — Extension Details

Pi offers the closest to a native glossary experience because it runs as a Pi Extension bundled inside this package.

Install

pi install npm:open-agent-glossary

How It Works

1. On session start, the extension loads ~/.agents/glossary.json(.l), ~/.pi/agent/glossary.json(.l), .agents/glossary.json(.l), and .pi/glossary.json(.l) from the current project.
2. Project entries override global entries when they share the same term.
3. Before each agent turn, the extension scans the user's prompt for matching glossary terms, aliases, or explicit regex patterns.
4. If terms match, only terms not already loaded in the current session are injected into the system prompt.
5. Loaded glossary handles stay visible in the footer status for the rest of the session as Glossary: term, term.

What You Get

• Automatic lazy injection — definitions only appear when the prompt references a matching handle
• Term highlighting while typing
• Footer status showing loaded glossary handles
• glossary_lookup tool the LLM can call explicitly
• /glossary — show glossary load status
• /glossary reload — reload glossary files without restarting Pi

When Glossary Files Change

Pi keeps glossary entries in memory for the session. Run /glossary reload after editing, or start a new session.

---

Claude Code Hooks

On every prompt:

1. Glossary files are loaded from disk.
2. Terms are matched against the prompt.
3. Matching definitions are returned to the agent as context.

Changes to shared project glossaries are picked up automatically on the next prompt — no reload needed.

---

MCP

Use MCP when your agent supports MCP but not prompt hooks, or when you want explicit tools for lookup/edit/list.

Tools

Tool	Description
glossary_lookup	Look up a term
glossary_list	List all terms
glossary_add	Add an entry
glossary_edit	Edit an entry
glossary_remove	Remove an entry

The MCP server re-reads glossary files on every tool call — no reload needed.

---

GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "glossary": {
      "command": "npx",
      "args": ["open-agent-glossary", "mcp-serve"]
    }
  }
}

Add .github/copilot-instructions.md to make Copilot use it proactively:

## Glossary

This project uses a shared glossary for domain-specific terms.
When the user mentions an unfamiliar project term or acronym,
use the `glossary_lookup` tool to get its authoritative definition.
At the start of a conversation, use `glossary_list` to see all available terms.

See hooks/github-copilot.md for full hook and CLI setup.

---

Shared Project Glossaries

This is a first-class use case. Put the team glossary at:

.agents/glossary.jsonl

Why .jsonl for shared files?

• Easier line-based diffs
• Fewer merge conflicts when multiple people add entries
• Easy to append entries
• Works with every integration (not just Pi)

Reload Behavior by Integration

Integration	Reload behavior
Pi	Loaded at session start; /glossary reload after changes
Claude hook	Re-read on every prompt
MCP	Re-read on every tool call
CLI	Re-read on every command

Merge Order (later wins on same term)

1. ~/.pi/agent/glossary.json(.l) — global Pi terms
2. ~/.agents/glossary.json(.l) — global cross-tool terms
3. .pi/glossary.json(.l) — project Pi terms
4. .agents/glossary.json(.l) — project cross-tool terms ← recommended

---

Glossary Entry Format

{
  "term": "BFF",
  "definition": "Backend For Frontend ...",
  "aliases": ["backend for frontend"],
  "pattern": "BFF|backend.?for.?frontend",
  "flags": "iu",
  "enabled": true,
  "source": "project-glossary"
}

Field	Required	Description
term	yes	canonical handle
definition	yes	authoritative definition
aliases	no	extra plain-text triggers
pattern	no	explicit regex — overrides default matcher
flags	no	regex flags, default iu
enabled	no	set false to disable
source	no	provenance label

---

Release / publish

Run the release script:

npm run release -- patch
# or: minor / major

This script will:

1. verify clean git state
2. run tests/typecheck/build
3. bump versions in root + ui/
4. create commit + git tag (vX.Y.Z)
5. push commit + tags
6. create GitHub release notes (gh release create --generate-notes)

Package publishing is handled by GitHub Actions Trusted Publishing (OIDC) on tag push via .github/workflows/publish.yml.

Requirements:

• npm Trusted Publisher configured for this repo/workflow
• gh CLI installed and authenticated (for automatic GitHub release creation)

CLI Quick Reference

open-agent-glossary init --cwd .
open-agent-glossary init --global
open-agent-glossary inject --prompt "what is BFF" --cwd .
open-agent-glossary lookup BFF --cwd .
open-agent-glossary list --cwd .
open-agent-glossary add "BFF" "Backend For Frontend" --scope project --cwd .
open-agent-glossary edit BFF --definition "Updated definition" --scope project --cwd .
open-agent-glossary remove BFF --scope project --cwd .
open-agent-glossary reset-session
open-agent-glossary mcp-serve
open-agent-glossary mcp-serve --port 7337 --open
open-agent-glossary mcp-serve --no-ui
open-agent-glossary ui --port 7337

---

Local UI — technical details

The UI is served by a lightweight hono control server embedded in the core package, binds to 127.0.0.1 only, and never transmits data anywhere.

How it works

• open-agent-glossary ui starts the control server and serves the UI assets
• the browser talks to the local JSON API under /api
• the UI uses the same glossary/config/session/usage logic as the CLI and MCP server
• everything is local-only and file-backed

Autostart

Enable autostart so the UI boots with every agent session:

{
  "ui": { "autostart": true, "port": 7337, "open": true }
}

Packaging note

The UI is shipped as a prebuilt package (open-agent-glossary-ui) via optionalDependencies — nothing is compiled on the user's machine. If it is not installed, the control server still serves the JSON API under /api and shows an install hint at /.

Global storage

Per-user state lives under ~/.open-agent-glossary/:

File	Purpose
usages.json	Usage tracking (per-term / per-session / global totals)
projects.json	Registry of project roots seen by the tool (powers discovery)
config.json	Optional package-scoped global config
glossary.json	Optional package-scoped global glossary

The registry grows organically — every time the control server starts in a repo, that root is recorded so the “glossaries on this computer” view stays current. No full-disk scanning is ever performed.

---

Config

Config uses first-found wins.

Project-level (highest priority)

• .open-agent-glossary/config.json
• .agents/open-agent-glossary/config.json
• .pi/open-agent-glossary/config.json

Global user-level (fallback)

• ~/.open-agent-glossary/config.json
• ~/.agents/open-agent-glossary/config.json
• ~/.config/open-agent-glossary/config.json
• ~/.pi/agent/extensions/open-agent-glossary/config.json

Example:

{
  "sessionTtlMinutes": 30,
  "glossaryMode": "merge",
  "glossaryPin": "",
  "extraGlossaryPaths": [],
  "disableGlobalGlossary": false,
  "disableProjectGlossary": false,
  "ui": {
    "autostart": false,
    "port": 7337,
    "open": true
  }
}

---

Compatibility

Schema-compatible with pi-glossary. Existing glossary.json files drop in without changes.

---

License

MIT