claude-dev-env

Consistent development standards for Claude Code across every repo. Install once, get TDD enforcement, code quality hooks, specialized agents, and battle-tested rules everywhere.

Quick Start

Prerequisites

• Node.js 18+ (includes npx)
• Python 3.8+ (for hook scripts)
• Claude Code CLI installed and working

Install

npx claude-dev-env

That's it. The installer will:

1. Detect your Python 3 command (python3, python, or py -3)
2. Copy rules, docs, commands, and hooks to ~/.claude/; copy agents and skills to ~/.agents/ and point ~/.claude/agents and ~/.claude/skills at that home
3. Copy hook scripts to ~/.claude/hooks/
4. Merge hook groups into ~/.claude/settings.json (preserves your existing hooks)
5. Write a manifest to ~/.claude/.claude-dev-env-manifest.json for clean uninstall
6. Copy Codex exec-policy files into ~/.codex/rules (CODEX_HOME/rules when that variable is set)

Selective Install

Use --only with one or more groups:

npx claude-dev-env --only core             # dev standards, hooks, agents, commands

Run node bin/install.mjs --help for the group list, including any group a declared dependency package contributes.

The installer reads only flags. A bare path argument such as npx claude-dev-env . carries no meaning: the run lands in ~/.claude the same way. Select another root with --target DIR, --profile ID, or the CLAUDE_CONFIG_DIR environment variable.

Verify

Start a new Claude Code session. You should see hook activity on your first prompt (code-rules-reminder, hook-structure-context). Run /sr-loop to confirm commands loaded.

For ChatGPT Work Cloud, use the cloud pstack startup verification. The local installer does not register skills with the cloud catalog or enable plugin shell hooks in cloud orchestration.

Update

Run the same command again. It overwrites existing files and updates hook entries in place:

npx claude-dev-env

Uninstall

Removes only the files this package installed (tracked via manifest) and cleans hook entries from settings.json:

npx claude-dev-env --uninstall

Bootstrap the project-path registry (one-time, post-install)

The Everything search command and the untracked-repo detector both read ~/.claude/project-paths.json. That file maps short repository names to absolute paths. It is per-user data and is not committed here.

After installing or updating claude-dev-env, run the bootstrap script once to populate the registry by scanning for .git directories with Everything's command-line binary:

python packages/claude-dev-env/scripts/setup_project_paths.py

Requirements:

• Everything (from voidtools) installed with its service running
• es.exe available on PATH

The script discovers candidate repos via es.exe, filters out ephemeral locations (temp, tmp, worktree, node_modules, .cache, $recycle.bin), shows the proposed mapping, and writes ~/.claude/project-paths.json only after you confirm at the prompt. The file is atomically replaced on write and merges with any entries already present.

Once the registry is populated, run:

python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <repo-name> <search arguments>

An exact repository name becomes one absolute path. The command then starts es.exe. Put the search scope in the first argument. An options-only request exits before es.exe starts.

What This Solves

Without shared config, every repo needs its own .claude/rules/, .claude/hooks/, .claude/agents/, etc. That means:

• Duplicated config across 5+ repos
• Drift when you update standards in one place but forget others
• New repos start with zero guardrails

This package centralizes all general-purpose Claude Code config. Project-specific rules still live in each repo's .claude/ directory and merge with these.

What's Included

Rules

Behavioral rules loaded into every session.

Codex exec-policy files

Starlark *.rules files Codex loads from ~/.codex/rules. The package ships claude-dev-env.rules so a local default.rules stays in place.

Cursor rule files

The installer writes no Cursor rule files. Cursor Agent reads a repository's own AGENTS.md, CLAUDE.md, .cursor/rules, and .agents/skills, and it reads ~/.cursor/rules only for a workspace inside the home directory. A full reinstall moves the ~/.cursor/rules files an older install generated into the run backup.

Task usage report

Use the task usage report guide to record task outcomes and compare cost per passed task.

Docs

Reference documents that rules and agents point to for detailed standards.

Agents (1)

Specialized agent prompts for common development tasks. Claude Code automatically discovers these and makes them available for delegation.

The 8 personal agents this package shipped before poteto-agent are archived under .agents/agents-archived/, each with a restore command in ARCHIVE-MANIFEST.md.

Commands (1)

Slash commands for common workflows.

Skills

Each skill lands under the agents home, with a directory pointer at ~/.claude/skills. A declared dependency package can add more; node bin/install.mjs --help names the groups that carry them.

Hooks

Automated enforcement that runs on Claude Code events. The installer detects your Python 3 command and rewrites hook paths to absolute ~/.claude/hooks/ paths in settings.json.

PreToolUse (before tool execution)

Other Events

Validators Module

The hooks/validators/ directory contains 30+ individual check modules with a full test suite:

Abbreviations, code quality, comments, file structure, git conventions, magic values, mypy integration, PR references, Python antipatterns, Python style, React patterns, ruff integration, security, TODO tracking, type safety, useless test detection, and more.

Also Available as a Plugin

If you prefer the Claude Code plugin system over npm:

claude plugin install jl-cmd/claude-dev-env

Recommended Companion Plugins

These plugins provide additional skills and capabilities that complement this config:

claude plugin install anthropics/claude-code-plugins        # Official: frontend-design, code-review, playwright, hookify, skill-creator, claude-md-management, serena, pyright-lsp, typescript-lsp, claude-code-setup
claude plugin install anthropics/claude-code-workflows      # Official: python-dev, ui-design, unit-testing, context-management, agent-teams, and more
claude plugin install jl-cmd/claude-workflow                # Workflow definitions with YAML schemas

Run node bin/install.mjs --help for the group list this build defines.

GSD (project management) is available as an npm package:

npx get-shit-done-cc

Customization

Installed rules merge with your project's .claude/ config. To override a rule for a specific project, create a rule with the same filename in your project's .claude/rules/ directory.

Installed hooks run alongside any hooks already in your settings.json or settings.local.json. The installer preserves existing hook entries.

Requirements

• Node.js 18+ (for the installer)
• Python 3.8+ (for hooks)
• Claude Code CLI

License

MIT