claude-init 1.0.0

package/.claude/agents/library-usage-researcher.md

@@ -0,0 +1,89 @@
+---
+name: library-usage-researcher
+description: Use this agent when you need to research how to use a specific library, framework, or technology. This agent will systematically gather information about best practices, API details, advanced techniques, and real-world usage examples. The agent follows a strict sequence: first identifying the library, then getting official documentation, and finally searching for real-world implementations. Examples:\n\n<example>\nContext: User wants to understand how to use React Query for data fetching\nuser: "我想了解如何使用 React Query 进行数据获取"\nassistant: "我将使用 library-usage-researcher 代理来系统地研究 React Query 的使用方法"\n<commentary>\nSince the user wants to understand library usage, use the library-usage-researcher agent to gather comprehensive information about React Query.\n</commentary>\n</example>\n\n<example>\nContext: User needs to know advanced Redux Toolkit patterns\nuser: "Redux Toolkit 有哪些高级用法和技巧？"\nassistant: "让我启动 library-usage-researcher 代理来深入研究 Redux Toolkit 的高级模式和最佳实践"\n<commentary>\nThe user is asking about advanced usage patterns, which is exactly what the library-usage-researcher agent is designed to investigate.\n</commentary>\n</example>
+tools: Task, mcp__grep__searchGitHub, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, TodoWrite, WebFetch, Bash, LS, Read, Edit, Write
+color: blue
+---
+
+你是一位专业的技术研究专家，专门负责深入调研库、框架和技术的使用方法。你的任务是系统性地收集和整理关于特定技术的全面信息。
+
+## 工作流程
+
+你必须严格按照以下顺序执行研究任务：
+
+1. **识别目标库**
+   - 使用 `resolve-library-id` 工具准确找到用户询问的库或框架
+   - 确保获得正确的库标识符，避免混淆相似名称的库
+
+2. **获取官方文档**
+   - 使用 `get-library-docs` 工具深入了解：
+     - API 规范和接口定义
+     - 官方推荐的最佳实践
+     - 核心概念和设计理念
+     - 使用示例和代码片段
+
+3. **搜索真实案例**
+   - 使用 `searchGitHub` 工具查找真实项目中的使用案例
+   - 重点关注：
+     - 生产环境的实际用法
+     - 社区认可的模式和技巧
+     - 常见问题的解决方案
+     - 性能优化和高级技巧
+
+## 研究重点
+
+你需要特别关注以下方面：
+- **功能用法**：基础功能如何使用，参数配置方式
+- **巧妙用法**：社区发现的创新使用方式
+- **高级技巧**：性能优化、复杂场景处理
+- **真实细节**：实际项目中的具体实现
+- **常见陷阱**：容易出错的地方和反模式
+- **重要警告**：安全问题、性能问题、兼容性问题
+
+## 输出格式
+
+你必须按照以下结构组织你的研究结果，并编写文档保存在当前项目的根目录下：
+
+1. **接口规范**
+   - 核心 API 和方法签名
+   - 参数说明和返回值
+   - 类型定义（如果适用）
+
+2. **基础使用**
+   - 安装和初始化步骤
+   - 最简单的使用示例
+   - 基本配置选项
+
+3. **进阶技巧**
+   - 高级配置和优化
+   - 复杂场景的处理方法
+   - 性能调优建议
+
+4. **巧妙用法**
+   - 社区创新的使用模式
+   - 与其他工具的集成技巧
+   - 非常规但有效的解决方案
+
+5. **注意事项**
+   - 常见错误和如何避免
+   - 性能陷阱和最佳实践
+   - 版本兼容性问题
+
+6. **真实代码片段**
+   - 从 GitHub 找到的优秀示例
+   - 包含上下文的完整代码
+   - 说明为什么这是好的实践
+
+7. **引用来源**
+   - 提供所有关键信息的来源 URL
+   - 标注哪些是官方文档，哪些是社区资源
+
+## 重要原则
+
+- **不要本地化**：你专注于获取外部信息，不关心用户的本地代码情况
+- **诚实报告**：如果某个步骤没有获得有效信息，明确说明"未找到相关信息"，绝不杜撰
+- **保持客观**：基于事实报告，不加入个人偏好或推测
+- **注重实用**：优先展示能立即应用的实践知识
+- **中文表达**：所有内容用清晰的中文表达，包括对英文资料的翻译和解释
+
+记住：你的目标是为用户提供关于特定技术最全面、最实用的研究报告，让他们能够快速掌握并正确使用该技术。

package/.claude/commands/debug.md

@@ -0,0 +1,3 @@
+ultrathink, help me debug and fix:
+
+$ARGUMENTS

package/.claude/commands/gogogo.md

@@ -0,0 +1,3 @@
+looks good, now let's document the detailed plan, with detailed todo lists, in CLAUDE.md
+
+then start the implementation

package/.claude/commands/plan.md

@@ -0,0 +1,28 @@
+You are an experienced project manager. For every question posed by the user, you do not rush to write code. Instead, you focus on thoughtful, structured reasoning to provide high-quality answers, explore multiple possible solutions, and identify the best one. Before starting, ensure you fully understand the following project requirements and process descriptions.
+
+You possess the following capabilities:
+
+1. Requirements Clarification
+
+- Clearly restate the user's question or problem in your own words.
+- Establish high-level communication to clarify the user's needs.
+- Offer analogous case studies to inspire the user's thinking.
+- Explain the primary challenges and constraints.
+- During your reasoning process, ask questions to fill in any missing information or details you need.
+
+2. Solution Exploration
+
+- Explore multiple feasible implementation methods based on existing technologies.
+- List the pros, cons, applicable scenarios, and costs of each solution.
+- Prioritize leveraging existing technical solutions in the ecosystem to avoid reinventing the wheel.
+- Provide an optimal recommendation based on the requirements, explaining the rationale and potential improvements.
+- Ensure the recommended solution is scalable and maintainable, offering corresponding optimization suggestions.
+
+Additionally, maintain the following principles throughout your work process:
+
+1. Optimal Choices: When selecting technologies or implementation methods, prioritize mature, stable, and efficient solutions.
+2. Environment Considerations: Thoughtfully address potential environment issues, such as dependency version conflicts or system compatibility, and proactively provide solutions.
+
+Now, no need to code, read through and understand the codebase, ultrathink and give me a plan on:
+
+$ARGUMENTS

package/.claude/commands/prompt-enhancement.md

@@ -0,0 +1,3 @@
+ultrathink, no need to code, just help me rewrite and enhance the prompt, make the instructions more clear and detailed, by reading through and understanding the codebase first:
+
+$ARGUMENTS

package/.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch"
+    ],
+    "deny": [
+      "Read(**/.env*)",
+      "Edit(**/.env*)",
+      "Write(**/.env*)",
+      "Bash(**:.env*)"
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "npx ccusage statusline"
+  },
+  "outputStyle": "Explanatory"
+}

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(npm install)",
+      "Bash(chmod:*)",
+      "Bash(npm test)",
+      "Bash(node:*)",
+      "Bash(npm pack:*)"
+    ],
+    "deny": [],
+    "ask": [],
+    "additionalDirectories": [
+      "/tmp"
+    ]
+  }
+}

package/.devcontainer/Dockerfile

@@ -0,0 +1,91 @@
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR nano
+ENV VISUAL nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
+USER node

package/.devcontainer/devcontainer.json

@@ -0,0 +1,56 @@
+{
+  "name": "Claude Code Sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Los_Angeles}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": [
+    "--cap-add=NET_ADMIN",
+    "--cap-add=NET_RAW"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens",
+        "anthropic.claude-code"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "node",
+  "mounts": [
+    "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace",
+  "postCreateCommand": "sudo /usr/local/bin/init-firewall.sh"
+}

package/.devcontainer/init-firewall.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# 1. Extract Docker DNS info BEFORE any flushing
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# 2. Selectively restore ONLY internal Docker DNS resolution
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+# Allow inbound SSH responses
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Fetch GitHub meta information and aggregate + add their IP ranges
+echo "Fetching GitHub IP ranges..."
+gh_ranges=$(curl -s https://api.github.com/meta)
+if [ -z "$gh_ranges" ]; then
+    echo "ERROR: Failed to fetch GitHub IP ranges"
+    exit 1
+fi
+
+if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then
+    echo "ERROR: GitHub API response missing required fields"
+    exit 1
+fi
+
+echo "Processing GitHub IPs..."
+while read -r cidr; do
+    if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then
+        echo "ERROR: Invalid CIDR range from GitHub meta: $cidr"
+        exit 1
+    fi
+    echo "Adding GitHub range $cidr"
+    ipset add allowed-domains "$cidr"
+done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)
+
+# Resolve and add other allowed domains
+for domain in \
+    "registry.npmjs.org" \
+    "api.anthropic.com" \
+    "sentry.io" \
+    "statsig.anthropic.com" \
+    "statsig.com"; do
+    echo "Resolving $domain..."
+    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+    
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip"
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Verify GitHub API access
+if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.github.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.github.com as expected"
+fi

package/CLAUDE.md

@@ -0,0 +1,4 @@
++ During you interaction with the user, if you find anything reusable in this project (e.g. version of a library, model name), especially about a fix to a mistake you made or a correction you received, you should take note in the `Lessons` section in the `CLAUDE.md` file so you will not make the same mistake again. 
++ You should also use the `CLAUDE.md` file as a scratchpad to organize your thoughts. Especially when you receive a new task, you should first review the content of the scratchpad, clear old different task but keep lessons learned, then explain the task, and plan the steps you need to take to complete the task. You can use todo markers to indicate the progress, e.g.
+[X] Task 1
+[ ] Task 2

package/README.md

@@ -0,0 +1,104 @@
+# claude-init
+
+A CLI tool to initialize Claude development environment with standardized configurations and templates.
+
+## Features
+
+- **Smart Setup**: Automatically detects existing files and only creates/updates what's needed
+- **Non-destructive**: Never overwrites existing files, only adds missing content
+- **Progress Feedback**: Clear visual indicators of what's being created, updated, or skipped
+- **Cross-platform**: Works on Windows, macOS, and Linux
+
+## Usage
+
+### Quick Start
+
+```bash
+npx claude-init
+```
+
+This will set up your current directory with:
+
+- `CLAUDE.md` - Project instructions and scratchpad for Claude
+- `.devcontainer/` - Development container configuration
+- `.claude/settings.json` - Claude-specific settings
+- `.claude/commands/` - Custom Claude commands
+- `.claude/agents/` - Specialized agent configurations
+
+### What It Does
+
+#### 📄 CLAUDE.md
+- **If missing**: Creates new file with template content
+- **If exists**: Appends template content under "# Claude Scratchpad Rules" heading
+- **If already contains template**: Skips to preserve your content
+
+#### 📁 .devcontainer
+- **If missing**: Creates complete directory with Docker configuration
+- **If exists**: Skips entirely to preserve your setup
+
+#### ⚙️ .claude/settings.json
+- **If missing**: Creates with default Claude settings
+- **If exists**: Skips to preserve your custom settings
+
+#### 📋 .claude/commands & .claude/agents
+- **If missing**: Creates with all template files
+- **If exists**: Only adds missing files, preserves existing ones
+
+## Example Output
+
+```
+🚀 Claude Environment Initializer
+Initializing in: /path/to/your/project
+
+✓ Created new CLAUDE.md
+✓ Created .devcontainer directory  
+✓ Created .claude/settings.json
+↻ Added 2 missing files to .claude/commands (2 files)
+- All files in .claude/agents are up to date
+
+📊 Summary:
+   Created: 3 items
+   Updated: 1 items
+   Skipped: 1 items (already exist)
+   Files added: 2
+
+✨ Claude environment is ready!
+```
+
+## File Structure Created
+
+```
+your-project/
+├── CLAUDE.md                      # Project instructions
+├── .devcontainer/
+│   ├── devcontainer.json         # VS Code dev container config
+│   ├── Dockerfile               # Container setup
+│   └── init-firewall.sh         # Initialization script
+└── .claude/
+    ├── settings.json            # Claude settings
+    ├── commands/                # Custom commands
+    │   ├── debug.md
+    │   ├── gogogo.md
+    │   ├── plan.md
+    │   └── prompt-enhancement.md
+    └── agents/                  # Specialized agents
+        └── library-usage-researcher.md
+```
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Local Development
+
+```bash
+npm run dev
+```
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { cli } from '../src/cli.js';
+
+// Entry point for npx claude-init
+cli().catch((error) => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "claude-init",
+  "version": "1.0.0",
+  "description": "Initialize Claude development environment with configurations and templates",
+  "type": "module",
+  "bin": {
+    "claude-init": "./bin/index.js"
+  },
+  "main": "./src/cli.js",
+  "files": [
+    "bin/",
+    "src/",
+    "CLAUDE.md",
+    ".claude/",
+    ".devcontainer/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "dev": "node bin/index.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "development",
+    "environment",
+    "cli",
+    "initialization",
+    "scaffolding"
+  ],
+  "author": "ChrisLinn <nanyishanshaoxiu@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^7.0.1"
+  },
+  "devDependencies": {
+    "tmp": "^0.2.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "bugs": {
+    "url": ""
+  },
+  "homepage": ""
+}

package/src/cli.js

@@ -0,0 +1,116 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { 
+  handleClaudeMarkdown,
+  handleDirectoryMirror,
+  handleSelectiveFileCopy,
+  handleSingleFile
+} from './fileManager.js';
+
+/**
+ * Format action result with appropriate colors and icons
+ */
+function formatResult(result) {
+  const { action, details, filesAdded } = result;
+  
+  switch (action) {
+    case 'created':
+      return chalk.green(`✓ ${details}`);
+    case 'updated':
+      const fileInfo = filesAdded !== undefined ? ` (${filesAdded} files)` : '';
+      return chalk.yellow(`↻ ${details}${fileInfo}`);
+    case 'skipped':
+      return chalk.gray(`- ${details}`);
+    default:
+      return details;
+  }
+}
+
+/**
+ * Main CLI function
+ */
+export async function cli() {
+  const targetDir = process.cwd();
+  
+  console.log(chalk.blue.bold('🚀 Claude Environment Initializer'));
+  console.log(chalk.gray(`Initializing in: ${targetDir}`));
+  console.log();
+  
+  const tasks = [
+    {
+      name: 'CLAUDE.md',
+      handler: () => handleClaudeMarkdown(targetDir)
+    },
+    {
+      name: '.devcontainer',
+      handler: () => handleDirectoryMirror(targetDir, '.devcontainer')
+    },
+    {
+      name: '.claude/settings.json',
+      handler: () => handleSingleFile(targetDir, '.claude/settings.json')
+    },
+    {
+      name: '.claude/commands',
+      handler: () => handleSelectiveFileCopy(targetDir, '.claude/commands')
+    },
+    {
+      name: '.claude/agents',
+      handler: () => handleSelectiveFileCopy(targetDir, '.claude/agents')
+    }
+  ];
+  
+  let totalActions = { created: 0, updated: 0, skipped: 0, filesAdded: 0 };
+  
+  for (const task of tasks) {
+    const spinner = ora(`Processing ${task.name}...`).start();
+    
+    try {
+      const result = await task.handler();
+      spinner.succeed(formatResult(result));
+      
+      // Track statistics
+      totalActions[result.action]++;
+      if (result.filesAdded) {
+        totalActions.filesAdded += result.filesAdded;
+      }
+      
+    } catch (error) {
+      spinner.fail(`Failed to process ${task.name}: ${error.message}`);
+      throw error;
+    }
+  }
+  
+  // Summary
+  console.log();
+  console.log(chalk.blue.bold('📊 Summary:'));
+  
+  if (totalActions.created > 0) {
+    console.log(chalk.green(`   Created: ${totalActions.created} items`));
+  }
+  
+  if (totalActions.updated > 0) {
+    console.log(chalk.yellow(`   Updated: ${totalActions.updated} items`));
+  }
+  
+  if (totalActions.skipped > 0) {
+    console.log(chalk.gray(`   Skipped: ${totalActions.skipped} items (already exist)`));
+  }
+  
+  if (totalActions.filesAdded > 0) {
+    console.log(chalk.cyan(`   Files added: ${totalActions.filesAdded}`));
+  }
+  
+  console.log();
+  
+  if (totalActions.created > 0 || totalActions.updated > 0) {
+    console.log(chalk.green.bold('✨ Claude environment is ready!'));
+  } else {
+    console.log(chalk.blue.bold('✅ Claude environment is already up to date!'));
+  }
+  
+  console.log();
+  console.log(chalk.gray('Next steps:'));
+  console.log(chalk.gray('• Review CLAUDE.md for project-specific instructions'));
+  console.log(chalk.gray('• Customize .claude/settings.json if needed'));
+  console.log(chalk.gray('• Add custom commands to .claude/commands/'));
+}

package/src/fileManager.js

@@ -0,0 +1,124 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { 
+  getTemplatesPath, 
+  createContentHash, 
+  contentContains, 
+  readTemplate,
+  getFilesInDirectory 
+} from './utils.js';
+
+/**
+ * Handle CLAUDE.md file creation or updating
+ */
+export async function handleClaudeMarkdown(targetDir) {
+  const claudeFile = path.join(targetDir, 'CLAUDE.md');
+  const templateContent = await readTemplate('CLAUDE.md');
+  const templateHash = createContentHash(templateContent);
+  
+  if (!(await fs.pathExists(claudeFile))) {
+    // File doesn't exist, create it
+    await fs.writeFile(claudeFile, templateContent);
+    return { action: 'created', details: 'Created new CLAUDE.md' };
+  }
+  
+  // File exists, check if it contains our template content
+  const existingContent = await fs.readFile(claudeFile, 'utf8');
+  const existingHash = createContentHash(existingContent);
+  
+  // Check if template content is already present
+  if (existingHash === templateHash || contentContains(existingContent, templateContent.trim())) {
+    return { action: 'skipped', details: 'CLAUDE.md already contains template content' };
+  }
+  
+  // Append template content under a heading
+  const heading = '\\n\\n# Claude Scratchpad Rules\\n\\n';
+  const updatedContent = existingContent + heading + templateContent;
+  await fs.writeFile(claudeFile, updatedContent);
+  
+  return { action: 'updated', details: 'Appended template content to existing CLAUDE.md' };
+}
+
+/**
+ * Handle directory mirroring (create if not exists, skip if exists)
+ */
+export async function handleDirectoryMirror(targetDir, relativePath) {
+  const targetPath = path.join(targetDir, relativePath);
+  const templatePath = path.join(getTemplatesPath(), relativePath);
+  
+  if (await fs.pathExists(targetPath)) {
+    return { action: 'skipped', details: `Directory ${relativePath} already exists` };
+  }
+  
+  // Copy entire directory
+  await fs.copy(templatePath, targetPath);
+  return { action: 'created', details: `Created ${relativePath} directory` };
+}
+
+/**
+ * Handle selective file copying (add missing files only)
+ */
+export async function handleSelectiveFileCopy(targetDir, relativePath) {
+  const targetPath = path.join(targetDir, relativePath);
+  const templatePath = path.join(getTemplatesPath(), relativePath);
+  
+  if (!(await fs.pathExists(targetPath))) {
+    // Directory doesn't exist, create it with all template files
+    await fs.copy(templatePath, targetPath);
+    const files = await getFilesInDirectory(templatePath);
+    return { 
+      action: 'created', 
+      details: `Created ${relativePath} with ${files.length} files`,
+      filesAdded: files.length
+    };
+  }
+  
+  // Directory exists, check for missing files
+  const templateFiles = await getFilesInDirectory(templatePath);
+  const targetFiles = await getFilesInDirectory(targetPath);
+  const missingFiles = templateFiles.filter(file => !targetFiles.includes(file));
+  
+  if (missingFiles.length === 0) {
+    return { 
+      action: 'skipped', 
+      details: `All files in ${relativePath} are up to date`,
+      filesAdded: 0
+    };
+  }
+  
+  // Copy missing files
+  let copiedCount = 0;
+  for (const missingFile of missingFiles) {
+    const sourcePath = path.join(templatePath, missingFile);
+    const destPath = path.join(targetPath, missingFile);
+    
+    // Ensure destination directory exists
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(sourcePath, destPath);
+    copiedCount++;
+  }
+  
+  return { 
+    action: 'updated', 
+    details: `Added ${copiedCount} missing files to ${relativePath}`,
+    filesAdded: copiedCount
+  };
+}
+
+/**
+ * Handle single file copying (create if not exists, skip if exists)
+ */
+export async function handleSingleFile(targetDir, relativePath) {
+  const targetPath = path.join(targetDir, relativePath);
+  const templatePath = path.join(getTemplatesPath(), relativePath);
+  
+  if (await fs.pathExists(targetPath)) {
+    return { action: 'skipped', details: `File ${relativePath} already exists` };
+  }
+  
+  // Ensure target directory exists
+  await fs.ensureDir(path.dirname(targetPath));
+  await fs.copy(templatePath, targetPath);
+  
+  return { action: 'created', details: `Created ${relativePath}` };
+}

package/src/utils.js

@@ -0,0 +1,65 @@
+import { createHash } from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Get the absolute path to the templates directory
+ */
+export function getTemplatesPath() {
+  // return path.join(__dirname, '..', 'templates');
+  return path.join(__dirname, '..');
+}
+
+/**
+ * Create a hash of file content for comparison
+ */
+export function createContentHash(content) {
+  return createHash('md5').update(content.trim()).digest('hex');
+}
+
+/**
+ * Check if content contains a specific text (case-insensitive)
+ */
+export function contentContains(content, searchText) {
+  return content.toLowerCase().includes(searchText.toLowerCase());
+}
+
+/**
+ * Read a template file
+ */
+export async function readTemplate(relativePath) {
+  const templatePath = path.join(getTemplatesPath(), relativePath);
+  return await fs.readFile(templatePath, 'utf8');
+}
+
+/**
+ * Get all files in a directory recursively
+ */
+export async function getFilesInDirectory(dirPath) {
+  const files = [];
+  
+  try {
+    const entries = await fs.readdir(dirPath);
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry);
+      const stats = await fs.stat(fullPath);
+      
+      if (stats.isFile()) {
+        files.push(entry);
+      } else if (stats.isDirectory()) {
+        const subFiles = await getFilesInDirectory(fullPath);
+        files.push(...subFiles.map(f => path.join(entry, f)));
+      }
+    }
+  } catch (error) {
+    // Directory doesn't exist
+    return [];
+  }
+  
+  return files;
+}