dotclaude installs a curated .claude/ folder and then argues itself down to size

A .claude/ folder, curated rather than dumped

The project describes itself as the standard `.claude/` folder structure for everyday development, and the README puts the design in one line: a lean setup with seven specialist agents, twelve workflow skills, six modular rules and eight safety and productivity hooks, with no bloat, no model assignments and no opinions you cannot override.

That last clause matters. A configuration kit that assigns models to agents or hard-codes opinions about how you want code written is a kit you will spend your first hour undoing. dotclaude's claim is that the defaults are foundations, and that your edits on top of them are what make the setup effective for a particular project.

The scope is Claude Code specifically. The artefacts are the ones that tool understands: a `settings.json`, an `agents/` directory of specialist subagents, a `skills/` directory of slash command skills, a `rules/` directory of modular rule files, a `hooks/` directory of shell scripts, and the `CLAUDE.md` instruction file, with a `CLAUDE.template.md` to copy from and a `CLAUDE.local.md.example` for personal preferences that stay out of version control.

The repository layout matches that description, with a `plugins/` directory holding the packaged versions of each piece, a `.claude-plugin/` directory for the plugin manifest, and `settings.local.json.example` alongside `settings.json`.

The licence is MIT, the primary language is Shell because the hooks are shell scripts, the repository is not archived, and the last push was on 2026-08-27.

The plugin path scans, interviews and asks before it copies

There are two ways in, and the README is clear that most people should take the first.

The marketplace path adds the marketplace once and installs the all-in-one setup plugin.

/plugin marketplace add poshan0126/dotclaude
/plugin install setupdotclaude@dotclaude

Then, in Claude Code, you run the setup command.

/setupdotclaude

The point of this path is what it does not do. The plugin carries the whole kit, settings, rules, hooks, agents, skills and the CLAUDE.md template, but running the command does not copy all of it into your project. The README says the skill deep-scans your codebase, covering manifests, real source and test files, the directory layout, the git workflow and any existing AI configuration, then interviews you about scope and preferences, and then proposes an install plan in which every component is justified by evidence from the scan. Only the approved plan is copied in, customized to your stack, and every change is confirmed before it is applied.

That is a meaningfully different behaviour from an installer that writes a folder. A plan you can read is a plan you can argue with, and a component that is skipped because your project has no frontend is a component you do not have to delete later.

If you only want one or two pieces, the individual plugins install the same way.

/plugin install code-reviewer@dotclaude
/plugin install safety-hooks@dotclaude
/plugin install ship@dotclaude

The full plugin list in the README runs to two dozen names, and it separates the agents from the skills. The agents include `code-reviewer`, `silent-failure-hunter`, `pr-test-analyzer`, `security-reviewer`, `performance-reviewer`, `doc-reviewer` and `frontend-designer`, and the skills cover the workflow, with `setupdotclaude`, `catchup`, `claude-md`, `fix-issue`, `debug-fix`, `ship`, `pr-review`, `tdd`, `explain`, `refactor`, `test-writer`, `context-budget`, `onboard` and `spec`.

Plugins are semver versioned in their own manifest, and `/plugin update` picks up new releases.

The clone path installs everything and then subtracts

The second option is for people who keep a dotfiles repository or who would rather skip the plugin layer entirely, and it is a straight file copy.

git clone https://github.com/poshan0126/dotclaude.git /tmp/dotclaude

cd your-project
mkdir -p .claude

cp /tmp/dotclaude/settings.json .claude/
cp -r /tmp/dotclaude/{rules,skills,agents,hooks} .claude/
cp /tmp/dotclaude/CLAUDE.template.md ./CLAUDE.md
cp /tmp/dotclaude/CLAUDE.local.md.example ./

chmod +x .claude/hooks/*.sh
rm -rf /tmp/dotclaude

echo "CLAUDE.local.md" >> .gitignore

The last two lines matter as much as the copies. The hooks have to be executable, and the local preferences file is added to `.gitignore` because it is personal and should not be committed.

The interesting part is what happens next. The README says that after reloading Claude Code you run the same `/setupdotclaude` skill, but it operates in reverse. Since you copied the entire kit, it scans the project, builds the same evidence-based plan, and then proposes removing the pieces your project does not need, along with repository artifacts such as folder READMEs, the `.claude-plugin/` directory and `hooks/tests/` if you did a bulk copy, and then customizes whatever stays.

So the two paths converge on the same end state, which is the claim the README makes about them being two paths to the same place. One starts from nothing and proposes an addition, the other starts from everything and proposes a subtraction. In both cases the human decides.

For a team, the subtraction path is worth understanding, because it means the kit can be cloned into a shared repository and then reduced to a common baseline that everybody applies.

Agents, skills, rules and hooks are four different things

The four component types are the vocabulary of the project, and each one has a distinct job.

Agents are the specialists, and they are listed with names that describe a review lens rather than a role in a workflow: a code reviewer, a silent failure hunter, a pull request test analyzer, a security reviewer, a performance reviewer, a documentation reviewer and a frontend designer. The silent failure hunter in particular suggests a focus on code that appears to work while hiding errors, which is the class of defect a general reviewer tends to miss.

Skills are slash commands invoked with `/name` inside a Claude Code session, and the README notes that all of them are manual only except `/test-writer`. That is an interesting default. A skill that runs on its own schedule is a surprise waiting to happen, and making the agentic ones manual keeps the session under the developer's control.

Rules are the modular instruction files, and the README is explicit about the three that matter most for a project: `rules/code-quality.md` for naming conventions, comment guidelines, code marker format and import order; `rules/frontend.md` for the design principle and the component framework the project actually uses; and `rules/security.md` for paths specific to the project's sensitive areas, beyond the defaults.

Hooks are the shell scripts, and the `safety-hooks` plugin is packaged as four PreToolUse guards covering dangerous commands, secret scanning, protected files and build artifacts. The README describes the point of that plugin as deterministic guardrails without copying any files, and the troubleshooting table notes that the guard scripts stay hard-blocked while the prompt to confirm an edit to `settings.json` is expected behaviour from `protect-files.sh`.

That combination is the interesting part of the design. A rule is advice the model may or may not follow, and a hook is a check that runs before a tool is invoked, so the same guardrail can be expressed at two levels of enforcement.

The fingerprint file and the drift nudge

The mechanism that keeps the configuration honest over time is a fingerprint file, and it is the part of the kit that goes beyond a one-off install.

When `/setupdotclaude` finishes, it saves a fingerprint of the project's manifests to `.claude/.dotclaude.json`, and the README says to commit that file, since the team shares the baseline. From then on, a `session-start` hook compares the current fingerprint with the saved one each session and emits a single line, `config drift: project manifests changed since setup`, but only when the stack actually changed. The README is explicit that it costs zero tokens otherwise.

That is a small idea with a large payoff. A configuration kit that is installed once and never revisited drifts silently, and the usual symptom is that the rules refer to a test directory that has moved or a package manager you no longer use. Here the drift is detected by comparing a file, and the notification is a line rather than a prompt, so it does not eat into the session budget.

The README also lists when to re-run the setup skill, and the list is where the guidance is most practical. Re-run it when the drift nudge appears, which the README ties to new scripts, a new framework, a new package manager or a new build tool being detected. Re-run it when you have added a major area the rules should cover, with the examples being first migrations, first frontend code, or a new package in a monorepo. And re-run it after a big restructuring that moved source or test directories, because path-scoped rule globs go stale.

Re-runs are described as cheap, and the mechanism explains why. On an existing `.claude/` directory the skill runs as a gap analysis and only proposes deltas, and the README puts it plainly: it never re-installs the world.

Three layers of instruction and the hooks that need jq

Two details decide whether a kit like this actually works in a team, and both are easy to miss.

The first is the layering of the instruction file. The README describes three levels. `CLAUDE.md` at the project root holds architectural decisions, domain knowledge and workflow quirks unique to the project. `CLAUDE.local.md` holds personal preferences and is gitignored, and the README says to rename the `.example` file to start. And `~/.claude/CLAUDE.md` holds global preferences applied across all of your projects, personal and never committed. The project file and any nested `CLAUDE.md` in subdirectories layer on top of the global one.

That layering is what allows one person to use the kit across several repositories while a team shares the committed baseline, and it is why the local file is excluded from version control rather than just being ignored by convention.

The second detail is the runtime dependency of the hooks. The troubleshooting table says that if hooks are not running you should run `chmod +x .claude/hooks/*.sh` and verify that `jq` is installed, and it lists the install commands for jq on macOS and on Linux. A `jq not found` message blocking everything is a first-run experience for anyone cloning the repository on a machine without jq, and it is the kind of thing the marketplace path avoids only because the plugin installs the same hook files underneath.

The README also names a specific behaviour worth knowing about, in the entry about permission denied on allowed commands. It says to check the glob in `settings.json`, and explains that a pattern such as `Bash(npm run test *)` matches the arguments after `test`. That is a Claude Code permission pattern subtlety, and it is the sort of thing that makes a copied settings file look broken when it is working as designed.

The formatter hook is more forgiving. The README says `hooks/format-on-save.sh` auto-detects Biome, Prettier, Ruff, Black, rustfmt and gofmt, and that if your formatter is not covered you add a detection block to the script.

No MCP servers, and why that is a design decision

The last thing the README emphasises is the one that looks like a limitation and is in fact a commitment.

It says the setup is cache-safe by design, and the reason is that every dotclaude plugin ships only skills, agents, rules and hooks, with no MCP servers. The consequence is that enabling or disabling them never invalidates Claude Code's prompt cache. Applying plugin changes is done with `/reload-plugins` or by starting a new session, and the first turn after a reload is uncached before it settles.

This is the kind of detail that separates a kit that people keep using from one they abandon. MCP servers are powerful, and they are also the part of a Claude Code configuration that tends to break the cache, so a kit that ships none of them is choosing a smaller surface in exchange for a stable session.

The cost of that choice is real. There is no tool server in the kit, so anything that needs a tool integration beyond the built-ins has to come from your own configuration, and the section of the README on making the kit your own does not suggest otherwise, since the customisation points it lists are all files rather than services.

The other piece of housekeeping is the cache behaviour of the kit itself, which the README treats as a rule rather than a preference. Because there are no MCP servers to invalidate anything, the plugin set can be toggled freely, which is what makes the individual plugin installs and the `/plugin update` flow safe to use.

Taken together with the drift detection, the layers of instruction and the reversal of the clone path, the through-line of the project is that configuration should be small, explicit and revisable rather than a large opaque bundle that nobody dares to touch.

Editorial conclusion

dotclaude fits a developer who wants a considered Claude Code setup for a real project rather than a pile of prompts copied from a gist, and who is prepared to review the install plan the setup skill proposes. Skip it if you want a single hand written CLAUDE.md and nothing else, since the kit is deliberately more than that, or if your environment cannot run the shell hooks, which need an executable bit and jq. Verify first that the plugins you want exist in the published list, that the plan the setup skill shows matches what you intended, and that the rules files you keep are ones you have actually read.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. poshan0126/dotclaude on GitHub
4. README