Pluribus

Intentional context across every AI tool you use.

Pluribus keeps project instructions, conventions, constraints, and team context in one versioned source of truth, then syncs that context into the formats each AI tool expects.

It is not a persistent memory layer, retrieval system, agent orchestrator, or agent-merging framework. Think CLAUDE.md, .cursorrules, copilot-instructions.md, AGENTS.md — one intentional context, multiple generated outputs.

The Problem

You use Claude, Copilot, Cursor, Windsurf, Continue, Zed, ChatGPT, and whatever ships next Tuesday.

Each one has its own way of understanding your project:

• CLAUDE.md for Claude Code
• copilot-instructions.md for GitHub Copilot
• .cursorrules for Cursor
• AGENTS.md for OpenClaw
• .windsurf/rules/pluribus.md for Windsurf Cascade
• .continue/rules/pluribus.md for Continue
• .rules for Zed

You end up maintaining 5+ files that say roughly the same thing — your project's architecture, conventions, tech stack, who you are, what matters. Copy-paste across files. They drift. They rot. You forget to update one. Your AI gives you wrong answers because it's reading stale context.

This is a multiplying problem. Every new AI tool = another context file = more maintenance = more drift.

The Vision

Pluribus is a universal format for intentional context in AI-assisted development.

Write your project context once, in pluribus.md. Keep it as a single file for small projects, or compose shared team/org Markdown with # @import when the context needs to be reused.

your-project/
├── pluribus.md                  # source of truth
└── shared/
    ├── team-context.md          # optional imported conventions
    └── security-constraints.md  # optional imported guardrails

Then preview or sync:

npx --yes pluribus-context@latest sync --dry-run
npx --yes pluribus-context@latest sync

And it generates the right files for each tool:

• CLAUDE.md ← for Claude Code
• .github/copilot-instructions.md ← for Copilot
• .cursorrules ← for Cursor
• AGENTS.md ← for OpenClaw
• .windsurf/rules/pluribus.md ← for Windsurf Cascade
• .continue/rules/pluribus.md ← for Continue
• .rules ← for Zed

One source of truth. Zero drift.

Why .md?

• It's human-readable — you can review it, version it, PR it
• It's universal — every tool already parses markdown
• It's composable — import shared contexts across projects
• It's versionable — git diff your AI context like you diff your code
• It's simple — no YAML schemas, minimal JSON only when you opt into locked remote imports

Getting Started

Pick the safe first command

If your repo already has AI context files such as CLAUDE.md, .cursorrules, Copilot instructions, or AGENTS.md, start with the read-only audit:

npx --yes pluribus-context@latest audit

It does not write files. Without pluribus.md, it lists existing AI context surfaces so you can decide what to migrate. With pluribus.md, it reports generated files that are missing or drifted.

If you are starting from scratch, preview the source-of-truth scaffold first, then create it when it looks right:

# Preview only; does not write files:
npx --yes pluribus-context@latest init --dry-run

# Write pluribus.md when the preview looks right:
npx --yes pluribus-context@latest init

What Pluribus writes

Pluribus is intentionally narrow about filesystem changes:

• audit, validate, and sync --dry-run are read-only.
• init writes pluribus.md only. If that file already exists, it refuses to overwrite it.
• sync writes only the configured/generated AI context files such as CLAUDE.md, .cursorrules, .github/copilot-instructions.md, AGENTS.md, Windsurf/Continue rules, and .rules.
• Generated files include a Generated by Pluribus ... do not edit manually header so drift is easy to spot in review.
• Remote imports only touch pluribus.lock.json and .pluribus/cache/remote/ when you explicitly pass --update-imports.

When in doubt, run npx --yes pluribus-context@latest audit or npx --yes pluribus-context@latest sync --dry-run first.

Install, uninstall, and network behavior

# Install globally if you prefer a persistent `pluribus` command
npm install -g pluribus-context@latest
pluribus --help

# Remove the global CLI later
npm uninstall -g pluribus-context

For local development:

git clone https://github.com/caioribeiroclw-pixel/pluribus.git
cd pluribus
npm link

# Remove the local global link later
npm unlink -g pluribus-context

One-off npx --yes pluribus-context@latest ... commands install into npm's normal temporary cache and do not create a persistent global pluribus command.

Pluribus does not make network requests during normal audit, validate, sync, or sync --dry-run runs. Network access is opt-in for remote imports only when you explicitly pass --update-imports; those fetches are limited to github:/HTTPS imports, then pinned in pluribus.lock.json and cached locally for deterministic offline syncs. Private GitHub imports may use GH_TOKEN/GITHUB_TOKEN or gh auth token during that explicit refresh, but tokens are never written to the lockfile or cache.

60-second smoke test

Want to see exactly what gets generated before adding it to a real project?

mkdir pluribus-demo && cd pluribus-demo
# Preview only; does not write files:
npx --yes pluribus-context@latest init --dry-run --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot

# Write pluribus.md when the preview looks right:
npx --yes pluribus-context@latest init --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot
npx --yes pluribus-context@latest validate
npx --yes pluribus-context@latest sync --dry-run

If the preview looks right, run npx --yes pluribus-context@latest sync to write the tool-specific files.

For a fuller walkthrough, see the Quickstart. To enforce generated context files in pull requests, use the CI audit example; to catch drift before commits leave your machine, use the Pre-commit Audit Hook. If your repo already has CLAUDE.md, .cursorrules, Copilot instructions, or AGENTS.md, run a Context Drift Audit first, try the intentionally drifted audit example, then follow Migrate Existing AI Context Files. Before committing shared or generated AI instructions, use the Context File Review Checklist. If you're deciding between Pluribus and a one-way rules converter, see When to use Pluribus. If you are debugging "context drift" after compaction or long sessions, start with the Context Drift Taxonomy to separate file drift from runtime precedence drift. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the Community Review Packet for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test.

Usage

1. Initialize your context file

cd your-project/
# Preview only; does not write files:
npx --yes pluribus-context@latest init --dry-run

# Write pluribus.md when the preview looks right:
npx --yes pluribus-context@latest init

The dry-run prints the scaffold without writing files. The second command creates pluribus.md with all required sections scaffolded. Fill in your project context.

You can also use flags for non-interactive init, including the same dry-run preview:

# Preview only; does not write files:
npx --yes pluribus-context@latest init --dry-run --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw

# Write pluribus.md when the preview looks right:
npx --yes pluribus-context@latest init --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw

2. Edit pluribus.md

Fill in your context once:

# Identity
I am Ana, building **Conduit** — a background job runner for Node.js.

# Stack
- Language: TypeScript 5.4
- Runtime: Node.js 22 LTS
- ...

# Conventions
- async/await everywhere — no .then()/.catch()
- ...

# Goals
1. Zero external infrastructure
2. Type safety end-to-end
...

# Constraints
- Never introduce native-compile dependencies
- ...

3. Compose shared context when needed

For team or org-wide conventions, import shared Markdown files before your local project sections:

# @import ./shared/team-context.md
# @import ./shared/security-constraints.md

# Identity
I am Ana, building **Conduit** — a background job runner for Node.js.

Local sections are applied after imported sections, so project-specific context can override shared context. See Composable Contexts for details.

4. Validate before syncing

pluribus validate

This checks that pluribus.md exists, imports resolve, required sections are present, top-level sections are not duplicated, and any pluribus:tools comment uses supported tool names.

If you use remote imports and want to refresh the lock/cache while validating:

pluribus validate --update-imports

5. Audit generated files before syncing

pluribus audit

This is read-only. It compares existing generated files with what pluribus.md would produce, reports missing or drifted outputs, and can run in CI with --strict:

pluribus audit --strict

In GitHub Actions, add annotations so drift appears inline in the check UI:

npx --yes pluribus-context@latest audit --strict --github-annotations

For GitHub Actions, --ci is the shorter equivalent of --strict --github-annotations:

npx --yes pluribus-context@latest audit --ci

For CI scripts, dashboards, or migration tooling, use machine-readable output:

npx --yes pluribus-context@latest audit --strict --json

To save the JSON as a CI artifact while keeping stdout quiet, add --output:

npx --yes pluribus-context@latest audit --strict --json --output pluribus-audit.json

The JSON shape is documented in schemas/audit-result.schema.json so CI wrappers and dashboards can validate integrations without scraping human output. For copy-paste enforcement, see the CI audit example and the Pre-commit Audit Hook.

If your project does not have pluribus.md yet, pluribus audit scans for known AI context files (CLAUDE.md, .cursorrules, Copilot instructions, AGENTS.md, Windsurf, Continue, Zed) so you know what to migrate.

6. Sync to all your tools

pluribus sync

If you use remote imports, refresh and pin them explicitly:

pluribus sync --update-imports

That writes pluribus.lock.json plus a local .pluribus/cache/remote/ content cache. Future plain pluribus sync runs resolve those remote imports from the lock/cache without network access, and fail if cached bytes no longer match the recorded digest.

Private github: imports use existing GitHub credentials only during --update-imports: GH_TOKEN/GITHUB_TOKEN if set, otherwise the logged-in GitHub CLI (gh auth token). Tokens are never stored in the lockfile or cache. Commit pluribus.lock.json; treat .pluribus/cache/remote/ as local, regenerable cache.

Output:

🔄 Syncing pluribus.md → claude, cursor, openclaw

   ✅ [claude]   → CLAUDE.md
   ✅ [cursor]   → .cursorrules
   ✅ [openclaw] → AGENTS.md

✅ Sync complete — 3 file(s) written.

Preview without writing (dry run):

pluribus sync --dry-run

Sync specific tools only:

pluribus sync --tools claude,openclaw

Keep tool files fresh while editing:

pluribus watch

watch monitors pluribus.md, debounces rapid editor saves, and re-runs sync automatically. It accepts the same --source, --tools, and --update-imports options as sync.

For scripts/hooks that should exit after the first detected change-triggered sync:

pluribus watch --once --tools claude,cursor

Supported Tools

| Flag | Output file | AI Tool | |---|---|---| | claude | CLAUDE.md | Claude Code (Anthropic) | | cursor | .cursorrules | Cursor AI editor | | openclaw | AGENTS.md | OpenClaw agent runner | | copilot | .github/copilot-instructions.md | GitHub Copilot | | zed | .rules | Zed Editor | | windsurf | .windsurf/rules/pluribus.md | Windsurf Cascade workspace rules | | continue | .continue/rules/pluribus.md | Continue workspace rules |

Custom Skills

Add a pluribus/skills/<tool>.md file to override or extend any built-in skill. See spec/skills-format.md for the skill file format.

Status

🚧 Early development — the spec and CLI are being built in public.

Roadmap

• [x] Problem definition & vision
• [x] Context format spec (pluribus.md flat format)
• [x] Skills format spec (extensible adapter system)
• [x] CLI: pluribus init — scaffold your context
• [x] CLI: pluribus sync — generate tool-specific files
• [x] OpenClaw integration (built-in skill)
• [x] Cursor integration (built-in skill)
• [x] Copilot integration (built-in skill)
• [x] Claude Code integration (built-in skill)
• [x] Zed Editor integration (built-in skill)
• [ ] Custom skill overrides (local pluribus/skills/)
• [x] Windsurf integration (built-in workspace rule)
• [x] Continue integration (built-in workspace rule)
• [x] pluribus validate command
• [x] pluribus watch command (debounced auto-sync on context changes)
• [x] Composable contexts MVP (local # @import ./file.md)
• [x] Remote composable contexts MVP (explicit --update-imports, public GitHub/HTTPS, safety limits)
• [x] Remote imports hardening (lockfile/cache/digest offline mode, optional GitHub auth, and CI coverage)
• [ ] CI/CD: auto-sync on commit
• [x] Published to npm as pluribus-context

Building in Public

I'm documenting every step of building Pluribus — the decisions, the trade-offs, the mistakes.

Follow along: @RibeiroCaioCLW

If you've felt this pain, tell me about your setup. What tools do you use? How do you manage context today? What's broken?

• Quickstart feedback — if install, validate, or dry-run felt confusing
• Audit feedback — if read-only pluribus audit missed drift, was noisy, or left the next step unclear
• Bug report — if a command failed or generated the wrong output
• Tool integration request — if another AI tool should be supported

Docs

• Quickstart — first install, validation, dry-run preview, and common friction
• Migrate Existing AI Context Files — move from CLAUDE.md, .cursorrules, Copilot instructions, or AGENTS.md to one source of truth
• When to use Pluribus — choose between sync, one-way conversion, and tool-native context files
• Context File Review Checklist — review AI instructions as supply-chain artifacts before committing generated context
• OpenClaw Integration — how Pluribus generates AGENTS.md for OpenClaw
• Composable Contexts — local/remote imports, merge behavior, and safety rules
• Remote Composable Context Imports — design notes for lockfile/cache/auth hardening
• Context Format Spec — the pluribus.md format reference
• Skills Format Spec — how adapters work and how to write custom skills
• Release Checklist — reproducible npm/GitHub release steps
• Changelog — user-facing release notes

Contributing

This project is just getting started. The best way to help right now:

1. Try the 60-second smoke test above in a throwaway directory
2. ⭐ Star the repo if the problem resonates
3. 🗣️ Open a quickstart feedback issue if anything felt confusing
4. 🔎 Open an audit feedback issue if the read-only audit missed drift or felt noisy
5. 📣 Share with someone who maintains 3+ AI context files

Looking for first contributions? Check out the open issues. The next good contributions are CI/CD workflow examples, real-world adapter feedback, and install/quickstart friction reports.

License

MIT — use it, fork it, build on it.

"E pluribus unum" — out of many, one.