CKB 8.1 is here, and it's focused on one thing: making refactoring less terrifying. Four new capabilities help your AI assistant understand not just what your code does, but how to safely change it.

What's New

Dependency Cycle Detection (`findCycles`)

Circular dependencies are one of those problems that slowly strangle a codebase. Module A imports B, B imports C, C imports A. Build times increase. Test isolation becomes impossible. Nobody wants to touch the cycle because they don't know which edge to cut.

findCycles uses Tarjan's strongly-connected-component algorithm to detect every circular dependency in your codebase. It works at three levels of granularity — module, directory, or file — and for each cycle it recommends which edge to break based on import strength.

User: "Are there any dependency cycles in the codebase?"

AI: [calls findCycles with granularity=directory]

"Found 3 dependency cycles:

1. internal/auth → internal/session → internal/auth (severity: low)
   Recommended break: session → auth (2 imports, break cost: 0.2)

2. pkg/api → pkg/models → pkg/validation → pkg/api (severity: medium)
   Recommended break: validation → api (1 import, break cost: 0.1)

3. internal/billing → internal/plans → internal/users →
   internal/permissions → internal/billing (severity: high)
   Recommended break: permissions → billing (3 imports, break cost: 0.15)

Summary: 1 high, 1 medium, 1 low severity."

The break-cost score (0 to 1) tells you how hard each edge is to remove. Lower means fewer imports to untangle. Start with the cheapest break in the highest-severity cycle.

Optimal usage tip: Run findCycles at directory granularity first — it's the most actionable level. File-level cycles are noisy, module-level cycles may be too coarse. If you find cycles, use prepareChange on the recommended break edge to see the full impact before refactoring.

Move/Relocate Analysis

prepareChange now supports a move change type. When you're relocating a file or symbol to a different package, CKB scans the entire repo for affected imports and checks the target location for naming conflicts.

User: "What happens if I move auth/middleware.go to http/middleware.go?"

AI: [calls prepareChange with changeType: "move", targetPath: "internal/http"]

"Move analysis for auth/middleware.go → internal/http/:

Affected imports: 14 files need updating
- internal/api/handlers/user.go (line 8)
- internal/api/handlers/admin.go (line 7)
- internal/api/handlers/webhook.go (line 9)
- ... 11 more files

Target conflicts: 1
- internal/http/middleware.go already exists (file conflict)

Package changes: 14
Risk: medium (many import updates, 1 conflict to resolve)"

With SCIP indexing available, import scanning is precise and complete. Without SCIP, CKB falls back to heuristic scanning that matches import patterns across Go, TypeScript, JavaScript, and Python files.

Optimal usage tip: Always check target conflicts before moving. If CKB reports a file conflict, you'll need to either rename the source file or merge with the existing target. Use planRefactor with changeType: "move" for a complete step-by-step plan including the import updates.

Extract Variable Flow Analysis

The extract change type in prepareChange now uses tree-sitter to analyze variable flow across the extraction boundary. Instead of guessing which variables become parameters and which become return values, CKB reads the AST and tells you.

User: "I want to extract lines 45-80 of processOrder into a separate function."

AI: [calls prepareChange with changeType: "extract"]

"Extract analysis for processOrder (internal/orders/processor.go):

Parameters (defined outside, used in extraction region):
- order Order (defined line 38, used 6 times)
- config *Config (defined line 12, used 3 times)

Returns (defined in region, used after):
- total float64 (defined line 52, used at line 85)
- err error (defined line 60, used at line 88)

Locals (defined and used only in region):
- discount float64 (defined line 55, used 2 times)
- taxRate float64 (defined line 58, used 1 time)

Suggested signature:
func calculateOrderTotal(order Order, config *Config) (float64, error)"

This works for Go, JavaScript/TypeScript, and Python. When CGO isn't available (rare in development, common in some CI environments), CKB gracefully degrades to boundary-only analysis.

Optimal usage tip: The suggested signature is a starting point — review the parameter types, since tree-sitter infers them from the AST rather than full type resolution. Pair this with planRefactor to get the complete extraction plan including test updates.

Proactive Refactoring Suggestions (`suggestRefactorings`)

Instead of waiting for you to ask "should I refactor this?", suggestRefactorings proactively scans your codebase and surfaces the highest-priority opportunities. It combines four existing analyzers in parallel:

Analyzer	What It Detects	Suggestion Types
Complexity	Functions with cyclomatic > 10 and > 50 lines, cognitive > 15	`extract_function`, `simplify_function`
Coupling	Files with co-change correlation > 0.7, > 10 dependents	`reduce_coupling`, `split_file`
Dead code	Unused exports and unreferenced symbols	`remove_dead_code`
Risk + test gaps	High-risk files without test coverage	`add_tests`

Each suggestion includes a severity (critical/high/medium/low), effort estimate (small/medium/large), and a priority score for ranking.

User: "What should I refactor in the billing module?"

AI: [calls suggestRefactorings with scope: "internal/billing"]

"Found 7 refactoring opportunities:

1. [critical] Extract parts of CalculateInvoice (cyclomatic: 34, 210 lines)
   Effort: large | Priority: 55
   Rationale: Cyclomatic complexity 34 exceeds threshold of 10

2. [high] Add tests for pricing.go (risk: high, score: 72)
   Effort: medium | Priority: 72
   Rationale: Risk score 72, no test file found

3. [high] Simplify ApplyDiscounts (cognitive complexity: 22)
   Effort: medium | Priority: 22
   Rationale: Deeply nested conditionals, hard to follow

4. [medium] Remove unused ExportLegacyFormat (dead code, 95% confidence)
   Effort: small | Priority: 95
   Rationale: No references found in codebase

5. [medium] Reduce coupling for invoice.go (4 highly coupled files)
   Effort: medium | Priority: 40
   Rationale: 4 files change together >70% of the time

... 2 more (low severity)"

Optimal usage tip: Use minSeverity: "medium" to cut noise. Filter by type if you're focused — types: ["extract_function", "simplify_function"] when you're doing complexity cleanup, types: ["remove_dead_code"] for a cleanup sprint. After identifying a target, feed it into prepareChange or planRefactor for the detailed impact analysis.

Unified Refactoring with `planRefactor`

All of these new capabilities feed into planRefactor, the compound tool introduced in 8.1 that ties everything together. It runs prepareChange, auditRisk, and analyzeTestGaps in parallel, then generates ordered refactoring steps.

User: "Plan the refactoring for moving UserService to a new package."

AI: [calls planRefactor with changeType: "move", targetPath: "internal/services/user"]

"Refactoring plan for UserService:

Risk Assessment: medium (score: 52)
- 8 risk factors analyzed
- Function complexity: handleAuth (cyclomatic: 18), validate (12)

Impact: 23 direct dependents, 41 transitive, 15 affected files

Test Strategy:
- 18 existing tests cover this code
- 2 test gaps found (highest risk: handleAuth)
- Coverage: 78%

Coupling: 5 co-change files (highest: user_repository.go)

Steps:
1. Verify target location — check for conflicts [low risk]
2. Move file/symbol — relocate to target [low risk]
3. Update imports — 23 dependent files [medium risk]
4. Run affected tests — verify nothing broke [low risk]"

Updated Presets: 92 Tools

CKB 8.1 brings the total to 92 MCP tools. The preset system has been updated to reflect this:

Preset	Tools	Tokens	What's New
core	21	~2k	`planRefactor` added
review	27	~3k	`scanSecrets` added
refactor	33	~4k	`findCycles`, `suggestRefactorings`, `analyzeTestGaps`, `planRefactor`
docs	27	~3k	—
ops	33	~4k	—
federation	34	~4k	—
full	92	~11k	All tools

The refactor preset is where most of the new action is. If you're planning a refactoring session, start your AI with:

ckb mcp --preset=refactor

For day-to-day work, the default core preset includes planRefactor so you always have access to unified refactoring planning without loading the full refactoring toolkit. Your AI can expand mid-session if it needs cycle detection or suggestions.

Putting It All Together: A Refactoring Workflow

Here's how to use 8.1's features together for a real refactoring session:

1. Survey the landscape

Ask your AI to scan for refactoring opportunities:

"Run suggestRefactorings on the api/ directory, medium severity and above"

This gives you a prioritized list of what deserves attention.

2. Check for structural problems

"Are there any dependency cycles involving the api/ package?"

findCycles reveals circular dependencies that might be causing the complexity issues surfaced in step 1.

3. Plan the specific refactoring

Pick the highest-priority suggestion and get a detailed plan:

"Plan the extraction of the validation logic from HandleRequest"

planRefactor gives you the risk assessment, impact analysis, test gaps, and ordered steps.

4. Check the move impact (if relocating)

"What happens if I move the extracted validator to internal/validation?"

prepareChange with move shows you every import that needs updating and any conflicts at the target.

5. Execute and verify

Make the changes, run the affected tests identified by CKB, and use the generated PR description to document the refactoring.

Upgrade

CKB 8.1 is backward compatible. Update and you're done:

npm update -g @tastehub/ckb

If you're using CKB via MCP, restart your AI assistant or run /clear to pick up the new tools.

Links: