AIBlueprint CLI

A comprehensive CLI tool for supercharging Claude Code with security, productivity, and workflow automation features. Transform your Claude Code experience with pre-configured commands, security hooks, intelligent status displays, and specialized AI agents.

Note

If you encounter permission errors when running the commands below, add sudo before the command.

🚀 Quick Start

Option 1: Install as Claude Code Plugin (Recommended)

# Add the AIBlueprint marketplace
/plugin marketplace add melvynx/aiblueprint

# Install the base plugin
/plugin install aibp-base@AIBlueprint

# Or install directly from GitHub
/plugin install github:melvynx/aiblueprint

Option 2: Use the CLI Tool

# Run immediately without installation
bunx aiblueprint-cli@latest claude-code setup

# Or install globally and use
npm install -g aiblueprint-cli
aiblueprint claude-code setup

🔌 Plugin Installation

Install from Claude Code Plugin Marketplace

The easiest way to get started is by installing AIBlueprint as a Claude Code plugin:

# Step 1: Add the AIBlueprint marketplace
/plugin marketplace add melvynx/aiblueprint

# Step 2: Install the aibp-base plugin
/plugin install aibp-base@AIBlueprint

# Alternative: Install directly from GitHub
/plugin install github:melvynx/aiblueprint

What Gets Installed

The aibp-base plugin includes:

✅ 16 Custom Commands - /commit, /create-pull-request, /deep-code-analysis, etc.
✅ 3 Specialized Agents - explore-codebase, Snipper, websearch
✅ Security Hooks - Command validation and TypeScript processing
✅ Custom Statusline - Git status, cost tracking, and token usage
✅ Notification Sounds - Audio alerts for task completion

Plugin Management

# List installed plugins
/plugin list

# Update plugin to latest version
/plugin update aibp-base

# Remove plugin
/plugin uninstall aibp-base

# View marketplace plugins
/plugin marketplace list

Plugin vs CLI Tool

Plugin Installation (Recommended):

✅ Automatic updates via marketplace
✅ No CLI tool installation needed
✅ Direct integration with Claude Code
✅ Easy to manage and update

CLI Tool Installation:

✅ More control over installation
✅ Custom folder locations
✅ Interactive feature selection
✅ Symlink management for other tools

💾 CLI Installation & Usage

Installation Methods

# Global installation
npm install -g aiblueprint-cli
bun install -g aiblueprint-cli

# Run without installation
npx aiblueprint-cli@latest claude-code setup
pnpm dlx aiblueprint-cli@latest claude-code setup
bunx aiblueprint-cli@latest claude-code setup

Basic Usage

# Interactive setup with feature selection
bunx aiblueprint-cli@latest claude-code setup

# Non-interactive setup (install all features)
bunx aiblueprint-cli@latest claude-code setup --skip

# Install to custom directory
bunx aiblueprint-cli@latest claude-code setup --folder ./custom-claude-config

# Install to project directory
cd your-project
bunx aiblueprint-cli@latest claude-code setup  # Creates .claude/ in project root

🎯 Command Reference

Main Commands

Command	Description	Options
`bunx aiblueprint-cli@latest claude-code setup`	Interactive setup with feature selection	`-f, --folder <path>` (alias for --claudeCodeFolder), `--claudeCodeFolder <path>`, `--codexFolder <path>`, `--openCodeFolder <path>`, `--factoryAiFolder <path>`, `-s, --skip`
`bunx aiblueprint-cli@latest claude-code symlink`	Create symlinks between CLI tools (Codex, OpenCode, FactoryAI)	`--claudeCodeFolder <path>`, `--codexFolder <path>`, `--openCodeFolder <path>`, `--factoryAiFolder <path>`
`bunx aiblueprint-cli@latest claude-code statusline`	Setup custom statusline with git status, costs, and token usage	`-f, --folder <path>`
`bunx aiblueprint-cli@latest claude-code add hook <type>`	Install specific hook	`-f, --folder <path>`
`bunx aiblueprint-cli@latest claude-code add commands [name]`	List or install commands	`-f, --folder <path>`

Command Examples

# Setup with options
bunx aiblueprint-cli@latest claude-code setup --skip                    # Install all features
bunx aiblueprint-cli@latest claude-code setup --folder ~/.my-claude     # Custom location
bunx aiblueprint-cli@latest claude-code setup --claudeCodeFolder ~/.claude --codexFolder ~/.codex  # Separate folders

# Add specific hooks
bunx aiblueprint-cli@latest claude-code add hook post-edit-typescript   # TypeScript processing hook

# Manage commands
bunx aiblueprint-cli@latest claude-code add commands                    # List all available commands
bunx aiblueprint-cli@latest claude-code add commands commit             # Install commit command
bunx aiblueprint-cli@latest claude-code add commands deep-code-analysis # Install analysis command

# Create symlinks between CLI tools
bunx aiblueprint-cli@latest claude-code symlink                         # Interactive symlink manager
bunx aiblueprint-cli@latest claude-code symlink --factoryAiFolder ~/.factory  # With custom paths

# Setup statusline
bunx aiblueprint-cli@latest claude-code statusline                      # Quick statusline setup
bunx aiblueprint-cli@latest claude-code statusline --folder ~/.my-claude # Custom location

Hook Types Available

post-edit-typescript - Automatic TypeScript file processing (Prettier + ESLint + type checking)

Installation Behavior

The CLI intelligently determines where to install configurations:

Project Local (.claude/ in project root) - When run in a Git repository
Global (~/.claude/) - When not in a Git repository or with custom folder
Custom Path - When using --folder option

✨ Available Features

🛡️ Shell Shortcuts

cc - Claude Code with permissions skipped (claude --dangerously-skip-permissions)
ccc - Claude Code with continue mode (claude --dangerously-skip-permissions -c)
Platform support: macOS (.zshenv), Linux (.bashrc/.zshrc)

🔒 Command Validation

700+ line security system protecting against dangerous bash commands
Real-time validation before command execution via PreToolUse hooks
Smart detection of privilege escalation, destructive operations, and command injection
Comprehensive logging to ~/.claude/security.log with severity levels

📊 Custom Statusline

Git integration - Branch status, changes, and repository info
Cost tracking - Session costs, daily limits, and token usage via ccusage
Real-time updates - Command-triggered statusline refresh
Colored output - Visual indicators for different status types
Quick setup - Install with one command: pnpm dlx aiblueprint-cli claude-code statusline

🤖 AIBlueprint Commands (16 Available)

Development Workflow

commit - Fast conventional commits with immediate push
create-pull-request - Auto-generated PR creation with templates
fix-pr-comments - Systematic PR review comment resolution
run-tasks - Execute GitHub issues with full EPCT workflow

Code Analysis & Research

deep-code-analysis - Comprehensive codebase investigation with research
explain-architecture - Pattern analysis with ASCII diagrams
cleanup-context - Memory optimization and duplicate removal

Utilities & Automation

claude-memory - Context management for long sessions
watch-ci - Automated CI/CD monitoring and failure fixing
prompt-command / prompt-agent - Template creation utilities
epct - Systematic Explore-Plan-Code-Test methodology

🎭 AIBlueprint Agents (3 Specialized)

explore-codebase (yellow) - Comprehensive code discovery and analysis
Snipper (blue) - Rapid code modification specialist with minimal output
websearch (yellow) - Quick web research with authoritative sources

🔊 Notification Sounds

Finish sound - Audio alert for completed operations (macOS afplay)
Need-human sound - Audio alert for attention requests
Volume control - Configurable audio levels

🔗 Symlink Management

Multi-tool integration - Create symlinks between Claude Code, Codex, OpenCode, and FactoryAI
Interactive selection - Choose source, content type (commands/agents), and destinations
Smart validation - Prevents overwriting non-symlink directories and validates paths
Bidirectional sync - Sync commands and agents in any direction
Supported tools:
- Claude Code - Commands + Agents (~/.claude/)
- Codex - Commands only (~/.codex/prompts)
- OpenCode - Commands only (~/.config/opencode/command)
- FactoryAI - Commands + Droids/Agents (~/.factory/)

⚙️ Configuration System

Settings.json Structure

The CLI automatically manages your ~/.claude/settings.json with:

{
  "statusLine": {
    "type": "command",
    "command": "bun ~/.claude/scripts/statusline/src/index.ts",
    "padding": 0
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "bun ~/.claude/scripts/validate-command.js"}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{"type": "command", "command": "bun ~/.claude/hooks/hook-post-file.ts"}]
      }
    ]
  }
}

GitHub Integration

Remote-first approach - Always downloads latest configurations from GitHub
Automatic fallback - Uses local files when GitHub is unavailable
Version independence - Get updates without CLI updates
Rate limiting aware - Handles GitHub API limitations gracefully

📚 Templates Catalog

Commands by Category

Development Workflow (4 commands)

Command	Tools	Purpose
`commit`	`Bash(git :*)`	Quick conventional commits with immediate push
`create-pull-request`	`Bash(git :)`, `Bash(gh :)`	PR creation with auto-generated descriptions
`fix-pr-comments`	`Bash(gh :*)`, `Read`, `Edit`	Systematic PR review resolution
`run-tasks`	`Bash(gh :)`, `Bash(git :)`	GitHub issue execution with EPCT

Analysis & Research (2 commands)

Command	Tools	Purpose
`deep-code-analysis`	`Task`, `WebSearch`, `mcp__context7__*`	Comprehensive codebase investigation
`explain-architecture`	`Read`, `Glob`, `Grep`, `Task`	Architectural pattern analysis

Maintenance & Optimization (2 commands)

Command	Tools	Purpose
`cleanup-context`	`TodoWrite`, `MultiEdit`, `Glob`	Memory bank optimization
`watch-ci`	`Bash(gh :)`, `Bash(sleep :)`	Automated CI monitoring

Utilities (8 commands)

Command	Tools	Purpose
`claude-memory`	`Read`, `Write`, `Edit`, `Glob`	CLAUDE.md file management
`epct`	`Task`	Explore-Plan-Code-Test methodology
`prompt-command`	`Read`, `Write`, `Edit`	Command template creation
`prompt-agent`	`Read`, `Write`, `Edit`	Agent template creation

Hooks Available

Hook	Language	Purpose	Triggers
`post-edit-typescript`	TypeScript/Bun	File processing after edits	Edit, Write, MultiEdit on .ts/.tsx

Scripts & Utilities

Script	Language	Purpose
`validate-command.js`	Bun/JavaScript	Security validation for bash commands
`statusline-ccusage.sh`	Bash	Git status and usage tracking display

🎯 Installation Targets

Local Project Installation (Recommended)

When run in a Git repository, creates .claude/ in your project root:

cd your-project/
bunx aiblueprint-cli@latest claude-code setup
# Creates: your-project/.claude/

Benefits:

Project-specific configurations
Team collaboration ready
Version control friendly
Isolated environments

Global Installation

When not in a Git repository, uses global directory:

cd ~/
bunx aiblueprint-cli@latest claude-code setup
# Creates: ~/.claude/

Benefits:

System-wide configurations
Works across all projects
Persistent settings

Custom Path Installation

Use --folder for specific locations:

bunx aiblueprint-cli@latest claude-code setup --folder ./custom-config
bunx aiblueprint-cli@latest claude-code setup --folder /opt/claude-config

🔐 Security Features

Command Validation System

The security system protects against dangerous operations:

Critical Commands Blocked:

rm -rf (with path validation)
dd, mkfs, fdisk (disk operations)
chmod 777, chown -R (permission changes)
curl | bash, wget | sh (remote execution)
sudo operations (privilege escalation)

Security Logging:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "command": "rm -rf /",
  "severity": "CRITICAL",
  "action": "BLOCKED",
  "reason": "Destructive command with critical path"
}

Safe Paths Allowed:

./, ~/, relative paths
node_modules/, .git/, common safe directories
Temporary directories (/tmp/, /var/tmp/)

Hook-Based Protection

PreToolUse validation - Commands checked before execution
Real-time analysis - Pattern matching and rule evaluation
User confirmation - Interactive prompts for questionable commands
Comprehensive rules - 50+ security patterns and checks

🛠️ Development

Local Development Setup

# Clone and setup
git clone <repository>
cd aiblueprint-cli
bun install

# Development mode
bun run dev claude-code setup
bun run dev claude-code add commands

# Testing
bun run test:run                    # Run test suite
bun run dev-test                    # Test with temporary config

Build and Release

# Build for distribution
bun run build                       # Compiles to dist/cli.js

# Local testing
bun run test-local                  # Creates npm link
aiblueprint claude-code setup       # Test globally

# Release (automated)
bun run release                     # Version bump, build, tag, publish

Project Structure

src/
├── cli.ts                          # Main CLI entry point
├── commands/
│   ├── setup.ts                    # Main setup command
│   ├── addHook.ts                  # Hook installation
│   └── addCommand.ts               # Command installation
└── utils/
    ├── claude-config.ts            # Configuration utilities
    ├── file-installer.ts           # GitHub/local fallback
    └── github.ts                   # GitHub API integration

claude-code-config/                 # Template repository
├── commands/                       # Command templates
├── hooks/                          # Hook scripts
├── agents/                         # Agent configurations
├── scripts/                        # Utility scripts
└── song/                           # Notification sounds

Testing Commands

# Test all major workflows
bun run dev claude-code setup --skip
bun run dev claude-code add hook post-edit-typescript
bun run dev claude-code add commands
bun run dev claude-code add commands commit

# Test with custom paths
bun run dev claude-code setup --folder ./test-config

📋 Requirements

System Requirements

Runtime: Node.js 16+ or Bun
Platform: macOS (full support), Linux (partial), Windows (limited)
Dependencies: Git (for repository detection)

Claude Code Requirements

Claude Code: Latest version installed
Permissions: Ability to modify ~/.claude/settings.json

Optional Dependencies

bun: Enhanced script execution and hooks
ccusage: Advanced statusline with cost tracking
gh CLI: GitHub integration for PR/issue commands
prettier, eslint: TypeScript hook functionality

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests: bun run test:run
Submit a pull request

Adding New Templates

Add template files to claude-code-config/
Update metadata with YAML frontmatter
Test installation: bun run dev claude-code add commands <name>
Document in README

💎 AIBlueprint CLI Premium

Unlock advanced features with AIBlueprint CLI Premium:

Premium Features

✨ Advanced Statusline - Enhanced git info, real-time costs, and token usage tracking
🚀 Premium Commands - Exclusive workflow automation templates
🤖 Premium Agents - Specialized AI agents for complex tasks
📦 Priority Updates - Get new features first
💬 Priority Support - Direct help when you need it

How to Upgrade

# 1. Get your premium token at https://mlv.sh/claude-cli

# 2. Activate premium
aiblueprint claude-code pro activate YOUR_TOKEN

# 3. Setup premium configs
aiblueprint claude-code pro setup

Premium Commands

# Check premium status
aiblueprint claude-code pro status

# Update premium configs
aiblueprint claude-code pro update

Learn more: https://mlv.sh/claude-cli

📄 License

MIT License - see LICENSE file for details.

Created by AIBlueprint - Enhancing Claude Code for modern development workflows.

Need help? Open an issue or check our documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.claude-plugin		.claude-plugin
.vscode		.vscode
claude-code-config		claude-code-config
docs		docs
prompts		prompts
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.release-it.json		.release-it.json
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lockb		bun.lockb
index.ts		index.ts
package.json		package.json
test-cli-manual.ts		test-cli-manual.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Melvynx/aiblueprint

Folders and files

Latest commit

History

Repository files navigation