Pragmatic Claude

pragmatic-claude

My personal Claude Code setup: a zsh launcher, session hooks, a custom system prompt, skills, slash commands, and a statusline. It lives at ~/.claude and replaces the default config directory.

Requirements

Tool	Status	Why
claude on PATH	required	Claude Code itself
zsh	required for cc	the launcher is zsh-only; run claude directly from any shell without it
git, jq, bash, shasum	required	used by hooks and the install script
python3 3.9+	required	used by two bash hooks (path resolution and the memory-graph rebuild); the hooks themselves are bash
rtk (Rust Token Killer)	required	a PreToolUse hook routes every Bash command through it to cut token use
gh	optional	statusline PR and CI status
agent-browser	optional	browser automation MCP used by /brainstorm for web-only tickets and attachments

Install

Config lives at ~/.claude (all paths are hardcoded to $HOME/.claude).

Quickest, no clone:

curl -fsSL https://raw.githubusercontent.com/igorjs/pragmatic-claude/main/install.sh | bash

Downloads the latest release (or main if none exists), backs up anything it replaces to ~/.claude/backups/, runs brew bundle, adds the launcher to ~/.zshrc, and opens a fresh shell. Pin a version or install files only:

PRAGMATIC_CLAUDE_REF=v0.1.0 curl -fsSL https://raw.githubusercontent.com/igorjs/pragmatic-claude/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/igorjs/pragmatic-claude/main/install.sh | bash -s -- --no-setup

Pin PRAGMATIC_CLAUDE_REF to a tag or commit for a reproducible, reviewable install: the same files every run, and a ref you inspect first.

Prefer git? Clone fresh:

git clone https://github.com/igorjs/pragmatic-claude.git ~/.claude

Already have a ~/.claude from Claude Code? Adopt it in place. The .gitignore is an allowlist, so sessions, caches, and runtime files stay ignored:

cd ~/.claude
git init
git remote add origin https://github.com/igorjs/pragmatic-claude.git
git fetch origin
git checkout -f main

Add the launcher to .zshrc:

source ~/.claude/shell/cc.zsh

Reload with exec zsh.

Usage

cc                     # resume this directory's last session, or start fresh
ccd                    # same, with --dangerously-skip-permissions
cc fresh               # new session, no history
cc list                # recent sessions for this directory
cc clean               # resume with /model, /effort, /config, /output-style, /style stripped
cc raw [id]            # resume verbatim, no fork or cleanup
cc worktree <branch>   # create/enter a git worktree, then start a session there
cc new <branch>        # alias for cc worktree

cc loads the system prompt, picks a model, and prunes old transcripts (keeps the newest 5; set CCD_KEEP to change, CCD_KEEP=0 disables).

cc worktree (also ccd worktree) creates or enters a worktree off the project's base branch, grouped under <repo-parent>/.worktrees/<repo>/<folder> (set WORKTREE_BASE_DIR to change the base folder). It names the folder after the JIRA key in the branch name, copies .env, clones node_modules with a copy-on-write copy so each branch gets an independent tree, pushes the branch to set upstream (pass --no-push or set WORKTREE_NO_PUSH=1 to skip), and runs a daily background cleanup of merged or stale worktrees. On a rebase conflict Claude offers to resolve it (--ai-resolve is always set): you get a prompt first, and it defaults to yes. Set WORKTREE_AI_RESOLVE_SILENT=1 to resolve without the prompt, or WORKTREE_AI_RESOLVE=0 to turn it off. Only available via cc/ccd. cc new <branch> is an alias for cc worktree.

Docs

Full documentation: docs/index.md.

• Concepts (docs/concepts/): system prompt design and the memory system.
• Guides (docs/guides/): plan-and-implement, review and PR flow, decisions and memory.
• Authoring (docs/authoring/): writing commands, skills, and hooks.
• Internals (docs/internals/): launcher, hooks, model routing, and memory injection.

System prompt

prompts/SYSTEM_PROMPT.md is passed as --system-prompt-file on every cc session. It sets the persona (senior principal engineer, security specialization) and the rules every session follows: terse output, voice rules for prose, rtk integration, model routing, TDD, verification, and the memory protocol. Edit it to change how sessions behave; changes take effect on the next fresh session.

Commands

Slash commands live in commands/. See docs/guides for full usage.