cosmotop: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cosmotop is a cross-platform system monitoring tool built as a single executable using Cosmopolitan Libc. It's a fork of btop++ that displays real-time system metrics (CPU, memory, disk, network, GPU, NPU) in a terminal interface. The project uses the Actually Portable Executable (APE) format to create binaries that run natively on multiple operating systems.

Build System and Commands

Core Build Commands

The project uses CMake with two distinct build targets that must be built separately:

# Build the multiplatform host executable (requires cosmocc toolchain)
export CC=cosmocc
export CXX=cosmoc++
cmake -B build-cosmotop -DTARGET=host
cmake --build build-cosmotop

# Build platform-native plugin binaries
cmake -B build-plugin -DTARGET=plugin
cmake --build build-plugin

Available Build Targets

• TARGET=host: Builds the multiplatform cosmotop.com executable using Cosmopolitan Libc
• TARGET=plugin: Builds platform-specific plugin executables/DLLs for system data collection

Testing and Validation

No automated test suite is present. Manual testing involves:

• Running the built executable on target platforms
• Verifying system metrics collection functionality
• Testing GPU/NPU detection and monitoring capabilities

Architecture Overview

Dual-Binary Architecture

The project uses a unique dual-binary architecture:

1. Host Executable (cosmotop.com): Multiplatform binary built with Cosmopolitan Libc that handles:

   • Terminal UI rendering and user interaction
   • Generic system metrics processing
   • Plugin management and communication
   • Configuration and theme management

2. Platform Plugins: Native executables/DLLs for each supported OS that handle:

   • OS-specific system data collection
   • Hardware-specific metrics (GPU, NPU, sensors)
   • Communication with host via plugin interface