{"id":40376496,"url":"https://github.com/maximbilan/ramjet","last_synced_at":"2026-01-20T11:35:48.398Z","repository":{"id":331369013,"uuid":"1126299508","full_name":"maximbilan/ramjet","owner":"maximbilan","description":"A fast, lightweight CLI tool for macOS that reports system-wide RAM usage using Mach APIs","archived":false,"fork":false,"pushed_at":"2026-01-03T12:00:01.000Z","size":63,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-07T02:36:04.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximbilan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T15:56:23.000Z","updated_at":"2026-01-03T12:00:04.000Z","dependencies_parsed_at":"2026-01-07T21:00:11.854Z","dependency_job_id":null,"html_url":"https://github.com/maximbilan/ramjet","commit_stats":null,"previous_names":["maximbilan/ramjet"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/maximbilan/ramjet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Framjet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Framjet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Framjet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Framjet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximbilan","download_url":"https://codeload.github.com/maximbilan/ramjet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Framjet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28602507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T10:46:13.255Z","status":"ssl_error","status_checked_at":"2026-01-20T10:42:51.865Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T11:35:47.840Z","updated_at":"2026-01-20T11:35:48.389Z","avatar_url":"https://github.com/maximbilan.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ramjet\n\nA fast, lightweight CLI tool for macOS that reports system-wide RAM usage using Mach APIs.\n\n## Features\n\n- **Fast**: Single system query per run, minimal overhead\n- **Zero allocations**: Stack-only memory usage\n- **Native**: Direct Mach API integration for accurate statistics\n- **Clean output**: Human-readable memory values (MB/GB)\n- **Watch mode**: Continuous monitoring with configurable interval\n- **Interactive TUI**: Full-screen terminal interface with keyboard navigation\n- **Memory leak detection**: Automatically detect processes with growing memory usage\n- **Process listing**: Top memory-consuming processes with filtering and sorting\n- **Detailed breakdown**: Active, wired, inactive, speculative, compressed memory\n- **Color output**: Color-coded by usage level (green/yellow/red)\n- **JSON/CSV export**: Machine-readable formats for scripting and data analysis\n- **Swap statistics**: Swap usage information\n- **Memory pressure**: System memory pressure indicator\n- **Process filtering**: Filter processes by minimum memory usage\n- **Multiple sort modes**: Sort by memory, PID, or name\n- **Quiet mode**: Suppress non-essential output for scripting\n\n## Requirements\n\n- macOS (any version with Mach APIs)\n- Zig 0.15.2 or later\n\n## Building\n\n```bash\nzig build\n```\n\nThe binary will be created at `zig-out/bin/ramjet`.\n\n## Running\n\n```bash\n# Basic usage\n./zig-out/bin/ramjet\n\n# Watch mode (updates every 2 seconds)\n./zig-out/bin/ramjet --watch\n\n# Watch mode with custom interval (5 seconds)\n./zig-out/bin/ramjet --watch 5\n\n# Compact single-line output\n./zig-out/bin/ramjet --compact\n\n# Show top 10 processes by memory\n./zig-out/bin/ramjet --top 10\n\n# Show detailed memory breakdown\n./zig-out/bin/ramjet --breakdown\n\n# Disable colors\n./zig-out/bin/ramjet --no-color\n\n# Combine options\n./zig-out/bin/ramjet --watch 3 --top 5 --breakdown\n\n# Interactive TUI mode\n./zig-out/bin/ramjet --interactive\n\n# Interactive TUI with leak detection\n./zig-out/bin/ramjet --interactive --detect-leaks\n\n# Watch mode with leak detection\n./zig-out/bin/ramjet --watch --detect-leaks\n\n# JSON output (for scripting)\n./zig-out/bin/ramjet --json\n\n# Filter processes by minimum memory (50MB)\n./zig-out/bin/ramjet --top 20 --min-memory 52428800\n\n# Sort processes by name\n./zig-out/bin/ramjet --top 10 --sort name\n\n# Export to CSV\n./zig-out/bin/ramjet --export csv --top 5 \u003e processes.csv\n\n# Quiet mode (suppress non-essential output)\n./zig-out/bin/ramjet --quiet --json\n```\n\n## Command-Line Options\n\n- `-w, --watch [SECONDS]` - Watch mode (update every N seconds, default: 2)\n- `-c, --compact` - Compact single-line output format\n- `-i, --interactive` - Interactive TUI mode with keyboard controls\n- `--detect-leaks` - Detect memory leaks (requires watch or interactive mode)\n- `--top N` - Show top N processes by memory usage (1-100)\n- `--min-memory BYTES` - Filter processes with memory \u003e= BYTES (e.g., 52428800 for 50MB)\n- `--sort MODE` - Sort processes: `memory` (default), `pid`, or `name`\n- `-b, --breakdown` - Show detailed memory breakdown\n- `--json` - Output in JSON format\n- `--export FORMAT` - Export to JSON or CSV format (includes process data with `--top`)\n- `-q, --quiet` - Quiet mode (suppress non-essential output)\n- `--no-color` - Disable colored output\n- `-v, --version` - Show version information\n- `-h, --help` - Show help message\n\n## Output Examples\n\n### Standard Output\n```\nTotal:    24.0 GB\nUsed:     11.8 GB (49.1%)\nFree:     332.7 MB\nCached:   9.3 GB\nSwap:     0.0 MB / 0.0 MB\nPressure: Normal\n```\n\n### Compact Output\n```\n24.0G total, 11.8G used (49.1%), 332.7M free, 9.3G cached\n```\n\n### With Breakdown\n```\nTotal:    24.0 GB\nUsed:     11.8 GB (49.1%)\nFree:     332.7 MB\nCached:   9.3 GB\nSwap:     0.0 MB / 0.0 MB\nPressure: Normal\nMemory Breakdown:\n  Active:     9.3 GB\n  Wired:      2.5 GB\n  Inactive:   9.1 GB\n  Speculative: 179.8 MB\n  Compressed: 2.1 GB\n```\n\n### With Top Processes\n```\nTotal:    24.0 GB\nUsed:     11.8 GB (49.1%)\n...\nTop 5 Processes (showing 5 of 412):\n    1234  Chrome             2.1 GB\n    5678  Xcode              1.8 GB\n    9012  Slack              512.3 MB\n    3456  Terminal           128.5 MB\n    7890  Finder             64.2 MB\n```\n\n### With Filtering and Sorting\n```\nTotal:    24.0 GB\nUsed:     11.8 GB (49.1%)\n...\nTop 20 Processes (showing 20 of 42):\n    1234  Chrome             2.1 GB\n    5678  Xcode              1.8 GB\n    ...\n```\n(Filtered to show only processes using \u003e= 50MB, sorted by memory)\n\n### JSON Output\n```json\n{\n  \"total\": 25769803776,\n  \"used\": 12666736640,\n  \"free\": 357171200,\n  \"cached\": 10000000000,\n  \"usage_percent\": 49.15,\n  \"active\": 9000000000,\n  \"wired\": 3666736640,\n  \"inactive\": 8000000000,\n  \"speculative\": 2000000000,\n  \"compressed\": 500000000,\n  \"swap_used\": 0,\n  \"swap_total\": 0,\n  \"pressure\": \"Normal\"\n}\n```\n\n### JSON Export with Processes\n```bash\nramjet --export json --top 5\n```\n```json\n{\n  \"total\": 25769803776,\n  \"used\": 12666736640,\n  \"free\": 357171200,\n  \"cached\": 10000000000,\n  \"usage_percent\": 49.15,\n  \"active\": 9000000000,\n  \"wired\": 3666736640,\n  \"inactive\": 8000000000,\n  \"speculative\": 2000000000,\n  \"compressed\": 500000000,\n  \"swap_used\": 0,\n  \"swap_total\": 0,\n  \"pressure\": \"Normal\",\n  \"processes\": [\n    {\"pid\": 1234, \"name\": \"Chrome\", \"memory\": 2252341248},\n    {\"pid\": 5678, \"name\": \"Xcode\", \"memory\": 1932735283},\n    {\"pid\": 9012, \"name\": \"Slack\", \"memory\": 537182208},\n    {\"pid\": 3456, \"name\": \"Terminal\", \"memory\": 134742016},\n    {\"pid\": 7890, \"name\": \"Finder\", \"memory\": 67371008}\n  ]\n}\n```\n\n### CSV Export\n```bash\nramjet --export csv --top 5\n```\n```csv\ntotal,used,free,cached,usage_percent,active,wired,inactive,speculative,compressed,swap_used,swap_total,pressure\n25769803776,12666736640,357171200,10000000000,49.15,9000000000,3666736640,8000000000,2000000000,500000000,0,0,\"Normal\"\n\npid,name,memory\n1234,\"Chrome\",2252341248\n5678,\"Xcode\",1932735283\n9012,\"Slack\",537182208\n3456,\"Terminal\",134742016\n7890,\"Finder\",67371008\n```\n\n### Interactive TUI Mode\n\nThe interactive TUI provides a full-screen interface with real-time updates:\n\n```\nramjet - Memory Monitor\nTotal: 24.0 GB  Used: 12.1 GB (50.3%)  Free: 1.1 GB\nPressure: Normal\n\nProcesses (Sorted by: memory) - 20 shown\n------------------------------------------------------------\n\u003e    1234  Chrome                             2.1 GB\n     5678  Xcode                              1.8 GB\n     9012  Slack                             512.3 MB\n     ...\n\nControls: [↑↓] Navigate  [s] Sort  [l] Toggle Leaks  [r] Refresh  [q] Quit  [h] Help\n```\n\n**Keyboard Controls:**\n- `↑` / `↓` - Navigate up/down through process list\n- `s` - Cycle sort mode (memory → PID → name)\n- `l` - Toggle leak detection display\n- `r` - Refresh data\n- `q` - Quit\n- `h` - Help\n\n**Note**: Keys are detected immediately - no need to press Enter!\n\n### Memory Leak Detection\n\nWhen enabled with `--detect-leaks`, ramjet tracks process memory over time and alerts you to potential leaks:\n\n```\n⚠ Potential Memory Leaks:\n  1234 Chrome: 2.0 GB -\u003e 2.5 GB (+512.0 MB over 10s)\n  5678 Node: 128.0 MB -\u003e 256.0 MB (+128.0 MB over 8s)\n```\n\nA process is flagged as a potential leak if:\n- Memory growth \u003e 50MB, or\n- Memory growth \u003e 20% of original size\n\nLeak detection requires at least 2 snapshots, so it works best with `--watch` or `--interactive` mode.\n\n## How It Works\n\n- Uses `sysctlbyname(\"hw.memsize\")` to get total physical memory\n- Queries Mach APIs (`host_statistics64`) for detailed VM statistics\n- Converts page counts to bytes using system page size\n- Calculates used (active + wired), free, and cached (inactive + speculative) memory\n- Uses `proc_pidinfo` with `PROC_PIDTASKINFO` for process memory statistics (no special privileges required)\n- Uses `sysctlbyname(\"vm.memory_pressure\")` for memory pressure information\n\n## Color Coding\n\n- **Green**: Memory usage \u003c 50%\n- **Yellow**: Memory usage 50-80%\n- **Red**: Memory usage \u003e 80%\n\n## Interactive TUI Mode\n\nThe interactive TUI mode (`--interactive` or `-i`) provides a full-screen terminal interface with:\n\n- **Real-time updates**: Memory statistics and process list update automatically\n- **Keyboard navigation**: Navigate through processes with arrow keys\n- **Multiple sort modes**: Sort by memory usage, PID, or process name\n- **Visual selection**: Highlighted process indicator\n- **Scrollable list**: View up to 20 processes at a time with automatic scrolling\n- **Leak detection display**: Toggle leak warnings on/off with the 'l' key\n- **Immediate key response**: Keys are detected instantly without pressing Enter\n\nThe TUI automatically restores your terminal settings when you exit, so your terminal will return to normal operation.\n\n## Memory Leak Detection\n\nThe `--detect-leaks` option enables automatic detection of processes with growing memory usage. This feature:\n\n- **Tracks memory over time**: Maintains a history of process memory snapshots\n- **Detects significant growth**: Flags processes with \u003e50MB growth or \u003e20% increase\n- **Shows growth details**: Displays old size, new size, growth amount, and time span\n- **Works with watch/interactive modes**: Requires continuous monitoring to build history\n\n**Usage:**\n```bash\n# Watch mode with leak detection\nramjet --watch --detect-leaks\n\n# Interactive TUI with leak detection\nramjet --interactive --detect-leaks\n```\n\n## Process Listing\n\n### Filtering and Sorting\n\nYou can filter and sort processes using the following options:\n\n- **`--min-memory BYTES`**: Filter processes to show only those using at least the specified amount of memory. Useful for focusing on memory-intensive processes.\n  ```bash\n  # Show top 20 processes using at least 50MB\n  ramjet --top 20 --min-memory 52428800\n  ```\n\n- **`--sort MODE`**: Sort processes by different criteria:\n  - `memory` (default): Sort by memory usage (descending)\n  - `pid`: Sort by process ID (ascending)\n  - `name`: Sort alphabetically by process name\n  ```bash\n  # Show top 10 processes sorted by name\n  ramjet --top 10 --sort name\n  ```\n\nThe output will show \"Top N Processes (showing X of Y)\" when processes are filtered or when fewer processes are displayed than available.\n\n### Export Formats\n\nExport memory statistics and process data to structured formats:\n\n- **JSON Export**: `ramjet --export json --top 5 \u003e output.json`\n  - Includes full memory statistics and process list\n  - Machine-readable format for scripting and analysis\n\n- **CSV Export**: `ramjet --export csv --top 5 \u003e output.csv`\n  - Comma-separated values for spreadsheet applications\n  - Two sections: memory stats and process list\n\n### Quiet Mode\n\nUse `--quiet` or `-q` to suppress non-essential output, useful for scripting:\n```bash\n# Only output JSON, no other messages\nramjet --quiet --json \u003e stats.json\n```\n\n### Process Access\n\nNote: Process memory information requires appropriate permissions. Some system processes (like WindowServer, kernel_task) may not be accessible via `proc_pidinfo` without special privileges due to macOS security restrictions. These processes will not appear in the process list. Activity Monitor can show them because it runs with system entitlements. The tool will gracefully handle inaccessible processes and show all processes it can access.\n\n## Installation\n\n### Homebrew (Recommended)\n\nInstall via Homebrew:\n\n```bash\nbrew tap maximbilan/ramjet https://github.com/maximbilan/ramjet\nbrew install ramjet\n```\n\nOr install in one command:\n\n```bash\nbrew install maximbilan/ramjet/ramjet\n```\n\nAfter installation, you can use `ramjet` from anywhere:\n\n```bash\nramjet\nramjet --watch\nramjet --top 10\n```\n\n### Manual Installation\n\nBuild from source:\n\n```bash\ngit clone https://github.com/maximbilan/ramjet.git\ncd ramjet\nzig build\nsudo cp zig-out/bin/ramjet /usr/local/bin/\n```\n\nThen run from anywhere:\n\n```bash\nramjet\nramjet --watch\nramjet --top 10\n```\n\n## License\n\nSee [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Framjet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximbilan%2Framjet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Framjet/lists"}