terminal-graph
Advanced tools
Real-time ASCII line graphs for terminal - monitor memory, metrics, and data streams
Real-time ASCII line graphs for your terminal. Monitor memory usage, visualize data streams, and create beautiful terminal dashboards.
# Install globally
npm install -g terminal-graph
# Or use directly with npx (no installation needed)
npx terminal-graph demo
npx terminal-graph --help
# Clone the repository
git clone https://github.com/giovannymassuia/terminal-graph.git
cd terminal-graph
# Install dependencies
npm install
# Link globally for CLI usage
npm link
# Now you can use terminal-graph anywhere
terminal-graph --help
# Install directly from GitHub
npm install -g git+https://github.com/giovannymassuia/terminal-graph.git
# Run examples and tests
npm run demo # Run built-in demo
node examples/example-app.js # Run example app
./examples/monitor-example.sh # Complete monitoring demo
# Use conventional commits (for contributors)
npm run commit # Guided commit with proper formatting
terminal-graph/
├── src/ # Core implementation
│ ├── cli.js # Main CLI entry point
│ ├── heap-monitor.js # Memory monitoring class
│ ├── graph-viewer.js # Real-time graph viewer
│ ├── graph-renderer.js # ASCII rendering engine
│ ├── monitoring-setup.js # Drop-in monitoring helper
│ └── index.js # Main exports
├── examples/ # Example implementations
│ ├── example-app.js # Complete example Node.js app
│ ├── monitor-example.sh # Demo script
│ ├── compare-metrics.js # Metrics comparison tool
│ └── *.js # Various demos and tests
├── MONITORING-GUIDE.md # Comprehensive monitoring guide
└── README.md # This file
# Run the complete demo (recommended first experience)
./examples/monitor-example.sh
# Or run individual commands:
terminal-graph demo # Built-in demo
terminal-graph monitor # Monitor current process
terminal-graph view --style lean --accumulate # Terminal view with lean style
terminal-graph web --style area --accumulate # Web browser view (multi-metric capable)
terminal-graph monitor [options]Start monitoring heap memory usage.
terminal-graph monitor # Default: heap.log, 100ms interval
terminal-graph monitor app.log 200 # Custom file and interval
terminal-graph monitor --simulate # With simulated memory patterns
terminal-graph view [options]View real-time graph in terminal.
terminal-graph view # Default settings
terminal-graph view --style lean # Minimal colon style
terminal-graph view --accumulate # Keep all historical data
terminal-graph view -s blocks -a # Filled blocks with accumulation
terminal-graph web [options]View real-time graph in web browser with multiple view modes.
terminal-graph web # Default settings (opens browser)
terminal-graph web --style area # Area chart style
terminal-graph web --port 8080 # Custom port
terminal-graph web --no-open # Don't auto-open browser
Web View Modes:
terminal-graph demoRun an interactive demo with simulated data.
terminal-graph demo
file - Log file path (default: heap.log)interval - Sampling interval in ms (default: 100)--simulate - Add simulated memory activity--file, -f - Log file to monitor (default: heap.log)--metric, -m - Metric to display:
--style, -s - Graph style: blocks, lean, ascii, dots, braille--accumulate, -a - Accumulate all data instead of rolling window--points, -p - Maximum data points for rolling window (default: 100)--refresh, -r - Refresh rate in milliseconds (default: 100)--file, -f - Log file to monitor (default: heap.log)--metric, -m - Initial metric to display:
--style, -s - Graph style: line, area, bars--accumulate, -a - Accumulate all data instead of rolling window--points, -p - Maximum data points for rolling window (default: 100)--port - Server port (default: 3456)--no-open - Don't automatically open browserTerminal View:
R - Reload data from file (restart from beginning)C - Clear screen and reloadL - Loop through graph styles (blocks → lean → ascii → dots → braille)M - Toggle between Memory and CPU metricsQ - Quit the viewerCtrl+C - ExitWeb View:
Space - Pause/Resume updatesC - Clear dataL - Cycle through styles (line → area → bars)M - In Single view: Toggle between Memory/CPU metrics; In other views: Cycle view modes1-9 - Toggle metrics in Compare mode (1-5 for Memory, 6-9 for CPU metrics)R - Reload pageTerminal Styles:
Web Styles:
The web interface provides three distinct view modes for analyzing memory data:
Traditional single-metric focus with detailed statistics:
Grid layout showing all metrics simultaneously:
Memory Metrics:
CPU Metrics:
Each chart updates independently and can be viewed in line, area, or bar style.
Overlay multiple metrics on one chart for direct comparison:
M - In Single view: Toggle between Memory/CPU metrics; In other views: Cycle modes1-9 - In Compare mode: toggle individual metrics (1-5 for Memory, 6-9 for CPU)L - Cycle graph styles across all active chartsSpace - Pause/resume real-time updatesC - Clear all data and reset chartsR - Reload the pageSimply wrap any command with tgraph-monitor:
# Monitor any Node.js command
tgraph-monitor node app.js
tgraph-monitor npm run dev
tgraph-monitor pnpm dev
tgraph-monitor yarn start
tgraph-monitor npm test
# View in another terminal
terminal-graph view --file memory-monitor.log --accumulate --style lean
Environment Variables:
export TGRAPH_LOG_FILE=my-app-memory.log
export TGRAPH_INTERVAL=1000
export TGRAPH_METRIC=heapUsed
tgraph-monitor pnpm dev # Uses your settings
// At the top of your main app file
const MemoryMonitor = require('terminal-graph/src/monitoring-setup');
// Start monitoring (creates app-memory.log)
const monitor = MemoryMonitor.quickSetup('my-app-memory.log', 500);
// Your existing app code...
const express = require('express');
const app = express();
app.listen(3000, () => {
console.log('Server running on port 3000');
console.log('View memory graph with:');
console.log(' terminal-graph view --file my-app-memory.log --accumulate --style lean');
});
# Set environment variables
export AUTO_MEMORY_MONITOR=true
export MEMORY_LOG_FILE=my-app.log
export MEMORY_LOG_INTERVAL=1000
# Option A: Require in your app code
# Add this line anywhere in your app
require('terminal-graph/src/monitoring-setup');
# Option B: Preload when starting your app
node -r terminal-graph/src/monitoring-setup your-app.js
# View the graph
terminal-graph view --file my-app.log --accumulate --style lean
const { HeapMonitor } = require('terminal-graph');
const monitor = new HeapMonitor({
logFile: 'app-heap.log',
interval: 500 // 500ms interval
});
monitor.start();
// Your application code here...
| Metric | Y-Axis Shows | Best For | Example Values |
|---|---|---|---|
| heapUsed | MB (actual memory) | Memory leak detection | 0-500MB |
| heapPercent | Percentage (0-100%) | Heap utilization | 0-100% |
| heapTotal | MB (allocated heap) | V8 heap growth | 0-1000MB |
| rss | MB (total process memory) | System memory usage | 0-2000MB |
| external | MB (C++ objects) | Native memory usage | 0-100MB |
| Metric | Y-Axis Shows | Best For | Example Values |
|---|---|---|---|
| cpuPercent | % (0-100) | CPU usage monitoring | 0-100% |
| cpuUser | ms (cumulative) | User mode activity | Increases over time |
| cpuSystem | ms (cumulative) | System calls tracking | Increases over time |
| cpuTotal | ms (cumulative) | Total CPU time | Increases over time |
Recommended defaults:
--metric heapUsed (shows actual MB usage)--metric cpuPercent (shows utilization %) Node.js Heap Monitor - Heap Used (MB)
════════════════════════════════════════════════════════════════════════════════
180.0 │ :::
160.0 │ :: : ::
140.0 │ :: : ::
120.0 │ ::: : ::
100.0 │ ::: : ::
80.0 │ ::: : ::
60.0 │ ::: : ::
40.0 │ ::: :
20.0 │ ::: :
0.0 │ :::
└────────────────────────────────────────────────────────────────────────
12:34:20 12:34:50
Current: 168.45 MB | Average: 82.31 MB | Min: 15.20 MB | Max: 180.00 MB
Data points: 450 (compressed from 1200) | Refresh: 500ms | example-app-memory.log
[R] Reload [C] Clear [L] Style (blocks) [Q] Quit
✅ Healthy Patterns:
⚠️ Warning Patterns:
🚨 Problem Patterns:
# Long-term monitoring with log rotation
terminal-graph view --file app-memory.log --accumulate --refresh 2000 --points 500
# Mobile-friendly compact view
terminal-graph view --file app.log --style lean --points 50 --refresh 1000
The log file contains JSON lines with memory metrics:
{
"timestamp": 1234567890,
"heapUsed": "12.34",
"heapTotal": "56.78",
"heapPercent": "21.74",
"rss": "90.12",
"external": "1.23",
"cpuPercent": "15.25",
"cpuUser": "123.45",
"cpuSystem": "67.89",
"cpuTotal": "191.34"
}
tail package to follow log files as they're writtenThis project welcomes contributions! The project uses automated publishing with semantic versioning.
npm installnpm run commit (guided commit helper)This project uses Conventional Commits for automated releases:
# Use the commit helper (recommended)
npm run commit
# Or format manually:
feat: add new graph style
fix: resolve timestamp alignment issue
docs: update installation guide
perf: optimize rendering performance
Contributors can:
See PUBLISH.md for detailed publishing workflow.
MIT
Getting Started: Run ./examples/monitor-example.sh for the complete experience! 🚀
FAQs
Real-time ASCII line graphs for terminal - monitor memory, metrics, and data streams
We found that terminal-graph demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.