dotclaude

A professional toolkit for managing Claude Code configuration files.

dotclaude helps you create, validate, and optimize your .claude/ directory with a focus on security, best practices, and maintainability.

---

Table of Contents

• Why dotclaude
• Installation
• Quick Start
• Commands
  • init
  • lint
  • agent
  • skill
  • hook
  • security
  • analyze
  • show
• Configuration
• Best Practices
• Security
• Contributing
• License

---

Why dotclaude

Claude Code uses a .claude/ directory to store configuration files that control its behavior: agents, skills, rules, hooks, and settings. Managing these files manually can be error-prone:

Problem	dotclaude Solution
Complex YAML frontmatter syntax	Interactive generators with validation
No validation before runtime	Lint command catches errors early
Security misconfigurations	Security audit detects risky patterns
Scattered configuration	Show command displays resolved hierarchy
Unused agents/skills accumulate	Analyze command detects dead configuration
No standard templates	Presets for common frameworks

---

Installation

pip install dotclaude

Requirements:

• Python 3.9+
• No external dependencies required for core functionality

Optional dependencies:

pip install dotclaude[full]  # Includes Jinja2 templates and JSON Schema validation

---

Quick Start

Initialize a new project

cd your-project
dotclaude init

This creates:

.claude/
├── CLAUDE.md           # Project instructions for Claude
├── settings.json       # Hooks and permissions
├── agents/             # Custom subagents
├── skills/             # Custom skills
└── rules/              # Modular rules

Create your first agent

dotclaude agent create code-reviewer

Interactive prompts guide you through:

? Agent name: code-reviewer
? Description: Reviews code for security issues and best practices
? Allowed tools (comma-separated): Read, Grep, Glob
? Model [sonnet]: sonnet

Created: .claude/agents/code-reviewer.md

Validate your configuration

dotclaude lint

Output:

.claude/CLAUDE.md                    OK
.claude/settings.json                OK
.claude/agents/code-reviewer.md      OK
.claude/rules/security.md            WARN  Line 12: import @secrets.md not found

1 warning, 0 errors

---

Commands

init

Initialize a .claude/ directory with recommended structure.

dotclaude init [OPTIONS]

Options:

Option	Description
--template <name>	Use a preset template (fastapi, django, cli, data-science)
--minimal	Create only essential files
--force	Overwrite existing configuration

Examples:

# Standard initialization
dotclaude init

# Initialize with FastAPI template
dotclaude init --template fastapi

# Minimal setup (only CLAUDE.md)
dotclaude init --minimal

---

lint

Validate all configuration files for syntax errors and best practices.

dotclaude lint [OPTIONS] [PATH]

Options:

Option	Description
--strict	Enable strict mode (warnings become errors)
--fix	Auto-fix simple issues (formatting, missing fields)
--format <fmt>	Output format: text (default), json, github

What it validates:

File Type	Checks
CLAUDE.md	Markdown syntax, import resolution (@path), encoding
settings.json	JSON syntax, schema validation, hook structure
agents/*.md	Required frontmatter (name, description), valid tools
skills/*/SKILL.md	Structure, size limits (<500 lines), allowed-tools
rules/*.md	Path patterns validity, frontmatter syntax

Examples:

# Validate everything
dotclaude lint

# Strict mode for CI
dotclaude lint --strict

# Validate specific file
dotclaude lint .claude/agents/reviewer.md

# JSON output for tooling
dotclaude lint --format json

Exit codes:

• 0 - No errors
• 1 - Errors found
• 2 - Configuration error

---

agent

Create and manage Claude Code subagents.

dotclaude agent <command> [OPTIONS]

Subcommands:

Command	Description
create <name>	Create a new agent interactively
list	List all agents in the project
validate <name>	Validate a specific agent
edit <name>	Open agent in $EDITOR

Create options:

Option	Description
--description <text>	Set description (skip prompt)
--tools <list>	Comma-separated tool list
--model <name>	Model to use (sonnet, opus, haiku)
--template <name>	Use a predefined template

Examples:

# Interactive creation
dotclaude agent create security-auditor

# Non-interactive creation
dotclaude agent create api-designer \
  --description "Designs REST API endpoints" \
  --tools "Read,Grep,Write" \
  --model sonnet

# List all agents
dotclaude agent list

# Output:
# NAME              DESCRIPTION                      TOOLS
# code-reviewer     Reviews code for issues          Read, Grep, Glob
# api-designer      Designs REST API endpoints       Read, Grep, Write

Generated agent structure:

---
name: security-auditor
description: Audits code for security vulnerabilities
tools: Read, Grep, Glob
model: sonnet
---

You are a security auditor. Your role is to identify potential security
vulnerabilities in code.

## Guidelines

- Focus on OWASP Top 10 vulnerabilities
- Check for hardcoded secrets
- Validate input sanitization
- Review authentication and authorization logic

## Output Format

Report findings as:
1. Severity (Critical/High/Medium/Low)
2. Location (file:line)
3. Description
4. Recommended fix

---

skill

Create and manage Claude Code skills.

dotclaude skill <command> [OPTIONS]

Subcommands:

Command	Description
create <name>	Create a new skill with proper structure
list	List all skills
validate <name>	Validate skill structure and content

Examples:

# Create a skill
dotclaude skill create deployment-helper

# This creates:
# ~/.claude/skills/deployment-helper/
# ├── SKILL.md
# ├── reference.md
# └── scripts/

Skill structure requirements:

• SKILL.md must be under 500 lines (progressive disclosure)
• Detailed documentation goes in reference.md
• Helper scripts go in scripts/ directory

---

hook

Add pre-built hooks or create custom ones.

dotclaude hook <command> [OPTIONS]

Subcommands:

Command	Description
add <preset>	Add a pre-built hook
list	List available presets
create <name>	Create a custom hook
remove <name>	Remove a hook

Available presets:

Preset	Event	Description
auto-format	PostToolUse	Run prettier/black after file edits
block-dangerous	PreToolUse	Block rm -rf, sudo, and similar
run-tests	PostToolUse	Run tests after code changes
validate-imports	PreToolUse	Check imports before writes
notify-slack	Notification	Send notifications to Slack

Examples:

# Add auto-formatting hook
dotclaude hook add auto-format

# List available hooks
dotclaude hook list

# Create custom hook
dotclaude hook create my-validator

Hook configuration in settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  }
}

---

security

Audit configuration for security issues.

dotclaude security <command> [OPTIONS]

Subcommands:

Command	Description
audit	Full security audit
check <type>	Check specific security aspect

What it checks:

Category	Checks
Permissions	permissionMode: none (too permissive)
Hooks	Dangerous commands (rm -rf, curl | sh, sudo)
Agents	Unrestricted tool access (tools: *)
Imports	@path imports exposing sensitive files
Skills	allowed-tools: * without justification

Examples:

# Full audit
dotclaude security audit

# Output:
# SECURITY AUDIT REPORT
# =====================
#
# [CRITICAL] .claude/agents/dev.md
#   permissionMode: none allows all operations without confirmation
#   Recommendation: Use 'default' or specify explicit permissions
#
# [WARNING] .claude/settings.json
#   Hook at PreToolUse executes: curl -s $URL | sh
#   Recommendation: Avoid piping remote content to shell
#
# [INFO] .claude/CLAUDE.md
#   Import @.env detected
#   Recommendation: Avoid importing sensitive files
#
# Summary: 1 critical, 1 warning, 1 info

Exit codes:

• 0 - No critical issues
• 1 - Critical issues found
• 2 - Configuration error

---

analyze

Analyze configuration for optimization opportunities.

dotclaude analyze [OPTIONS]

Options:

Option	Description
--context	Show context token budget analysis
--deps	Show dependency graph
--unused	Detect unused agents/skills

Examples:

# Full analysis
dotclaude analyze

# Output:
# CONFIGURATION ANALYSIS
# ======================
#
# Context Budget:
#   CLAUDE.md:     ~2,100 tokens
#   rules/:        ~800 tokens
#   agents/:       ~1,200 tokens (on-demand)
#   Total base:    ~2,900 tokens
#
# Optimization Suggestions:
#   - rules/style.md and rules/formatting.md overlap 40%
#     Consider merging to reduce context usage
#
#   - Agent 'helper' declares 12 tools but analysis shows
#     only 3 are used. Consider restricting.
#
# Unused Configuration:
#   - .claude/agents/old-reviewer.md (no references found)
#   - .claude/skills/deprecated/ (no invocations detected)

---

show

Display the resolved configuration hierarchy.

dotclaude show [OPTIONS]

Options:

Option	Description
--memory	Show CLAUDE.md hierarchy
--agents	List all active agents
--hooks	Show configured hooks
--all	Show everything

Examples:

# Show memory hierarchy
dotclaude show --memory

# Output:
# CLAUDE.MD HIERARCHY (in load order)
# ===================================
#
# 1. [enterprise] /etc/claude-code/CLAUDE.md
#    (not present)
#
# 2. [project] ./CLAUDE.md
#    Lines: 45 | Imports: 2 | Tokens: ~1,200
#
# 3. [rules] ./.claude/rules/
#    ├── code-style.md (120 lines)
#    ├── testing.md (80 lines)
#    └── security.md (95 lines)
#
# 4. [user] ~/.claude/CLAUDE.md
#    Lines: 30 | Imports: 0 | Tokens: ~400
#
# 5. [local] ./CLAUDE.local.md
#    Lines: 10 | Tokens: ~100
#
# Effective tokens: ~3,200

---

Configuration

dotclaude can be configured via:

1. Command-line arguments (highest priority)
2. Environment variables (prefix: DOTCLAUDE_)
3. Configuration file .dotclaude.toml

Configuration file

# .dotclaude.toml

[lint]
strict = false
format = "text"

[security]
block_permission_none = true
block_tools_wildcard = true

[analyze]
max_context_tokens = 4000
warn_unused_after_days = 30

[templates]
default = "minimal"

Environment variables

export DOTCLAUDE_LINT_STRICT=true
export DOTCLAUDE_SECURITY_BLOCK_PERMISSION_NONE=true

---

Best Practices

Agent Design

1. Clear descriptions - The description determines when Claude delegates to the agent

   # Good
   description: Reviews Python code for PEP 8 compliance and common bugs
   
   # Bad
   description: Code reviewer
   

2. Minimal tool access - Only grant tools the agent actually needs

   # Good
   tools: Read, Grep, Glob
   
   # Bad
   tools: *
   

3. Specific system prompts - Include concrete guidelines, not vague instructions

Skill Design

1. Progressive disclosure - Keep SKILL.md under 500 lines
2. Reference files - Put detailed docs in reference.md
3. Helper scripts - Use scripts/ for complex operations

Hook Design

1. Always set timeouts - Prevent hung processes
2. Handle failures gracefully - Exit code 2 to deny, not crash
3. Avoid shell piping from remote - Security risk

Rules Organization

1. Path-specific rules - Use frontmatter for targeted rules

   ---
   paths: src/api/**/*.py
   ---
   

2. Modular files - One concern per file in rules/
3. Avoid duplication - Use imports instead of copying

---

Security

Threat Model

dotclaude helps protect against:

Threat	Mitigation
Overly permissive agents	Warns on permissionMode: none
Dangerous hooks	Detects rm -rf, curl|sh patterns
Secret exposure	Warns on @.env imports
Unrestricted tools	Flags tools: * usage

Security Audit Levels

Level	Description
CRITICAL	Immediate action required
WARNING	Should be reviewed
INFO	Best practice suggestion

Recommended CI Integration

# .github/workflows/claude-lint.yml
name: Claude Config Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install dotclaude
      - run: dotclaude lint --strict --format github
      - run: dotclaude security audit

---

Contributing

Contributions are welcome. Please read the contributing guidelines before submitting a pull request.

Development Setup

git clone https://github.com/yourusername/dotclaude.git
cd dotclaude
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

pytest
pytest --cov=dotclaude  # With coverage

Code Style

This project uses:

• ruff for linting
• black for formatting
• Type hints throughout

---

License

MIT License. See LICENSE for details.

---

Changelog

See CHANGELOG.md for version history.