Getting Started

Install

npm install -g agent-tags

Or use it without installing:

npx agent-tags status

Alternatively, build from source (requires Rust):

git clone https://github.com/cabljac/agent-tags.git
cd agent-tags/git-agent-tags
cargo install --path .

Tag your first file

See what’s untagged:

agent-tags missing

Pick an important file and add a header in its first 30 lines:

/**
 * @agents(auth-module)
 * OAuth PKCE flow for third-party providers.
 * Uses refresh tokens in httpOnly cookies.
 * Related: src/auth/guard.ts#token-validation, src/types/auth.d.ts
 * Don't add session logic here — see session-manager.ts
 */

Validate your tags:

agent-tags check

Install the pre-commit hook

Block broken references from ever reaching main:

agent-tags hook --install

This adds a git pre-commit hook that runs agent-tags check on every commit. Broken Related: paths are errors (commit blocked). Stale headers are warnings (commit allowed).

Give your agent the skill

Copy the agent skill into your repo:

cp -r .agents/skills/agent-tags your-repo/.agents/skills/agent-tags

Agents that support skills (Claude Code, Cursor, Copilot, etc.) will automatically:

1. Read tags before editing any file
2. Update tags after making changes
3. Validate references before committing

How agents use it

Before editing:

agent-tags context --for src/auth/token.ts --hops 1

The agent reads all tags from the file and its neighbors in the reference graph. It knows the file’s purpose, dependencies, and constraints before changing anything.

After editing:

agent-tags check

The agent validates that no references are broken and no headers are stale. Tags stay accurate automatically.

Next steps

• Tag syntax and specification — the full format reference
• CLI reference — every command explained
• Why agent-tags? — how it compares to other approaches