dotclaude

Shared Claude Code configuration repo, symlinked into ~/.claude/ so edits here propagate to every project automatically.

Manage rules, skills, commands, agents, hooks, and templates in one place instead of duplicating them across every project.

Note: This repo contains scripts that modify files on your system. Please review the contents before use.

Platform: Only tested and developed on macOS. Linux may work but is untested; Windows is not supported.

Why this design

Symlinking into ~/.claude/ and version-controlling everything in git turns this repo into the substrate for the learn skill: when Claude updates a rule, skill, or command based on session feedback, the change goes live in every project immediately and shows up as a reviewable git diff — making self-improvement auditable rather than a black box.

Security-first defaults. Telemetry and error reporting are disabled, OS-level sandboxing isolates every bash command, and a layered deny/ask permission model plus PreToolUse hooks block destructive operations (rm -rf, force-push to main) and gate access to credentials, shell config, and cloud tokens — see settings.json for the full posture.

Scope. This repo configures Claude Code — it does not bundle a linter or test runner. The Stop hook delegates to whatever the host project uses (make lint, make test); it skips gracefully when those targets aren't defined.

Runtime Flow

flowchart LR
    User([User prompt]) --> Claude
    Claude -->|tool call| Pre[PreToolUse hooks]
    Pre -->|load context rules<br/>auto-approve reads<br/>block destructive ops| Tool[Tool execution]
    Tool --> Claude
    Claude -.turn ends.-> Stop[Stop hook]
    Stop -->|make lint + make test| Claude

Loading

What's Included

Rules

Always-loaded rule files discovered automatically by Claude Code.

File	Scope	Description
general.md	All files	No-guessing policy, tool preferences

Context Rules

Rule files loaded on demand by the load-context-rules.sh hook when Edit/Write targets a matching file pattern. Not auto-discovered by Claude Code — the hook controls when they enter context.

File	Loaded when	Description
py-code.md	Python files	Python style, KISS/YAGNI, error handling, data models
py-test.md	Python test files	pytest conventions, parametrize patterns, test organization
docs.md	Markdown files	Documentation principles, timeless writing, avoid volatile details

Shared

Reference files explicitly read by commands and skills — not auto-loaded.

File	Description
shared/rules-index.md	Registry of all rule files — what each covers and when to load it
shared/code-review.md	Subagent-based review orchestration protocol with parallel batch analysis
shared/analyze-project.md	Project survey steps, imported by /primer, /init-rules, and /refine-rules
shared/project-rules/file-writing.md	Rule-file shape and writing rules, imported by /init-rules and /refine-rules
shared/project-rules/claudemd-section.md	CLAUDE.md progressive-disclosure section template, imported by /init-rules and /refine-rules

Commands

Command	Description
/primer	Prime context for a session

project-rules/

Command	Description
/init-rules	Decompose a fresh project into modules, write per-module .claude/rules/*.md files with a paths frontmatter, and add a progressive-disclosure table to CLAUDE.md
/refine-rules	Audit existing .claude/rules/*.md files and apply a minimal delta — modify, split, merge, remove, or add — keeping the CLAUDE.md table in sync

git/

Command	Description
/commit-msg	Generate a suggested conventional commit message for the current changes
/pr-summary	Brief PR summary grouped by feature/area

review/

Command	Description
/pr-review	Full technical code review
/delta-review	Review uncommitted changes against latest commit
/fix-review	Fix issues found in a code review
/skill-review	Review a skill or command file for best practices — structure, writing style, progressive disclosure, and prompt engineering

prp/

Command	Description
/generate-prp	Generate a Product Requirements Prompt
/execute-prp	Execute a PRP — internalize, plan, implement, validate, and verify
/refine-prp	Refine a PRP in place — check logical correctness and rule compliance, then edit the PRP to fix issues

parallel/

Command	Description
/prep-parallel	Set up worktrees for parallel Claude Code agents
/execute-parallel	Run parallel task execution

Skills

Skill	Description
claude-code	Claude Code configuration & troubleshooting
claude-agent-sdk	Agent SDK implementation patterns
prompt-engineering	Prompt crafting and optimization techniques
learn	Self-improvement from conversation feedback
plugin-browser	Browse, discover, and explore skills/agents/plugins from multiple indexed community and official repos
agent-harness	Browse and explore agent harness frameworks and Claude Code resource collections (Archon, everything-claude-code)
slither	Slither static analysis for Solidity & Vyper
py-debug	Python debugging
skill-creator	Create & benchmark skills (vendored, gitignored)

Agents

Agent	Description
validation-gates	Runs tests and iterates on fixes until they pass
documentation-manager	Keeps docs in sync with code changes

review/

Agent	Description
code-reviewer	Focused code reviewer for batches of changed files, dispatched by review commands
diff-summarizer	Reads diffs on demand and returns structured change summaries

Hooks

Event-driven shell scripts registered in settings.json.

Hook	Event	Description
auto-approve-claude-dir.sh	PreToolUse	Auto-approves Read, Grep, and Glob operations on .claude/ paths
load-context-rules.sh	PreToolUse	Loads context rules from context-rules/ on first Edit/Write per session when the target file matches a rule's glob pattern. Deduplicates via transcript markers
stop-lint-and-test.sh	Stop	Runs make lint and make test after any session that used Edit or Write tools on non-gitignored files. Exits with code 2 to block and prompt Claude to fix failures; skips gracefully when no Makefile or make is found; skips individual lint/test targets that are not defined
block-rm-rf.sh	PreToolUse	Blocks destructive rm -rf and rm -fr Bash commands
block-push-to-main.sh	PreToolUse	Blocks direct git push to the main branch

Templates

File	Description
prp_template.md	Language-agnostic PRP template used by the /generate-prp command

Scripts

File	Description
statusline-command.sh	Custom status line script
index_codebase.py	Indexes codebase for the claude-context MCP server

review/

File	Description
delta-diff.sh	Injects a local change overview (stats, file list) as markdown context — diffs are read on demand by subagents
pr-diff.sh	Injects a branch change overview (stats, file list, commits) as markdown context — diffs are read on demand by subagents
latest-review.sh	Outputs the path to the newest code review file in .claude/.code-reviews/

settings.json

Shared permissions, preferences, and security posture.

Privacy: Three env flags disable telemetry, error reporting, and the feedback survey — Claude doesn't phone home by default. Override per-project if needed.

Deny list:

• Destructive commands: rm -rf, sudo, mkfs, dd, wget ... | bash (classic supply-chain attack vector)
• Irreversible git: force-push, git reset --hard, and destructive git clean variants (-f, -d, -x)
• Shell config: ~/.bashrc, ~/.zshrc — PATH manipulation and alias injection are off the table
• Credential stores: SSH keys, AWS/Azure/GitHub CLI configs, git-credentials, Docker, Kubernetes, npm/pypi/gem tokens, macOS Keychain, .env files — and crypto wallet data (MetaMask, Electrum, Exodus, Phantom, Solflare)

Ask list (allowed but requires confirmation):

• Root-equivalent access: docker, curl --unix-socket, socat *UNIX*, nc -U, ncat --unixsock — the Docker socket and arbitrary Unix sockets grant host-level control
• Permission/ownership: chmod, chown
• Network/data transfer: ssh, scp, rsync — outbound sessions and file exfiltration vectors
• Git write operations: pushing, pulling, merging, rebasing, resetting, branch switching, cleaning, stashing, history rewriting — all state-mutating git commands (the JSON is the source of truth for the exact list)
• Process control: pkill, kill, launchctl — killing processes or managing macOS services

Hooks: block-rm-rf.sh and block-push-to-main.sh fire on every Bash call as a PreToolUse hook, independent of the permission system. If a permission rule is misconfigured, the hook still blocks it.

Sandboxing: OS-level filesystem and network isolation for all bash commands and their subprocesses. Bash commands within sandbox boundaries are auto-approved — reducing prompt fatigue while maintaining security. The escape hatch is disabled; commands must run sandboxed or be explicitly excluded. Deny permission rules and sandbox isolation complement each other for defense in depth.

How It Works

Claude Code merges configuration from two levels:

Level	Location	Scope
User-level	~/.claude/ (this repo, via symlinks)	All projects
Project-level	project/.claude/	That project only

Array settings (e.g. permissions.allow) concatenate across levels. Project-level wins for same-named items.

Prerequisites

• Claude Code installed
• A Makefile in each project with at least: lint, test, tree targets
• Project-level Claude memory lives at .claude/CLAUDE.md (not a root-level CLAUDE.md) — commands and agents that read or write project memory assume this path

claude-context

The claude-context MCP server (configured in .mcp.json) needs:

• an OPENAI_API_KEY set in project root .env
• a locally running instance of Milvus vector db
  • check out this repo to run Milvus via Docker Compose

Installation

make install

This runs setup/install.sh, which symlinks directories and files from this repo into ~/.claude/:

• Directories: rules/, context-rules/, commands/, agents/, skills/, templates/, hooks/, scripts/, shared/
• Files: settings.json

If a real (non-symlink) directory or file already exists at the target, the script warns and skips it. Existing files are backed up with a timestamp before being replaced. Safe to re-run.

Uninstallation

make uninstall

Removes only symlinks created by install.sh. Real directories and files are left untouched. If a backup exists for a file, the most recent backup is restored.

Fetching Vendored Skills

skill-creator is gitignored because it's a large vendored skill. To fetch it:

make fetch-skill-creator

Some skills require Python dependencies:

make python-deps

Editing Workflow

Because ~/.claude/ directories are symlinks into this repo, editing any file in ~/.claude/rules/, ~/.claude/skills/, etc. is editing the real file here. Changes are immediately visible in all projects.

Commit and push from this repo to version-control shared config. No need to touch project repos when updating shared configuration.

Project-Level Layer

After installing dotclaude, each project's .claude/ should only contain project-specific overrides:

project/.claude/
├── CLAUDE.md              # project-specific instructions
├── settings.json          # project permissions, MCP servers
├── settings.local.json    # personal overrides (gitignored)
├── .gitignore
├── rules/                 # project-specific rules only (if any)
└── skills/                # project-specific skills only (if any)

Use template.CLAUDE.md, template.mcp.json, and template.serena.project.yml from this repo as starters when setting up a new project.

Conventions

• No project-specific content here. Rules, commands, or skills referencing a specific project's paths belong in that project's .claude/.
• Context rules (context-rules/) are loaded by the load-context-rules.sh hook on Edit/Write — not auto-discovered. Add new context rules there and register their patterns in the hook script.
• Templates should be referenced via absolute path: ~/.claude/templates/prp_template.md.
• make lint / make test in shared commands are acceptable — all projects are assumed to use a Makefile.

Acknowledgments

• coleam00/context-engineering-intro — inspiration for some commands and rules
• trailofbits/claude-code-config — security and privacy focused settings
• EveryInc/compound-engineering-plugin — naming conventions and code review patterns
• wshobson/agents — Python style and naming patterns
• anthropics/claude-plugins-official — multi-agent code review pattern
• coleam00/archon — agent-harness skill reference repo
• affaan-m/everything-claude-code — agent-harness skill reference repo