Dot-Claude

Warning

Under Active Development This project is currently being built and refined. Features and documentation may change frequently. Feel free to use and contribute, but expect updates!

📑 Table of Contents

• Overview
• Installation
• Features
• Tools & Hooks
• Configuration
• Project Structure
• Contributing
• License

---

Overview

Dot-Claude provides a production-ready .claude directory with powerful hooks and configurations to enhance Claude Code's capabilities. Whether you're managing documentation, enforcing code standards, or streamlining your workflow, this configuration has you covered.

Installation

Platform Support: Works on macOS, Linux, and Windows (via Git Bash/WSL)

Quick Setup

1. Clone this repository:

   git clone https://github.com/owenob1/Dot-Claude.git
   cd Dot-Claude

2. Copy the .claude directory to your project root:

   # macOS/Linux
   cp -r .claude /path/to/your/project/
   
   # Windows (Git Bash)
   cp -r .claude /c/path/to/your/project/
   
   # Windows (PowerShell)
   Copy-Item -Recurse .claude C:\path\to\your\project\

3. Make hooks executable (macOS/Linux/Git Bash only):

   chmod +x .claude/hooks/*.sh

4. Restart Claude Code to load the new configuration.

Manual Setup

Alternatively, you can copy individual files from the .claude directory into your existing setup:

# Copy settings
cp .claude/settings.json /path/to/your/project/.claude/

# Copy specific hooks
cp .claude/hooks/pre-tool-use.sh /path/to/your/project/.claude/hooks/

Features

🎯 Smart Hooks System

The configuration includes a comprehensive hooks system that runs automatically during Claude Code operations:

• Session Management: Hooks for session start and end events
• Tool Use Controls: Pre and post-tool execution hooks
• Formatting: Automatic file formatting after edits
• Notifications: Custom notification handling
• Compaction Control: Pre-compact hooks for context management

🔒 Network Security

Configured allowlist for safe external API access:

• NPM Registry
• GitHub (including raw content)
• MCP Context services

Tools & Hooks

🛡️ Pre-Tool Use Safety Guard

The Star Feature! - A comprehensive safety system that runs before every tool call.

File: .claude/hooks/pre-tool-use.sh

View Details

This hook combines 4 intelligent guardrails into one powerful safety system:

1. 💥 Bash Command Safety

Blocks destructive commands from all platforms (because Git Bash on Windows has Unix commands too!):

• Unix/Linux/macOS: rm -rf /, fork bombs, mkfs, dangerous dd operations
• Windows: del /S, format C:, rmdir /S
• Git: Warns about force pushes to main/master

2. 📦 Large File Warning

Warns before reading files >1MB to prevent context overflow.

3. 📝 Package.json Alerts

Reminds you to run npm install after modifications.

4. 📁 Markdown Structure Enforcement

Enforces organized documentation structure. Only allows markdown files in designated locations (docs/, .claude/commands/, .claude/agents/, README.md).

Example responses:

{"decision": "deny", "reason": "Potentially destructive command blocked: rm -rf /"}
{"decision": "ask", "reason": "Large file (5 MB). This may use significant context. Continue?"}

---

Other Hooks (Customizable)

All hooks below are placeholder templates ready for your customization. They currently exit successfully without taking action.

🔄 Session Hooks - Session lifecycle management

Files: session-start.sh • session-end.sh • stop.sh

Use cases: Initialize settings on start, clean up files on end, save context between sessions, trigger notifications.

---

📋 User Prompt Hook - Intercept and validate prompts

File: .claude/hooks/user-prompt-submit.sh

Use cases: Add project context, validate format, log interactions, pre-process prompts.

---

🎨 File Formatting Hook - Auto-format after edits

File: .claude/hooks/format-file.sh

Use cases: Run Prettier/ESLint, ensure consistent style, add headers, validate contents.

---

📦 Pre-Compact Hook - Actions before compaction

File: .claude/hooks/pre-compact.sh

Use cases: Save context, log state, archive previous context, optimize preservation.

---

🔔 Notification Hook - Handle system notifications

File: .claude/hooks/notification.sh

Use cases: Desktop notifications, event logging, Slack/Discord integration, custom alerts.

---

Configuration

⚙️ Settings & Customization

Settings File

The .claude/settings.json file configures all hooks and network policies:

{
  "hooks": {
    "SessionStart": [...],
    "PreToolUse": [...],
    "PostToolUse": [...]
    // ... and more
  },
  "network": {
    "allowlist": ["registry.npmjs.org", "*.github.com", ...]
  }
}

Customizing Hooks

Hook scripts should:

• Exit with code 0 on success
• Return JSON with decision and reason for blocking actions
• Complete within configured timeout
• Be executable (chmod +x)

Response examples:

{"decision": "deny", "reason": "Explanation..."}
{"decision": "proceed", "message": "Warning..."}

---

Project Structure

.claude/
├── settings.json              # Main configuration file
└── hooks/                     # Hook scripts directory
    ├── pre-tool-use.sh       # 🛡️ Multi-feature safety guard (main tool!)
    ├── session-start.sh      # Session initialization
    ├── session-end.sh        # Session cleanup
    ├── user-prompt-submit.sh # Prompt preprocessing
    ├── format-file.sh        # Post-edit formatting
    ├── pre-compact.sh        # Pre-compaction actions
    ├── stop.sh               # Stop event handler
    └── notification.sh       # Notification handler

Contributing

Contributions are welcome! If you have useful hooks, commands, or agents to share:

1. Fork the repository
2. Create a feature branch
3. Add your improvements
4. Submit a pull request

Please ensure your hooks are well-documented and include usage examples.

License

MIT License - feel free to use and modify for your projects.

Acknowledgments

Built for the Claude Code community to help maintain clean, organized, and efficient AI-assisted development workflows.

---

Made with ❤️ for Claude Code users