zcc: The zsh for Claude Code

Transform Claude Code from a basic AI assistant into a project-aware, context-intelligent development powerhouse.

The Problem

Claude Code breaks down as your codebase grows:

• 😔 Re-adding the same CLAUDE.md instructions across projects
• 📝 Claude spams markdown files instead of organized task tracking
• 🔄 Goes in circles after context compacting, repeating failed approaches
• 🎭 Copy-pasting roleplay prompts: "Act as engineer..." "Be a reviewer..."

The Solution: oh-my-zsh for AI

Just as zsh transformed terminals with themes and plugins, zcc transforms Claude Code with:

# Before: Basic Claude Code
"Please review my code"  # Generic responses

# After: With zcc
/mode reviewer          # Specialized AI personality
"Review the auth module" # Context-aware, focused analysis

See It In Action

# 1. Install (30 seconds)
npx zcc init

# 2. Use enhanced features immediately
/mode architect         # Switch to system design mode
/ticket create "Add authentication"  # Persistent task tracking
/zcc                    # See project status

# 3. Claude becomes context-aware
"Implement the auth feature"  # Claude knows about your ticket, 
                              # project structure, git status, etc.

Core Features

Feature	What It Does	zsh Equivalent
AI Modes	Switch personalities (architect/engineer/reviewer)	Themes
Tickets	Persistent task tracking across sessions	tmux sessions
External Packs	Install community packs from GitHub	oh-my-zsh plugins
Fuzzy Matching	/mode eng → finds engineer	Smart completions
Hooks	Auto-load context, expand acronyms	precmd/preexec
Workflows	Reusable procedures (review, deploy, audit)	Functions
Agents	Specialized tools (research, analysis)	Plugins

Getting Started

Installation Options

1. Quick Start (Recommended)

# Interactive setup - choose from available starter packs
npx zcc init

# Or install a specific starter pack directly (headless)
npx zcc init --pack essentials
npx zcc init --pack advanced-code-refactoring

2. Global Installation

# Install globally for use across all projects
npm install -g z-claude-code
zcc init

3. Local Development (From Source)

# Clone and build from source
git clone https://github.com/git-on-my-level/zcc.git
cd zcc
npm install
npm run build

# Use in your project
cd /your/project
node /path/to/zcc/dist/cli.js init

Common Setup Scenarios

# Essential setup (recommended for new users)
zcc init --pack essentials

# Advanced code refactoring toolkit
zcc init --pack advanced-code-refactoring

# Start fresh (overwrite existing)
zcc init --force

# Automated CI/CD setup
zcc init --pack essentials --force

Starter Packs: Ready-to-Use Bundles

Get up and running instantly with curated collections of modes, workflows, and agents:

# Interactive pack selection
npx zcc init

# Or specify a pack directly
npx zcc init --pack frontend-react

Available Packs

Pack	Description	Includes
essentials	Essential setup for general development	Core modes (autonomous-project-manager, engineer, architect, reviewer, ai-debt-maintainer) + workflows (review, summarize, openmemory-setup) + hooks (routing, git context, project overview, acronym expander)
advanced-code-refactoring	AST/semantic refactoring toolkit	Mode (refactoring-specialist) + workflows (semantic-search, safe-refactoring) + agent (code-archaeologist) + hook (ast-grep-awareness)

Coming Soon

• backend-api - RESTful API development
• fullstack - End-to-end development combining frontend and backend capabilities

Community Packs 🎉 NEW!

Install packs from external sources like GitHub:

# Add a community pack source
zcc source add awesome-packs --type github --owner community --repo zcc-packs

# Search and install packs
zcc search react
zcc add pack react-toolkit

Learn more about external packs →

Just like oh-my-zsh themes transform your terminal experience, starter packs transform Claude Code for your project type.

Daily Workflow

# Morning: Architecture & Planning
/mode architect
"Design the payment system"

# Afternoon: Implementation  
/mode engineer
"Implement stripe integration"

# Evening: Review
/mode reviewer
"Check for security issues"

# Track Everything
/ticket list                  # See all tasks
/ticket payment-system        # Load ticket context

Why It Works

Problem: Claude Code loses context and repeats mistakes
Solution: Persistent tickets + smart hooks = continuous context

Problem: Same prompts copy-pasted everywhere
Solution: Built-in modes with best practices baked in

Problem: Scattered markdown files everywhere
Solution: Organized ticket system with clear status tracking

Documentation

Essential Guides

• 🚀 Quick Start Guide - Get running in 5 minutes
• 🪝 Hooks Guide - Event-driven automation

Advanced Topics

• 🌍 External Packs - Install community packs from GitHub
• 📖 API Reference - Programmatic usage
• 🛠️ Troubleshooting - Common issues and solutions

Examples

Switch Modes with Fuzzy Matching

/mode arc      # → architect
/mode eng      # → engineer  
/mode apm      # → autonomous-project-manager

Create and Track Tasks

/ticket create "Add user authentication"
/ticket move auth-task in-progress
/ticket finish auth-task

Auto-Expand Acronyms

zcc acronym add API "Application Programming Interface"
zcc acronym add DDD "Domain-Driven Design"
# Now Claude automatically understands your project's terminology

Philosophy

Like zsh enhances bash without replacing it, zcc enhances Claude Code while preserving everything that works. Start simple, add power as needed.

Coming Soon

• 🌍 Community Hub: Share modes and workflows
• 📝 ~/.zcc/config.yaml: Global config file (unified structure with project config)
• 🔌 Plugin Manager: Easy install/update (like zplug)
• 📊 Analytics: Track productivity and usage patterns

Star History

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Support

• 🐛 Issues
• 💬 Discussions
• 📖 Wiki

License

MIT © zcc Contributors

---