Power Directory Invoker

Execute a command or script across multiple directories in a monorepo or multi-project workspace, collecting and aggregating results from each location.

When to Use This Command

Run this command when...

• You need to run the same command (build, test, lint) across all packages in a monorepo
• You want to execute a script in every project directory matching a glob pattern
• You need aggregated pass/fail results from running a command in multiple locations

Avoid this command when...

• You only need to run a command in a single directory
• Your monorepo tool (Nx, Turborepo, Lerna) already handles cross-package orchestration

Quick Start

Copy
# .claude/commands/power-directory-invoker.md
---
allowed-tools: ["Bash", "Glob"]
---
Find directories matching the given pattern. Execute the
specified command in each. Aggregate and report results.

Example usage:

/power-directory-invoker "npm test" packages/*
/power-directory-invoker "cargo build" crates/*

Example output:

Directories matched: 5

  packages/core/       npm test  PASS  (2.1s)
  packages/ui/         npm test  PASS  (3.4s)
  packages/api/        npm test  FAIL  (1.8s)
  packages/utils/      npm test  PASS  (0.9s)
  packages/config/     npm test  PASS  (0.4s)

Summary: 4 passed, 1 failed
Failed: packages/api/ (exit code 1)

Core Concepts

Concept	Description
Directory discovery	Finds directories matching a glob or explicit list
Command execution	Runs the same command in each matched directory sequentially
Result aggregation	Collects exit codes, output, and timing from each run
Parallel option	Optionally run commands concurrently to reduce total time

Pattern (packages/*) --> Match Directories
                              |
                 +------+------+------+
                 |      |      |      |
               dir1   dir2   dir3   dir4
                 |      |      |      |
              Run Command in Each
                 |      |      |      |
                 +------+------+------+
                         |
                  Aggregate Results

Configuration

Option	Default	Description
pattern	packages/*	Glob pattern for directory matching
parallel	false	Run commands concurrently across directories
concurrency	4	Max parallel executions when parallel is enabled
bail	false	Stop on first failure without running remaining directories
output	summary	Output mode (summary, verbose, json)

Best Practices

1. Use specific patterns -- packages/*/ is better than **/ to avoid matching deeply nested directories.
2. Enable parallel for independent packages -- if packages do not depend on each other, parallel saves significant time.
3. Bail on critical commands -- set bail=true for build commands where a failure invalidates downstream steps.
4. Check concurrency limits -- too many parallel processes can exhaust memory or file descriptors.
5. Use verbose mode for debugging -- when a command fails, switch to verbose to see its full output.

Common Issues

1. Directory not found -- ensure the glob pattern matches actual directories. Run ls to verify.
2. Command not found in subdirectory -- the command must be in each directory's PATH. Use absolute paths or npx.
3. Parallel race conditions -- if packages share build output directories, parallel runs can cause file conflicts. Use sequential mode.