Cairn

An agent-agnostic CLI toolkit for working with Markdown files and related assets. Cairn supports all LLM coding agents, as well as humans and CI systems; its commands do not depend on Claude or any model-provider API.

Published as @cairn-tool/cairn on the public npm registry; the installed binary is named cairn.

Renamed from claude-cli. The old name implied a coupling that never existed. Every identifier Cairn writes into your files or environment is still read under its pre-rename spelling, so nothing on disk has to change — see Migrating from claude-cli.

Install

No registry configuration and no token — the package is public.

npm install -g @cairn-tool/cairn
cairn --version

Or without installing: npx @cairn-tool/cairn md lint README.md.

Releases are published through OIDC trusted publishing, so every version carries a provenance attestation. Node 22.22.2+, 24.15.0+, or 26+ is required. Installation details covers keeping a stable path across Node upgrades and building from source.

Quick start

# Markdown: check a docs tree, then fix what is mechanical.
cairn md lint-dir docs --style
cairn md fix docs --write

# Find what points at a file before you move it, then move it.
cairn md refs-to docs/setup.md
cairn md rename-file docs/setup.md docs/getting-started.md

# Agent bundles: write once, render for every host.
cairn agent convert ./my-bundle --target all --output ./dist
cairn agent verify                      # has the committed tree drifted?

# Named scripts: same result from any directory in the repo.
cairn scripts run lint-changed -- --fix

# Where did the tokens go?
cairn usage summary

Every command takes --format llm|human|json (-fh/-fj for short) and exits 0 when clean, 1 on a usage error, and 2 when it found something — exit 2 is the answer, not a failure to retry. The complete command listing has all of them.

What is in it

Eight toolsets, plus describe, schema, serve, completion, and check-update.

| Toolset | Does | Guide | | --------- | -------------------------------------------------------------------------------- | -------------------------------------------- | | md | Lint, validate, query, and safely refactor a Markdown workspace. | Markdown | | agent | Compile one portable bundle into every assistant's native format. | Agent bundles | | scripts | Resolve and run a repository's named commands from anywhere inside it. | Named scripts | | usage | Report on local assistant transcripts: tokens, tools, sessions, and cost. | Usage reporting | | archive | Keep what a session produced before the logs are pruned, and get it back. | Archiving | | jira | Convert Jira and Confluence rich text between ADF and Markdown. | Jira rich text | | pdf | Read PDF documents: text, structure, embedded files, and conversion to Markdown. | PDF documents | | qa | Run TC-N test-case plans through Cursor, Claude Code, and Codex backends. | QA harness |

scripts run and qa run are the two commands that execute anything. scripts run only runs what a tracked file in your repository names. qa run discovers _plans/tc-N.yaml and spawns the named agent backend with permission checks bypassed.

Documentation

Full documentation lives in docs/.

| Page | Covers | | ---------------------------------------------------- | --------------------------------------------------------------- | | Documentation contents | Index of everything below. | | Complete command listing | Every command, with a one-line description. | | Guides | Why each toolset exists. | | Project configuration | The .cairn.yml schema. | | Machine-readable result contract | JSON output, the envelope, and what may change. | | File formats and schemas | The files Cairn itself reads and writes. | | Diagnostic codes | Every AB###, AD###, and AP###, with severity and meaning. | | Providers | What is known about each assistant's own formats. | | Cairn's own plugins | The toolsets, shipped as agent bundles. | | Installing Cairn | Node versions, stable paths, and building from source. | | Migrating from claude-cli | Every pre-rename identifier, and what still reads it. |

Plugins

Cairn ships its own toolsets as installable plugins, so an assistant has the command surface available without rediscovering it from --help. Everything is published to a single release branch, which carries each host's catalog at its own root path:

| Host | Catalog | Install from | | ----------- | ---------------------------------- | ------------------------------ | | Claude Code | .claude-plugin/marketplace.json | the marketplace, or bundles/ | | Codex | .agents/plugins/marketplace.json | the marketplace, or bundles/ | | Cursor | .cursor-plugin/marketplace.json | the marketplace, or bundles/ | | Antigravity | none | bundles/ |

The marketplace is named cairn, and the plugins in it are cairn-markdown, cairn-scripts, cairn-usage, cairn-archive, cairn-agent, cairn-jira, cairn-pdf, and cairn-qa.

The branch also publishes the source bundles under bundles/, so a host with no marketplace concept is installed straight off the same branch:

git clone --branch release https://github.com/cairn-tool/cairn.git
cairn agent install cairn/bundles/cairn-markdown --target antigravity --scope user

Moved from the per-host branches. claude-plugins, codex-plugins and cursor-plugins are replaced by release. A marketplace added from one of those must be removed and re-added — the marketplace key changed, and there is no in-place upgrade across that.

Claude Code

/plugin marketplace add cairn-tool/cairn@release
/plugin install cairn-markdown@cairn

Codex

Add the branch as a marketplace, then install from it by name. --ref is what pins the marketplace to the published branch rather than main:

codex plugin marketplace add cairn-tool/cairn --ref release
codex plugin add cairn-markdown@cairn

codex plugin list --marketplace cairn shows what the branch offers, and codex plugin marketplace upgrade cairn re-fetches it after a release — the snapshot Codex installs from is local, so it does not update on its own.

Cursor

Cursor has no CLI for adding a marketplace; a repository-backed one is a team marketplace, which is a Teams or Enterprise feature. In the dashboard, go to Plugins → Team Marketplaces → Add Marketplace → Import from Repo, point it at https://github.com/cairn-tool/cairn and the release branch, then install from Customize in the sidebar. Turning on Auto Refresh re-reads the catalog whenever that branch is pushed.

Without a team plan, install locally instead — this drops the plugins into ~/.cursor/plugins/local, which Cursor scans on startup:

scripts/install-cursor.sh

Antigravity and OpenCode have no marketplace concept at all; there a plugin is a directory drop, so use agent install or the install scripts.

The plugins are authored as agent bundles under plugins/, built with the same agent commands they document. The cairn binary is a separate install — the plugins invoke it, they do not carry it. See Cairn's own plugins for what each one contains.

Contributing

Pull requests are welcome. CONTRIBUTING.md covers the setup, the pre-push checks, the Conventional Commits requirement, and the handful of conventions that are load-bearing rather than stylistic.

Security

Report a vulnerability privately through GitHub Security Advisories rather than in a public issue. SECURITY.md lists what is in scope — chiefly scripts run, the only command that executes anything.

License

MIT — see LICENSE.