██████╗░██╗░░░██╗██╗░░░░░██╗░░░██╗
██╔══██╗██║░░░██║██║░░░░░╚██╗░██╔╝
██████╔╝██║░░░██║██║░░░░░░╚████╔╝░
██╔══██╗██║░░░██║██║░░░░░░░╚██╔╝░░
██║░░██║╚██████╔╝███████╗░░░██║░░░
╚═╝░░╚═╝░╚═════╝░╚══════╝░░░╚═╝░░░
Ruly compiles the rules each task needs, from one shared rules repository, into the files Claude Code reads: CLAUDE.local.md, .claude/skills/, .claude/commands/ and .claude/agents/.
- Task-scoped recipes: a named recipe lists the rule files, skills, commands and MCP servers for one kind of work, and
ruly squash <recipe>writes only that set. requires:dependency resolution: rule files declare their dependencies; ruly resolves them recursively, includes each file once, andruly statsreports circularrequires:chains.- A recipe and model per subagent: each entry under a recipe's
subagents:gets its own recipe and model, written to.claude/agents/. - One rules repo on every machine:
ruly squash --syncmirrors a sharedrecipes.ymland the files it uses; per-machineoverrides:add to it without copying it. - Checks on squash output: every squash that writes files (not
--dry-run) reports ambiguous anchor links, and files that several skills require but the recipe leaves out.
See Ruly vs. native Claude Code for how each of these compares with what Claude Code does on its own, and Ruly vs. Ruler and rulesync for two cross-agent rule tools.
curl -fsSL https://raw.githubusercontent.com/patrickclery/ruly/main/setup.rb -o /tmp/ruly_setup.rb && ruby /tmp/ruly_setup.rbThis will:
- Install Ruly to
~/ruly - Add
rulycommand to your PATH - Set up initial configuration at
~/.config/ruly/recipes.yml
If you prefer to install manually:
# Clone the repository
git clone https://github.com/patrickclery/ruly.git ~/ruly
cd ~/ruly
# Install dependencies
bundle config set --local path 'vendor/bundle'
bundle install
# Add to PATH (add to your ~/.bashrc or ~/.zshrc)
export PATH="$HOME/ruly/bin:$PATH"
# Initialize configuration
ruly initTo remove Ruly:
rm -rf ~/ruly
# Remove the PATH export from your shell configuration fileAfter installation, you can immediately start using Ruly:
# Initialize configuration (if not done during install)
$ ruly init
# List available commands
$ ruly help
# Combine all rules into one file
$ ruly squash
# Use a specific recipe
$ ruly squash starter
# Clean up generated files
$ ruly clean
# List available recipes
$ ruly list-recipes
# Show version
$ ruly versionClaude Code already loads CLAUDE.md, .claude/rules/, @path imports, skills and subagents itself. Ruly runs before that: it picks the files a task needs and writes them where Claude Code reads them.
| Capability | Native Claude Code | Ruly |
|---|---|---|
| Per-task selection | A rule is scoped by file path only: paths is the only frontmatter field a rule reads (docs). It loads every session or when a matching file is opened; the docs send task-specific instructions to skills, which load on demand (docs). |
A named recipe lists the files, skills, commands and MCP servers for one task, and ruly squash <recipe> writes only that set. |
| Dependency resolution | @path imports pull files into a CLAUDE.md, up to four hops deep (docs); a rule file has no field for declaring dependencies (docs). |
requires: frontmatter is resolved recursively, each file is included once, --strict fails on a missing dependency, and ruly stats lists circular chains. |
| Token cost of includes | Imports "don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them" (docs); path-scoped rules and skills defer loading instead (docs). | The squashed output holds only the recipe's files and their requires:, and ruly stats reports token counts per file and in total. On ruly's synthetic bench fixture (five recipes, cl100k_base tokens), the squashed recipe output plus its skill and command descriptions was 74.3% smaller than loading every rule (median), and 68.4% smaller than a native layout's always-loaded set (63.0% if three fixture rules that no recipe uses are left out; benchmark details). |
| Cross-machine sharing | Symlinked shared rules load only after a once-per-project approval of external imports, and then only the rules without paths (docs); ~/.claude/rules/ applies to every project on one machine (docs). |
ruly squash --sync mirrors a shared recipes.yml and every file it uses into ~/.config/ruly/remotes/, and per-machine overrides: add to a shared recipe without copying it. |
| Per-subagent model | Each subagent file sets its own model: and preloaded skills: by hand (docs). |
A recipe's subagents: entries each name a recipe and a model; ruly writes the .claude/agents/ files, and the model falls back from subagent to recipe to inherit. |
| Post-squash checks | Rules and imports are read as written, at session start or when a matching file is opened, with no compile step in between (docs). | Every squash that writes output checks for ambiguous anchor links (a heading that appears more than once) and warns when several skills require a file the recipe leaves out. |
Native behavior is quoted from the Claude Code docs as of November 2026.
Ruler and rulesync write one rules source to many agents. The table compares how each tool chooses which rules go into an output, where the three tools overlap.
| Capability | Ruler | rulesync | Ruly |
|---|---|---|---|
| Named rule sets | No. Every .md under .ruler/ (except skills and subagents) is concatenated (source), and ruler.toml has no key that selects rule files (schema). |
No. The config has no profile or preset key (schema); a rule's targets and globs pick tools and paths (schema), and --input-roots layers whole source directories per run (docs). |
A named recipe lists the files, skills, commands and MCP servers for one task, and ruly squash <recipe> writes only that set. |
| Includes between rule files | No. Rule files are joined with source markers; there is no include syntax (source). | No. Rule frontmatter has no requires or include field (schema). |
requires: frontmatter is resolved recursively, for local and GitHub sources, and each file is included once. |
| Cycle reporting | No. Without includes there are no include cycles to report (source). | No. Without includes there are no include cycles to report (schema). | ruly stats lists circular requires: chains; squash includes each file once, so a cycle cannot loop. |
| Per-subagent model | Yes. A .ruler/agents/*.md subagent takes a model field (source); each subagent is one hand-written file, and the feature is marked experimental. |
Yes. A subagent file sets a model per tool, such as claudecode.model (docs); each subagent is one hand-written file. |
Each subagents: entry names a recipe and a model; ruly compiles that recipe into the subagent's .claude/agents/ file. |
| Shared source + overrides | No. Without a local .ruler/ it falls back to $XDG_CONFIG_HOME/ruler as a whole, with no remote source and no merge (source). |
Yes. sources installs rules from GitHub, git or npm, pinned to commit SHAs in rulesync.lock (docs), and a later --input-roots tree replaces same-path files (docs). |
ruly squash --sync mirrors a shared recipes.yml and its files, and overrides: add to a named recipe without copying it; there is no lockfile, so --sync mirrors the current remote. |
| Post-compile checks | Partial. Warns on skill directories without SKILL.md and on invalid subagent frontmatter (skills, subagents); no link checks. |
Partial. generate --check exits 1 on stale output (source) and doctor lints config and AGENTS.md size (docs); no link checks. |
Every squash that writes output checks for ambiguous anchor links (a heading that appears more than once) and warns when several skills require a file the recipe leaves out. |
| Agents | 32 agent targets, including AGENTS.md (source). |
69 --targets values, 61 of them with project rules, including agentsmd (docs). |
3 targets, claude, agents (AGENTS.md) and cursor; skills, commands and subagents are written only for Claude Code. |
Ruler and rulesync were checked by reading their source and docs at Ruler @5e551e6 (2026-10-27) and rulesync @6e3869d (2026-11-02), in November 2026; neither tool was run. Agent counts change often.
Ruly is a standalone command-line tool that manages AI assistant rules:
- Simple Installation: One-line install with curl
- Self-Contained: Everything runs from
~/ruly - Recipe System: Use pre-configured recipes or create your own
- Multiple Formats: Support for different AI assistants (Claude, Cursor, etc.)
Benefits:
- ✅ Standalone: No gem installation required
- ✅ Easy updates: Just pull the latest changes
- ✅ Requirements: Ruby 3.3+ (with Bundler), and the
ghCLI for GitHub sources - ✅ Flexible rules system: Define your own rules repository or use remote sources
- ✅ Cross-platform: Works anywhere Ruby is installed
The ruly command provides:
- ✅ Combine multiple rule files into one document
- ✅ Use recipe collections for different contexts
- ✅ Fetch and include remote GitHub files
- ✅ Support for Claude, Cursor, and other AI assistants
- ✅ Clean up all agent-related files automatically
Generated Files:
your-project/
├── CLAUDE.local.md # Generated by ruly squash (default)
├── .ruly/
│ └── bin/ # Executable scripts (from scripts: key)
└── .claude/
├── commands/ # Command files for Claude agent
│ ├── bug/ # Bug-related commands
│ ├── pr/ # PR management commands
│ └── workflow/ # Workflow commands
└── skills/ # Skill files for Claude agent
├── debugging/
│ └── SKILL.md
└── pr-review-loop/
└── SKILL.md
For other agents:
- Cursor: Uses
.cursor/directory with.mdcfiles - AGENTS.md:
-a agentswritesAGENTS.mdfor agents that read the AGENTS.md standard. See AGENTS.md Output. - Claude Code plugin:
-a claude-pluginpackages the same skills, commands, agents, hooks and MCP servers as a plugin directory. See Claude Code Plugin Output. - Custom: Specify with
--agentand--output-fileoptions
Ruly is a CLI tool that manages AI assistant rules and configurations for software development projects. It provides a framework for organizing and combining rule files from various sources - your own private repositories, public GitHub repos, or local files - into a single document for AI assistants like Claude or Cursor.
This repository does not include rule files. You need to:
- Create your own rules repository (private or public)
- Configure recipes to point to your rule sources
- Use the
ruly initcommand to get started with a template
-
Create a new repository for your rules:
# Create a private repository gh repo create yourusername/rules --private --description "My AI assistant rules" # Clone it locally git clone git@github.com:yourusername/rules.git cd rules
-
Organize your rules:
rules/ ├── ruby/ │ ├── common.md │ ├── rspec.md │ └── best-practices.md ├── testing/ │ └── patterns.md ├── commands/ │ ├── bug/ │ │ └── diagnose.md │ └── pr/ │ └── create.md ├── comms/ │ ├── jira/ │ │ ├── common.md # Shared Jira patterns │ │ └── bin/ # Shell scripts for Jira operations │ │ └── fetch-jira-details.sh │ └── ms-teams/ │ ├── common.md # Shared Teams patterns │ ├── commands/ │ │ └── dm.md # User-facing command │ └── agents/ │ └── ms-teams-dm.md # Subagent instructions ├── github/ │ ├── pr/ │ │ └── bin/ # Shell scripts for PR operations │ │ └── fetch-pr-details.sh │ └── bin/ # General GitHub scripts │ └── git_prettycommit.rb └── core/ └── debugging.mdDirectory conventions:
commands/- User-invocable slash commands (e.g.,/ms-teams:dm). Must be listed under thecommands:recipe key to be output as.claude/commands/files.skills/- Skill files that becomeSKILL.mdin.claude/skills/. Must be listed under theskills:recipe key.agents/- Subagent instruction files (dispatched by orchestrator, not user-invocable)bin/- Shell scripts and executables. Must be listed under thescripts:recipe key to be copied to.claude/scripts/.- Root files - Common patterns and shared configuration
Create ~/.config/ruly/recipes.yml to combine rules from different repositories:
recipes:
my-complete-rules:
description: "Combines personal and company rules"
sources:
# Your personal rules repository
- github: yourusername/rules
branch: main
rules:
- ruby
- testing
- commands
# Company rules (e.g., "FakeCorp")
- github: fakecorp/development-standards
branch: main
rules:
- guidelines/code-review.md
- guidelines/security.md
# Individual files from public repos
- https://github.com/thoughtbot/guides/blob/main/ruby/README.mdMachine-specific absolute paths in recipes.yml are the main reason two machines end up squashing different file lists. Ruly solves this by mirroring a shared recipes file, together with every rule file it references, into a fixed local directory that looks the same on every machine.
1. Put a recipes.yml in your rules repository, using paths relative to the repo root:
# patrickclery/rules → recipes.yml
recipes:
homelab:
description: "Local development dispatcher"
files:
- home/use-media-stack.md
skills:
- home/skills/ # directories expand to every .md file inside
subagents:
- name: media_stack
recipe: media-stack2. Declare it as a remote in ~/.config/ruly/recipes.yml on each machine:
remotes:
- github: patrickclery/rules
path: recipes.yml # default
branch: main # default3. Mirror it with --sync:
ruly squash homelab --sync--sync fetches the remote recipes.yml and the closure of files it needs — every entry under files:, skills:, commands: and scripts:, directory contents, and everything those files pull in through requires: and skills: frontmatter — into ~/.config/ruly/remotes/<owner>/<repo>/, preserving repo-relative paths. The mirror is replaced atomically; if a file a recipe lists directly cannot be fetched the sync aborts, lists the missing paths, and leaves the previous mirror untouched. Files reached only through requires:/skills: frontmatter are warned about and skipped, matching squash. If the recipes file itself cannot be fetched (offline), an existing mirror is kept with a warning.
Without --sync, Ruly makes no network calls for recipes and reads the mirror as-is.
Where recipes come from (first hit wins):
~/.config/ruly/remotes/<owner>/<repo>/recipes.yml— mirrored remotes./.recipes.yml— a project-local recipes file in the current directory~/.config/ruly/recipes.yml— the user config
Entries in a mirrored file are rebased onto the mirror directory; absolute paths, ~ paths and http(s) URLs are left untouched. ruly list-recipes shows which source won and where each recipe came from.
Per-machine tweaks with overrides:
remotes: and overrides: are settings, so they are read from both ~/.config/ruly/recipes.yml and ./.recipes.yml whichever source wins. An override adds to a shared recipe instead of restating it — arrays are unioned, scalars replaced, subagents merged by name:
# ~/.config/ruly/recipes.yml
remotes:
- github: patrickclery/rules
overrides:
homelab:
files:
- ~/notes/this-machine-only.md # appended to the shared list
mcp_servers:
- grafanaOverriding a recipe that is not loaded is an error. The recipes: block in the user config still works as before and is used only when nothing higher in the chain exists; relative paths under a mirrored recipe (including in overrides) resolve inside the mirror.
After installing Ruly, you can quickly get started with a basic configuration:
# Initialize Ruly with a starter configuration
ruly init
# This creates ~/.config/ruly/recipes.yml with example recipes
# Edit this file to add your own rule sourcesIf you don't want to maintain your own rules repository, you can use rules directly from GitHub:
recipes:
remote-only:
description: "Rules from various GitHub sources"
sources:
# Individual files
- https://github.com/rubocop/ruby-style-guide/blob/master/README.md
- https://github.com/testdouble/standard/blob/main/docs/README.md
# Entire directories (expands to all .md files)
- https://github.com/fakecorp/standards/tree/main/ruby
- https://github.com/fakecorp/standards/tree/main/testingHere's how the maintainer set up their private rules repository:
-
Created a private repository:
gh repo create patrickclery/rules --private --description "Private rules for Ruly gem" -
Created your rules content and pushed to GitHub
-
Updated your Ruly configuration:
# ~/.config/ruly/recipes.yml recipes: complete: description: "Personal + FakeCorp rules" sources: - github: patrickclery/rules branch: main rules: - ruby - testing - commands - github: fakecorp/cursor-rules branch: main rules: - workflow - jira
Ruly provides a CLI for managing and compiling your AI assistant rules.
Combine all rules into one file:
ruly squashUse a specific recipe:
# Recipe name as positional parameter
ruly squash rails
ruly squash apiCustom output file:
# Squash mode with custom output
ruly squash --output-file=combined-rules.md
# or using short option
ruly squash -o docs/my-rules.md
# Combine with recipe
ruly squash rails -o RAILS.mdToken statistics:
# Token stats for every file and recipe
ruly stats
# Token stats for one recipe
ruly stats rails
# Write the report somewhere else
ruly stats rails -o tokens.mdruly stats writes stats.md (per-file token counts, per-recipe totals, orphaned files, circular
requires: chains) to the rules directory unless -o is given. With no recipe source configured, it
still writes the per-file counts and warns on stderr that recipe totals are skipped.
Clean up generated files:
# Clean all agent-related files for current agent
ruly clean
# Clean files from specific recipe
ruly clean rails
# Clean files for specific agent
ruly clean --agent cursor
# Dry run to see what would be deleted
ruly clean --dry-run
ruly clean -d
# Clean before squashing (remove old files first)
ruly squash --clean
ruly squash rails --clean
ruly squash -c # Short form
# Deep clean before squashing (remove ALL Claude artifacts)
ruly squash --deepclean
ruly squash rails --deepcleanMCP servers are chosen per recipe with mcp_servers: (definitions come from
~/.config/ruly/mcp.json) and written to .mcp.json by ruly squash. For one-off servers, use
Claude Code's claude mcp add.
Subagents (a recipe and model per subagent, MCP server propagation and the generated agent file format) are documented under Reference: see Subagents.
Recipes allow you to define collections of rules to combine, rather than always including all files.
List available recipes:
ruly list-recipesUse a specific recipe:
# Use the 'core' recipe
ruly squash core
# Use 'testing' recipe with custom output
ruly squash testing -o testing-rules.md
# Another recipe
ruly squash minimalRecipes depend on having access to rule files. The recommended setup is a recipes.yml at the root of your rules repository, declared under remotes: and mirrored with ruly squash --sync (see Sharing Recipes Across Machines). Alternatively, define recipes directly in ./.recipes.yml or ~/.config/ruly/recipes.yml.
- qa — WorkAxle QA acceptance testing. Write and run Playwright specs in the automation-test-qa repo against dev.workaxle.com. Includes skills for running acceptance tests and syncing the QA repo.
Create a ~/.config/ruly/recipes.yml file to define your own recipes or override existing ones:
# ~/.config/ruly/recipes.yml
---
recipes:
# Complete development environment combining multiple sources
my_company_core:
description: Complete development environment with Ruby, testing, and workflow rules
sources:
# John's private rules repository
- github: john/private-rules
branch: main
rules:
- rules/commands/bug
- rules/commands/pr
- rules/bug
- rules/commands.md
- rules/core
- rules/core/debugging
- rules/pr
- rules/ruby
- rules/testing
- rules/commands/testing
- rules/commands/workflow
# Company's shared rules repository
- github: my_company/development-standards
branch: main
rules:
- rules/commands/jira/details.md
- rules/workflow
- rules/jira
# Local files from various projects
development_local:
description: Auto-generated from local sources
files:
- /Users/john/Projects/my_app/rules/ruby/common.md
- /Users/john/Projects/my_app/rules/ruby/monads.md
- /Users/john/Projects/my_app/rules/ruby/rspec.md
- /Users/john/Projects/my_app/rules/ruby/sequel.md
- /Users/john/Projects/my_app/rules/testing/common.md
- /Users/john/Projects/my_app/rules/commands.md
- /Users/john/Projects/my_app/rules/commands/bug/diagnose.md
- /Users/john/Projects/my_app/rules/commands/bug/fix.md
- /Users/john/Projects/my_app/rules/commands/pr/create.md
# Simple recipe for specific context
testing_only:
description: Testing and QA rules
files:
- /Users/john/Projects/my_app/rules/testing/*.md
- /Users/john/Projects/my_app/rules/commands/testing/*.mdUnknown or removed recipe keys print a warning on stderr and are ignored. A top-level tier: in
~/.config/ruly/recipes.yml or .recipes.yml (removed in 0.2.0) also warns and is ignored.
Recipes support explicit keys for files that need special treatment. Files listed under files: are always squashed into the main output (CLAUDE.local.md) regardless of their path. To output files as skills, commands, or bins, use the dedicated keys:
recipes:
my-recipe:
description: "Example with explicit keys"
files:
# Regular rule files — squashed into CLAUDE.local.md
- /path/to/rules/core.md
- /path/to/rules/frameworks/ruby.md
skills:
# Output as .claude/skills/{name}/SKILL.md
- /path/to/rules/skills/debugging.md
- /path/to/rules/github/pr/skills/pr-review-loop.md
commands:
# Output as .claude/commands/{path}.md
- /path/to/rules/github/pr/commands/create.md
- /path/to/rules/comms/jira/commands/comment.md
scripts:
# Copied to .claude/scripts/ as executables
- /path/to/rules/bin/deploy.shKey behavior:
| Recipe key | Output location | What it does |
|---|---|---|
files: |
CLAUDE.local.md |
Squashed into main output (always, regardless of path) |
skills: |
.claude/skills/{name}/SKILL.md |
Creates individual skill files |
commands: |
.claude/commands/{path}.md |
Creates slash command files |
scripts: |
.claude/scripts/ |
Copies scripts as executables |
All four keys support both individual file paths and directory paths. Directories are expanded:
skills:andcommands:directories expand to all*.mdfilesscripts:directories expand to all*.shfiles
Frontmatter skills: references in individual rule files still work independently. If a rule file declares skills: in its frontmatter, those referenced files are automatically resolved and output as SKILL.md files during squash, regardless of which recipe key they appear under.
Remote Sources:
- Supports pulling rules directly from GitHub repositories
- Automatically converts GitHub blob URLs to raw URLs
- Non-Claude agents include all files in the main output
GitHub URL Formats:
- Individual files: Use
/blob/URLs for specific files- Example:
https://github.com/owner/repo/blob/branch/path/to/file.md
- Example:
- Directories: Use
/tree/URLs to include all.mdfiles in a directory- Example:
https://github.com/owner/repo/tree/branch/path/to/directory - Automatically expands to include all markdown files in that directory
- Example:
- Important: Files with extensions (like
.md) in/tree/URLs are treated as individual files, not directories
Command File Handling:
- When
--agent claude(default), files listed under thecommands:recipe key are saved to.claude/commands/ - For other agents (
cursor,agents), command files are not written;-a agentslists them in its skipped-parts line - With
-a claude-plugin, recipe commands go to the plugin'scommands/directory - Files in
/commands/paths underfiles:are treated as regular content (squashed into main output)
User recipes:
- Are automatically loaded from
~/.config/ruly/recipes.yml - Override base recipes with the same name
- Are stored in your home directory configuration
- Allow user-specific or team-specific customizations
Recipes can extend other recipes using the extends: key. The child recipe inherits all keys from the parent, with:
- Array keys (
files,skills,commands,scripts,sources,mcp_servers,omit_command_prefix): Merged via union — parent entries first, then child entries, deduplicated - Scalar keys (
description,model): Child wins — parent value only used if child doesn't define it - Subagents: Merged by
name— child entry overrides parent entry with same name
recipes:
base:
description: "Base development recipe"
files:
- rules/core.md
- rules/common.md
mcp_servers:
- teams
extended:
extends: base
description: "Extended recipe with extra tools"
files:
- rules/extra.md
mcp_servers:
- atlassianAfter resolution, extended will have:
files:[rules/core.md, rules/common.md, rules/extra.md]mcp_servers:[teams, atlassian]description:"Extended recipe with extra tools"
Multi-level inheritance is supported (A extends B extends C). Circular references are detected and produce an error.
When running Claude Code in a subdirectory, it walks up the directory tree loading every CLAUDE.md and CLAUDE.local.md it finds. This can cause context bloat when worktrees or submodules are nested inside directories that have their own Claude instructions.
The isolate: true recipe option prevents this inheritance by populating claudeMdExcludes in .claude/settings.local.json with every parent CLAUDE.md and CLAUDE.local.md file found between the output directory and the filesystem root.
recipes:
my-isolated-recipe:
description: "Engineer with no parent context inheritance"
isolate: true
files:
- /path/to/rules/core.md
- /path/to/rules/frameworks/After ruly squash my-isolated-recipe, the generated .claude/settings.local.json will contain:
{
"claudeMdExcludes": [
"/Users/you/agents/orchestrator/CLAUDE.local.md",
"/Users/you/agents/orchestrator/workaxle-core/CLAUDE.md",
"/Users/you/agents/orchestrator/workaxle-core/CLAUDE.local.md"
]
}When to use:
- Worktrees nested inside parent projects with large CLAUDE files
- Submodules that should only use their own squashed rules
- Any recipe where you want a clean, self-contained context
AGENTS.md is the cross-agent instruction file standard and the recommended cross-agent path for sharing a ruly recipe with agents other than Claude Code.
ruly squash RECIPE -a agentswritesAGENTS.md;agents-mdandagentsmdare aliases, and-o PATHwrites elsewhere. There is no new command or recipe key.- The file starts with the header
<!-- Generated by ruly from recipe: NAME — do not edit -->, followed by the same squashed rulesCLAUDE.local.mdgets (requires:resolved, frontmatter stripped), then the recipe's skills as plain sections under## Skills. The Claude Code directivesCLAUDE.local.mdkeeps in a rule's frontmatter (name:,description:,permissionMode:,allowed_tools:) are stripped too, unless you pass--front-matter. - Commands, subagents, hooks,
mcp_serversand themodel/isolatesettings are Claude Code features, so they are skipped. Squash prints one line naming what it skipped (AGENTS.md target skips Claude-only parts: commands (2), subagents (1), ...). - Squash refuses to overwrite an
AGENTS.mdwhose first line is not the ruly header (move it aside or pass-o PATH). The check runs before--clean/--deepclean, so a refused squash deletes nothing.ruly clean -a agentsremovesAGENTS.mdonly when it has that header and leaves.claude/,.mcp.jsonandCLAUDE.local.mdalone;--deepcleanstill removes only Claude artifacts. Adding the header to a hand-written file hands that file to ruly. A UTF-8 BOM before the header (an editor re-save) is ignored. -i/-IaddAGENTS.mdto.gitignore/.git/info/exclude.AGENTS.mdis usually committed, so if the recipe pulls rules from a private repository, use-ior-I. New entries are merged into the existing# Ruly generated filessection, so running-ifor one target keeps the other target's entries (CLAUDE.local.md,.claude/commands/) ignored.- Recipe
scripts:are copied to.claude/scripts/for both targets, andAGENTS.mdrefers to them there.-i/-Ialso add each copied script (.claude/scripts/NAME).ruly clean -a agentskeeps them;ruly clean --deepcleanremoves them. - Post-squash checks (such as ambiguous links) run over the whole
AGENTS.md, inlined skills included. -a cursoris unchanged.
ruly squash RECIPE -a claude-plugin writes the recipe as a
Claude Code plugin directory that you load with
claude --plugin-dir or share, instead of writing into the project's .claude/. The default output
is unchanged. -o DIR picks the directory; the default is ruly-plugin-RECIPE/.
ruly-plugin-RECIPE/
├── .claude-plugin/plugin.json
├── skills/RECIPE-rules/SKILL.md # the squashed rules
├── skills/<skill>/SKILL.md
├── commands/
├── agents/
├── hooks/hooks.json
├── scripts/
└── .mcp.json
- Manifest:
nameis the recipe name (kebab-case recommended;claude plugin validatewarns otherwise, and names Claude Code reserves, such asclaude-*, are refused),versionis the ruly version,descriptionis the recipe description,authorisgit config user.namewhen set, andmetadata.generator: rulymarks ruly's ownership. - Known limitation:
version.versionis always the ruly version, whatever the rules hold. Claude Code caches marketplace and git installs by version, so rules re-squashed under the same ruly version reach only--plugin-dirand local-path installs, which load in place. Before you publish updated rules, raiseversionin the generatedplugin.jsonby hand (the next squash resets it). - Rules are not always-on. Plugins cannot carry always-on instructions: a plugin-root
CLAUDE.mdis not loaded (the docs say to ship instructions as a skill), a SessionStart hook's added context is capped at 10,000 characters, a forced plugin output style replaces the user's own and never reaches subagents, and a pluginagentsetting replaces the whole system prompt. So the rules become the skill/RECIPE:RECIPE-rules, loaded when invoked, and squash prints a notice. For always-on rules keep usingruly squash RECIPE(CLAUDE.local.md). If you want a nudge, add your own SessionStart hook that tells Claude to invoke that skill; ruly does not generate one. - Skills and subagents: nested skill paths are flattened (
skills/tdd/SKILL.mdbecomesskills/tdd/,git/commitbecomesgit-commit). Recipe and subagent skills are checked before they are written: a skill namedRECIPE-rules, or one whose flattened name is not letters, digits,.,_and-(or holds..), is refused, and two skill files with the same flattened name get a warning (the last one wins). Subagentmodel:is kept.permissionMode,hooksandmcpServersare left out of plugin agents because Claude Code ignores them there; the recipe's hooks and MCP servers (subagent servers included) go tohooks/hooks.jsonand.mcp.jsoninstead. Preloaded skills are listed asRECIPE:skill. Squash names what it left out, for exampleclaude-plugin target skips: model, isolate, subagent permissionMode, subagent cwd hooks. - Scripts (the recipe's and its subagents') are copied to
scripts/, and references in skills, commands, agents and hook commands are rewritten to${CLAUDE_PLUGIN_ROOT}/scripts/.... In hook commands.claude/scripts/X,./.claude/scripts/Xand$CLAUDE_PROJECT_DIR/.claude/scripts/X(quoted or with braces) are rewritten; the result is double-quoted unless the reference already sits inside a quoted string (bash -c "...",sh -c '...'). Squash names any other.claude/scripts/reference it leaves in a hook, such as~/.claude/scripts/X. - MCP secrets:
.mcp.jsoncopies server definitions from~/.config/ruly/mcp.json. Squash names (never prints) the servers with literal values that may be secrets: anyenvorheadersvalue,argssuch as--token VALUE,--api-key=VALUE,KEY=VALUEor a token-shaped value, and aurlwithuser:password@or a credential query parameter. Replace those values with${VAR}references before sharing the plugin. - Safety: squash refuses a directory ruly did not generate (no ruly metadata in
.claude-plugin/plugin.json), the working directory, its parents and$HOME(compared after resolving symlinks, so a symlinked path or//is caught too), and a-opath starting with~(ruly does not expand it). A ruly-generated directory is replaced only when the whole build succeeds: the previous plugin is moved to a hidden.DIR.ruly-previous-*sibling during the build and put back if the build fails. Subagent names must be letters, digits,.,_and-(no/or..) for every target that writes subagents.ruly clean RECIPE -a claude-pluginremoves only a ruly-generated plugin directory and never.claude/;--deepcleankeeps its meaning. Adding the marker to a hand-madeplugin.jsonhands that directory to ruly.-i/-Iadd the directory to.gitignore/.git/info/exclude. - Check and share: run
claude plugin validate ruly-plugin-RECIPE. Ruly does not write amarketplace.json; publishing is up to you.
-
Squash (
squash [RECIPE]): Combines all rule content into a single large file. Recipe is optional positional parameter. Supports fetching remote GitHub files. Use--tocor-tto generate a table of contents with unique anchors for all headers, ensuring proper navigation even when multiple files have identical header names. Also includes a list of available slash commands. Use--deepcleanto remove all Claude artifacts before squashing (overrides--clean). Use--verboseor-vto show detailed per-file processing output (file paths, token counts, requires discovery). Default output shows only recipe, subagents, errors, and summary. Use--syncto mirror everyremotes:entry (itsrecipes.ymlplus all referenced rule files) into~/.config/ruly/remotes/<owner>/<repo>/before squashing. See Sharing Recipes Across Machines. Use-a agentsto writeAGENTS.mdinstead. See AGENTS.md Output. Use-a claude-pluginto write a Claude Code plugin directory instead. See Claude Code Plugin Output. -
Stats (
stats [RECIPE]): Writesstats.mdwith per-file token counts, per-recipe totals, orphaned files and circularrequires:chains. Use-oto choose the output path. -
Clean (
clean [RECIPE]): Deletes output files created by the squash command. Recipe is optional. Removes main output file and command files directory. Use--deepcleanto remove all Claude artifacts (.claude/ directory, CLAUDE.local.md, CLAUDE.md) regardless of recipe.ruly clean -a agentsremoves only a ruly-generatedAGENTS.md.ruly clean RECIPE -a claude-pluginremoves only a ruly-generated plugin directory. -
Introspect (
introspect RECIPE SOURCE...): Scans one or more local directories or GitHub repo URLs for markdown files and creates or updates the named recipe in~/.config/ruly/recipes.yml(or the path given with-o). Options:-d/--descriptionsets the recipe description,--dry-runprints the recipe YAML and writes nothing, and--relativewrites repo-relative paths. -
List Recipes (
list-recipes): Shows all available recipes, which source in the lookup chain they came from (mirrored remote,./.recipes.yml, or~/.config/ruly/recipes.yml) and whether anoverrides:block was applied. Accepts--synclikesquash. -
Version (
version): Shows the current Ruly version.
Slash commands are special commands that can be defined in your rule files to provide quick actions for AI assistants. When you include command files in your rules (typically in a commands/ directory), they become available as slash commands in the generated output.
For example, if you have a file commands/bug/diagnose.md in your rules, it would become available as /bug:diagnose when using the generated rules with Claude or other AI assistants.
The --toc option will automatically generate:
- A table of contents with links to all headers in the combined document
- Unique anchors for headers (prefixed with the source file path) to handle duplicate header names across files
- A list of all available slash commands in your squashed output
This ensures proper navigation even when multiple rule files contain headers with identical names (e.g., multiple files with "# Introduction" sections).
/recipe-from-project- Drafts a recipe from a project folder's current rules, skills, commands, subagents and MCP servers, and writes it to the rules repo'srecipes.ymlonly after you approve the draft./ruly:compress- Analyze markdown rules to find redundancies and make them more DRY/ruly:decompose- Decompose a markdown file into a directory using git mv (preserves history)/run-acceptance-test- Takes acceptance criteria (direct text, Jira ticketWA-XXXX, or PR numberPR:NNNN), reads page objects from automation-test-qa, writes a Playwright spec, runs it, and reports results./sync-qa-repo- Pulls latest from automation-test-qa, reports new/changed page objects, specs, and API helpers.
The skill is not installed with the gem. ruly squash fetches it from https://github.com/patrickclery/ruly/blob/main/skills/recipe-from-project.md, so any recipe that lists this URL needs the network at squash time and exits 1 offline.
There are two ways to run it:
- A project already built from a recipe. Add the URL to that recipe's
skills:, or add it underoverrides:in~/.config/ruly/recipes.ymlfor one machine, then squash as usual. The skill defaults to the current folder. - Any other project. Run
ruly squash ruly-toolsin an empty directory (add--syncthe first time so the mirror has the recipe). Start Claude there withclaude --add-dir <project> --add-dir <rules clone>, and pass the project path to the skill.
The ruly-tools recipe is defined in the rules repo's recipes.yml, so a machine that mirrors that repo gets it from ruly squash --sync. Ruly reads recipes: from ./.recipes.yml or ~/.config/ruly/recipes.yml only when no remote is mirrored, and overrides: cannot add a new recipe. Without a mirror, define it in one of those files:
recipes:
ruly-tools:
description: "Ruly authoring tools"
skills:
- https://github.com/patrickclery/ruly/blob/main/skills/recipe-from-project.mdDo not squash ruly-tools inside the project you want to scan. Squashing there overwrites CLAUDE.local.md and empties mcpServers in .mcp.json, even when the fetch fails, which destroys the files the skill reads.
Every match in the draft is labelled exact or inferred. Content that matches nothing in the rules repo is reported and left out. The skill shows the draft first, and once you approve it, writes and validates the recipe and leaves the change uncommitted.
# Generate CLAUDE.local.md with all rules
ruly squash
# Dry run - see what would be created without creating it
ruly squash --dry-run
ruly squash -d
# Generate core rules only
ruly squash core
# Generate squashed testing rules to a custom file
ruly squash testing -o test/testing-rules.md
# Generate rules for a different agent (e.g., cursor)
ruly squash rails --agent cursor -o CURSOR.md
ruly squash rails -a cursor -o CURSOR.md
# Generate AGENTS.md for agents that read the AGENTS.md standard
ruly squash rails -a agents
# Remove a ruly-generated AGENTS.md (a hand-written one is left alone)
ruly clean -a agents
# Package the rails recipe as a Claude Code plugin in ruly-plugin-rails/
ruly squash rails -a claude-plugin
# Load the generated plugin for one session
claude --plugin-dir ruly-plugin-rails
# Remove the ruly-generated plugin directory
ruly clean rails -a claude-plugin
# Generate with remote sources (command files go to .claude/commands/)
ruly squash example_mixed
# Mirror shared recipes from `remotes:` first, then squash from the mirror
ruly squash homelab --sync
# Clean up generated files
ruly clean
# Dry run - see what would be deleted
ruly clean --dry-run
ruly clean -d
# Deep clean - remove all Claude artifacts
ruly clean --deepclean
# Clean specific output file
ruly clean -o test/testing-rules.md
# Preview a 'ruby' recipe built from a rules directory (writes nothing)
ruly introspect ruby rules/ruby/ --dry-run
# Write it with repo-relative paths and a description
ruly introspect ruby rules/ruby/ --relative -d "Ruby rules"
# List what recipes are available
ruly list-recipes
# Show version
ruly version
# View help
ruly help
ruly help squash
ruly help clean
ruly help introspect
# Per-command help flags work too
ruly squash --help
ruly stats -hRuly will automatically:
- Load recipes from the first of: mirrored remotes (
~/.config/ruly/remotes/),./.recipes.yml,~/.config/ruly/recipes.yml - Expand a directory entry in a recipe to every
.mdfile inside it - Create parent directories if using custom output paths
- Display file count and output size
- Show which recipe was used in the output
This section holds detailed reference for features summarized above.
Subagents allow you to generate specialized agent files that Claude can dispatch to for specific tasks. Each subagent is a self-contained agent with its own rules, commands, and MCP server access.
Add a subagents array to any recipe. Each subagent references another recipe:
recipes:
# Main recipe that spawns subagents
full:
description: "Complete development environment"
files:
- /path/to/rules/core.md
subagents:
- name: bug_investigator
recipe: bug
- name: test_runner
recipe: testing
- name: pr_manager
recipe: pr
# Recipes used by subagents
bug:
description: "Bug investigation and debugging"
files:
- /path/to/rules/bug/
- /path/to/rules/debugging.md
mcp_servers:
- teams
testing:
description: "Testing and QA workflows"
files:
- /path/to/rules/testing/
mcp_servers:
- playwright
pr:
description: "PR management"
files:
- /path/to/rules/github/pr/When you run ruly squash full:
- MCP servers collected: Recursively collects
mcp_serversfrom all subagent recipes .mcp.jsonwritten: Parent's.mcp.jsonincludes all collected servers (deduplicated)- Main rules generated:
CLAUDE.local.mdwith the main recipe content - Agent files created:
.claude/agents/{name}.mdfor each subagent - Commands organized:
.claude/commands/{agent_name}/for agent-specific commands
your-project/
├── CLAUDE.local.md # Main rules (from 'full' recipe)
├── .mcp.json # MCP servers (parent + all subagent servers)
├── .ruly/
│ └── bin/ # Bin files (from scripts: key)
└── .claude/
├── agents/
│ ├── bug_investigator.md # Squashed 'bug' recipe
│ ├── test_runner.md # Squashed 'testing' recipe
│ └── pr_manager.md # Squashed 'pr' recipe
├── commands/
│ ├── bug_investigator/ # Commands for bug agent
│ ├── test_runner/ # Commands for testing agent
│ └── pr_manager/ # Commands for PR agent
└── skills/ # Skills (from skills: key)
└── debugging/
└── SKILL.md
Claude Code subagents inherit the parent session's MCP configuration — they cannot have independent MCP servers. Ruly handles this automatically: during ruly squash, MCP servers from all subagent recipes (recursively, including nested subagents) are collected and merged into the parent's .mcp.json.
For example, given this recipe configuration:
recipes:
core:
description: "Main orchestrator"
files:
- /path/to/rules/core.md
# Note: no mcp_servers defined here
subagents:
- name: comms
recipe: comms
- name: feature
recipe: feature
comms:
description: "Communication agent"
files:
- /path/to/rules/comms/
mcp_servers:
- teams
feature:
description: "Feature development"
files:
- /path/to/rules/feature/
mcp_servers:
- RefRunning ruly squash core produces a .mcp.json containing teams and Ref — all propagated from the subagent recipes — even though core itself defines no MCP servers. The console output shows which servers were propagated:
🔌 Propagated MCP servers from subagents: teams, Ref
🔌 Updated .mcp.json with MCP servers
This propagation is recursive: if comms itself has subagents with additional MCP servers, those are collected too. Circular references are handled safely.
Generated agent files have YAML frontmatter that Claude understands:
---
name: bug_investigator
description: Bug investigation and debugging
tools: inherit
model: haiku # Set via subagent or recipe config (default: inherit)
# Auto-generated from recipe: bug
# Do not edit manually - regenerate using 'ruly squash full'
---
# Bug Investigator
Bug investigation and debugging
## Recipe Content
[squashed content from bug recipe]
## MCP Servers
This subagent has access to the following MCP servers:
- teams
---
*Last generated: 2026-02-04 12:30:00*
*Source recipe: bug*Control which Claude model each subagent uses. Route lightweight tasks (context fetching, DMs) to faster/cheaper models while keeping complex tasks on the most capable model.
Specify model directly on a subagent entry:
subagents:
- name: context_grabber
recipe: context-grabber
model: haiku # Fast, cheap — just fetching data
- name: core_engineer
recipe: core-engineer
model: opus # Most capable — complex implementation
- name: comms
recipe: comms # No model — inherits from recipe or defaults to 'inherit'Set a default model for all subagents in a recipe:
recipes:
core:
description: "Main orchestrator"
model: sonnet # Default for all subagents
files:
- /path/to/rules/core.md
subagents:
- name: fast_agent
recipe: fast-tasks
model: haiku # Overrides recipe default
- name: smart_agent
recipe: complex-tasks
# Uses recipe default (sonnet)Model is resolved in this order:
- Subagent
model— if specified on the subagent entry - Parent recipe
model— if set on the recipe containing the subagents inherit— the default (inherits from the calling session)
Valid values: haiku, sonnet, opus, or inherit.
Note: Skills can also specify
modelin their frontmatter — this is already supported and preserved during squash.
Subagent instruction files should be organized in agents/ directories:
rules/
└── comms/
├── ms-teams/
│ ├── common.md # Shared patterns (loaded by both)
│ ├── commands/
│ │ └── dm.md # User command: /ms-teams:dm
│ └── agents/
│ └── ms-teams-dm.md # Subagent: dispatched on "send it"
Key distinction:
commands/- User-invocable via/command-nameagents/- Dispatched programmatically by the orchestrator
| Use Case | Benefit |
|---|---|
| Specialized tasks | Each agent has focused rules for its domain |
| Parallel work | Dispatch multiple agents for independent tasks |
| Context isolation | Agents only load rules they need |
| MCP server propagation | Subagent MCP servers are automatically propagated to parent |
recipes:
workaxle:
description: "Main WorkAxle development"
files:
- /path/to/rules/core.md
subagents:
- name: comms
recipe: comms # Jira, Teams, GitHub communications
- name: merger
recipe: merger # PR merging operations
- name: dashboard
recipe: dashboard # PR status dashboard
comms:
description: "Communication via Jira, Teams, GitHub"
files:
- /path/to/rules/comms/
mcp_servers:
- teams
- atlassian
merger:
description: "PR merging commands"
files:
- /path/to/rules/github/pr/
mcp_servers: []
dashboard:
description: "Open PRs dashboard"
files:
- /path/to/rules/dashboard.md
mcp_servers: []Then Claude can dispatch to these agents:
User: "Update all my PRs with latest main"
Claude: [Dispatches to merger agent which has PR merge rules]
User: "Send a Teams message about WA-1234"
Claude: [Dispatches to comms agent which has Teams MCP access]
User: "Show me my open PRs"
Claude: [Dispatches to dashboard agent]
An orchestrator that manages multiple repositories, each with their own CLAUDE.md and hooks. Subagents dispatched into each repo automatically pick up the repo's configuration.
~/agents/orchestrator/
├── CLAUDE.local.md # Generated orchestrator rules
├── .mcp.json # MCP servers (collected from all subagents)
├── .claude/
│ ├── agents/
│ │ ├── backend_engineer.md # Has acme-api's CLAUDE.md + hooks baked in
│ │ ├── frontend_engineer.md # Has acme-web's CLAUDE.md + rules + hooks baked in
│ │ └── comms.md # Pure ruly recipe (no repo append)
│ ├── scripts/
│ │ └── worktree-create.sh # Propagated to all submodule dirs
│ └── settings.local.json # Parent hooks (WorktreeCreate)
├── acme-api/ # Backend repo (git submodule)
│ ├── CLAUDE.md # 1800-line repo-specific guidance
│ └── .claude/
│ └── settings.json # No custom hooks
├── acme-web/ # Frontend repo (git submodule)
│ ├── CLAUDE.md # 500-line repo-specific guidance
│ └── .claude/
│ ├── rules/
│ │ └── command-timeouts.md # Repo-specific rules
│ ├── hooks/
│ │ └── eslint-fix.sh # Repo-specific hook script
│ └── settings.json # PostToolUse hook for ESLint
recipes:
orchestrator:
description: "Multi-repo dispatcher"
hooks:
WorktreeCreate:
- hooks:
- type: command
command: ".claude/scripts/worktree-create.sh"
timeout: 120
files:
- /path/to/rules/orchestrator/dispatch.md
scripts:
- /path/to/rules/orchestrator/bin/worktree-create.sh
subagents:
# Backend — reads acme-api's CLAUDE.md and hooks
- name: backend_engineer
recipe: backend-engineer
cwd: acme-api
append: true
# Frontend — reads acme-web's CLAUDE.md, rules, and hooks
- name: frontend_engineer
recipe: frontend-engineer
cwd: acme-web
append: true
# Comms — pure ruly recipe, no repo to append
- name: comms
recipe: commsWhen a subagent has both cwd: and append: true, ruly reads from the repo directory during squash:
| Source | What's read | Where it goes |
|---|---|---|
{cwd}/CLAUDE.md |
Repo's main guidance doc | Appended to agent body as ## Repository Context |
{cwd}/.claude/rules/*.md |
Repo-specific rules | Appended to agent body as ## Repository Rules |
{cwd}/.claude/settings.json |
Repo's hooks | Merged into agent frontmatter hooks: |
Each subagent gets only its own repo's hooks — no cross-contamination between subagents.
The frontend_engineer subagent gets the parent's WorktreeCreate hook merged with the repo's PostToolUse hook:
---
name: frontend_engineer
description: Frontend feature development - React/TypeScript with TDD
tools: Bash, Read, Write, Edit, Glob, Grep
model: inherit
mcpServers: "[playwright, Ref]"
permissionMode: bypassPermissions
hooks:
WorktreeCreate:
- hooks:
- type: command
command: ".claude/scripts/worktree-create.sh"
timeout: 120
PostToolUse:
- matcher: Edit|Write
hooks:
- type: command
command: ".claude/hooks/eslint-fix.sh"
# Auto-generated from recipe: frontend-engineer
# Do not edit manually - regenerate using 'ruly squash orchestrator'
---The backend_engineer subagent only gets the parent's hook (since acme-api has no custom hooks):
---
name: backend_engineer
description: Backend feature development - Ruby/Sequel with TDD
tools: Bash, Read, Write, Edit, Glob, Grep
model: inherit
hooks:
WorktreeCreate:
- hooks:
- type: command
command: ".claude/scripts/worktree-create.sh"
timeout: 120
# Auto-generated from recipe: backend-engineer
# Do not edit manually - regenerate using 'ruly squash orchestrator'
---After the recipe's squashed content, each subagent with append: true gets additional sections:
## Recipe Content
[squashed content from frontend-engineer recipe]
---
## Repository Context
# CLAUDE.md
This file provides guidance for the acme-web frontend application...
## Development
- Use `yarn dev` for development server
- Use `yarn typecheck` for type checking
- Use `yarn lint --fix` for linting
---
## Repository Rules
## Command Timeouts
### Rule
Always use a **5-minute timeout** (300000ms) for:
- `yarn typecheck`
- `yarn lint`
---
*Last generated: 2026-03-06 10:43:25*
*Source recipe: frontend-engineer*| Feature | append: true |
No append |
|---|---|---|
| Recipe content | Included | Included |
| Repo CLAUDE.md | Baked into agent body | Not visible to subagent |
| Repo .claude/rules/ | Baked into agent body | Not visible to subagent |
| Repo hooks (settings.json) | Merged into frontmatter | Not applied |
| Parent hooks | Always included | Always included |
| MCP servers | From recipe (propagated to parent) | From recipe (propagated to parent) |
Note: Claude Code subagents do not automatically discover
CLAUDE.md,.claude/rules/, or.claude/settings.jsonfrom their CWD. Theappendfeature exists specifically to bridge this gap by baking repo configuration into the agent file at squash time.
Permission denied:
- Ensure you have write access to your project directory
- Check that Ruby gems can be installed globally
Recipe not found:
- Run
ruly list-recipesto see available recipes - Check
~/.config/ruly/recipes.ymlfor user-defined recipes - Ensure recipe names match exactly (case-sensitive)
Files not being cleaned:
- Use
ruly clean --dry-runto preview what will be deleted - Specify agent with
--agentoption if not using Claude - Ensure you're using the correct recipe name if specified