@macpaw/cctk 1.0.0-beta.1

package/templates/common/.cct.json

@@ -0,0 +1,41 @@
+{
+  "codingLevel": -1,
+  "privacyBlock": true,
+  "docs": {
+    "maxLoc": 800
+  },
+  "plan": {
+    "namingFormat": "{date}-{issue}-{slug}",
+    "dateFormat": "YYMMDD-HHmm",
+    "issuePrefix": "GH-",
+    "reportsDir": "reports",
+    "resolution": {
+      "order": ["session", "branch"],
+      "branchPattern": "(?:feat|fix|chore|refactor|docs)/(?:[^/]+/)?(.+)"
+    },
+    "validation": {
+      "mode": "prompt",
+      "minQuestions": 3,
+      "maxQuestions": 8,
+      "focusAreas": ["assumptions", "risks", "tradeoffs", "architecture"]
+    }
+  },
+  "paths": {
+    "docs": "docs",
+    "plans": "plans"
+  },
+  "locale": {
+    "thinkingLanguage": null,
+    "responseLanguage": null
+  },
+  "trust": {
+    "passphrase": null,
+    "enabled": false
+  },
+  "project": {
+    "type": "auto",
+    "packageManager": "auto",
+    "framework": "auto"
+  },
+  "assertions": []
+}

package/templates/common/.cctkignore

@@ -0,0 +1,22 @@
+# Blocks directories with heavy file counts that fill LLM context
+# Syntax: gitignore-spec | Use ! prefix to allow (e.g., !src/vendor)
+
+# JS/TS
+node_modules
+dist
+build
+.next
+.nuxt
+
+# Python
+__pycache__
+.venv
+venv
+
+# Go/PHP/Rust/Java
+vendor
+target
+
+# VCS & Coverage
+.git
+coverage

package/templates/common/.env.example

@@ -0,0 +1,39 @@
+# Claude Code - Global Environment Variables
+# Location: .claude/.env
+# Priority: LOWEST (overridden by skills/.env and skill-specific .env)
+# Scope: Project-wide configuration, global defaults
+# Setup: Copy to .claude/.env and configure
+
+# ============================================
+# Environment Variable Hierarchy
+# ============================================
+# Priority order (highest to lowest):
+# 1. process.env                    - Runtime environment (HIGHEST)
+# 2. .claude/skills/<skill>/.env    - Skill-specific overrides
+# 3. .claude/skills/.env            - Shared across all skills
+# 4. .claude/.env                   - Global defaults (this file, LOWEST)
+#
+# ============================================
+# Context7 API Configuration (optional)
+# ============================================
+# Get your API key from https://context7.com/dashboard/api-keys
+CONTEXT7_API_KEY=
+
+# ============================================
+# Gemini API Configuration (optional)
+# ============================================
+# Used for research, documentation search, and enhanced capabilities
+# Get your API key from https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+
+# ============================================
+# Development & CI/CD
+# ============================================
+# NODE_ENV=development
+# LOG_LEVEL=info
+
+# ============================================
+# Output settings
+# ============================================
+OUTPUT_FORMAT=json
+DEBUG=false

package/templates/common/.mcp.json.example

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

package/templates/common/metadata.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.0.1",
+  "name": "cctk",
+  "description": "A comprehensive CLI toolkit for boosting Claude Code to the insane level.",
+  "buildDate": "2026-01-05T04:24:39.330Z",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MacPawLabs/claude-code-toolkit.git"
+  },
+  "download": {
+    "lastDownloadedAt": null,
+    "downloadedBy": null,
+    "installCount": 0
+  }
+}

package/templates/common/settings.json

@@ -0,0 +1,79 @@
+{
+  "includeCoAuthoredBy": false,
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/statusline.cjs",
+    "padding": 0
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/session-init.cjs"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/subagent-init.cjs"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/dev-rules-reminder.cjs"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Glob|Grep|Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/scout-block.cjs"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/privacy-block.cjs"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/write-compact-marker.cjs"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/session-end.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/common/statusline.cjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+'use strict';
+
+const { stdin, env } = require('process');
+const { execSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+const { trackContext } = require('./hooks/lib/context-tracker.cjs');
+
+/**
+ * Safe command execution wrapper
+ * @param {string} cmd - command to execute
+ */
+function exec(cmd) {
+    try {
+        return execSync(cmd, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            windowsHide: true
+        }).trim();
+    } catch (err) {
+        return '';
+    }
+}
+
+/**
+ * Format epoch timestamp as HH:mm
+ * @param {number} epoch - epoch timestamp
+ */
+function formatTimeHM(epoch) {
+    try {
+        const date = new Date(epoch * 1000);
+        const hours = date.getHours().toString().padStart(2, '0');
+        const minutes = date.getMinutes().toString().padStart(2, '0');
+        return `${hours}:${minutes}`;
+    } catch (err) {
+        return '00:00';
+    }
+}
+
+/**
+ * Generate Unicode progress bar (horizontal rectangles)
+ * Uses smooth block characters for consistent rendering
+ *
+ * @param {number} percent - 0-100 percentage
+ * @param {number} width - bar width in characters (default 12)
+ * @returns {string} Unicode progress bar like ▰▰▰▰▰▱▱▱▱▱▱▱
+ */
+function progressBar(percent, width = 12) {
+    const clamped = Math.max(0, Math.min(100, percent));
+    const filled = Math.round(clamped * width / 100);
+    const empty = width - filled;
+    // ▰ (U+25B0) filled, ▱ (U+25B1) empty - smooth horizontal rectangles
+    return '▰'.repeat(filled) + '▱'.repeat(empty);
+}
+
+/**
+ * Get severity emoji based on percentage (no color codes)
+ *
+ * @param {number} percent - 0-100 percentage
+ * @returns {string} Emoji indicator
+ */
+function getSeverityEmoji(percent) {
+    if (percent >= 90) return '🔴';      // Critical
+    if (percent >= 70) return '🟡';      // Warning
+    return '🟢';                          // Healthy
+}
+
+/**
+ * Expand home directory to ~
+ * @param {string} filePath - file path to expand
+ */
+function expandHome(filePath) {
+    const homeDir = os.homedir();
+    if (filePath.startsWith(homeDir)) {
+        return filePath.replace(homeDir, '~');
+    }
+    return filePath;
+}
+
+/**
+ * Read stdin asynchronously
+ */
+async function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stdin.setEncoding('utf8');
+
+        stdin.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+
+        stdin.on('end', () => {
+            resolve(chunks.join(''));
+        });
+
+        stdin.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+
+/**
+ * Main function
+ */
+async function main() {
+    try {
+        const input = await readStdin();
+        if (!input.trim()) {
+            console.error('No input provided');
+            process.exit(1);
+        }
+
+        const data = JSON.parse(input);
+
+        let currentDir = 'unknown';
+        if (data.workspace?.current_dir) {
+            currentDir = data.workspace.current_dir;
+        } else if (data.cwd) {
+            currentDir = data.cwd;
+        }
+        currentDir = expandHome(currentDir);
+
+        const modelName = data.model?.display_name || 'Claude';
+        const modelVersion = data.model?.version && data.model.version !== 'null' ? data.model.version : '';
+
+        let gitBranch = '';
+        let gitUnstaged = 0;
+        const gitCheck = exec('git rev-parse --git-dir');
+        if (gitCheck) {
+            gitBranch = exec('git branch --show-current');
+            if (!gitBranch) {
+                gitBranch = exec('git rev-parse --short HEAD');
+            }
+            const unstagedOutput = exec('git diff --name-only');
+            if (unstagedOutput) {
+                gitUnstaged = unstagedOutput.split('\n').filter(line => line.trim()).length;
+            }
+        }
+
+        let sessionText = '';
+        let costUSD = '';
+        let linesAdded = 0;
+        let linesRemoved = 0;
+        let contextPercent = 0;
+        let contextText = '';
+        const billingMode = env.CLAUDE_BILLING_MODE || 'api';
+
+        costUSD = data.cost?.total_cost_usd || '';
+        linesAdded = data.cost?.total_lines_added || 0;
+        linesRemoved = data.cost?.total_lines_removed || 0;
+
+        const contextInput = data.context_window?.total_input_tokens || 0;
+        const contextOutput = data.context_window?.total_output_tokens || 0;
+        const contextSize = data.context_window?.context_window_size || 0;
+
+        if (contextSize > 0) {
+            const result = trackContext({
+                sessionId: data.session_id,
+                contextInput,
+                contextOutput,
+                contextWindowSize: contextSize
+            });
+
+            contextPercent = result.percentage;
+
+            if (result.showCompactIndicator) {
+                contextText = `🔄 ▱▱▱▱▱▱▱▱▱▱▱▱`;
+            } else {
+                const emoji = getSeverityEmoji(contextPercent);
+                const bar = progressBar(contextPercent, 12);
+                contextText = `${emoji} ${bar} ${contextPercent}%`;
+            }
+        }
+
+        const transcriptPath = data.transcript_path;
+
+        if (transcriptPath) {
+            try {
+                if (fs.existsSync(transcriptPath)) {
+                    const content = fs.readFileSync(transcriptPath, 'utf8');
+                    const lines = content.split('\n').filter(l => l.trim());
+
+                    let firstApiCall = null;
+                    for (const line of lines) {
+                        try {
+                            const entry = JSON.parse(line);
+                            if (entry.usage && entry.timestamp) {
+                                firstApiCall = entry.timestamp;
+                                break;
+                            }
+                        } catch (e) {
+                            continue;
+                        }
+                    }
+
+                    if (firstApiCall) {
+                        const now = new Date();
+                        const currentUtcHour = now.getUTCHours();
+                        const blockStart = Math.floor(currentUtcHour / 5) * 5;
+                        let blockEnd = blockStart + 5;
+
+                        let blockEndDate = new Date(now);
+                        if (blockEnd >= 24) {
+                            blockEnd -= 24;
+                            blockEndDate.setUTCDate(blockEndDate.getUTCDate() + 1);
+                        }
+                        blockEndDate.setUTCHours(blockEnd, 0, 0, 0);
+
+                        const nowSec = Math.floor(Date.now() / 1000);
+                        const blockEndSec = Math.floor(blockEndDate.getTime() / 1000);
+                        const remaining = blockEndSec - nowSec;
+
+                        if (remaining > 0 && remaining < 18000) {
+                            const rh = Math.floor(remaining / 3600);
+                            const rm = Math.floor((remaining % 3600) / 60);
+                            const blockEndLocal = formatTimeHM(blockEndSec);
+                            sessionText = `${rh}h ${rm}m until reset at ${blockEndLocal}`;
+                        }
+                    }
+                }
+            } catch (err) {
+                // Silent fail - transcript not readable
+            }
+        }
+
+        let output = '';
+
+        output += `📁 ${currentDir}`;
+
+        if (gitBranch) {
+            output += `  🌿 ${gitBranch}`;
+            if (gitUnstaged > 0) {
+                output += ` (${gitUnstaged})`;
+            }
+        }
+
+        output += `  🤖 ${modelName}`;
+
+        if (modelVersion) {
+            output += ` ${modelVersion}`;
+        }
+
+        if (sessionText) {
+            output += `  ⌛ ${sessionText}`;
+        }
+
+        if (billingMode === 'api' && costUSD && /^\d+(\.\d+)?$/.test(costUSD.toString())) {
+            const costUSDNum = parseFloat(costUSD);
+            output += `  💵 $${costUSDNum.toFixed(4)}`;
+        }
+
+        if ((linesAdded > 0 || linesRemoved > 0)) {
+            output += `  📝 +${linesAdded} -${linesRemoved}`;
+        }
+
+        if (contextText) {
+            output += `  ${contextText}`;
+        }
+
+        console.log(output);
+    } catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+}
+
+main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/templates/config/.repomixignore

@@ -0,0 +1,22 @@
+docs/*
+plans/*
+assets/*
+dist/*
+coverage/*
+build/*
+ios/*
+android/*
+tests/*
+__tests__/*
+__pycache__/*
+node_modules/*
+
+.opencode/*
+.claude/*
+.serena/*
+.pnpm-store/*
+.github/*
+.dart_tool/*
+.idea/*
+.husky/*
+.venv/*

package/templates/config/AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+This file provides guidance to OpenCode when working with code in this repository.
+
+## Role & Responsibilities
+
+Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards.
+
+## Workflows
+
+- Primary workflow: `./.claude/rules/primary-workflow.md`
+- Development rules: `./.claude/rules/development-rules.md`
+- Orchestration protocols: `./.claude/rules/orchestration-protocol.md`
+- Documentation management: `./.claude/rules/documentation-management.md`
+- And other workflows: `./.claude/rules/*`
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** You must follow strictly the development rules in `./.claude/rules/development-rules.md` file.
+**IMPORTANT:** Before you plan or proceed any implementation, always read the `./README.md` file first to get context.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+## Development Principles
+
+- **YAGNI**: You Aren't Gonna Need It - avoid over-engineering
+- **KISS**: Keep It Simple, Stupid - prefer simple solutions
+- **DRY**: Don't Repeat Yourself - eliminate code duplication
+
+## Documentation
+
+Keep all important docs in `./docs` folder:
+
+```
+./docs
+├── project-overview-pdr.md
+├── code-standards.md
+├── codebase-summary.md
+├── design-guidelines.md
+└── system-architecture.md
+```
+
+## External Files
+
+Reference external instruction files in `opencode.json`:
+
+```json
+{
+  "instructions": ["docs/*.md", ".opencode/agents/*.md"]
+}
+```
+
+---
+
+*Generated by Claude Code Toolkit OpenCode Generator*
+*Date: 2026-01-11*

package/templates/config/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Role & Responsibilities
+
+Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards.
+
+## Workflows
+
+- Primary workflow: `./.claude/rules/primary-workflow.md`
+- Development rules: `./.claude/rules/development-rules.md`
+- Orchestration protocols: `./.claude/rules/orchestration-protocol.md`
+- Documentation management: `./.claude/rules/documentation-management.md`
+- And other workflows: `./.claude/rules/*`
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** You must follow strictly the development rules in `./.claude/rules/development-rules.md` file.
+**IMPORTANT:** Before you plan or proceed any implementation, always read the `./README.md` file first to get context.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+## Hook Response Protocol
+
+### Privacy Block Hook (`@@PRIVACY_PROMPT@@`)
+
+When a tool call is blocked by the privacy-block hook, the output contains a JSON marker between `@@PRIVACY_PROMPT_START@@` and `@@PRIVACY_PROMPT_END@@`. **You MUST use the `AskUserQuestion` tool** to get proper user approval.
+
+**Required Flow:**
+
+1. Parse the JSON from the hook output
+2. Use `AskUserQuestion` with the question data from the JSON
+3. Based on user's selection:
+   - **"Yes, approve access"** → Use `bash cat "filepath"` to read the file (bash is auto-approved)
+   - **"No, skip this file"** → Continue without accessing the file
+
+**Example AskUserQuestion call:**
+```json
+{
+  "questions": [{
+    "question": "I need to read \".env\" which may contain sensitive data. Do you approve?",
+    "header": "File Access",
+    "options": [
+      { "label": "Yes, approve access", "description": "Allow reading .env this time" },
+      { "label": "No, skip this file", "description": "Continue without accessing this file" }
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+**IMPORTANT:** Always ask the user via `AskUserQuestion` first. Never try to work around the privacy block without explicit user approval.
+
+## Python Scripts (Skills)
+
+When running Python scripts from `.claude/skills/`, use the venv Python interpreter:
+- **Linux/macOS:** `.claude/skills/.venv/bin/python3 scripts/xxx.py`
+
+This ensures packages installed by the CLI toolkit are available.
+
+**IMPORTANT:** When scripts of skills failed, don't stop, try to fix them directly.
+
+## [IMPORTANT] Consider Modularization
+- If a code file exceeds 200 lines of code, consider modularizing it
+- Check existing modules before creating new
+- Analyze logical separation boundaries (functions, classes, concerns)
+- Use kebab-case naming with long descriptive names, it's fine if the file name is long because this ensures file names are self-documenting for LLM tools (Grep, Glob, Search)
+- Write descriptive code comments
+- After modularization, continue with main task
+- When not to modularize: Markdown files, plain text files, bash scripts, configuration files, environment variables files, etc.
+
+## Documentation Management
+
+We keep all important docs in `./docs` folder and keep updating them, structure like below:
+
+```
+./docs
+├── project-overview-pdr.md
+├── code-standards.md
+├── codebase-summary.md
+├── design-guidelines.md
+├── deployment-guide.md
+├── system-architecture.md
+└── project-roadmap.md
+```
+
+**IMPORTANT:** *MUST READ* and *MUST COMPLY* all *INSTRUCTIONS* in project `./CLAUDE.md`, especially *WORKFLOWS* section is *CRITICALLY IMPORTANT*, this rule is *MANDATORY. NON-NEGOTIABLE. NO EXCEPTIONS. MUST REMEMBER AT ALL TIMES!!!*