codebase-context-skill

codebase-context-skill

Context engineering middleware for Claude Code. Intelligent codebase indexing, token-efficient file selection, local tracking, testing, auditing, and session persistence — all via local MD files.

What It Does

This skill plugin sits between your queries and Claude Code. It ensures every interaction has precisely the right context — no wasted tokens exploring files that don't matter, no losing track of what was changed.

Before this skill: Claude Code explores your codebase from scratch on every query, reading files it doesn't need, losing context when the window fills up.

With this skill: Your codebase is indexed once, only relevant files are read per query, and everything is tracked in local MD files that persist across the session.

Installation

npx (recommended)

npx codebase-context-skill init

bun

bunx codebase-context-skill init

Global install

npm install -g codebase-context-skill
ccs init

Manual

git clone https://github.com/AnitChaudhry/codebase-context-skill.git
# Copy each skill as its own directory (Claude Code requires one level deep)
for d in codebase-context-skill/skills/*/; do
  name=$(basename "$d")
  cp -r "$d" ".claude/skills/ccs-$name/"
done
# Copy shared resources
cp -r codebase-context-skill/{agents,templates,references} .claude/skills/_ccs/
# Copy MCP config
cp codebase-context-skill/.mcp.json .mcp.json

Important: Skills must be at .claude/skills/<name>/SKILL.md (one level deep). Do NOT copy into .claude/skills/ccs/skills/ — Claude Code won't discover nested skills.

If you already have a .mcp.json, merge the ccs entry manually (see MCP Server Connection below).

Slash Commands

Naming: When installed via npx/CLI, commands use hyphens: /ccs-init, /ccs-build, etc. When installed as a Claude Code plugin (git clone with .claude-plugin/), the plugin namespace adds the prefix automatically: /ccs-init, /ccs-build, etc.

Context Management

Command	Description
/ccs-init	Deep-research the codebase, generate project-map, architecture, file-index, conventions
/ccs-status	Show what's indexed, staleness, file counts, token savings estimate
/ccs-refresh	Rebuild index (full, incremental, or session-based)
/ccs-query [question]	Preview which files would be selected for a given query

Workflow

Command	Description
/ccs-plan [task]	Plan a task with full dependency-aware context
/ccs-build [task]	Create/implement with tracked context and commit-style logging
/ccs-refactor [scope]	Scope a refactor — identify all affected files and dependencies
/ccs-fix [issue]	Fix bugs with dependency tracking, root-cause analysis, and verification
/ccs-team [task]	Spawn an agent team for complex multi-part tasks

Testing & Quality

Command	Description
/ccs-test [scope]	Run tests, track results locally, suggest and auto-fix failures
/ccs-audit [scope]	Audit code for security, performance, patterns, accessibility, dead code
/ccs-review [scope]	Code review with full context — style, logic, security, performance

Research & Docs

Command	Description
/ccs-research [query]	Search official docs, resolve errors, check deps, find best practices

Setup

Command	Description
/ccs-connect	Set up MCP server — creates/updates .mcp.json, configures endpoint, verifies connection

Git Workflow

Command	Description
/ccs-branch	Create/switch branches with auto-generated context reference files
/ccs-pr	Prepare PR with full context — title, summary, blast radius, review areas
/ccs-merge	Merge with dependency checking — conflict prediction, resolution context
/ccs-diff	Smart diff with impact analysis — dependency chains, blast radius, categorization
/ccs-sync	Pull/rebase/push with conflict context and resolution recommendations
/ccs-stash	Stash with tracked context — remembers what you were working on
/ccs-log	Smart commit history — groups by branch, cross-references with task.md

Operations

Command	Description
/ccs-deploy	Pre-deployment checklist — tests, build, env vars, dependencies, breaking changes
/ccs-track	View/manage session task log, see all changes made this session

MCP Server Connection

The plugin ships with a .mcp.json that configures the CCS remote MCP server automatically. When you install (via npx, manual clone, or /ccs-init), this config is created in your project root:

{
  "mcpServers": {
    "ccs": {
      "type": "http",
      "url": "https://skills.thinqmesh.com/api/mcp"
    }
  }
}

What this gives you: 6 MCP tools available to Claude Code — skill info, all 23 command docs, OS-specific install commands, model strategy, and context file details.

If you already have a .mcp.json with other MCP servers, run /ccs-connect — it merges the CCS entry safely without overwriting your existing servers.

To reconfigure or verify, run:

/ccs-connect

Alternative (global config):

claude mcp add --transport http ccs https://skills.thinqmesh.com/api/mcp

Note: All MCP config lives in the plugin's .mcp.json at your project root. To modify the endpoint or switch between remote/local, edit this file directly — do not modify ~/.claude/settings.json for project-level config.

How It Works

1. Initialization (/ccs-init)

Scans your entire codebase and generates local reference files in .ccs/:

• project-map.md — File tree + dependency graph (imports/exports/references)
• architecture.md — Tech stack, patterns, entry points, data flow
• file-index.md — Files ranked by importance (most-imported = highest rank)
• conventions.md — Coding style, naming patterns, test patterns

2. Per-Query Context (automatic)

When you ask Claude Code anything, the skill:

• Looks up the pre-built index for matching files/symbols
• Runs targeted Glob + Grep (zero API cost) to find candidates
• Follows import/dependency chains of matched files
• Claude Code reads ONLY the files that matter

3. Session Tracking

Every action is logged in .ccs/task.md with git-commit-style entries:

• Task description, files read/modified/created/deleted
• Dependencies identified, status, diff summary
• Persists context without consuming API tokens

Model Strategy

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

Generated Files

All context files are stored in .ccs/ (add to .gitignore):

.ccs/
├── project-map.md      # File structure + dependency graph
├── architecture.md     # Tech stack, patterns, data flow
├── file-index.md       # Files ranked by importance
├── conventions.md      # Coding style and patterns
├── task.md             # Session task log (commit-style)
└── preferences.json    # User preferences (refresh mode, etc.)

Index Refresh Modes

Set your preference on first init (saved in .ccs/preferences.json):

• On-demand — Run /ccs-refresh manually
• Incremental — Auto-detect changed files, re-index only those
• Session-based — Fresh index at the start of each session

License

MIT

Built by Anit Chaudhary — codebase-context-skill v2.0.0