CodexBar Memory Requirements: How Much RAM Does the Menu Bar App Need?

CodexBar typically consumes under 100 MB of RAM, often hovering between 30–50 MB, because it stores all runtime data in transient, in-memory caches that are automatically trimmed when macOS signals memory pressure.

CodexBar is a lightweight macOS menu bar utility developed in the steipete/CodexBar repository. Unlike traditional applications that persist large datasets to disk, CodexBar is engineered specifically to minimize memory requirements by keeping all state in bounded, ephemeral memory structures. This design ensures the app remains unobtrusive while running continuously in the background.

In-Memory Only Architecture

The application deliberately avoids persistent storage for its primary data structures, relying instead on volatile memory that clears on every launch.

UsageStore Design

All usage tracking and menu interaction timestamps live exclusively in memory. In Sources/CodexBar/UsageStore.swift, the store is explicitly documented as "In-memory only; resets on every launch" (line 267). This means the cache size is naturally bounded by the number of recent entries—typically a few dozen records—rather than growing indefinitely.

// Sources/CodexBar/UsageStore.swift
extension UsageStore {
    /// Called whenever the menu is opened; records the timestamp in a simple in‑memory variable.
    func noteMenuOpened(at date: Date = .now) {
        self.lastMenuOpenAt = date          // `lastMenuOpenAt` lives only in memory.
    }
}

Transient Credential Caching

Authentication data follows the same volatile pattern. OAuth tokens are cached in memory for a limited period—defaulting to 30 minutes—before automatic expiration. As implemented in Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift (line 92), the credentials use an "In-memory cache (nonisolated for synchronous access)" that prevents long-term memory accumulation.

Automatic Memory Pressure Handling

CodexBar actively monitors system resources and self-regulates its footprint when macOS reports memory constraints.

MemoryPressureMonitor Implementation

The MemoryPressureMonitor class in Sources/CodexBar/MemoryPressureMonitor.swift subscribes to system signals and triggers immediate cache trimming when pressure occurs. According to the source code at line 142, the monitor "Trimmed app caches for memory pressure" by invoking internal cleanup routines.

// Sources/CodexBar/MemoryPressureMonitor.swift
private func handlePressure(_ level: OSLogType) {
    logger.warning("System memory pressure", metadata: ["level": level])
    trimAppCaches()                       // Trims all in‑memory caches.
}

Bounded Data Parsing

To prevent memory spikes from external data, CodexBar enforces strict limits on incoming payloads. The Docs/custom-provider-design.md documentation specifies a "1 MiB cap; bounded depth and path length" (line 184) for JSON parsing. This ensures that even when fetching provider status or cost usage data, the application never allocates unbounded memory for temporary processing structures.

Typical Memory Footprint

Because of these architectural constraints, CodexBar maintains a minimal runtime profile:

• Baseline usage: 30–50 MB on fresh launch
• Maximum observed: Well under 100 MB
• Cache items: Limited to dozens of recent entries and 30-minute credential windows

These memory requirements make CodexBar suitable for any Mac capable of running macOS menu bar applications, including older hardware with limited RAM.

Summary

• CodexBar stores all data in memory only, with no disk persistence for caches or usage history, as enforced by UsageStore.
• Memory footprint stays under 100 MB, typically 30–50 MB, due to bounded caches and transient credential storage.
• Automatic trimming occurs via MemoryPressureMonitor when the OS signals memory pressure.
• JSON processing is capped at 1 MiB per payload to prevent memory spikes from external data sources.

Frequently Asked Questions

How much RAM does CodexBar need to run?

CodexBar requires minimal RAM, typically utilizing between 30–50 MB during normal operation and rarely exceeding 100 MB. The application is designed to run comfortably on any modern Mac with 8 GB of RAM or more, as well as older systems with limited memory.

Does CodexBar store data on disk or only in memory?

CodexBar stores runtime data exclusively in memory. According to the source code in Sources/CodexBar/UsageStore.swift, the architecture is "In-memory only; resets on every launch," meaning no persistent cache files are created on disk. OAuth credentials similarly expire from memory after 30 minutes.

What happens when macOS reports memory pressure?

When macOS signals memory pressure, the MemoryPressureMonitor automatically triggers trimAppCaches() to release all in-memory caches. This self-regulating behavior ensures CodexBar never competes with foreground applications for system resources.

Is there a limit on how much data CodexBar can load?

Yes. The application enforces a strict 1 MiB cap on JSON payloads as documented in Docs/custom-provider-design.md. This prevents the parsers from allocating excessive memory when processing provider status or cost usage data, keeping the memory footprint predictable regardless of external data size.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}