🔍 CodePulse CLI

🚀 Advanced Architectural Intelligence & Code Health Engine

Architectural Intelligence • Semantic Modeling • Real-time Monitoring • AI-Agentic Ready

CodePulse is a next-generation architectural health engine designed for large-scale JavaScript, TypeScript, Python, and mixed-language projects. It provides deep, systemic insights into code structure, dependency risks, and evolutionary trends, enabling teams and AI agents to maintain robust and maintainable codebases with surgical precision.

v5.2 Evolution: Featuring our new non-linear scoring model, 🛡️️ Confidence Metric, and Architectural Ghost Mode.

---

🌐 Multi-Language Support

English | Українська | Русский | Čeština | 한국어 | Deutsch | Français

📖 Full Documentation

English | Українська | Русский | Čeština | 한국어 | Deutsch | Français

---

⚡ Quick Start

Installation

npm install -g @archpulse/codepulse

First Scan

# Analyze your project and generate an HTML report
codepulse scan .

# Start the real-time TUI dashboard
codepulse watch .

---

🚀 Performance & Analysis Engines

CodePulse provides two distinct analysis paths optimized for different workflows. We build a comprehensive systemic model of your entire project, going far beyond standard file-based linting.

Fast Mode (Ultra-fast scanning)

Focus: Instant feedback on core structural health and basic issues.

Tool	Engine	Runtime (s)
ESLint	Baseline	~4.8s
CodePulse	Oxlint Engine	~2.8s

Extended Analysis Mode (Full Ecosystem Compatibility)

Focus: Deep architectural insights, complex dependency analysis, and full ESLint rule compatibility.

Tool	Engine	Runtime (s)
ESLint	Raw Baseline	~3.3s
CodePulse	ESLint + Systemic Analysis	~5.5s

Why the difference? In Extended Analysis Mode, CodePulse executes your project's full ESLint suite plus its own systemic analysis (dependency graph, circularity detection, architectural boundary checks, and historical churn). The result is a unified report that combines ecosystem-standard linting with deep structural intelligence.

---

🔍 Scan Modes & Engines

Engine Selection

# Auto-detect (Default)
# Uses ESLint if config is found, otherwise Oxlint
codepulse scan .

# Force ultra-fast mode (Oxlint-powered)
codepulse scan . --engine oxlint

# Force extended analysis mode (higher precision & compatibility)
codepulse scan . --engine eslint
# or
codepulse scan . --precision

Verbose / Debug Modes

# Show program-level issues only
codepulse scan . -d

# Linter debug mode (surfaces raw output from underlying tools)
codepulse scan . -ld

---

🏆 Core Features & Competitive Advantage

CodePulse is the only tool that seamlessly unifies AST static analysis, Git-based churn & coupling analytics, and native MCP integration for AI-agent workflows. Optimized for modern development environments, it answers 'how it was, how it is, and what to do next'.

Feature	Description
🏛️️ Architectural Radar	Define layers and catch boundary violations automatically
💡 Semantic Duplication	AST-based structural hashing finds identical logic, not just identical lines
🔄 Circular Dependency Breaker	Detect and visualize circular imports and dependency loops
⚡ Real-time Watch Mode	Interactive TUI dashboard that updates as you code
🚀 Parallel Pipeline	Core analysis, fast linters, and security checks run concurrently
📦 Smart Caching	Efficiently reuses results from unchanged files
🛠️️ Auto Linter Setup	Automatically installs required external linters for your project
🎨 Professional TUI/CLI	Rich colors, interactive visualizations, and clear feedback
🌐 7-Language Support	Full localization for global development teams
📄 License Management	Instantly generate and verify open-source licenses

---

📋 Command Reference

Primary Commands

Command	Description
codepulse scan [dir]	Full analysis + HTML report + status badge
codepulse watch [dir]	Interactive real-time TUI dashboard
codepulse verify [dir]	[GOD TIER] Deep verification: Build, Typecheck, and Tests
codepulse audit [dir]	[NEW] Comprehensive architectural audit and AUDIT.md generation
codepulse ghost <file>	[NEW] Predict the architectural "blast radius" of changes to a file
codepulse mcp	Start the Model Context Protocol (MCP) server for AI agents
codepulse setup-mcp	Generate MCP configuration and agent rule files
codepulse stats [dir]	Quick project statistics and health overview
codepulse explain [topic]	Detailed explanation and remediation advice for specific issues

Advanced Analytics

Command	Description
codepulse pr-risk [dir]	Evaluate architectural risk of Pull Request changes
codepulse coupling [dir]	Detect "Temporal Coupling" (files that change together)
codepulse health-trend	Visualize health score evolution over time
codepulse heatmap [dir]	Interactive TUI treemap of codebase risk zones
codepulse diff <branch>	Compare architectural health between branches
codepulse time-machine	Analyze dependency graph history and evolution
codepulse profile	Correlate runtime profiler data with code complexity
codepulse synth [dir]	Generate a synthetic stress test plan for your architecture

---

🏛️️ Architecture Governance

Enforce your project's structure and boundaries using .codepulse.json:

{
  "architecture": {
    "layers": [
      { 
        "name": "UI", 
        "pattern": "src/ui/.*", 
        "allowDependenciesFrom": ["Services", "Utils"] 
      },
      { 
        "name": "Services", 
        "pattern": "src/services/.*", 
        "allowDependenciesFrom": ["DB", "Utils"] 
      },
      { 
        "name": "DB", 
        "pattern": "src/db/.*", 
        "allowDependenciesFrom": ["Utils"] 
      }
    ],
    "strict": true
  }
}

---

🔌 Plugin System

Extend CodePulse with custom analysis rules tailored to your team's needs.

Creating a Plugin

Create a TypeScript/JavaScript plugin in your project's plugins/ directory:

import { Rule, AnalysisContext, Issue } from '@archpulse/codepulse';

export default class CustomQualityRule implements Rule {
  name = 'custom-quality-rule';
  description = 'Ensures team-specific standards are met';
  version = '1.0.0';
  category = 'code-quality';

  run(context: AnalysisContext): Issue[] {
    // Custom analysis logic
    return [];
  }
}

📘 Explore Plugin Development →

---

🤖 AI-Agent Integration (MCP)

CodePulse features a native Model Context Protocol (MCP) server, enabling AI assistants (Claude, Cursor, etc.) to perform expert-level architectural analysis.

Setup for AI Assistants

# Configure MCP and generate IDE-specific rules
codepulse setup-mcp

This command generates optimized rules for various IDEs and agents (.cursorrules, .clinerules, CLAUDE.md, etc.), instructing them to use CodePulse tools for deeper context.

Agent-Specific Tools (17+ Tools)

Tool	Description
codepulse_identity	Get project health score and identify critical "God Files"
get_file_context	Deep architectural dossier (coupling, risk, complexity) for a file
predict_change_impact	Predict the transitive blast radius of a symbol change
optimize_context	[NEW] Filter and identify minimal relevant files for a specific goal
find_similar_functions	AST-based structural duplication search across the project
suggest_split_strategy	Concrete decomposition and refactoring plan for large files
simulate_edit	Validate proposed code changes against architectural rules

---

🛠️️ CI/CD Integration

Automate architectural reviews in your GitHub workflows.

- name: CodePulse Review
  uses: archpulse/codepulse@v5
  with:
    command: 'review'
    github_token: ${{ secrets.GITHUB_TOKEN }}

CI Capabilities:

• Review: Post PR summaries and impact analysis directly to GitHub.
• Verify: Enforce build, typecheck, and test pass rates.
• Audit: Generate AUDIT.md artifacts for every build.

---

🚀 Visualizations

Interactive HTML Report	Temporal Coupling Analytics	Architectural Ghost Mode
Health Score Evolution	Interactive Risk Heatmap	Advanced TUI Dashboard

---

🌐 Localization

Full support for multiple languages:

# View help in French
codepulse --help --lang fr

# Scan in Ukrainian
codepulse scan . --lang ua

# Watch in German
codepulse watch . --lang de

Supported: English, Українська, Русский, Čeština, 한국어, Deutsch, Français

---

💻 System Requirements

• Node.js: 16.0.0+
• OS: Linux, macOS, Windows
• RAM: 512MB (1GB+ recommended for large projects)

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide to get started.

git clone https://github.com/archpulse/codepulse-cli.git
npm install
npm test
npm run dev -- scan .

---

📄 License

MIT License © 2024 ArchPulse

---

⭐ Love CodePulse? Give us a star on GitHub!

archpulse