@thuanha-groove/gck
v0.0.5
Published
CLI tool for bootstrapping and updating ClaudeKit projects
Maintainers
Readme
ClaudeKit Config UI
Command-line tool and web dashboard for managing ClaudeKit projects.
Version: 1.17.0
Overview
ClaudeKit Config UI (gck) provides both CLI and web dashboard for managing ClaudeKit projects. It is built with Bun, TypeScript, and React for development, while the published CLI runs on plain Node.js so end users do not need Bun installed.
Key Features:
- CLI Commands (16): new, init, config, projects, setup, skills, agents, commands, migrate, doctor, versions, update, uninstall, watch, content, easter-egg
- Web Dashboard: Interactive React UI via
gck config uifor configuration and project management - Desktop App: The same dashboard as an installable macOS/Windows app, with every
gckcommand runnable from the UI (see Desktop App) - Hook Diagnostics Dashboard: Inspect recent Claude hook activity and failures from
gck configacross global and project scopes - Projects Registry: Centralized registry at
~/.claudekit/projects.jsonwith file locking - Skill Installation: Install ClaudeKit skills to other coding agents (Cursor, Codex, etc.)
- Multi-tier Authentication: gh CLI → env vars → keychain → prompt fallback
- Smart Merging: Conflict detection with user customization preservation
- Skills Migration: Auto-detects and migrates skills structure changes
- Offline Installation: From local archives or directories
- Security: Path traversal protection, symlink validation, UNC path protection
- Cross-Platform: macOS, Linux, Windows with platform-specific optimizations
- Update Notifications: Intelligent 7-day cache for version checks
Documentation
Comprehensive documentation in /docs:
- Codebase Summary - Overview, structure, key components
- Project Overview & PDR - Requirements, features, roadmap
- System Architecture - Architecture diagrams, data flow
- Reconciliation Architecture -
gck migrateRECONCILE → EXECUTE → REPORT design - Code Standards - Coding conventions, best practices
- Project Roadmap - Release timeline, feature status
- Deployment Guide - Release procedures
- Desktop App - Installable dashboard for macOS and Windows, update flow, shell development
- gck watch - GitHub issue monitoring daemon
- gck content - Automated content generation from git activity
Prerequisites
Before using ClaudeKit CLI, you need to:
- Purchase a ClaudeKit Starter Kit from ClaudeKit.cc
- Get Repository Access: After purchase, you'll receive access to the private GitHub repository containing your kit
- Create a GitHub Personal Access Token (PAT) with
reposcope to download releases
Without a purchased kit and repository access, the CLI will not be able to download any project templates.
Installation
The ClaudeKit CLI is published on npm at npmjs.com/package/gck.
End-user runtime note: global installs from npm, pnpm, yarn, or bun all execute the packaged Node.js CLI. Bun is optional for users and only needed for local ClaudeKit CLI development workflows. Most commands do not require native build tools; gck content uses an optional SQLite driver and shows remediation steps if that driver is unavailable.
Using npm (Recommended)
npm install -g gckUsing Bun
bun add -g gckUsing Yarn
yarn global add gckUsing pnpm
pnpm add -g gckAfter installation, verify it's working:
gck --versionDesktop App (no Node.js required)
Prefer a window over a terminal? Download GCK for macOS or Windows from
github.com/thuanha-groove/gck-release/releases/latest.
The app bundles the dashboard and the CLI, shares the same config files as a
terminal gck, and tells you when a new version is available. Builds are not
code-signed yet, so the first launch needs Open anyway on macOS or Run anyway
on Windows. Details in docs/desktop-app.md.
Usage
Discoverability Quick Start
# Top-level command discovery
gck --help
# Open config dashboard immediately
gck config
# Expose the dashboard intentionally to your LAN/Tailscale
gck config --host 0.0.0.0 --no-open
# Command-level help (recommended)
gck config --help
gck skills --help
gck agents --help
gck commands --help
gck migrate --helpConfig Dashboard Access
By default, gck config binds the dashboard to 127.0.0.1 for local-only access.
Use --host when you intentionally want remote access from another device on the same trusted network:
# Bind to all interfaces
gck config --host 0.0.0.0 --no-open
# Bind to a specific interface or hostname
gck config --host 100.88.12.4 --no-open
gck config --host dashboard.local --no-openThe dashboard still enforces same-origin browser access. Remote access works when you open the UI from the same host/origin that reaches the server, instead of relying on a hardcoded IP allowlist.
Create New Project
# Interactive mode
gck new
# With options
gck new --dir my-project --kit engineer
# Show beta versions
gck new --beta
# With exclude patterns
gck new --exclude "*.log" --exclude "temp/**"
# Optional packages (OpenCode, Gemini)
gck new --opencode --gemini
# Install skills dependencies (Python, Node packages, system tools)
gck new --install-skills
# Command prefix (/gck: namespace to avoid conflicts)
gck new --prefix
# Offline installation (from local archive or directory)
gck new --archive ~/downloads/engineer-v1.16.0.zip
gck new --kit-path ~/extracted-kit/
# Direct repo downloads are also supported
gck new --archive ~/downloads/claudekit-engineer-main.zip
gck new --kit-path ~/downloads/claudekit-engineer-main/Flags:
--install-skills: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages--prefix: Move commands to /gck: namespace (/plan → /gck:plan)--beta: Show pre-release versions in selection--opencode/--gemini: Install optional packages--archive <path>: Use local archive (zip/tar.gz) instead of downloading--kit-path <path>: Use local kit directory instead of downloading
--archive and --kit-path both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain claudekit-engineer-main/ or similar at the top level.
Initialize or Update Project
Note: Run from project root.
# Interactive mode
gck init
# Non-interactive mode with sensible defaults
gck init --yes
gck init -y
# Combine with other flags
gck init -g --kit engineer -y
# With options
gck init --kit engineer --beta
# Global mode (platform-specific paths)
gck init --global
# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
gck init --fresh
# With exclude patterns and prefix
gck init --exclude "*.local" --prefix
# Offline installation (from local archive or directory)
gck init --archive ~/downloads/engineer-v1.16.0.zip
gck init --kit-path ~/extracted-kit/
# Direct repo downloads are also supported
gck init --archive ~/downloads/claudekit-engineer-main.zip
gck init --kit-path ~/downloads/claudekit-engineer-main/Flags:
--yes/-y: Non-interactive mode with sensible defaults (skip all prompts)--global/-g: Use platform-specific config (macOS/Linux: ~/.claude, Windows: %USERPROFILE%.claude)--fresh: Clean reinstall, removes .claude directory (requires "yes" confirmation)--beta: Show pre-release versions--prefix: Apply /gck: namespace to commands--archive <path>: Use local archive (zip/tar.gz) instead of downloading--kit-path <path>: Use local kit directory instead of downloading
--archive and --kit-path both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain claudekit-engineer-main/ or similar at the top level.
Default Behavior with -y Flag:
| Prompt | Default |
|--------|---------|
| Select ClaudeKit | engineer (first option) |
| Target directory | Current directory (.) |
| Version selection | Latest stable release |
| Google Gemini setup | Skip |
| Other optional features | Skip |
Update CLI
Keep the ClaudeKit CLI up to date:
# Check for CLI updates
gck update --check
# Update to latest version
gck update
# Update to specific version
gck update --version 1.17.0
# Update to beta / skip confirmation
gck update --beta
gck update --yesThe CLI notifies you when updates are available via gck --version.
Skills Migration:
- Auto-detects structure changes (flat → categorized)
- Preserves customizations (SHA-256 hashing)
- Creates backup before migration
- Rollback on failure
List Available Versions
# Show all available versions for all kits
gck versions
# Filter by specific kit
gck versions --kit engineer
gck versions --kit marketing
# Show more versions (default: 30)
gck versions --limit 50
# Include prereleases and drafts
gck versions --allDiagnostics & Doctor
# Full health check (default)
gck doctor
# Verbose mode with execution timing and command details
gck doctor --verbose
# Generate shareable diagnostic report (prompts for gist upload)
gck doctor --report
# Auto-fix all fixable issues
gck doctor --fix
# CI mode: no prompts, exit 1 on failures
gck doctor --check-only
# Machine-readable JSON output
gck doctor --json
# Combine flags
gck doctor --verbose --check-only --json
gck doctor --verbose --fixHealth Checks:
- System: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
- ClaudeKit: Global/project installation, versions, skills, skill listing budget, duplicate skill inventory
- Auth: GitHub CLI authentication, repository access
- Project: package.json, node_modules, lock files
- Modules: Dynamic skill dependency resolution
Auto-Fix Capabilities:
| Issue | Fix Action |
|-------|------------|
| Missing dependencies | Install via package manager |
| Missing gh auth | Run gh auth login |
| Corrupted node_modules | Reinstall dependencies |
| Missing global install | Run gck init --global |
| Missing skill deps | Install in skill directory |
| Missing/low Engineer skill listing budget | Ensure computed skillListingBudgetFraction and a valid ClaudeKit-recommended skillListingMaxDescChars ceiling in project settings |
gck doctor never writes skillOverrides, hides skills, or deletes duplicate skills automatically. It reports existing skillOverrides and inventory issues so all active project/global skills can stay user-invocable while listing pressure is managed through 200k-context-floor project settings and bounded descriptions.
Exit Codes:
0: All checks pass or issues fixed1: Failures detected (only with--check-only)
Note:
gck diagnoseis deprecated. Usegck doctorinstead.
Uninstall
Remove ClaudeKit installations from your system:
gck uninstall # Interactive mode - prompts for scope and confirmation
gck uninstall --local # Uninstall only local installation (current project)
gck uninstall --global # Uninstall only global installation (~/.claude/)
gck uninstall -g --kit marketing # Remove only global Marketing kit
gck uninstall -l -y # Local only, skip confirmation
gck uninstall -g -y # Global only, skip confirmation
gck uninstall --yes # Non-interactive - skip confirmation (for scripts)Scope Selection:
- When both local and global installations exist, you'll be prompted to choose:
- Local only: Remove from current project (
.claude/) - Global only: Remove from user directory (
~/.claude/) - Both: Remove all ClaudeKit installations
- Local only: Remove from current project (
- When multiple kits are installed in the selected scope, interactive uninstall prompts for:
- Marketing kit only or Engineer kit only: Remove one kit and preserve the other
- All ClaudeKit kits: Remove the full selected installation scope
- Use
--localor--globalflags to skip the prompt - Use
--kit engineeror--kit marketingto skip the kit prompt
What it does:
- Detects local
.claudedirectory in current project - Detects global
~/.claudeClaudeKit installation - Shows paths before deletion
- Requires confirmation (unless
--yesflag) - Removes ClaudeKit subdirectories (
commands/,agents/,skills/,workflows/,hooks/,metadata.json) - Preserves user configs like
settings.json,settings.local.json, andCLAUDE.md
Note: Only removes valid ClaudeKit installations (with metadata.json). Regular .claude directories from Claude Desktop are not affected.
Watch GitHub Issues (gck watch)
Autonomous daemon that monitors GitHub issues, analyzes them with Claude, generates plans, and creates PRs.
# Start watching (single repo)
gck watch
# Dry-run mode (no posts/PRs)
gck watch --dry-run
# Custom poll interval (ms)
gck watch --interval 60000
# Force restart (clear state)
gck watch --force
# Verbose logging
gck watch --verboseFeatures: issue lifecycle management (10 statuses), Claude-powered brainstorming/planning, automatic PR creation, rate limiting (persisted across restarts), maintainer reply filtering, processedIssues TTL, optional git worktree isolation per issue, multi-repo support, graceful shutdown.
Config: .ck.json under watch key. See docs/ck-watch.md for full configuration reference.
Content Generation (gck content)
Daemon that scans git activity (commits, PRs, tags), generates social media content with Claude, and publishes to X/Twitter and Facebook.
# Interactive setup wizard
gck content setup
# Start daemon
gck content start
# Check status
gck content status
# View logs
gck content logs
# Queue manual content
gck content queue
# Review workflow
gck content approve <id>
gck content reject <id>
# Dry-run / verbose
gck content start --dry-run
gck content start --verboseFeatures: 11-phase pipeline (scan → filter → classify → context → create → validate → review → photo → publish → engage → analyze), noise filtering, context caching (24h TTL), content validation, photo generation, 3 review modes (auto/manual/hybrid), quiet hours scheduling, engagement tracking, SQLite database, platform-specific adapters.
Runtime dependency: gck content uses the optional native SQLite driver better-sqlite3. If the driver is unavailable, other CLI commands still work and gck content prints reinstall/build-tool guidance.
Config: .ck.json under content key. See docs/ck-content.md for full configuration reference.
Other Commands
# Show CLI version (shows local + global kit versions)
gck --version
# Show help
gck --help
gck -h
# Command-specific help
gck new --help
gck init --help
gck config --help
gck skills --help
gck versions --helpDebugging
gck new --verbose # Enable verbose logging
gck new --verbose --log-file debug.log # Save to file
CLAUDEKIT_VERBOSE=1 gck new # Via environment variableCache Configuration
Release data is cached locally to improve performance. You can configure the cache TTL:
# Set custom cache TTL (in seconds, default: 3600 = 1 hour)
CK_CACHE_TTL=7200 gck versions # Cache for 2 hours
CK_CACHE_TTL=0 gck versions # Disable caching (always fetch fresh)
# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
export CK_CACHE_TTL=1800 # 30 minutesCache Location: ~/.claudekit/cache/releases/
Update Notifications
The gck --version command checks for newer versions of your installed ClaudeKit and displays a notification if an update is available. The check is cached for 7 days to minimize API calls.
Disable Update Notifications:
# Set environment variable to disable
NO_UPDATE_NOTIFIER=1 gck --version
# Windows (permanent)
[System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User)
# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
export NO_UPDATE_NOTIFIER=1Cache Location: ~/.claudekit/cache/version-check.json (Windows: %USERPROFILE%\.claudekit\cache\)
Authentication
The CLI requires GitHub authentication to download releases from private repositories.
Authentication Flow
┌─────────────────────────────────────────────────┐
│ Multi-Tier Authentication │
│ │
│ 1. GitHub CLI (gh auth token) │
│ ↓ (if not available) │
│ 2. Environment Variables (GITHUB_TOKEN) │
│ ↓ (if not set) │
│ 3. Config File (~/.claudekit/config.json) │
│ ↓ (if not found) │
│ 4. OS Keychain (secure storage) │
│ ↓ (if not stored) │
│ 5. User Prompt (with save option) │
└─────────────────────────────────────────────────┘Quick Setup
Step 1: Install GitHub CLI
# Windows
winget install GitHub.cli
# macOS
brew install gh
# Linux
sudo apt install ghStep 2: Authenticate with GitHub CLI
gh auth loginWhen prompted, follow these steps:
- Select GitHub.com
- Select HTTPS (or SSH if preferred)
- Authenticate Git? → Yes
- Select Login with a web browser (⚠️ recommended)
- Copy the one-time code shown
- Press Enter to open browser and paste the code
- Authorize GitHub CLI
⚠️ Important: Select "Login with a web browser" - do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories.
Troubleshooting
Run the doctor command to diagnose issues:
# Interactive diagnostics
gck doctor
# Generate report for support
gck doctor --report
# CI/automation
gck doctor --check-only --json
# Verbose logging
gck new --verbose
gck init --verboseCommon Issues:
- "Access denied": Run
gck doctorto check auth, use--fixto auto-repair - "Authentication failed": Run
gck doctor --fixto re-authenticate, or manually rungh auth login(select 'Login with a web browser') - "GitHub CLI not authenticated": Run
gh auth loginand select 'Login with a web browser' (NOT 'Paste token') - Module errors: Run
gck doctor --fixto reinstall skill dependencies - Need help: Run
gck doctor --reportand share the gist URL
Available Kits
ClaudeKit offers premium starter kits available for purchase at ClaudeKit.cc:
- engineer: ClaudeKit Engineer - Engineering toolkit for building with Claude (v1.0.0+)
- marketing: ClaudeKit Marketing - Content automation toolkit (v1.0.0 available)
Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.
Configuration
Configuration is stored in ~/.claudekit/config.json:
{
"github": {
"token": "stored_in_keychain"
},
"defaults": {
"kit": "engineer",
"dir": "."
}
}Protected Files
The following file patterns are protected and will not be overwritten during updates:
.env,.env.local,.env.*.local*.key,*.pem,*.p12node_modules/**,.git/**dist/**,build/**
Excluding Files
Use --exclude flag with glob patterns to skip files:
gck new --exclude "*.log" --exclude "temp/**"
gck update --exclude "node_modules/**" --exclude "dist/**"Patterns: * (any chars), ** (recursive), ? (single char), [abc], {a,b}
Restrictions: No absolute paths, no path traversal (..), 1-500 chars
Note: User patterns are ADDED to default protected patterns
Custom .claude Files & Skills Migration
Custom File Preservation:
The CLI automatically preserves your custom .claude/ files during updates:
- Custom slash commands
- Personal workflows
- Project-specific configurations
- Any other custom files in
.claude/directory
Skills Directory Migration: Automatic migration when structure changes (flat → categorized):
- Detection: Manifest-based + heuristic fallback
- Customizations: SHA-256 hash comparison detects modifications
- Safety: Backup before migration, rollback on failure
- Preservation: All customizations preserved during migration
- Interactive: Prompts for confirmation (can skip in CI/CD)
Example Migration:
Before (flat):
.claude/skills/
├── gemini-vision/
├── postgresql-psql/
└── cloudflare-dns/
After (categorized):
.claude/skills/
├── ai-multimodal/
│ └── gemini-vision/
├── databases/
│ └── postgresql-psql/
└── devops/
└── cloudflare-dns/Customizations in any skill are detected and preserved automatically.
Development
See Development Guide for:
- Project structure (modular domain-driven architecture)
- Build & compilation (
bun run build,bun run compile) - Testing & type checking
- Code standards & linting
Architecture Highlights:
- Modular design: 122 focused modules (target: <100 lines each)
- Facade pattern: Each domain exposes public API via facade
- Phase handlers: Complex commands use orchestrator + phase handlers
- Self-documenting names: kebab-case file names describe purpose
Quick Start:
bun install
bun run dev new --kit engineer
bun test
# Optional: run expensive CLI integration tests explicitly
bun run test:integrationE2E Tests
Playwright E2E tests cover the gck migrate dashboard (3 scenarios). Tests run against the local dev server and use API mocking — no real filesystem state is modified.
Prerequisites: Node 18+ or Bun 1.0+, Chromium (installed automatically).
# One-time browser setup (if not already installed)
./node_modules/.bin/playwright install chromium
# Run all E2E specs
bun run test:e2e
# Interactive UI mode (watch + trace viewer)
bun run test:e2e:uiNote: The dev server starts automatically via bun run dashboard:dev. CI wiring is a separate follow-up (local-only for now).
FAQ
Q: Do I need GitHub CLI? A: Yes, GitHub CLI is required. ClaudeKit uses it exclusively for authentication with private repositories.
Q: How do I authenticate?
A: Run gh auth login, select 'Login with a web browser', complete OAuth in browser. Do NOT use 'Paste an authentication token'.
Q: "Access denied" error?
A: Accept GitHub repo invitation, re-run gh auth login with web browser login, wait 2-5min for permissions.
Q: "GitHub CLI not authenticated" error?
A: Run gh auth login and select 'Login with a web browser' (NOT 'Paste token'). PAT authentication is no longer supported.
Q: Is my token secure? A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.
License
MIT
