Skip to content

berekvolgyipeter/dotclaude

BranchesTags

Repository files navigation

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.

Engineering philosophy. A single stance runs through the engineering artifacts here: deep modules behind simple interfaces, behavior-first testing, and design grounded in the project's domain language.

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, consistency, check-before-implementing, rules awareness

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 /overview, /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

explore/

Command Description
/overview Build a lightweight, high-level overview of a project
/architecture Discover a module's architecture, functionality, and communication interfaces, saved to docs/architecture/ — excludes tests and CI/CD

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

plan/

Command Description
/to-plan Synthesize the current conversation into a plan saved under .claude/plans/ — pairs with the grill-with-docs skill
/generate-plan Generate a plan from a short prompt by researching the target area of the codebase autonomously, saved under .claude/plans/
/refine-plan Refine a plan in place — check logical correctness and rule compliance, then edit the plan to fix issues
/execute-plan Execute a plan test-first — internalize, sequence the work, implement via the tdd red-green-refactor loop, validate, and verify

parallel/

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

Skills

Skills must live flat under skills/ — Claude Code only discovers a skill whose SKILL.md is one level deep, so there are no subdirectories to group by.

Skill Description
prompt-engineering Prompt crafting and optimization techniques
learn Self-improvement from conversation feedback
skill-creator Create & benchmark skills (vendored, gitignored)
claude-code Claude Code configuration & troubleshooting
claude-agent-sdk Agent SDK implementation patterns
tdd Test-driven development with the red-green-refactor loop
grill-with-docs Grill design decisions, maintaining a CONTEXT.md glossary & ADRs
improve-codebase-architecture Find module-deepening refactor opportunities, presented as an HTML report
py-debug Python debugging
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)

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, or scoped to a single command via its hooks frontmatter.

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. Skipped when DOTCLAUDE_DISABLE_CONTEXT_RULES_HOOK is set to 1/true
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. make lint is skipped when DOTCLAUDE_DISABLE_AUTO_LINT is set to 1/true; make test when DOTCLAUDE_DISABLE_AUTO_TEST is set to 1/true
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
block-git-mutations.sh PreToolUse Blocks state-mutating git commands. Scoped via the hooks frontmatter of the read-only review commands (pr-review, delta-review, consistency-review), so it fires only while one of those is active

Output Styles

Markdown files that modify Claude Code's system prompt to change its role, tone, and default response format. Activate one via /config → Output style, or set outputStyle in a settings file. Takes effect after /clear or a new session.

Style Description
lean Terse by default, built to be read fast — leads with the answer, cuts filler and bloated comments, expands only when an idea truly needs the room

Templates

File Description
plan-template.md Plan artifact structure used by the /to-plan and /generate-plan commands

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, current branch) as markdown context — diffs are read on demand by subagents
pr-diff.sh Injects a branch change overview (stats, file list, commits, current branch) as markdown context — diffs are read on demand by subagents
automated-checks.sh Runs make lint and make test and injects their output as markdown context for the review. make lint is skipped when DOTCLAUDE_DISABLE_AUTO_LINT is set to 1/true; make test when DOTCLAUDE_DISABLE_AUTO_TEST is set to 1/true
latest-review.sh Outputs the path to the newest code review file in .claude/.code-reviews/
remove-latest-review.sh Deletes 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, destructive git clean variants (-f, -d, -x), and un-stashing (git stash pop/apply — can clobber uncommitted work with conflicts)
  • 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/, output-styles/, 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/plan-template.md.
  • make lint / make test in shared commands are acceptable — all projects are assumed to use a Makefile.

Acknowledgments

About

Personal Claude Code config — rules, skills, commands, agents, and hooks symlinked into ~/.claude/ to give Claude consistent behavior, conventions, and workflows across every project.

Topics

productivity hooks skills developer-tools slash-commands ai-tools anthropic coding-agents agentic-ai claude-code subagents

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages