CodePulse Documentation

The application operates on a three-layer mental model: Detection, Decision, and Delivery. It monitors file activity across configured workspace roots, resolves these signals to identify the active project and current work phase, and publishes the resulting state to both Discord and a dedicated local desktop interface.

This decoupled approach allows CodePulse to stay editor-agnostic. Whether you are working in VS Code, JetBrains, or a simple text editor, the utility provides a consistent presence layer based on the actual file system and git state of your project.

• Detection layer: Gathers local signals by watching file activity and runtime contexts.
• Decision layer: Resolves signals to pick the active project and derive an activity label.
• Delivery layer: Updates Discord Rich Presence and the local desktop UI with current state.
• Editor-agnostic: Operates independently of specific IDE or code editor plugins.

CodePulse derives human-readable activity labels, or "phases," using a layered heuristic approach. It first checks for git branch rules, mapping prefixes like `bugfix` or `feature` to specific work types. If no branch matches, it analyzes recent file paths to categorize the work.

This system allows the application to automatically distinguish between UI design (detecting .css or .tsx files), backend development (detecting API or service routes), and project documentation (detecting .md files), providing deep context to Discord friends and teammates.

• Branch Rules: Maps git branch names to phases (e.g., bugfix, refactor, testing).
• Path Rules: Maps directory and file extensions to categories (e.g., UI work, Backend).
• Fallback Logic: Defaults to "Editing [filename]" or a general "In Progress" label.
• Configurable templates for dynamic presence strings.

For users wanting more precise activity descriptions, CodePulse includes an optional AI labeling layer. This integration uses a privacy-aware context summary rather than raw file contents to generate refined activity labels that reflect the actual intent of the work.

The AI layer captures the project name, branch, and changed file groups, hashing this context to reuse cached labels and minimize API calls. A normalization step ensures returned labels are concise and adhere to safety rules before being published to Discord.

• Optional OpenAI integration (defaulting to gpt-5.4-mini).
• Privacy-aware: Sends sanitized context summaries, not raw code.
• Intelligent Caching: Uses SHA-1 context hashing to minimize throttled requests.
• Safety filtering to discard repetitive or invalid generated labels.

Instead of a headless service, CodePulse provides a compact desktop UI built with Electron. The main window features a frameless design with a live status view, displaying the active project, derived phase, session timer, and the connection status for both Discord and the AI service.

The utility is designed to stay out of the way, minimizing to the system tray for background operation. Users can access a tray menu to quickly check status, open the main window, or access settings for workspace and presence configuration.

• Frameless status window with live data updates.
• System tray integration for lightweight background operation.
• Persistent session timer showing elapsed time per project.
• Settings modal for workspace paths, templates, and AI configuration.

The runtime lifecycle is managed by an Electron shell that ensures a single-instance lock and handles configuration loading across multiple sources, including JSON settings and environment variables. On startup, the shell initializes the PresenceWatcherApp and begins publishing snapshots.

Discord communication is handled via Windows named pipes, allowing direct IPC with the local Discord client. The application manages the handshake, suppresses duplicate payloads, and includes automatic reconnection logic to ensure a stable presence throughout long coding sessions.

• Single-instance locking and unified configuration management.
• Direct Discord IPC via Windows named pipes (\\\\?\\pipe\\discord-ipc-0).
• Automatic session resetting based on project or Codex context shifts.
• Builds and publishes WatcherSnapshot payloads for UI and Presence layers.