Claude Code Starter

A production-ready starter template for Claude Code. Get a fully configured setup in minutes instead of hours.

Prerequisites

Required:

• Claude Code CLI installed and authenticated
• Bash 3.2+ (macOS default works)
• Git
• jq - JSON parsing in hooks (brew install jq / apt install jq)

Optional (for formatting hooks):

• Your language's formatter: prettier, black/ruff, gofmt, rustfmt, rubocop, mix format

Check your setup:

claude --version     # Should show Claude Code version
bash --version       # Should be 3.2+ (macOS default works)
jq --version         # Required for hooks

Compatibility

| Component | Requirement | Notes | |-----------|-------------|-------| | OS | Linux, macOS | Tested on Ubuntu 22.04+, macOS 13+ | | Bash | 3.2+ | macOS default (3.2) works fine | | jq | Any version | Required for hooks | | Claude Code | Any version | Tested with 1.x |

Stack-specific formatters (optional):

| Stack | Formatter | Install | |-------|-----------|---------| | TypeScript | prettier | npm i -g prettier | | Python | black, ruff | pip install black ruff | | Go | gofmt | Included with Go | | Rust | rustfmt | rustup component add rustfmt | | Ruby | rubocop | gem install rubocop | | Elixir | mix format | Included with Elixir |

Why This Exists

Most developers install Claude Code and use maybe 10% of its capabilities. This repo gives you:

• Stack-specific presets - TypeScript, Python, Go, Rust, Ruby, Elixir configurations
• Security by default - Blocked sensitive files, dangerous command prevention
• Custom skills - Reusable commands like review, test, explain
• Specialized agents - Subagents for research, code review, test writing
• Pre-commit review - Forces you to understand what you're committing
• Auto-formatting - Runs your formatter after every edit
• Version detection - Reads from .tool-versions automatically

---

Installation

Homebrew (recommended)

brew tap zbruhnke/claude-code-starter
brew install claude-code-starter

Update:

brew upgrade claude-code-starter

Shell script

curl -fsSL https://raw.githubusercontent.com/zbruhnke/claude-code-starter/main/install.sh | bash

This installs ccs (short alias) and claude-code-starter (full name) to your PATH.

The installer automatically verifies SHA256 checksums when available (v0.7.0+).

Update:

ccs update

Pin to a specific version:

curl -fsSL https://raw.githubusercontent.com/zbruhnke/claude-code-starter/main/install.sh | bash -s -- --version <version>

---

5 Minute Tour

See it work end-to-end:

# 1. Install the CLI (if you haven't already)
curl -fsSL https://raw.githubusercontent.com/zbruhnke/claude-code-starter/main/install.sh | bash
source ~/.zshrc  # or restart your terminal

# 2. Create your project and configure it
mkdir my-app && cd my-app
git init
ccs init    # Pick TypeScript, accept defaults

# 3. Create something to work with
mkdir -p src && echo "export const hello = () => 'world';" > src/utils.ts
git add -A

# 4. Start Claude Code
claude

Now in Claude Code:

> Review my staged changes
# → Claude runs code-review skill, analyzes src/utils.ts

> Add a helper function to validate emails in src/utils.ts
# → After edit, auto-format hook runs prettier automatically

> Stage and commit these changes
# → Pre-commit hook shows diff, Claude explains before committing

That's the core loop: edit → auto-format → review → commit with understanding.

---

Quick Start

New Project

mkdir my-project && cd my-project
git init
ccs init

Existing Project

cd your-existing-project
ccs init

Add Components

ccs adopt              # Interactive mode - choose what to install
ccs adopt all          # Install core: skills, agents, hooks, rules, security
ccs adopt skills       # Just skills
ccs adopt agents       # Just agents
ccs adopt precommit    # Pre-commit review hook
ccs adopt security     # Security config only
ccs adopt stack        # Stack-specific preset

Note: adopt all installs core components but NOT stack presets or precommit hook (since those are project-specific choices). Use interactive mode or add them explicitly.

CLI Reference

ccs help              # Show all commands
ccs init              # Interactive setup
ccs adopt [component] # Add components
ccs update            # Update to latest version
ccs version           # Show version

Note: claude-code-starter also works as the full command name.

The setup script will:

1. Ask which stack you're using (TypeScript, Python, Go, Rust, Ruby, Elixir)
2. Auto-detect versions from .tool-versions if present
3. Ask for your project name and description
4. Ask for your dev/test/build commands
5. Select components to install (rules, skills, agents, hooks)
6. Generate all configuration files

---

Alternative Installation Methods

Clone and run directly

git clone https://github.com/zbruhnke/claude-code-starter.git ~/claude-code-starter
cd your-project
~/claude-code-starter/setup.sh

Download a specific release

# Download and verify (recommended)
VERSION="v0.8.3"  # Check releases for latest
TARBALL="claude-code-starter-${VERSION#v}.tar.gz"

curl -fsSL "https://github.com/zbruhnke/claude-code-starter/archive/refs/tags/${VERSION}.tar.gz" -o "$TARBALL"
curl -fsSL "https://github.com/zbruhnke/claude-code-starter/releases/download/${VERSION}/checksums.txt" -o checksums.txt

# Verify checksum before extracting
grep "$TARBALL" checksums.txt | sha256sum -c -

# Extract and run
tar -xzf "$TARBALL"
cd your-project
~/claude-code-starter-${VERSION#v}/setup.sh

Copy files manually

# Core files
cp CLAUDE.template.md your-project/CLAUDE.md
cp .claudeignore your-project/
cp -r .claude your-project/

# Stack-specific preset (requires jq for settings merge)
cp stacks/typescript/CLAUDE.md your-project/CLAUDE.md
jq -s '.[0] as $core | .[1] as $stack | {permissions: {allow: ($core.permissions.allow + $stack.permissions.allow), deny: ($core.permissions.deny + $stack.permissions.deny)}, hooks: $core.hooks}' \
  .claude/core-settings.json stacks/typescript/stack-settings.json > your-project/.claude/settings.json

Note: Stack templates contain {{PLACEHOLDER}} variables. Manual copies require replacing these yourself.

---

Documentation

| Topic | Description | |-------|-------------| | Skills | Creating and using custom skills | | Agents | Specialized subagents for focused tasks | | Hooks | Automation via PreToolUse/PostToolUse | | Permissions | Allow/deny rules and patterns | | PR Reviews | Automated CI/CD code reviews |

---

Stability & Versioning

Current status: Pre-release. The file structure and core concepts are stable, but details may change.

What's stable:

• File structure (.claude/, CLAUDE.md, .claudeignore)
• Skill and agent YAML frontmatter format
• Hook input/output contract (JSON on stdin, exit codes)
• Permission pattern syntax

What may change:

• Setup script prompts and flow
• Default permissions in presets
• Included skills/agents/rules content

For reproducible installs, pin to a specific version:

curl -fsSL https://raw.githubusercontent.com/zbruhnke/claude-code-starter/main/install.sh | bash -s -- --version <version>

Upgrade to latest:

ccs update

This downloads the latest release while preserving your project's CLAUDE.md and .claude/settings.local.json.

See Releases for all versions.

---

Detailed Usage Guide

Understanding the File Structure

your-project/
├── CLAUDE.md                    # Project context (Claude reads this first)
├── CLAUDE.local.md              # Personal context (gitignored)
├── .claudeignore                # Files to exclude from Claude's context
├── .claude/
│   ├── settings.json            # Permissions, hooks, environment
│   ├── settings.local.json      # Personal overrides (gitignored)
│   ├── rules/                   # Reference documentation (NOT auto-loaded)
│   │   ├── code-style.md
│   │   ├── git.md
│   │   ├── quality-gates.md
│   │   ├── security.md
│   │   ├── security-model.md
│   │   └── testing.md
│   ├── skills/                  # Custom skill definitions
│   │   ├── code-review/SKILL.md
│   │   ├── explain-code/SKILL.md
│   │   ├── generate-tests/SKILL.md
│   │   ├── install-precommit/SKILL.md
│   │   ├── refactor-code/SKILL.md
│   │   ├── refresh-claude/SKILL.md
│   │   ├── review-mr/SKILL.md
│   │   ├── wiggum/SKILL.md
│   │   ├── changelog-writer/SKILL.md
│   │   ├── release-checklist/SKILL.md
│   │   └── risk-register/SKILL.md
│   ├── agents/                  # Specialized subagents
│   │   ├── researcher.md
│   │   ├── code-reviewer.md
│   │   ├── code-simplifier.md
│   │   ├── test-writer.md
│   │   ├── documentation-writer.md
│   │   └── adr-writer.md
│   └── hooks/                   # Automation scripts
│       ├── validate-bash.sh
│       ├── auto-format.sh
│       └── pre-commit-review.sh

In the starter repo only (not copied to your project):

stacks/                          # Stack presets used by setup.sh
├── typescript/
├── python/
├── go/
├── rust/
├── ruby/
└── elix