Show HN: Claude Composer

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

• Features
• Quick Start
  • Installation
  • Basic Usage
• What is Claude Composer?
• Installation & Setup
  • Prerequisites
  • Installation
  • Initial Configuration
  • Directory Structure
• Basic Usage
  • Command Structure
  • Common Workflows
  • Examples
• Configuration
  • Configuration File Locations
  • Basic Configuration Options
  • Environment Variables
  • Roots Configuration
• Rulesets
  • What are Rulesets?
  • Internal Rulesets
  • Project-Level Rulesets
  • Using Rulesets
  • Creating Custom Rulesets
• Toolsets
  • What are Toolsets?
  • Internal Toolsets
  • Project-Level Toolsets
  • Using Toolsets
  • Creating Custom Toolsets
• Command Line Options
  • Core Options
  • Subcommands
  • Pass-through Options
  • Advanced Notification Controls
• Development
  • Contributing
  • Release Process

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:

Or with other package managers:

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

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:

Project configuration (with --project):

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

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

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

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.

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:

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:

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 <name...> - Use specified rulesets (can be used multiple times)
• --toolset <name...> - 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:

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:

Fine-tune which notifications appear:

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: