Code Guardian Studio - Quickstart Guide

Get your first code analysis in under 3 minutes.

Prerequisites

Node.js 18+ installed
A code project you want to analyze

Installation & First Analysis

# 1. Install Code Guardian Studio globally
npm install -g codeguardian-studio

# 2. Navigate to your project
cd /path/to/your/project

# 3. Run quickstart
ccg quickstart

That's it! The quickstart command handles everything automatically.

What Happens During Quickstart?

When you run ccg quickstart, here's what happens behind the scenes:

1. Auto-Initialization & Migration (5 seconds)

Creates .ccg/ directory for configuration and data
Sets up hooks for Claude Code integration
Configures MCP server settings
Auto-migrates old configurations (if upgrading from previous version)
Validates configuration and auto-fixes common issues

2. Codebase Scan (~30 seconds)

Recursively scans your project files
Identifies source code files (excludes node_modules, dist, etc.)
Counts lines of code and file types

3. Metrics Analysis (~60 seconds)

Calculates complexity scores for each file
Measures nesting depth
Counts branching (if/switch statements)
Identifies TODO and FIXME comments

4. Hotspot Detection (~10 seconds)

Ranks files by complexity + size
Identifies files that need attention first
Suggests optimization goals (refactor, simplify, add tests, etc.)

5. Report Generation (~5 seconds)

Creates a local markdown report in docs/reports/ (gitignored by default)
Includes overview, hotspots table, and recommendations
Report is human-readable, not JSON
Reports are local to your machine and not committed to git

Total time: ~2 minutes for most projects (30k LOC or less)

Understanding Your Report

The generated report includes:

Overview Section

Files analyzed: Total source files scanned
Avg complexity: Average complexity score (lower is better)
Hotspots found: Files that need attention

Hotspots Table

Rank: Priority order (fix #1 first)
Score: Combined complexity + size score (0-100)
File: Path to the problematic file
Reason: Why it's flagged (e.g., "Very high complexity: 85, Deep nesting: level 8")
Goal: Suggested action (simplify, refactor, add-tests, split-module)

Recommendations

Step-by-step suggestions to improve code quality
Links to specific files and line numbers

Next Steps

After your first analysis:

Open the report:

# Report path is shown at the end of quickstart
# Example: docs/reports/optimization-2025-12-05-quickstart-123456.md

Start fixing hotspots (highest score first):
- Focus on files with score > 70 first
- Break down large functions
- Reduce nesting depth
- Extract complex logic into smaller functions
Run analysis again to track improvements:
```
ccg code-optimize --report
```
Compare before/after:
- Check if avg complexity decreased
- See how many hotspots you resolved

Example Output

⚡ CCG Quickstart - Get started in 3 minutes!

This will guide you through your first code analysis.

✓ CCG initialized

Starting Quick Analysis...

Scanning your codebase for optimization opportunities...

═════════════════════════════════════════════════

ANALYSIS COMPLETE

Files analyzed: 42
Avg complexity: 12.3
Hotspots found: 5

⚠  Top issues to address:

  1. src/services/payment-processor.ts
     simplify: Very high complexity: 78, Deep nesting: level 9

  2. src/utils/data-transformer.ts
     refactor: High complexity: 65, Large file: 450 lines

  3. src/api/user-controller.ts
     add-tests: No tests found, High complexity: 52

═════════════════════════════════════════════════

Generating detailed report...

✓ Report saved: docs/reports/optimization-2025-12-05-quickstart-1764901234567.md

NEXT STEPS:

  1. Open the report: docs/reports/optimization-2025-12-05-quickstart-1764901234567.md
  2. Start fixing hotspots (highest score first)
  3. Run analysis again to track improvement

Tip: Use ccg code-optimize --help for more options

Advanced Usage

Once you're comfortable with quickstart, explore more options:

Run Analysis with Custom Options

# Focus on complexity instead of size
ccg code-optimize --strategy complexity --report

# Scan more files (default: 1000)
ccg code-optimize --max-files 5000 --report

# Output as JSON for scripts
ccg code-optimize --json > analysis.json

See All Advanced Options

ccg code-optimize --help-advanced

CI/CD Integration

# Fail build if hotspots exceed threshold
ccg code-optimize --ci --threshold 70

Track Progress Over Time (Team Tier)

With a Team license, reports automatically track your progress:

# First analysis
ccg code-optimize --report

# ... make improvements ...

# Second analysis - shows before/after comparison!
ccg code-optimize --report

Team reports include:

Tech Debt Summary: Hotspot count/score deltas
Before vs After: Visual comparison between sessions
ROI Notes: Estimated time savings

To upgrade: ccg activate or visit codeguardian.studio/pricing

Common Questions

Where is my data stored?

Configuration: .ccg/config.json
Reports: docs/reports/ (local, gitignored by default)
Analysis cache: .ccg/optimizer-cache.json (optional)

Can I customize the analysis?

Yes! Edit .ccg/config.json after initialization. See User Guide for details.

Does it work offline?

Yes! Dev tier runs entirely locally with no cloud dependencies.

Team/Enterprise licenses cache validation for 24 hours, so you can work offline after initial verification.

What languages are supported?

JavaScript/TypeScript (best support)
Python, Java, Go, Rust, C/C++
Any language with recognizable syntax (basic metrics)

How do I use this with Claude Code?

After ccg quickstart, the MCP server is automatically configured. Just:

Start Claude Code: claude
CCG tools are available via MCP
Ask Claude to analyze your code

MCP Tools Examples

Once CCG is configured with Claude Code, you can use 113+ MCP tools directly. Here are practical examples:

Quick Analysis via Natural Language

The simplest way - use /ccg with natural language:

# In Claude Code conversation:
/ccg "analyze code"           # Quick codebase analysis
/ccg "run tests"              # Run test suite
/ccg "check memory"           # View stored memories
/ccg "validate src/app.ts"    # Validate specific file

Code Guard Examples

Validate code quality before committing:

// Claude will use guard_validate tool:
// "Please validate this code for issues"

// Example response:
// ✓ No fake tests detected
// ✓ No empty catch blocks
// ⚠ Warning: console.log found at line 42
// ✗ Error: Hardcoded secret detected at line 15

Common guard rules:

fake-test - Detects tests without assertions
empty-catch - Finds empty catch blocks
console-log - Warns about console.log in production code
hardcoded-secrets - Detects API keys and passwords
todo-fixme - Lists TODO/FIXME comments

Memory & Workflow Examples

Store important decisions:

"Remember: We decided to use JWT tokens for authentication because
it's stateless and works well with our microservices architecture"

CCG stores this in persistent memory with tags like [decision, auth, architecture].

Recall past decisions:

"What decisions did we make about authentication?"

CCG searches memory and returns relevant stored information.

Track tasks:

"Create task: Implement user login endpoint"
"Start working on the login task"
"Mark login task as complete"

Testing Examples

Run tests:

"Run the test suite"
"Run tests for src/auth/*.ts files"
"Run tests with coverage"

Browser testing:

"Open browser to http://localhost:3000"
"Take a screenshot of the current page"
"Check for console errors"
"Close the browser session"

Code Optimization Workflow

Full optimization workflow:

Step 1: "Scan the codebase for hotspots"
Step 2: "Show me the top 5 files that need refactoring"
Step 3: "Create a refactor plan for src/services/payment.ts"
Step 4: "Generate an optimization report"

Example hotspot output:

📊 Top Hotspots:

1. src/services/payment-processor.ts
   Score: 85 | Reason: Deep nesting (9), High complexity (78)
   Goal: simplify

2. src/utils/data-transformer.ts
   Score: 72 | Reason: Large file (450 LOC), Many branches
   Goal: split-module

3. src/api/order-controller.ts
   Score: 65 | Reason: Mixed concerns, No tests
   Goal: refactor + add-tests

Session Management Examples

Save progress before risky changes:

"Create a checkpoint before I refactor the auth module"

Resume after disconnect:

"Check if there's a previous session to resume"
"Resume from the last checkpoint"

View session history:

"Show me the session timeline"
"What tasks were completed today?"

Latent Chain for Complex Tasks

For multi-step tasks, use Latent Chain Mode:

"Start a latent context for the auth-refactor task"
"We're in analysis phase - identified these files need changes..."
"Transition to plan phase"
"Here's the implementation plan..."
"Transition to impl phase and apply these changes..."
"Transition to review phase"
"Mark auth-refactor as complete"

This preserves context across phases and enables better reasoning.

Troubleshooting

"No source files found"

Make sure you're in a project directory with code files
Check if your files are in excluded patterns (node_modules, dist, etc.)

"Command not found: ccg"

Run npm install -g codeguardian-studio again
Check that npm global bin is in your PATH

Analysis takes too long

Try reducing max-files: ccg code-optimize --max-files 500 --report
Exclude large directories in .ccg/config.json

Upgrading from Previous Versions

If you're upgrading from a previous version of CCG, the quickstart command handles migration automatically:

# Run quickstart - auto-detects and migrates old config
ccg quickstart
# → Found config v0.9.0, current is v1.3.0
# → Migrating configuration...
# → Migration complete!

Migration Paths Supported

From	To	Auto-Migrated
0.x	1.0.0	Module restructuring, new defaults
1.0.0	1.2.0	AutoAgent, Latent modules
1.2.0	1.3.0	Context profiles, Security STRIDE

Manual Configuration Check

# Validate configuration
ccg doctor

# Auto-fix configuration issues
ccg doctor --fix

After Refresh or Reconnect

If your browser refreshes or you get disconnected:

Check for resume offer - CCG will offer to restore your session
Resume if available - Restores tasks, progress, and context
Check nextToolCalls - If tasks were blocked, see suggested next actions
Continue where you left off - All timeline events are preserved

See Session Resume for details on recovery workflows.

Learn More

User Guide - Complete documentation
Latent Chain Guide - Advanced reasoning mode
Session Resume - Recovery after disconnects
Completion Gates - Task completion requirements
Code Guardian Website - Case studies and examples

Ready to optimize your codebase?

ccg quickstart

FilesExpand file tree

QUICKSTART.md

Latest commit

History