CLAUDE.md — Universal ASCII / Terminal Dashboard Generator: guidance file for Claude Code to create beautiful, production-quality ASCII, ANSI, Unicode, and TUI dashboards from simple user objectives. Includes design system, composition rules, primitives, anti-patterns, library selection, and domain templates.

CLAUDE.md

CLAUDE.md

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

Project Mission

ascii-dashboards is a terminal UI dashboard generator library and toolkit.

Its mission is to create beautiful, useful, production-quality ASCII, ANSI, Unicode, and TUI dashboards from simple user objectives.

A user should be able to provide a minimal request such as:

Objective: Monitor my Kubernetes cluster.

or:

Objective: Create an AI coding agent activity dashboard.

or:

Objective: Build a terminal dashboard for SaaS revenue metrics.

The system should infer the domain, choose the right metrics, design the layout, generate a polished mockup, and provide implementation guidance or runnable code when requested.

Dashboards should feel intentional, readable, and impressive, like something from an ops room, observability platform, financial terminal, security operations center, AI agent console, UNIX system monitor, or cyberpunk command panel.

Core Product Promise

The user provides the objective. The generator provides the dashboard.

Do not require users to specify every metric, panel, library, or layout. Make intelligent assumptions, produce a strong first version, and allow refinement.

Default outputs may include:

• A concise dashboard concept
• A polished ASCII or Unicode mockup
• A recommended implementation approach
• Complete runnable code when requested
• Notes for replacing mock data with live data

Design Principles

Always prioritize in this order:

1. Clarity over decoration — the dashboard must communicate system state quickly.
2. Dense but readable — information-rich is good; cramped is bad.
3. Strong visual hierarchy — critical information must stand out first.
4. Consistent spacing and alignment — the layout should feel designed, not assembled.
5. Meaningful status visualization — colors, symbols, values, and labels should work together.
6. Terminal compatibility — support graceful fallback for plain ASCII environments.
7. Implementation realism — generated dashboards should be practical to build and maintain.

A great terminal dashboard should be useful before it is beautiful, and beautiful because it is useful.

Default Response Behavior

Unless the user requests a different format, respond with:

1. A concise dashboard concept
2. A polished ASCII or Unicode dashboard mockup
3. A recommended implementation stack
4. Data model and live-data adaptation notes

If the user asks for code, provide complete runnable code, not fragments.

If the user asks for only a mockup, output only the dashboard mockup with no explanation.

If the user asks for a reusable template, produce a reusable dashboard template.

If the user asks for a live dashboard, produce a refreshable implementation.

If the user gives no stack, default to Python + Rich.

Do not ask many questions up front. Make reasonable assumptions and generate something useful immediately. Ask a clarifying question only when the objective is impossible to infer.

Supported Dashboard Styles and Domains

Adapt the dashboard to the user's domain.

Common dashboard domains include:

• Infrastructure and Ops — servers, Kubernetes, Docker, cloud, home lab, resource usage
• Business and Finance — revenue, SaaS KPIs, trading, billing, growth, churn
• AI and Agents — coding agents, LLM telemetry, sessions, token usage, tool calls, cost
• Security — threats, alerts, auth failures, endpoint health, suspicious activity
• CI/CD — builds, tests, deployments, commits, environments, rollback readiness
• Weather — conditions, forecasts, maps, warnings, wind, precipitation
• Personal Productivity — goals, tasks, habits, focus, calendar, daily review
• Databases — query latency, locks, replication, cache hit rate, storage, slow queries
• Networks — throughput, latency, packet loss, interfaces, DNS, routes, topology
• IoT and Sensors — temperature, humidity, power, occupancy, device status

Common visual styles include:

• Retro ASCII ops dashboard
• Grafana-inspired terminal dashboard
• Cyberpunk command console
• Minimal UNIX status monitor
• Financial trading terminal
• Security operations center display
• AI agent telemetry console
• Weather terminal report
• Mainframe control panel
• Network operations center board

Choose the style that best fits the objective. Combine styles only when it improves the result.

Layout Intelligence Rules

Infer the layout from the user's objective.

Infrastructure Dashboards

Include health summary, CPU, memory, disk, network, latency, errors, deployments, logs, alerts, topology, uptime, and service status when relevant.

Business Dashboards

Include primary KPI, revenue, MRR or ARR, growth rate, churn, conversion, funnel, active users, cohorts, forecast, top accounts, failed payments, and recent events when relevant.

AI Agent Dashboards

Include active agents, sessions, tasks, tool calls, success rate, token usage, latency, errors, cost, code changes, changed files, command activity, and timeline when relevant.

Security Dashboards

Include threat summary, severity breakdown, blocked attempts, suspicious IPs, auth failures, endpoint status, incident timeline, detection rules, and escalation state when relevant.

CI/CD Dashboards

Include build status, test results, deployment progress, environments, commits, services, failures, flaky tests, rollback readiness, and release timeline when relevant.

Weather Dashboards

Include current conditions, forecast, precipitation, humidity, wind, visibility, sunrise/sunset, warnings, radar-like summaries, and ASCII weather icons when relevant.

Personal Dashboards

Include today's priorities, goals, habits, calendar, focus blocks, energy, tasks, streaks, notes, and progress when relevant.

Composition Rules

Every dashboard should have a clear visual structure.

Use this default composition unless the domain suggests something better:

Top band      → title, scope, timestamp, global status, key KPIs
Main area     → primary chart, topology, map, table, or operational view
Side rail     → alerts, active entities, ranked items, or current state
Bottom band   → logs, timeline, recent events, next actions, or diagnostics

Avoid giving every panel equal visual weight. One area should be dominant.

Use asymmetric layouts when they improve readability, such as a large chart on the left with a narrow alert rail on the right.

Use whitespace intentionally. Dense dashboards are good; cluttered dashboards are not.

Use repeated visual grammar: the same border style, label casing, status symbols, unit formatting, and panel spacing throughout the dashboard.

Place the most important information top-left or top-center.

Place noisy information such as logs near the bottom or in a side rail.

Place alerts where they are impossible to miss.

Use visual rhythm: large panel, small panel, table, chart, log. Avoid monotonous grids of identical boxes.

Default Dashboard Dimensions

Default target size:

120 columns × 40 rows

When writing code, make dashboards responsive where practical.

Responsive behavior:

Wide terminal   120+ columns  → full detail, multiple columns, charts, logs, side rail
Medium terminal 80-119 cols   → essential panels, fewer columns, compact tables
Narrow terminal <80 cols      → summary-first, stacked panels, minimal charts

If a static mockup is requested, target 120 columns unless the user provides dimensions.

Visual Components

Use the right component for the information.

Useful dashboard components include:

• KPI cards
• Boxed panels
• Nested sections
• Status badges
• Alert banners
• Tables
• Tree views
• Event logs
• Timelines
• ASCII maps
• Service topology diagrams
• Dependency graphs
• Sparklines
• Braille charts
• Block bar charts
• Gauges
• Progress bars
• Heatmaps
• Histograms
• Latency distributions
• Queue depth indicators
• Deployment progress views
• Calendar grids
• Leaderboards
• Process lists

Do not use decorative components unless they serve comprehension.

Character Sets

Unicode Default

Prefer Unicode when the user has not requested ASCII-only.

Box drawing:       ┌ ┐ └ ┘ ─ │ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯
Double borders:    ╔ ╗ ╚ ╝ ═ ║ ╠ ╣ ╦ ╩ ╬
Bars / Sparklines: █ ▇ ▆ ▅ ▄ ▃ ▂ ▁ ░ ▒ ▓
Arrows:            ↑ ↓ → ← ↗ ↘
Status symbols:    ● ○ ◆ ◇ ▲ ▼
Braille:           ⠁ ⠃ ⠇ ⡇ ⣿

ASCII Fallback

Use ASCII-only when the user requests maximum compatibility or when rendering environments are unknown.

Boxes:    + - | / \
Bars:     # = * .
Status:   OK WARN FAIL UP DOWN
Markers:  o x ! *
Arrows:   -> <- ^ v

ASCII dashboards should still look intentional and clean. Do not treat ASCII-only as a lower-quality mode.

Color Semantics

Use ANSI colors consistently:

Green    → healthy, success, passing, available, low risk
Yellow   → warning, latency, medium usage, pending
Red      → critical, failed, down, high risk
Blue     → info, network, neutral system metrics
Cyan     → active, selected, live, current state
Magenta  → special, AI, automation, experimental
Gray     → inactive, historical, disabled, metadata

Never rely only on color. Always include text, symbols, or numeric values:

● healthy
▲ warning
◆ degraded
✖ failed

In code, centralize color and status rules in a theme module.

Number and Unit Formatting

Use compact, readable values:

42ms     1.2s     98.7%
3.4GB    812MB/s  1.2M
$12.8k   4.7k req/min

Avoid fake precision unless the domain requires it. Always show units. Align numbers vertically in tables.

Use deltas when helpful:

MRR        $84.2k   ↑ 12.4%
Error Rate 0.18%   ↓ 0.07%
Latency    42ms    ↑ 6ms

Mock Data Rules

When users do not provide data:

• Create realistic mock data.
• Clearly label it as mock or sample data when appropriate.
• Use plausible values with variance and trends, not perfectly flat values.
• Make the data easy to replace with live data.

A static dashboard should still feel alive by including timestamps, recent events, trend lines, status changes, or refresh indicators.

Mockup Quality Rules

Static mockups must look plausible and production-grade. Avoid placeholder labels such as Metric 1, Data here, or Chart goes here. Every panel must have a purpose. Every chart should communicate a meaningful trend. Every alert should include severity and context.

A strong dashboard answers:

Is the system healthy?
What changed?
What needs attention?
What is the trend?
What should I inspect next?

Core Dashboard Primitives

Prefer building dashboards from reusable primitives:

Panel(title, content, status)
KPI(label, value, delta, status, sparkline)
Gauge(label, value, min, max, thresholds)
Sparkline(series, width, style)
Bar(label, value, max, width)
Table(columns, rows, alignments)
Timeline(events)
LogView(entries, severity)
Topology(nodes, edges, statuses)
Heatmap(matrix, labels)
AlertBanner(severity, message)
Progress(label, value, total, status)

When writing code, implement or reuse primitives rather than hardcoding every dashboard.

Data Architecture

Separate concerns in code:

Data collection      → fetch metrics, read APIs, query files, collect system stats
State transformation → aggregate, normalize, compute health, thresholds, deltas
Rendering            → panels, charts, tables, colors, layout
Refresh loop         → timing, live updates, graceful shutdown
Configuration        → thresholds, labels, sources, refresh intervals, theme

Recommended Project Architecture

src/ascii_dashboards/
  __init__.py
  cli.py

  core/
    layout.py        # grid, panels, responsive sizing
    render.py        # rendering helpers and dashboard assembly
    theme.py         # colors, symbols, borders, status styles
    data.py          # mock/live data adapters and schemas
    charts.py        # sparklines, bars, gauges, histograms
    primitives.py    # KPI, Panel, Table, Timeline, LogView

  templates/
    infra.py
    business.py
    agents.py
    security.py
    cicd.py
    weather.py
    personal.py

  collectors/
    system.py        # psutil/local metrics
    http.py          # API polling
    files.py         # JSON/CSV/log tailing

examples/
  homelab_dashboard.py
  agents_dashboard.py
  saas_metrics_dashboard.py
  security_dashboard.py

tests/
  test_layout.py
  test_charts.py
  test_theme.py
  test_primitives.py

Separate reusable rendering primitives from domain-specific dashboard templates.

Default Stack

When no language is specified, default to Python + Rich.

Python + Rich has low setup friction, excellent terminal rendering, good layout primitives, color support, live refresh, tables, panels, and progress bars.

Upgrade to Textual when the user needs full interactivity, keyboard navigation, mouse support, or complex stateful TUI behavior.

Use Go or Rust when the user explicitly wants a compiled binary, high performance, or ecosystem-specific deployment.

Commands

When the project scaffold exists:

pip install -e ".[dev]"
python examples/<dashboard_name>.py
pytest
ruff format .
ruff check .
mypy src

For single-file examples:

pip install rich psutil
python dashboard.py

If these commands are not implemented yet, create or update the project scaffold to support them.

Library Selection by Language

Python

• Rich — default for polished dashboards, tables, panels, progress bars, live refresh, and ANSI styling
• Textual — full interactive TUI applications with keyboard and mouse events
• Plotext — terminal-native charts when real plotting is needed
• psutil — local system metrics
• Blessed — lightweight terminal control
• curses — standard-library fallback for low-level terminal interfaces

Go

• Bubble Tea — TUI architecture and event handling
• Lip Gloss — styling and layout
• Termenv — terminal color capability detection

Node.js

• blessed / blessed-contrib — full terminal dashboard systems
• Ink — React-style CLI UIs
• cli-table3 — formatted tables
• chalk — color and styling
• ora — spinners and status feedback

Rust

• ratatui — modern TUI rendering (supersedes the archived tui-rs)
• crossterm — terminal events, input, and alternate screen control

Shell

• tput — terminal control in shell scripts
• awk — data formatting and transformation
• watch — simple refresh loops
• jq — JSON parsing
• curl — API data fetching

Implementation Standards

When generating code:

• Make it runnable with complete examples, not fragments.
• Include clear file names and install commands.
• Avoid hardcoded terminal dimensions; handle resize when reasonable.
• Isolate data collection from rendering.
• Use safe refresh intervals and avoid excessive CPU usage.
• Include mock data when live sources are not available.
• Keep the first implementation understandable before making it clever.

Preferred refresh intervals:

1-5 seconds      → active system metrics
10-30 seconds    → application metrics
30-300 seconds   → business metrics, weather, analytics

Workflow for User Requests

When a user provides an objective:

1. Infer the domain.
2. Identify the most important metrics.
3. Choose a visual style.
4. Choose a layout composition.
5. Generate a polished mockup.
6. Recommend an implementation stack.
7. Provide code when requested.
8. Explain how to connect live data when relevant.

Do not stall on missing details. Make reasonable assumptions. Deliver a strong first version.

Output Modes

Mockup     → static ASCII/Unicode dashboard visualization
Code       → complete runnable implementation
Template   → reusable dashboard structure
Live       → refreshable dashboard with real-time updates
Enhanced   → highly polished version with extra visual detail
ASCII      → strict ASCII-only version
Unicode    → Unicode-enhanced terminal dashboard
Library    → reusable package/module implementation

If the user uses words like "awesome," "beautiful," "pro," "elite," or "10/10," increase polish, visual hierarchy, density, and realism.

Dashboard Quality Checklist

Before finalizing a dashboard:

✓ Title is clear and descriptive
✓ Scope/context is visible
✓ Timestamp or refresh state is visible when relevant
✓ Most important KPIs appear top-left or top-center
✓ Reading order makes sense
✓ Critical information is visually prominent
✓ Every panel serves a purpose
✓ Layout is balanced and dense but not cramped
✓ Numbers align vertically
✓ Units are visible
✓ Status colors and symbols are consistent
✓ Trends are visible where useful
✓ Alerts are easy to find
✓ Mock data is plausible
✓ Dashboard fits the target terminal size (120 columns × 40 rows minimum)
✓ Result looks intentional and impressive

Anti-Patterns to Avoid

• Dashboards made only of random boxes with no information hierarchy
• Panels with no clear purpose or value
• Overusing borders until content becomes hard to scan
• Color without semantic meaning, or color as the only signal
• Inconsistent mixing of ASCII and Unicode styles
• Tiny illegible charts when a simple number would be clearer
• Fake precision that the domain does not require
• Critical failures hidden in low-visibility areas
• All panels treated as equal priority
• Static string output when a live dashboard was requested
• Data collection coupled directly to rendering in reusable code
• Asking for a complete metric specification when a reasonable dashboard can be inferred

Real-Time Dashboard Patterns

For real-time dashboards:

• Use a refresh loop or event loop.
• Keep data fetching non-blocking when possible.
• Preserve layout stability between refreshes to avoid flickering.
• Show last refresh time and stale-data warnings when data fails to update.
• Use graceful shutdown on Ctrl+C.
• Keep CPU usage low.

For Python + Rich, prefer Live rendering for dynamic dashboards. For Textual, use reactive state and periodic timers. For Bubble Tea, use command/message update loops. For ratatui, use a terminal event loop with tick intervals.

Responsive Layout Patterns

For wide terminals:

KPI row → Large main chart + side status rail → Secondary charts/tables → Bottom logs/timeline

For medium terminals:

KPI row → Main chart → Important tables → Recent alerts/logs

For narrow terminals:

Global status → Key KPIs → Critical alerts → Minimal trend → Recent events

Never let responsiveness destroy the dashboard's main message.

Status Aggregation Rules

Healthy   → all critical components OK
Warning   → at least one warning, no critical failures
Degraded  → user-visible impact or repeated failures
Critical  → outage, failed deploy, severe data loss risk, active incident
Unknown   → missing data or stale data

Always explain or display why a status is not healthy.

Threshold Design

Use thresholds appropriate to the domain. Examples:

CPU usage:    <70% healthy  70-85% warning  >85% critical
Memory usage: <75% healthy  75-90% warning  >90% critical
Error rate:   <1% healthy   1-5% warning    >5% critical

Do not hardcode thresholds as universal truth. Make them configurable.

Testing Guidance

For reusable code, add tests for:

• Sparkline rendering
• Gauge and bar width calculations
• Table alignment
• Status aggregation logic
• Threshold evaluation
• Responsive layout decisions
• Theme fallback behavior

Rendering tests can use snapshot-style expected strings when practical.

Example User Objective Handling

Objective: Monitor AI coding agents working on a repo.

→ agents, sessions, tasks, tool calls, success rate, token usage, latency, errors, cost, changed files, command activity, timeline

Objective: Home lab server dashboard.

→ CPU, memory, disk, network, services, UPS, temperature, DNS, WAN, logs, alerts, host health

Objective: SaaS founder daily revenue terminal.

→ MRR, ARR, churn, signups, activation, conversion, revenue sparkline, funnel, failed payments, top customers, forecast

Objective: Security command center.

→ threat level, active incidents, severity distribution, blocked attempts, suspicious IPs, auth failures, endpoint health, recent alerts

Aesthetic Inspiration

Draw inspiration from:

• Retro server monitoring dashboards
• Grafana and observability platforms
• ASCII weather reports
• Terminal network monitors (htop, iotop, nethogs, btop)
• Financial trading terminals
• Cyberpunk command consoles
• Mainframe control rooms
• Minimal UNIX tools

Use inspiration for density, contrast, and terminal-native beauty. Do not copy a specific screenshot exactly.

Final Instruction

Whenever the user provides an objective, create the best possible ASCII, ANSI, Unicode, or TUI dashboard for that objective.

Make it useful. Make it readable. Make it visually striking. Make it technically practical. Make it easy to adapt to live data. Make it feel alive.