Guide the user through setting up cc-track in their project. This is the primary entry point for new users after installing the plugin.
Guides users through initial cc-track plugin setup with feature selection and configuration.
/plugin marketplace add cahaseler/cc-track/plugin install cc-track@cc-track-marketplaceGuide the user through setting up cc-track in their project. This is the primary entry point for new users after installing the plugin.
Before proceeding with setup, verify:
Check if Bun is installed:
bun --version
If this fails:
powershell -c "irm bun.sh/install.ps1 | iex" or download from https://bun.shcurl -fsSL https://bun.sh/install | bash/setup-cc-track againCheck if plugin dependencies are installed by verifying these directories exist:
${CLAUDE_PLUGIN_ROOT}/node_modules/@anthropic-ai/claude-agent-sdk${CLAUDE_PLUGIN_ROOT}/node_modules/ccusageUse the file system to check existence (platform-independent).
If either directory doesn't exist:
cd ${CLAUDE_PLUGIN_ROOT}
bun install
/setup-cc-track again after installation completesCheck if the old npm version of cc-track is still installed:
which cc-trackwhere cc-track or Get-Command cc-trackIf this returns a path (meaning npm version is installed):
npm uninstall -g cc-track
/setup-cc-track againAll three checks must pass before proceeding with setup.
Once pre-checks pass, guide the user through:
Ask about their project:
.claude/ or .cc-track/ files? (migration vs new setup)Run git status to verify:
If uncommitted changes exist:
If not a git repo:
git initPresent feature options and let user choose what to enable:
Always Enabled (Core Functionality):
/cc-track:specify, /cc-track:plan, /cc-track:tasks workflow.cc-track/Optional Features:
Development Workflow:
edit_validation - Real-time TypeScript and lint checking on file edits
pre_tool_validation - Task file integrity checks before tool use
branch_protection - Prevent edits on protected branches (main/master)
/cc-track:plan or /cc-track:specify to create feature branches firstGit & GitHub Integration:
git_branching - Automatic feature branch creation from tasks
github_integration - Issue and PR automation
gh) installed and authenticatedauto_create_issues - Create GitHub issue for each task (recommended for teams)use_issue_branches - Use gh issue develop for issue-linked branchesauto_create_prs - Create PR on task completion rather than auto-mergegh is installed: gh --versionDisplay & Monitoring:
statusline - Custom status line with task, costs, API limits
api_timer - API rate limit timer display in statusline
"sonnet-only" (default) - Show timer only for Claude Sonnet (most common limit)"show" - Always show timer for all models"hide" - Never show timerCode Quality:
code_review - Automated code review integration
claude - Uses Claude Code SDK for fast, context-aware reviews (10min timeout)codex - Uses Codex CLI for systematic, thorough reviews (30min timeout)coderabbit - Uses CodeRabbit CLI to analyze code changes (30min timeout)Advanced:
autoflow - Autonomous operation mode for unattended task completion
throttle_limit - Max auto-continues before exit (default: 3)window_duration_minutes - Throttle detection window (default: 5)private_journal - Use private journal MCP for context preservation
websearch_validation - Validate WebSearch tool usage
Windows Only:
powershell_guidance - Windows compatibility hook with two functions:
Based on user selections, create .cc-track/track.config.json:
Read the template from ${CLAUDE_PLUGIN_ROOT}/templates/track.config.json and customize based on user's feature selections.
Example structure:
{
"hooks": {
"edit_validation": {
"enabled": true/false,
"typecheck": {
"enabled": true/false
},
"lint": {
"enabled": true/false
}
},
"pre_tool_validation": {
"enabled": true/false
},
"powershell_guidance": {
"enabled": true/false
},
"autoflow": {
"enabled": true/false,
"throttle_limit": 3,
"window_duration_minutes": 5
}
},
"features": {
"statusline": {
"enabled": true/false
},
"git_branching": {
"enabled": true/false
},
"private_journal": {
"enabled": true/false
},
"branch_protection": {
"enabled": true/false,
"protected_branches": ["main", "master"],
"allow_gitignored": true
},
"api_timer": {
"display": "hide"|"show"|"sonnet-only"
},
"github_integration": {
"enabled": true/false,
"auto_create_issues": true/false,
"use_issue_branches": true/false,
"auto_create_prs": true/false
},
"code_review": {
"enabled": true/false,
"tool": "claude"|"codex"|"coderabbit"
},
"websearch_validation": {
"enabled": true/false
}
},
"logging": {
"enabled": true,
"level": "info",
"retentionDays": 7
}
}
Set enabled flags based on user's choices from step 3.
CRITICAL: Only create files that don't already exist. Never overwrite existing files without explicit user permission.
First, create the .cc-track/ directory structure:
Use Claude Code's file system tools to create directories (platform-independent), or:
mkdir -p .cc-track/specsmkdir .cc-track\specs (creates parent directories automatically)Then create customized project files in .cc-track/ ONLY if they don't exist:
For each file:
${CLAUDE_PLUGIN_ROOT}/templates/.cc-track/ directoryFiles to create (read templates, customize, write):
CLAUDE.md (project root)
${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md.cc-track/)CLAUDE.md.cc-track/no_active_task.md
${CLAUDE_PLUGIN_ROOT}/templates/no_active_task.md.cc-track/no_active_task.md.cc-track/product_context.md
${CLAUDE_PLUGIN_ROOT}/templates/product_context.md.cc-track/product_context.md.cc-track/system_patterns.md
${CLAUDE_PLUGIN_ROOT}/templates/system_patterns.md.cc-track/system_patterns.md.cc-track/decision_log.md
${CLAUDE_PLUGIN_ROOT}/templates/decision_log.md.cc-track/decision_log.md.cc-track/code_index.md
${CLAUDE_PLUGIN_ROOT}/templates/code_index.md.cc-track/code_index.md.cc-track/user_context.md
${CLAUDE_PLUGIN_ROOT}/templates/user_context.md.cc-track/user_context.md.cc-track/backlog.md
${CLAUDE_PLUGIN_ROOT}/templates/backlog.md.cc-track/backlog.md.cc-track/progress_log.md
${CLAUDE_PLUGIN_ROOT}/templates/progress_log.md.cc-track/progress_log.mdAfter creating files, inform the user:
Based on enabled features, configure hooks in Claude Code settings.
Show user what hooks will be enabled:
edit_validation → PostToolUse hookpre_tool_validation → PreToolUse hookpowershell_guidance → PreToolUse hook (Windows only)Explain:
${CLAUDE_PLUGIN_ROOT}/hooks//config-track laterpowershell_guidance hook intercepts Bash/Edit/Write/Read tools to:
If the user enabled the statusline feature, configure it in the project-local .claude/settings.json file.
Create or update .claude/settings.json in the project root:
{
"statusLine": {
"type": "command",
"command": "bun run ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.ts",
"padding": 0
}
}
Use Claude Code's Write tool to create/update this file (platform-independent).
Inform the user:
Note: The statusline uses ${CLAUDE_PLUGIN_ROOT} which Claude Code expands automatically. This works cross-platform.
After setup completes:
Verify installation:
.cc-track/track.config.json existsNext steps guidance:
/cc-track:constitution to set up project guardrails and architectural constraints"/cc-track:specify \"your feature idea\""/config-track"GitHub setup (if enabled):
gh auth login"/cc-track:specify to create your first task with auto-issue creation"Use these pre-formatted messages for common issues:
⚠️ Bun runtime not found
cc-track plugin requires Bun runtime to execute TypeScript directly.
To install Bun:
**Windows (PowerShell):**
powershell -c "irm bun.sh/install.ps1 | iex"
**macOS/Linux:**
curl -fsSL https://bun.sh/install | bash
Or visit https://bun.sh for installation instructions.
After installing Bun, restart your terminal and try `/setup-cc-track` again.
⚠️ Plugin dependencies not installed
cc-track plugin dependencies are not installed. You need to run `bun install` in the plugin directory.
To install dependencies:
```bash
cd ${CLAUDE_PLUGIN_ROOT}
bun install
After installing, try /setup-cc-track again.
### npm/Plugin Conflict
⚠️ npm/plugin conflict detected
You have both the npm package and plugin versions of cc-track installed. This will cause conflicts. Please uninstall the npm version first.
To uninstall the npm version: npm uninstall -g cc-track
Verify removal:
After uninstalling, try /setup-cc-track again.
---
## Important Notes
- **Never run git commands without user permission** (except read-only like `git status`)
- **Never overwrite existing files without asking** (check existence first)
- **Always explain what each feature does** before enabling
- **Provide undo instructions** for any destructive actions
- **Be explicit about dependencies** (gh CLI, Bun, etc.)
- **Show next steps clearly** after successful setup
This is the user's first experience with cc-track - make it smooth and transparent! 🚅