🔍 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

🌐 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