Clueprint

Product Introduction

1. Definition: Clueprint is a native macOS menu bar application (SwiftUI) designed for developer environment monitoring and intelligent cleanup. It functions as a real-time system scanner and project manager for software development workflows, specifically tracking Git worktrees, Docker containers, local development servers, and AI agent sessions (like Anthropic's Claude Code and Codex).

2. Core Value Proposition: Clueprint exists to solve developer environment sprawl and resource waste. It provides live visibility into all active development artifacts—grouped by project and branch—and enables safe, verified cleanup of only those resources that are definitively idle or completed, thereby reclaiming system memory, CPU, and disk space without risking active work.

Main Features

1. Live System-Wide Monitoring Dashboard: Clueprint continuously scans and displays every development artifact on a macOS system. It groups Git worktrees under their parent projects, lists associated Docker Compose stacks (decoding wp-env hashed container names), and shows all running dev servers (Node.js, PHP, etc.) with their ports, PIDs, and real-time CPU/memory consumption. The dashboard updates dynamically, showing aggregate metrics like total running worktrees, system-wide CPU load attributed to development, and total memory used.

2. Intelligent, Verification-Based Cleanup: The app's cleanup mechanism is predicated on multi-layered verification. Before suggesting removal of any worktree or runtime, Clueprint checks a strict set of safety heuristics: the Git branch must be merged into its upstream (e.g., origin/main), have no uncommitted changes, have no unpushed commits, and show no Git or process activity for a configurable period (default 24 hours). Cleanup actions are re-verified against a fresh system scan before execution. It never deletes files; instead, it moves abandoned projects to an archive or stops runtimes (e.g., docker compose down with volumes kept).

3. Menu Bar Integration and Agent Session Awareness: As a native menu bar app, Clueprint provides glanceable metrics (like running process count or total memory usage) without opening a full window. A key technical differentiator is its integration with AI coding agents; it identifies and displays branches that still have an active Claude Code or Codex chat session attached, preventing the premature cleanup of in-progress AI-assisted work. It also facilitates "hand-off cleanup," allowing users to send a messy worktree's context back to the AI agent via CLI.

Problems Solved

1. Pain Point: Developers, especially those using AI coding agents and multi-repository workflows, accumulate "zombie" resources: forgotten Docker containers consuming gigabytes of RAM, abandoned Git worktrees occupying disk space, and local dev servers left running on random ports. This leads to system slowdowns, confusing port conflicts, and wasted time manually hunting down and cleaning these processes.

2. Target Audience: The primary user persona is the professional macOS-based software engineer or developer who frequently uses Git worktrees for parallel feature development, relies on Docker for local environments, and utilizes AI coding assistants like Claude Code. Secondary users include engineering managers who need visibility into team resource patterns and developers working on multiple microservices or client projects simultaneously.

3. Use Cases: Essential scenarios include: a) After an intensive coding session with an AI agent, quickly identifying and safely stopping all associated runtimes. b) Preparing for a demo or deployment by ensuring no stray processes are conflicting on needed ports (e.g., :5173 or :8080). c) Performing weekly "hygiene" to archive dozens of merged feature branches and their node_modules directories, freeing up tens of gigabytes of disk space. d) Diagnosing sudden MacBook fan spin-up by distinguishing between system/application load (e.g., Chrome, Xcode) and load from personal development environments.

Unique Advantages

1. Differentiation: Unlike generic system monitors (Activity Monitor) or manual CLI scripts, Clueprint semantically understands developer workflows. It connects low-level system processes (Docker, Node) to high-level project context (Git branch, AI session). Compared to other cleanup tools, its strict verification model and "archive, never delete" philosophy eliminate the risk of data loss, setting it apart from more aggressive uninstallers or disk cleaners.

2. Key Innovation: The core innovation is its contextual linking engine. It doesn't just list processes; it builds a real-time graph linking Git repositories, worktree directories, Docker container networks, listening ports, and AI agent session files. This allows it to present a unified "project view" and make intelligent, safe decisions about what constitutes "finished work" that can be cleaned. Its native SwiftUI implementation ensures high performance and low resource overhead compared to Electron-based alternatives.

Frequently Asked Questions (FAQ)

1. Is Clueprint safe? Does it delete my code? Clueprint is designed with safety as its core principle. It never directly deletes source code or Git worktrees. Its cleanup process involves multiple verifications (merged branch, no uncommitted changes, no activity) and for abandoned projects, it moves the entire directory to an archive location. For runtimes, it uses safe stop commands like docker compose down.

2. How does Clueprint detect AI agent sessions from Claude or Codex? Clueprint monitors the filesystem and process environment for artifacts and session files associated with Anthropic's Claude desktop applications. It identifies which project directories have active chat sessions linked to them, allowing it to flag those branches as "in-use" by an agent and exclude them from cleanup suggestions.

3. What is the performance impact of Clueprint running on my Mac? As a native SwiftUI application (not Electron), Clueprint is extremely lightweight, with the download under 5 MB. It performs periodic, efficient scans of the filesystem and process table. Its menu bar resident memory footprint is minimal, and scanning is optimized to avoid impacting system performance during active development work.

4. Can Clueprint clean up node_modules or Docker volumes? Clueprint's primary focus is on project and runtime lifecycle management. It can identify and list large directories like node_modules within its Disk view. However, its automated cleanup is centered on entire verified worktrees. For granular cleanup of dependencies or Docker volumes, it provides visibility but typically relies on moving the entire project archive, leaving manual cleanup of subdirectories as a user decision.

5. Does Clueprint work with other AI tools besides Claude? The current version is specifically optimized for workflows involving Anthropic's Claude Code and Codex, as these are highlighted as primary sources of environment sprawl. Its architecture for detecting agent sessions is tailored to these tools. While it monitors all development runtimes (Git, Docker, Node, etc.) universally, deep integration with other AI coding assistants would depend on future development.