possibilities/claude-composer: A tool for enhancing Claude Code

A tool for enhancing Claude Code

• Automatic dialog dismissal
• System notifications for lifecycle events and dialogs
• Toolsets: Configure tool permissions and MCP servers
• Rulesets: Fine grained control for automatic dialog dismissal

npm install -g claude-composer
# or
yarn global add claude-composer
# or
pnpm add -g claude-composer

# Initialize global configuration
claude-composer cc-init

# Start Claude Code with automatic dialog dismissal
claude-composer  # Uses the ruleset configured during cc-init

# Use a more permissive ruleset
claude-composer --ruleset internal:yolo

Claude Composer is a CLI wrapper for Claude Code that adds small enhancements around automation, UX, and configuration.

Key benefits:

• Reduced interruptions: Automatically handles permission dialogs based on configurable rules
• Enhanced visibility: System notifications keep you informed without switching contexts
• Flexible control: Rulesets let you define exactly which actions to allow automatically
• Tool management: Toolsets simplify configuring which tools Claude can use

See docs/installation.md for detailed installation instructions.

• Node.js 18 or higher
• npm, yarn, or pnpm package manager
• Claude Code installed and configured

Install Claude Composer globally:

pnpm add -g claude-composer

Or with other package managers:

yarn global add claude-composer
npm install -g claude-composer

Run claude-composer cc-init to create your initial configuration:

# Create global configuration (default)
claude-composer cc-init

# Or create project-specific configuration
claude-composer cc-init --project

By default, claude-composer cc-init creates a global configuration that applies to all projects:

• Configuration location: ~/.claude-composer/config.yaml
• Interactive prompts for ruleset and toolset selection
• Applies to all Claude Composer invocations unless overridden

Use claude-composer cc-init --project to create a project-specific configuration:

• Creates .claude-composer/config.yaml in current directory
• Takes precedence over global configuration when present
• Ideal for project-specific rules and tool settings

Global configuration:

~/.claude-composer/
├── config.yaml          # Global configuration
├── rulesets/           # Custom global rulesets (unprefixed)
│   ├── my-workflow.yaml
│   └── backend-dev.yaml
└── toolsets/           # Custom global toolsets (unprefixed)
    ├── my-tools.yaml
    └── web-dev.yaml

Project configuration (with --project):

your-project/
├── .claude-composer/
│   ├── config.yaml     # Project configuration
│   ├── rulesets/       # Custom project rulesets
│   └── toolsets/       # Custom project toolsets
└── ... (your project files)

claude-composer [claude-composer-options] [claude-code-args]

Claude Composer acts as a wrapper around Claude Code, passing through all supported arguments to Claude Code.

# Use global configuration
claude-composer

# Use project configuration (if present)
cd your-project
claude-composer

# Override with specific ruleset
claude-composer --ruleset internal:safe

# Pass model selection to Claude Code
claude-composer --model claude-3-opus-20240229

# Combine composer options with Claude Code args
claude-composer --ruleset internal:yolo --model claude-3-opus-20240229

# Safe mode - all dialogs require confirmation
claude-composer --ruleset internal:safe

# Cautious mode - auto-accept project-level operations
claude-composer --ruleset internal:cautious

# YOLO mode - auto-accept all operations
claude-composer --ruleset internal:yolo

# Global custom ruleset (no prefix needed)
claude-composer --ruleset my-workflow

# Project-specific ruleset
claude-composer --ruleset project:my-custom-rules

# Chain multiple rulesets
claude-composer --ruleset internal:safe --ruleset my-overrides

See docs/examples.md for more usage examples and advanced workflows.

mkdir my-project && cd my-project
claude-composer cc-init --project
claude-composer  # Uses the configuration created by cc-init

# Use YOLO mode if you are truly living in the moment
claude-composer --ruleset internal:yolo

# This effectively disables accepting all confirmations
claude-composer --ruleset internal:safe

# Enable built-in tools
claude-composer --toolset internal:core --ruleset internal:cautious

# Use global custom toolset
claude-composer --toolset my-tools --ruleset my-workflow

Claude Composer uses YAML configuration files to define behavior. Configuration is loaded from multiple sources with the following precedence (highest to lowest):

1. Command-line flags
2. Project configuration (.claude-composer/config.yaml)
3. Global configuration (~/.claude-composer/config.yaml)
4. Built-in defaults

• Global: ~/.claude-composer/config.yaml
• Project: .claude-composer/config.yaml
• Custom rulesets: {config-dir}/rulesets/*.yaml
• Custom toolsets: {config-dir}/toolsets/*.yaml

# Rulesets to apply (in order)
rulesets:
  - internal:cautious # Built-in ruleset
  - my-defaults # Global custom ruleset
  - project:custom-rules # Project-specific ruleset

# Toolsets to enable
toolsets:
  - internal:core # Built-in toolset
  - development-tools # Global custom toolset
  - project:my-tools # Project-specific toolset

# Trusted root directories
roots:
  - ~/projects/work
  - ~/projects/personal

# UI preferences
show_notifications: true
sticky_notifications: false

See docs/configuration.md for comprehensive configuration documentation.

Claude Composer supports environment variables for configuration:

• CLAUDE_COMPOSER_CONFIG_DIR – Override config directory location
• CLAUDE_COMPOSER_NO_NOTIFY – Disable all notifications
• FORCE_COLOR – Control color output

See docs/environment-variables.md for details.

Roots define trusted parent directories where Claude Code’s initial trust prompt is automatically accepted. See docs/roots-config.md for detailed configuration options.

roots:
  - ~/projects # Trust direct children of ~/projects
  - /tmp/sandbox # Trust direct children of /tmp/sandbox
  - $WORK_DIR/repos # Environment variable expansion supported

When you start Claude Composer in a directory whose parent is listed in roots:

• The “Do you trust the files in this folder?” prompt is automatically accepted
• The automatic acceptance confirmation prompt is suppressed

Important: Only direct children of root directories are trusted. For example, if ~/projects is a root, then ~/projects/my-app is trusted, but ~/projects/my-app/src is not.

Rulesets control which permission dialogs are automatically accepted or rejected. They provide fine-grained control over Claude Code’s interactions with your system.

Rulesets are YAML files that define:

• Which dialogs to automatically accept or reject
• Path-based rules for file and directory operations
• Pattern-based command filtering
• Domain allowlists for web requests

Claude Composer includes three built-in rulesets. See docs/internal-rulesets.md for detailed information about each ruleset.

Maximum security – all dialogs require manual confirmation. No automatic acceptance of any operations.

Balanced approach – automatically accepts project-level operations (file edits, creates, bash commands) while requiring confirmation for global operations and web requests.

Maximum automation – accepts all operations without confirmation, including global file operations and web requests. Use with caution.

See docs/rulesets.md for detailed ruleset documentation and creating custom rulesets.

Create custom rulesets in your project’s .claude-composer/rulesets/ directory:

# .claude-composer/rulesets/backend.yaml
name: backend
description: Rules for backend development

# Accept file operations with path restrictions
accept_project_edit_file_prompts:
  paths:
    - 'src/**/*.js'
    - 'src/**/*.ts'
    - 'test/**'
    - '!**/*.env'

accept_project_bash_command_prompts: true
accept_fetch_content_prompts: false

# Use internal ruleset
claude-composer --ruleset internal:cautious

# Use global custom ruleset (no prefix)
claude-composer --ruleset my-workflow

# Use project ruleset
claude-composer --ruleset project:backend

# Chain multiple rulesets (later rules override earlier)
claude-composer --ruleset internal:cautious --ruleset my-defaults --ruleset project:backend

Custom rulesets allow fine-grained control over automation. See docs/rulesets.md for complete syntax and examples.

Toolsets control which tools Claude can use and configure MCP (Model Context Protocol) servers. They provide a flexible way to manage Claude’s capabilities on a per-project or global basis.

Toolsets are YAML files that define:

• Which tools Claude is allowed to use
• Which tools Claude is explicitly blocked from using
• MCP server configurations for additional tool capabilities

Claude Composer includes one built-in toolset. See docs/internal-toolsets.md for detailed information.

Provides access to Context7 documentation tools, allowing Claude to fetch up-to-date library documentation.

Create custom toolsets in your project’s .claude-composer/toolsets/ directory:

# .claude-composer/toolsets/dev-tools.yaml
allowed:
  - Read
  - Write
  - Edit
  - MultiEdit
  - Bash

disallowed:
  - WebSearch

mcp:
  my-server:
    type: stdio
    command: node
    args:
      - ./tools/mcp-server.js

# Use internal toolset
claude-composer --toolset internal:core

# Use global custom toolset (no prefix)
claude-composer --toolset my-tools

# Use project toolset
claude-composer --toolset project:dev-tools

# Chain multiple toolsets
claude-composer --toolset internal:core --toolset project:backend-tools

Toolsets control which tools Claude can use and configure MCP servers. See docs/toolsets.md for complete documentation.

See docs/cli-reference.md for complete command line documentation.

• --ruleset – Use specified rulesets (can be used multiple times)
• --toolset – Use specified toolsets (can be used multiple times)
• --ignore-global-config – Ignore global configuration file

• --dangerously-allow-in-dirty-directory – Allow running with uncommitted git changes
• --dangerously-allow-without-version-control – Allow running outside version control
• --dangerously-suppress-automatic-acceptance-confirmation – Skip confirmation prompts

• --show-notifications / --no-show-notifications – Enable/disable desktop notifications
• --sticky-notifications / --no-sticky-notifications – Make notifications stay until dismissed
• --show-work-complete-notifications / --no-show-work-complete-notifications – Show/hide work completion notifications

• --quiet – Suppress preflight messages
• --allow-buffer-snapshots – Enable Ctrl+Shift+S terminal snapshots
• --log-all-pattern-matches – Log pattern matches to ~/.claude-composer/logs/

Initialize a new configuration file:

# Create global config
claude-composer cc-init

# Create project config
claude-composer cc-init --project

# Specify ruleset during init
claude-composer cc-init --use-cautious-ruleset

Options:

• --project – Create config in current directory
• --use-yolo-ruleset – Use YOLO ruleset
• --use-cautious-ruleset – Use cautious ruleset (recommended)
• --use-safe-ruleset – Use safe ruleset
• --use-core-toolset / --no-use-core-toolset – Enable/disable core toolset

All unrecognized options are passed to Claude Code:

# These go to Claude Code
claude-composer --model claude-3-opus-20240229
claude-composer --print
claude-composer --help  # Shows both claude-composer and claude help

Fine-tune which notifications appear:

# Control specific notification types
claude-composer --no-show-edit-file-confirm-notify
claude-composer --show-accepted-confirm-notify
claude-composer --sticky-work-complete-notifications

See docs/notifications.md for detailed notification configuration.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project uses automated releases via npm and GitHub. See docs/release-process.md for detailed release instructions.

Quick release commands:

npm run release:patch  # Bug fixes (0.1.0 → 0.1.1)
npm run release:minor  # New features (0.1.0 → 0.2.0)
npm run release:major  # Breaking changes (0.1.0 → 1.0.0)