README
¶
csaw
Mount, not install. One registry of AI rules, skills, and configs — mounted into every project, never committed, never drifted.
Works with: Claude Code · Codex · Cursor · Copilot · Windsurf · OpenCode · Gemini CLI
The Problem
Your AI tools need configuration — AGENTS.md, skills, rules, MCP configs. Today:
- They're copy-pasted everywhere. The same AGENTS.md lives in 12 repos. Each copy drifts independently.
- They clutter git. Every AI tool wants its own config files. That's 10+ files committed to every repo, creating PR noise and merge conflicts.
- Onboarding is manual. New person joins. "Copy these files from the wiki." They miss one. Their AI gives bad advice.
- Cleanup is impossible. You tried an experimental AI config. Now you have to find and delete 6 files across 3 tool directories — and hope you didn't miss one.
The Fix
Keep your AI config in one git repo (a registry). csaw symlinks it into your projects. Update the registry, every project sees the change instantly. Unmount, and it's like csaw was never there.
your-registry/ your-project/
AGENTS.md ──→ AGENTS.md (symlink)
rules/ .claude/rules/
go-conventions.md ──→ go-conventions.md (symlink)
agents/ .claude/agents/
code-reviewer.md ──→ code-reviewer.md (symlink)
skills/ .claude/skills/
code-review/SKILL.md ──→ code-review/SKILL.md (symlink)
mcp/ .mcp.json (symlink)
claude-code.json ──→
Nothing is committed to your project. Git never sees the files. Unmount, and they're gone.
Install
uv tool install csaw
Other install methods
# macOS / Linux
brew install --cask NicholasCullenCooper/tap/csaw
# Windows
scoop bucket add csaw https://github.com/NicholasCullenCooper/scoop-bucket
scoop install csaw
# pipx
pipx install csaw
# Go from source
go install github.com/NicholasCullenCooper/csaw/cmd/csaw@latest
macOS note (Homebrew): If you see "Apple could not verify", run:
xattr -d com.apple.quarantine "$(which csaw)"This is normal for unsigned CLI tools distributed via Homebrew casks.
Starting a New Project
You have a brand new repo with no AI config. Create a personal registry:
csaw init ~/my-ai-config
✔ initialized registry "my-ai-config"
╭─────────────────────────────────────────────────────╮
│ Register as a source? │
│ ▸ Yes No │
╰─────────────────────────────────────────────────────╯
✔ registered source "my-ai-config" with priority 10
This creates a ready-to-use registry:
~/my-ai-config/
csaw.yml ← default profile
AGENTS.md ← your coding rules
skills/
code-review/SKILL.md
commit-message/SKILL.md
Now mount it into your project:
cd ~/my-project
csaw mount --profile my-ai-config/default
╭──────────────────────────────────────────────────╮
│ │
│ mounted │
│ │
│ my-ai-config │
│ ✔ AGENTS.md │
│ ✔ .claude/skills/code-review/SKILL.md │
│ ✔ .claude/skills/commit-message/SKILL.md │
│ │
│ 3 files mounted · 1 tool dirs │
│ │
╰──────────────────────────────────────────────────╯
Your project now looks like this:
my-project/
src/
package.json
AGENTS.md ← symlink to ~/my-ai-config/AGENTS.md
.claude/
skills/
code-review/SKILL.md ← symlink
commit-message/SKILL.md ← symlink
Open Claude Code (or Cursor, Codex, Copilot) — it finds the files automatically. Run git status — nothing shows up. The files are hidden via .git/info/exclude.
I Already Have an AGENTS.md
You have an existing project with AI config files scattered around — an AGENTS.md, maybe some skills in .claude/skills/. You want to pull them into a registry instead of leaving them committed.
cd ~/my-project
csaw init --adopt ~/my-ai-config
╭───────────────────────────────────────╮
│ │
│ adopted 3 files │
│ │
│ ✔ AGENTS.md │
│ ✔ skills/testing/SKILL.md │
│ ✔ agents/go.md │
│ │
╰───────────────────────────────────────╯
csaw scans your project, finds AI config files, and copies them into the new registry with the correct structure. It reverses the projection — .claude/skills/testing/SKILL.md becomes skills/testing/SKILL.md in the registry, .claude/rules/go.md becomes agents/go.md.
Now you can delete the originals from your project, register the source, and mount instead:
csaw source add personal ~/my-ai-config --priority 10
csaw mount --profile personal/default
Mounting a Team Source
Your team keeps shared AI config in a git repo. One command to get it:
csaw source add team git@github.com:your-org/ai-config.git
✔ registered source "team"
✔ cloned team
csaw auto-clones the repo. Now mount:
cd ~/my-project
csaw mount --profile team/backend
Your project gets the team's AGENTS.md, skills, and rules — all symlinked. Every repo on the team mounts the same source. When someone updates the team config:
csaw pull team
# ✔ pulled team
Every project sees the update instantly through the symlinks. No re-mounting needed.
Having Your Own Config Alongside the Team
You want the team's shared config plus your personal preferences. Create a personal registry:
csaw init ~/my-ai-config
csaw source add personal ~/my-ai-config --priority 10
Now you have two sources. Mount uses both:
csaw mount --profile team/backend
If personal has skills/debug-strategy/SKILL.md and team has skills/code-review/SKILL.md, both get mounted — they're different files, no conflict.
What if both have the same file?
If both personal and team provide AGENTS.md, priority decides. Personal has priority 10, team has priority 0 (default). Personal wins.
csaw inspect
Sources
personal (local, priority 10) → ~/my-ai-config
team (remote) → ~/.csaw/sources/team
You can set priority on any source:
csaw source add team git@github.com:org/config.git --priority 0
csaw source add personal ~/my-config --priority 10 # wins on conflicts
Higher number wins. If two sources have the same priority and provide the same file, csaw errors and tells you to resolve it.
Experimental Skills
Working on a new skill? Put it in skills/experimental/:
~/my-ai-config/
skills/
code-review/SKILL.md ← stable, always mounted
experimental/
debug-strategy/SKILL.md ← hidden from default mounts
The .csawignore file hides skills/experimental/** by default. To test an experimental skill:
csaw mount --profile personal/default --include-experimental
When you're confident it works, promote it:
csaw promote personal/skills/experimental/debug-strategy
# ✔ promoted debug-strategy from experimental to stable
# Push: csaw push personal -m "promote debug-strategy"
This moves it from skills/experimental/debug-strategy/ to skills/debug-strategy/ — now it mounts by default.
To share a promoted skill with the team:
csaw fork personal/skills/debug-strategy/SKILL.md --into team
csaw push team -m "add debug-strategy skill"
Pulling Team Updates
A teammate updated the team's AGENTS.md. Get the latest:
csaw pull team
# ✔ pulled team
Since your project's AGENTS.md is a symlink to the team registry, the update is visible instantly — no remount needed.
What if I edited a mounted file?
If you edited AGENTS.md in your project, you actually edited the team registry (through the symlink). Now csaw pull detects uncommitted changes:
! team has uncommitted changes
Commit: cd ~/.csaw/sources/team && git add -A && git commit -m "..."
Or stash: csaw pull team --stash
--stash stashes your changes, pulls, then pops the stash:
csaw pull team --stash
# ✔ pulled team
What if the team and I changed the same file?
If you have local commits and the remote has diverged:
! team has diverged (2 local, 5 remote commits)
Resolve: cd ~/.csaw/sources/team && git pull --rebase
This is standard git — csaw tells you what happened and where to fix it. The registry is a normal git repo.
Sharing Your Changes
You updated a skill through a symlink (or edited the registry directly). Push it:
csaw push team -m "improve code review skill"
# ✔ pushed team
This runs git add -A && git commit && git push in the team registry. Your teammates pull the update with csaw pull.
If you're not sure and want to go through a PR instead:
csaw source clone team ~/Developer/team-config
cd ~/Developer/team-config
git checkout -b improve-code-review
# ... edit files ...
git add -A && git commit -m "improve code review"
git push -u origin improve-code-review
gh pr create
csaw source clone moves a remote source to a local directory for contribution. Now you can branch, PR, and collaborate like any codebase.
Testing a Branch
You want to try a feature branch of the team config without affecting other projects:
csaw pin team@feature/new-rules
csaw pull team
csaw mount --profile team/backend
This project now uses the feature/new-rules branch. Other projects stay on main. When you're done:
csaw unpin team
csaw pull team
Back to main.
Team Governance: Protected Files
A team can mark certain files as protected — files that should not be overridden by personal sources or forked for customization. Put this in the team registry's csaw.yml:
csaw:
protected:
- AGENTS.md
- rules/security.md
backend:
include:
- AGENTS.md
- rules/**
When a file is protected:
- Priority is bypassed. If personal has priority 100 and team's
AGENTS.mdis protected, team's version wins regardless. - Fork is refused.
csaw fork team/AGENTS.md --into personalreturns an error. - Protection is visible.
csaw inspectmarks protected files with a*under the source.
Protection is advisory within csaw — it prevents csaw's own mechanisms from bypassing team rules. A developer can still manually delete a symlink and write their own file in its place. csaw doesn't try to stop that. This is an open-source tool, not an enterprise MDM.
Future work: content-hash verification. csaw could record the SHA of each protected file at mount time and detect if someone replaces the symlink with a modified copy.
csaw check --strictwould fail the check. This isn't built yet — filed as tech debt.
Forking a Team File
You like the team's AGENTS.md but want to customize it. Fork it:
csaw fork team/AGENTS.md --into personal
This copies the file to your personal registry. Since personal has higher priority, your version gets mounted instead of the team's. The team original is untouched.
Switching Profiles
Mounting a new profile replaces the previous one automatically:
csaw mount --profile team/backend
# ... working on backend ...
csaw mount --profile team/frontend
# previous mount removed, frontend mounted
To go back to what you had before:
csaw mount --restore
To add files on top of an existing mount without replacing:
csaw mount --keep --profile personal/extras
Clean Removal
csaw unmount
Every symlink is removed. If csaw stashed any original files during mount (because they existed before), they're restored. Your project is exactly as it was.
✔ 6 removed · 2 restored
Remount: csaw mount --restore
Where Files Get Mounted
csaw knows the four pillars of AI tool configuration and projects each to the right place:
Registry path Project path What it is
────────────────────────────────────────────────────────────────────────────
AGENTS.md AGENTS.md Project guidance (the standard)
rules/go.md .claude/rules/go.md Always-on coding standards
.cursor/rules/go.md
agents/reviewer.md .claude/agents/reviewer.md Subagent definitions
.cursor/agents/reviewer.md
skills/foo/SKILL.md .claude/skills/foo/SKILL.md On-demand reusable workflows
.agents/skills/foo/SKILL.md
mcp/claude-code.json .mcp.json Tool/data connectivity
You write files once in your registry. csaw projects them into every tool's native directory.
Mounted files are hidden from git via .git/info/exclude. Use csaw show <path> to make one visible, csaw hide <path> to hide it.
Configuring Tools
On first mount, csaw asks which AI tools you use:
╭──────────────────────────────────────────╮
│ Which AI tools do you use? │
│ │
│ ● Claude Code │
│ ● Cursor │
│ ○ OpenCode │
│ ○ Codex │
│ ○ Windsurf │
│ │
│ space toggle · enter confirm │
╰──────────────────────────────────────────╯
This is saved to ~/.csaw/config.yml and applies to all projects. You can also set it directly:
csaw config set tools claude,cursor
Registry Structure
A csaw source is just a git repo with markdown files:
my-ai-config/
csaw.yml ← profiles (which files to mount)
.csawignore ← files hidden from default mounts
AGENTS.md ← project guidance (the standard)
rules/ ← always-on coding standards
go-conventions.md
testing-standards.md
agents/ ← subagent definitions (separate context windows)
code-reviewer.md
planner.md
skills/ ← on-demand reusable workflows
code-review/
SKILL.md
testing/
SKILL.md
experimental/ ← work in progress (hidden by .csawignore)
new-idea/
SKILL.md
mcp/ ← MCP server configs
claude-code.json
Every file is standard markdown — usable with or without csaw.
Profiles
Profiles go in csaw.yml. They define which files to mount:
backend:
description: Go backend development
include:
- AGENTS.md
- agents/go.md
- skills/code-review/**
- skills/testing/**
frontend:
extends: backend
include:
- agents/react.md
- skills/react-patterns/**
Profiles support glob patterns and inheritance. extends pulls in everything from the parent.
Full command reference
Commands
| Command | What it does |
|---|---|
csaw init [dir] |
Scaffold a new registry. --adopt imports from existing project. |
csaw source add name url |
Add a source (auto-clones remote). --priority n for conflicts. |
csaw source remove name |
Remove a source. |
csaw source clone name dir |
Clone remote source locally for contributing. |
csaw source list |
List configured sources. |
csaw mount [patterns] |
Mount files. Replaces previous mount. Picker if no args. |
csaw mount --profile name |
Mount a named profile. |
csaw mount --restore |
Re-mount the previous selection. |
csaw unmount [patterns] |
Remove mounted files, restore originals. |
csaw inspect |
Full state: sources, mounts, priorities, pins. |
csaw check |
Detect broken or drifted symlinks. |
csaw update |
Repair drifted links. |
csaw diff path |
Diff a mounted file against its source. |
csaw pull [source] |
Pull latest from remote sources. --stash for dirty state. |
csaw push [source] -m "msg" |
Commit and push source changes. |
csaw pin source@ref |
Pin source to a branch/tag for this project. |
csaw unpin source |
Unpin, return to default branch. |
csaw fork source/path |
Copy a file into another source. --into target. |
csaw promote source/skills/experimental/name |
Promote experimental skill to stable. |
csaw config set key value |
Set config (tools, default_fork_target). |
csaw config list |
Show configuration. |
csaw show / hide path |
Control git visibility of mounted files. |
csaw status |
Quick summary. |
Key Flags
| Flag | Commands | What it does |
|---|---|---|
--profile name |
mount | Named profile to mount. |
--force |
mount | Overwrite conflicts, stash originals. |
--keep |
mount | Add to existing mount instead of replacing. |
--tools list |
mount | Target tools (e.g., --tools claude,cursor). |
--restore |
mount | Re-mount previous selection. |
--include-experimental |
mount | Include experimental skills (hidden by .csawignore). |
--adopt |
init | Import existing AI config from current project. |
--stash |
pull | Stash uncommitted changes before pulling. |
--priority n |
source add | Source priority (higher wins on conflict). |
--into source |
fork | Target source to fork into. |
Contributing
See CONTRIBUTING.md for workflow, validation, and repo standards.
License
MIT
Directories