dotclaude 0.2.0
Professional toolkit for managing Claude Code configuration
Requires Python: >=3.9
Keywords: ai, claude, claude-code, cli, configuration, developer-tools, linter, llm

# 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](#why-dotclaude)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [init](#init)
  - [lint](#lint)
  - [agent](#agent)
  - [skill](#skill)
  - [hook](#hook)
  - [security](#security)
  - [analyze](#analyze)
  - [show](#show)
- [Configuration](#configuration)
- [Best Practices](#best-practices)
- [Security](#security-1)
- [Contributing](#contributing)
- [License](#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

```bash
pip install dotclaude
```

**Requirements:**
- Python 3.9+
- No external dependencies required for core functionality

**Optional dependencies:**
```bash
pip install dotclaude[full]  # Includes Jinja2 templates and JSON Schema validation
```

---

## Quick Start

### Initialize a new project

```bash
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

```bash
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

```bash
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.

```bash
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:**
```bash
# 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.

```bash
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:**
```bash
# 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.

```bash
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:**
```bash
# 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:**
```markdown
---
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.

```bash
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:**
```bash
# 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.

```bash
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:**
```bash
# 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:**
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

---

### security

Audit configuration for security issues.

```bash
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:**
```bash
# 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.

```bash
dotclaude analyze [OPTIONS]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--context` | Show context token budget analysis |
| `--deps` | Show dependency graph |
| `--unused` | Detect unused agents/skills |

**Examples:**
```bash
# 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.

```bash
dotclaude show [OPTIONS]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--memory` | Show CLAUDE.md hierarchy |
| `--agents` | List all active agents |
| `--hooks` | Show configured hooks |
| `--all` | Show everything |

**Examples:**
```bash
# 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

```toml
# .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

```bash
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
   ```yaml
   # 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
   ```yaml
   # 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
   ```yaml
   ---
   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

```yaml
# .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

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

### Running Tests

```bash
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](LICENSE) for details.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.