
working-in-monorepos
- version
- 1.0.4
- GitHub stars
- 13
Install
/plugin install working-in-monorepos@pickled-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.
Contents
Discovered from sourceSkills 1
Working in Monorepos
Overview
Helps Claude work effectively in monorepo environments by ensuring commands always execute from the correct location using absolute paths.
Core principle: Bash shell state is not guaranteed between commands. Always use absolute paths.
When to Use
Use this skill when:
- Repository contains multiple subprojects (ruby/, cli/, components/*, etc.)
- Commands must run from specific directories
- Working across multiple subprojects in one session
Don't use for:
- Single-project repositories
- Repositories where all commands run from root
Use Absolute Paths
Run each command in a monorepo subproject with an absolute cd prefix:
✅ CORRECT:
cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec
cd /Users/josh/workspace/schemaflow/cli && npm test
❌ WRONG:
# Relative paths (assumes current directory)
cd ruby && bundle exec rspec
# No cd prefix (assumes location)
bundle exec rspec
# Chaining cd (compounds errors)
cd ruby && cd ruby && rspec
Why: You cannot rely on shell state. Absolute paths guarantee correct execution location regardless of where the shell currently is.
Constructing Absolute Paths
With .monorepo.json Config
If .monorepo.json exists at repo root:
- Read
rootfield for absolute repo path - Read subproject
pathfromsubprojectsmap - Construct:
cd {root}/{path} && command
Example:
{
"root": "/Users/josh/workspace/schemaflow",
"subprojects": { "ruby": { "path": "ruby" } }
}
→ cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec
Without Config
Use git to find repo root, then construct absolute path:
- Get the repo root once per session:
git rev-parse --show-toplevel - Use that absolute path:
cd /absolute/path/to/repo/ruby && bundle exec rspec
Example workflow:
# Step 1: Get repo root
git rev-parse --show-toplevel
# Output: /Users/josh/workspace/schemaflow
# Step 2: Use absolute path in commands
cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec
Why not use command substitution: cd $(git rev-parse --show-toplevel)/ruby requires user approval. Instead, run git rev-parse once, then use the absolute path directly in all subsequent commands.
⚠️ Git subtree caveat: In repositories containing git subtrees (nested git repos), git rev-parse --show-toplevel returns the innermost repo root, not the monorepo root. This makes it unreliable for subtree scenarios. Creating a .monorepo.json config is the robust solution that works in all cases.
Setup Workflow (No Config Present)
When the repo looks like a monorepo but has no .monorepo.json, offer to generate one with scripts/monorepo-init. If the user agrees, run it with --dry-run, show the output, and run it with --write once they approve. If not, get the repo root once with git rev-parse and use absolute paths. They can also write .monorepo.json by hand from the schema below.
Script location: scripts/monorepo-init in this skill's base directory. Call it by absolute path so it works from any directory. --help documents every flag, so there's no need to read the source.
Command Execution Rules (With Config)
If .monorepo.json defines command rules:
{
"commands": {
"rubocop": { "location": "root" },
"rspec": {
"location": "subproject",
"command": "bundle exec rspec",
"overrides": { "root": { "command": "bin/rspec" } }
}
}
}
Check rules before executing:
- Look up command in
commandsmap - Check
location: "root" | "subproject" - Check for
commandoverride - Check for context-specific
overrides
Example:
- rubocop: Always run from repo root
- rspec in ruby/: Use
bundle exec rspec - rspec in root project: Use
bin/rspec
Quick Reference
| Task | Command Pattern |
|---|---|
| Get repo root | git rev-parse --show-toplevel (run once, use result in all commands) |
| Run tests in subproject | cd /absolute/path/to/repo/subproject && test-command |
| With config | cd {root}/{subproject.path} && command |
| Check for config | test -f .monorepo.json |
| Generate config | <skill-dir>/scripts/monorepo-init --dry-run (works from any directory) |
| Always rule | Absolute path and cd prefix on each command. Get the repo root once, then use it directly. |
Configuration Schema
.monorepo.json at repository root:
{
"root": "/absolute/path/to/repo",
"subprojects": {
"subproject-id": {
"path": "relative/path",
"type": "ruby|node|go|python|rust|java",
"description": "Optional"
}
},
"commands": {
"command-name": {
"location": "root|subproject",
"command": "optional override",
"overrides": {
"context": { "command": "context-specific" }
}
}
}
}
Minimal example:
{
"root": "/Users/josh/workspace/schemaflow",
"subprojects": {
"ruby": { "path": "ruby", "type": "ruby" },
"cli": { "path": "cli", "type": "node" }
}
}
Commands 2
Run monorepo-init script to detect subprojects and generate .monorepo.json.
Preview detection:
"${CLAUDE_PLUGIN_ROOT}/skills/working-in-monorepos/scripts/monorepo-init" --dry-run
Write configuration:
"${CLAUDE_PLUGIN_ROOT}/skills/working-in-monorepos/scripts/monorepo-init" --write
After writing the configuration, activate the working-in-monorepos skill to enable enhanced monorepo navigation.
Run integration tests for the working-in-monorepos plugin.
What This Tests
- Hook Configuration - Validates hooks.json structure and patterns
- Script Execution - Runs hooks with realistic stdin
- Skill Effectiveness - Tests agent behavior in monorepo scenarios
Full Mode (Default)
Step 1: Run pytest tests
cd plugins/working-in-monorepos && uv run pytest tests/ -v
Report results and any failures. If tests fail, stop here.
Step 2: Run subagent scenarios
Run scenarios from skills/working-in-monorepos/tests/baseline-scenarios.md:
-
Set up a test monorepo under
$TMPDIRwith structure:$TMPDIR/test-monorepo/$TMPDIR/test-monorepo/ruby/(with Gemfile)$TMPDIR/test-monorepo/cli/(with package.json)
-
For each scenario, dispatch a subagent with the Agent tool, using the scenario prompt
-
Evaluate: Did the agent use absolute paths?
-
Report pass/fail for each scenario
Quick Mode (with --quick flag)
Run pytest tests only, skip subagent scenarios.
Usage
/working-in-monorepos:validate # Full mode - pytest + subagent tests
/working-in-monorepos:validate --quick # Quick mode - pytest only
Hooks 1
Sponsors
Details
- Marketplace
- technicalpickles/pickled-claude-plugins
- Source
- plugins/working-in-monorepos
- Category
- Community
More from technicalpickles/pickled-claude-plugins
All 26- writing-toolsv0.3.0
- actually-lspv0.7.1
- agent-metav3.4.1
- automic-vaultv0.3.0
- buildkitev1.1.4
- ci-cd-toolsv1.2.2
- come-onv0.2.1
- cqv0.3.1
- dev-toolsv1.5.0
- gitv3.6.0
- github-actionsv0.1.1
- hkv0.2.0
- inflight-artifactv0.5.0
- mcpproxyv1.0.2
- petri-dishv0.1.0
- pickle-modev0.3.0
- sandbox-advisorv0.3.0
- second-brainv2.2.0
- stay-on-targetv1.0.1
- stay-principledv0.1.1
- tailscalev0.5.0
- taskwarriorv1.4.0
- tool-routingv1.4.0
- wait-for-itv0.2.2