Documentation

Installation

macOS / Linux

Windows

Manual (any OS)

Quick Start

1. Install the skill in your project (see above)
2. Run /ccs-init to index your codebase
3. Choose your refresh preference (on-demand, incremental, or session-based)
4. Start using any command — context is now available

Context Files

All generated context lives in .ccs/ at your project root. Add it to .gitignore.

• project-map.md — File tree + dependency graph showing which files import which
• architecture.md — Tech stack, patterns (MVC, hooks, etc.), entry points, data flow
• file-index.md — Every file ranked S/A/B/C/D by importance (import count)
• conventions.md — Detected coding style, naming patterns, test patterns, import style
• task.md — Session task log with git-commit-style entries
• preferences.json — Your refresh mode and settings

Preferences

On first /ccs-init, you'll be asked to choose a refresh mode. This is saved in .ccs/preferences.json.

• On-demand — Index is only refreshed when you run /ccs-refresh
• Incremental — Auto-detects changed files and re-indexes only those per query
• Session-based — Fresh index at the start of each Claude Code session

/ccs-init

Opus 4.6

Deep-research your entire codebase and generate context files in .ccs/. This is the foundation — run it once per project.

• Scans all source files (JS, TS, Python, Go, Rust, Java, etc.)
• Extracts imports/exports from file headers (first 50 lines)
• Builds a dependency graph and ranks files by centrality
• Detects architecture pattern, naming conventions, test framework
• Generates project-map, architecture, file-index, and conventions docs

/ccs-status

Haiku 4.5

Shows index health: what's indexed, staleness, file counts per rank, and estimated token savings.

/ccs-refresh

Haiku 4.5

Rebuilds the index. Supports three modes:

• /ccs-refresh full — Complete rebuild from scratch
• /ccs-refresh incremental — Only re-index changed files
• /ccs-refresh session — Incremental + archive old task.md

/ccs-query

Haiku 4.5

Preview which files would be selected for a query without executing anything. Shows file rankings, selection reasons, dependency chains, and estimated token cost.

• /ccs-query "add dark mode toggle"
• /ccs-query "fix login redirect bug"

/ccs-plan

Opus 4.6

Creates a full implementation plan before writing any code. Identifies files to read, modify, create, and delete. Includes dependency chains, test strategy, and risk assessment.

• /ccs-plan "add user authentication with JWT"
• /ccs-plan "migrate from REST to GraphQL"

/ccs-build

Sonnet 4.6

Implements a feature with full context tracking. Uses the plan (if available), reads only relevant files, follows project conventions, and logs every change in task.md.

• /ccs-build "implement JWT auth from plan"
• /ccs-build "add search component with debouncing"

/ccs-refactor

Opus 4.6

Analyzes the full blast radius of a refactor. Maps every file that imports, references, or depends on the target code. Creates an ordered execution plan.

• /ccs-refactor "rename UserService to AuthService"
• /ccs-refactor "extract shared validation logic"

/ccs-fix

Sonnet 4.6

Diagnoses and fixes bugs by tracing from symptom to root cause. Uses web search for library-specific errors. Verifies the fix with tests.

• /ccs-fix "Cannot read properties of undefined (reading 'map')"
• /ccs-fix "login redirect loops infinitely"

/ccs-test

Sonnet 4.6

Runs tests, diagnoses every failure, suggests fixes, and optionally auto-fixes. Can also write new tests for untested code.

• /ccs-test — Run all tests
• /ccs-test src/auth/ — Test specific directory
• /ccs-test --fix — Run and auto-fix failures
• /ccs-test --write src/utils.ts — Generate tests for a file
• /ccs-test --coverage — Run with coverage report

/ccs-audit

Opus 4.6

Systematic code audit across multiple dimensions. Produces severity-ranked findings with actionable fixes.

• /ccs-audit — Full audit (all dimensions)
• /ccs-audit security — Security vulnerabilities only
• /ccs-audit performance — Performance anti-patterns
• /ccs-audit patterns — Code consistency issues
• /ccs-audit a11y — Accessibility (UI codebases)
• /ccs-audit dead-code — Unused exports, unreachable code
• /ccs-audit deps — Dependency health, vulnerabilities, outdated packages

/ccs-review

Opus 4.6

Code review with full codebase context. Checks correctness, security, performance, convention adherence, maintainability, and test coverage.

• /ccs-review src/auth/login.ts — Review specific file
• /ccs-review staged — Review git staged changes
• /ccs-review changes — Review all uncommitted changes
• /ccs-review session — Review all files modified this session

/ccs-research

Opus 4.6

Web-powered research engine. Searches official docs, resolves errors, checks dependency compatibility, finds best practices. Results cached in task.md.

• /ccs-research "CORS policy blocked" — Error research
• /ccs-research react-query — Library docs lookup
• /ccs-research deps — Full dependency health check
• /ccs-research best-practices "error boundaries" — Best practices
• /ccs-research breaking-changes next.js — Migration guide

/ccs-deploy

Opus 4.6

Pre-deployment checklist verifying: tests pass, build succeeds, linting clean, types check, env vars documented, dependencies secure, no breaking changes, git clean.

/ccs-track

Haiku 4.5

View and manage the session task log.

• /ccs-track — Summary view (task counts, files touched, test results)
• /ccs-track detail — Full task log with all entries
• /ccs-track files — List only files touched this session
• /ccs-track stats — Session statistics
• /ccs-track export — Export session as standalone markdown
• /ccs-track clear — Archive and start fresh

/ccs-branch

Sonnet 4.6

Create or switch branches with auto-generated context files in .ccs/branches/. When creating, generates a branch reference. When switching, reads the ref first so Claude knows what the branch is about.

• /ccs-branch create feature-auth "Add authentication"
• /ccs-branch feature-auth
• /ccs-branch list

/ccs-pr

Opus 4.6

Prepare a PR with full context from branch reference. Generates title, summary, blast radius analysis, review area recommendations. Outputs ready-to-paste PR description.

• /ccs-pr main
• /ccs-pr --draft

/ccs-merge

Opus 4.6

Merge with dependency checking. Compares branch refs, identifies conflicting files, predicts conflicts, provides merge strategy recommendation.

• /ccs-merge feature-auth
• /ccs-merge feature-auth into develop

/ccs-diff

Opus 4.6

Smart diff with impact analysis. Goes beyond line changes to show dependency chains, blast radius, and change categorization (feature/fix/refactor).

• /ccs-diff feature-auth main
• /ccs-diff feature-auth

/ccs-sync

Sonnet 4.6

Pull, push, or rebase with conflict context. Reads branch refs to explain WHY conflicts occur and recommends resolution strategies.

• /ccs-sync pull
• /ccs-sync push
• /ccs-sync rebase main

/ccs-stash

Haiku 4.5

Stash and restore work-in-progress with tracked context. Logs what was being worked on so Claude remembers when unstashing.

• /ccs-stash save "working on auth"
• /ccs-stash pop
• /ccs-stash list

/ccs-log

Haiku 4.5

Smart commit history grouped by branch/feature, cross-referenced with task.md entries. More context than raw git log.

• /ccs-log
• /ccs-log feature-auth
• /ccs-log --all --since=7d

/ccs-connect

Sonnet 4.6

Sets up the MCP server connection for your project. Creates or updates .mcp.json with the CCS remote tools endpoint. Merges safely with any existing MCP servers you already have configured.

• /ccs-connect — Auto-detect, create/merge config, verify connection

This gives Claude Code access to 6 tools: skill info, command docs, install commands, model strategy, and context file details. Alternatively, use the CLI:

Hooks System

CCS ships with four Claude Code lifecycle hooks that automate session management. Hooks activate only in CCS-enabled projects (detected via a .ccs marker file).

Hook	Trigger	What It Does
session-orient	SessionStart	Injects workspace tree, goals, maintenance conditions, and previous session state at session start
write-validate	PostToolUse (Write)	Validates YAML frontmatter on notes — checks for required description, topics fields, and frontmatter block
auto-commit	PostToolUse (Write, async)	Auto-commits any staged changes to git after every write — no manual commits needed during work
session-capture	Stop	Saves session state JSON to ops/sessions/, commits goals and methodology artifacts before session ends

session-orient

Fires at session start. Outputs workspace structure, previous session context from ops/sessions/current.json, current goals, identity, and condition-based maintenance signals (e.g. orphan count, inbox pressure, stale methodology).

write-validate

Fires synchronously after every Write tool use. Reads the tool input JSON from stdin, extracts the file path, and validates notes in notes/ or thinking/ directories for required YAML frontmatter fields. Returns an additionalContext warning if fields are missing.

auto-commit

Fires asynchronously after every Write. Stages all changes (git add -A), builds a commit message from changed filenames and diff stats, and commits. Skips cleanly if not in a git repo or if there's nothing to commit.

session-capture

Fires on session end. Extracts the session ID from stdin JSON, writes a timestamped session record to ops/sessions/, and auto-commits session artifacts (sessions/, observations/, methodology/). Ensures no work is lost between sessions.

Session Rhythm

Every session follows three phases: Orient → Work → Persist. This prevents context loss and keeps system memory current.

• Orient — Read goals, check conditions, understand current state. Takes 1-2 minutes max.
• Work — One task per session. Discoveries become future tasks, not immediate tangents.
• Persist — Update goals, commit changes, log observations, leave a handoff note.

Context budget: ~20% orientation · ~60% actual work · ~20% persistence. If a task needs more than 60%, break it across sessions.

Handoff protocol: Every session end should answer three questions — what was accomplished, what's unfinished, and what the next session should do first.

Processing Pipeline

Every piece of content follows a four-phase pipeline. Capture and process are temporally separated because quality requires focused attention.

Phase	What Happens	Quality Gate
Capture	Zero friction — everything enters through inbox/. No structuring at capture time.	Speed over precision
Process	Extract atomic notes from source material. Apply selectivity gate — does this add genuine insight?	Title works as prose, description adds new info, claim is specific enough to disagree with
Connect	Forward connections to existing notes + backward pass updating older notes. Update topic maps.	Every connection articulates the relationship — not "related to" but "extends X because Y"
Verify	Cold-read test (description predicts content), schema compliance, health check (no orphans, no dangling links).	PASS / WARN / FAIL with immediate correction on FAIL

Pipeline state is tracked in ops/queue/queue.json. Each note gets one queue entry. Phase progression tracked via current_phase and completed_phases.

Graph Analysis

Your wiki-linked vault is a graph database — nodes are markdown files, edges are [[wiki links]], properties are YAML frontmatter. Query it with ripgrep.

Operation Type	Script	Purpose
Traversal	graph/n-hop-forward.sh, graph/recursive-backlinks.sh	Navigate N hops from any starting note
Synthesis	graph/find-triangles.sh, graph/topic-siblings.sh	Detect open triadic closures — synthesis opportunities
Structural	graph/find-clusters.sh, graph/find-bridges.sh	Detect isolated islands and bridge notes
Density	link-density.sh, orphan-notes.sh, dangling-links.sh	Health metrics — target 3+ links per note, 0 orphans
Centrality	graph/influence-flow.sh	Rank notes by hub/authority/synthesizer patterns

Maintenance

Health checks are condition-based, not time-based — triggered by actual state, not a calendar.

Condition	Threshold	Action
Orphan notes	Any detected	Surface for connection-finding (session priority)
Dangling links	Any detected	Surface for resolution (session priority)
Pending observations	≥10	Suggest review pass
Pending tensions	≥5	Suggest review pass
Topic map size	>40 notes	Suggest splitting into sub-topic maps
Inbox pressure	Items >3 days old	Suggest processing
Schema violations	Any detected	Surface for immediate correction

The reweaving practice revisits old notes and asks: "If I wrote this today, what would be different?" New notes may require updating older ones that predate them.

Self Evolution

The system grows from friction, not features. Complexity arrives at pain points, not before.

• Observations — Capture friction, surprises, and process gaps to ops/observations/
• Tensions — Capture contradictions and unresolved conflicts to ops/tensions/
• Methodology folder — ops/methodology/ is the canonical spec of how the system operates (Rule Zero)
• Changelog — Track what changed and why in ops/changelog.md

The lifecycle: Seed (minimal setup) → Evolve (add modules at friction points) → Reseed (reassess when accumulated complexity warrants it).

Model Strategy

Each command uses the optimal model for its task:

Model	Used For	Commands
Haiku 4.5	Lightweight scanning, lookups, status	status, refresh, query, track, stash, log
Sonnet 4.6	Standard coding execution	build, fix, test, branch, sync
Opus 4.6	Deep reasoning, architecture, analysis	init, plan, refactor, audit, review, research, deploy, pr, merge, diff

MCP Endpoint

The CCS remote MCP server runs on Vercel and exposes 6 tools to Claude Code. No local server needed.

Endpoint

Available Tools

Tool	Description
ccs-info	Skill overview, features, all install methods
ccs-commands	All 15 slash commands with descriptions and model assignments
ccs-command-help	Detailed usage for any specific command
ccs-install	OS-specific install command for any package manager
ccs-models	Model strategy — which Claude model handles which task
ccs-context-files	Info about generated .ccs/ context files

MCP Configuration

The plugin ships with a .mcp.json that configures the MCP server automatically. This file lives at your project root and is committed to git.

Project-level config (.mcp.json)

If you already have a .mcp.json with other MCP servers, /ccs-connect merges the ccs entry safely — your existing servers are never overwritten.

Config file locations

File	Scope	Use
.mcp.json	Project-level	Shared with team via git (recommended)
~/.claude/settings.json	Global	Applies to all projects for this user
.claude/settings.local.json	Project, user-specific	Permissions only — never commit

Verify connection

Developed by Anit Chaudhary