docs: include simple reporter

Author: boneskull

cspell.json

@@ -27,7 +27,7 @@
     "CHANGELOG.md",
     "coverage",
     "dist",
-    "docs",
+    "/docs",
     "node_modules",
     "*.csv",
     "worktrees",
@@ -57,7 +57,12 @@
     "mnode",
     "mplatform",
     "mcpu",
-    "mmem"
+    "mmem",
+    "pyplot",
+    "ylabel",
+    "xticks",
+    "tolist",
+    "seti"
   ],
   "words": ["bupkis"]
 }

package.json

@@ -179,6 +179,10 @@
     "**/!(.github/prompts)/*.md": [
       "prettier --write",
       "cspell"
+    ],
+    "*.mdx": [
+      "prettier --write",
+      "cspell"
     ]
   },
   "prettier": {

site/src/content/docs/getting-started/index.md

@@ -140,7 +140,7 @@ modestbench run "tests/**/*.bench.ts"
 
 ## View Results
 
-modestbench provides a clean, colorized output:
+modestbench provides clean, colorized output in interactive terminals:
 
 ```text
 🚀 modestbench
@@ -174,6 +174,10 @@ Found 1 benchmark file(s)
 🎉 All benchmarks completed successfully!
 ```
 
+:::note[Output Format]
+The colorized output above is from the `human` reporter, used automatically in interactive terminals. In CI/CD or when piping output, modestbench uses the `simple` reporter for clean, plain-text output without colors.
+:::
+
 ## Common Options
 
 ### Control Benchmark Duration

site/src/content/docs/guides/advanced.md

@@ -274,7 +274,7 @@ const isProd = process.env.NODE_ENV === 'production';
 export default {
   iterations: isCI ? 5000 : 100,
   warmup: isCI ? 100 : 0,
-  reporters: isCI ? ['json', 'csv'] : ['human'],
+  reporters: isCI ? ['json', 'csv'] : ['simple'], // Simple reporter for CI, auto-detect for local
   quiet: isCI,
   outputDir: isCI ? './benchmark-results' : undefined,
 
@@ -286,6 +286,10 @@ export default {
 };
 ```
 
+:::tip[Reporter Auto-Selection]
+You can omit the `reporters` option entirely to let modestbench auto-select based on the environment (TTY detection).
+:::
+
 ## CI/CD Integration
 
 ### GitHub Actions

site/src/content/docs/guides/cli.md

@@ -132,10 +132,15 @@ modestbench run --reporters human,json,csv
 
 Available reporters:
 
-- `human` - Color-coded terminal output (default)
+- `human` - Color-coded terminal output (default for TTY with colors)
+- `simple` - Plain text output (default for non-TTY environments)
 - `json` - Structured JSON data
 - `csv` - Tabular CSV format
 
+:::note[Auto-Selection]
+modestbench automatically selects `human` (TTY with color) or `simple` (non-TTY) as the default. Override with `--reporters` if needed.
+:::
+
 ##### `--output <directory>`
 
 Directory path for saving benchmark results and reports.
@@ -158,8 +163,8 @@ Minimal output mode. Suppresses progress bars and non-essential messages.
 modestbench run --quiet
 ```
 
-:::note
-`--quiet` suppresses progress (stderr), not data output (stdout). Perfect for CI/CD pipelines.
+:::note[CI/CD Pipelines]
+In non-TTY environments, modestbench automatically uses the `simple` reporter which has no progress bars. `--quiet` further suppresses status messages for completely clean output.
 :::
 
 ##### `--verbose`

site/src/content/docs/guides/configuration.md

@@ -208,11 +208,12 @@ Stop execution on first benchmark failure.
 #### `reporters`
 
 **Type:** `string[]`  
-**Default:** `["human"]`
+**Default:** Auto-selected based on environment
 
 Array of reporter names to use for output. Available reporters:
 
-- `human` - Color-coded terminal output with progress bars
+- `human` - Color-coded terminal output with progress bars (default for TTY with colors)
+- `simple` - Plain text output without colors (default for non-TTY environments)
 - `json` - Structured JSON data for programmatic analysis
 - `csv` - Tabular data for spreadsheets
 
@@ -222,6 +223,10 @@ Array of reporter names to use for output. Available reporters:
 }
 ```
 
+:::note[Auto-Selection]
+When not specified, modestbench automatically selects `human` (TTY + color support) or `simple` (non-TTY). The `human` reporter is used when `FORCE_COLOR=1` even in non-TTY environments.
+:::
+
 :::note[Multiple Reporters]
 You can use multiple reporters simultaneously! Results will be output in all specified formats.
 :::
@@ -256,6 +261,10 @@ Minimal output mode. Suppresses progress bars and non-essential messages on stde
 }
 ```
 
+:::tip[CI/CD Usage]
+In CI/CD environments, modestbench automatically uses the `simple` reporter which has no progress bars. Use `quiet` to further suppress status messages for completely clean output.
+:::
+
 :::tip[quiet vs output]
 `quiet` suppresses progress (stderr), not data output (stdout). Use it in CI to reduce noise while still getting results.
 :::

site/src/content/docs/guides/output.md

@@ -5,9 +5,19 @@ description: Understanding modestbench reporter output formats
 
 modestbench supports multiple output formats through its reporter system. You can use multiple reporters simultaneously to get results in different formats.
 
-## Human Reporter (Default)
+## Default Reporter Selection
 
-The human reporter provides color-coded terminal output with real-time progress bars and formatted results.
+modestbench automatically selects the appropriate reporter based on your environment:
+
+- **Interactive terminals** (TTY with color support): `human` reporter with colors and progress bars
+- **Non-TTY environments** (CI/CD, piped output): `simple` reporter with plain text output
+- **Forced color mode** (`FORCE_COLOR=1`): `human` reporter even in non-TTY environments
+
+You can always override the default by explicitly specifying `--reporters`.
+
+## Human Reporter
+
+The human reporter provides color-coded terminal output with real-time progress bars and formatted results. This is the default when running in an interactive terminal (TTY) with color support.
 
 ### Features
 
@@ -70,9 +80,74 @@ modestbench run --reporters human --quiet
 - **stderr** - Progress bars and real-time updates
 
 :::tip[CI/CD Usage]
-Use `--quiet` flag to suppress progress bars while keeping results output.
+In CI/CD environments, modestbench automatically uses the `simple` reporter for clean, parseable output. Use `--quiet` to suppress progress messages if using the `human` reporter explicitly.
 :::
 
+## Simple Reporter
+
+The simple reporter provides clean, text-only output without colors or progress bars. This is the default in non-TTY environments (CI/CD, piped output) or when `FORCE_COLOR` is not set.
+
+### Features
+
+- **Plain text output** - No ANSI colors or escape codes
+- **No progress bars** - Clean output suitable for logs and pipes
+- **Structured results** - Same hierarchy as human reporter (File → Suite → Task)
+- **Machine-readable** - Perfect for parsing and CI/CD logs
+
+### Example Output
+
+```text
+modestbench
+
+Environment:
+  Node.js: v24.10.0
+  Platform: darwin arm64
+  CPU: Apple M4 Max (16 cores)
+  Memory: 48.0 GB
+
+Found 1 benchmark file(s)
+
+> benchmarks/example.bench.js
+
+  > Array Operations
+    ✓ Array.push()
+      810.05μs ±2.45% (1.23M ops/sec)
+    ✓ Array spread
+      81.01ms ±4.12% (12.34K ops/sec)
+  ✓ 2 passed
+
+  ✓ All 2 tasks passed
+
+Results
+
+✓ All tests passed: 2
+Files: 1
+Suites: 1
+Duration: 1.82s
+
+All benchmarks completed successfully!
+```
+
+### Usage
+
+```bash
+# Simple reporter is default in non-TTY environments
+modestbench run | tee results.log
+
+# Explicitly specify simple reporter
+modestbench run --reporters simple
+
+# Force human reporter in non-TTY (requires FORCE_COLOR=1)
+FORCE_COLOR=1 modestbench run --reporters human
+```
+
+### When to Use
+
+- **CI/CD pipelines** - Clean logs without ANSI codes
+- **Piped output** - `modestbench run | grep "passed"`
+- **Log files** - Readable output without color codes
+- **Automated parsing** - Consistent text format
+
 ## JSON Reporter
 
 The JSON reporter outputs structured data perfect for programmatic analysis, CI/CD integration, and historical tracking.
@@ -383,8 +458,11 @@ modestbench run
 #### CI/CD
 
 ```bash
-# JSON + CSV for analysis, quiet mode
+# JSON + CSV for analysis (simple reporter used automatically)
 modestbench run --reporters json,csv --output ./results --quiet
+
+# Or let auto-detection handle it
+modestbench run --output ./results
 ```
 
 #### Documentation
@@ -400,27 +478,30 @@ modestbench run --reporters human,json,csv --output ./benchmark-results
 
 - **JSON reporter**: Writes to `{output}/results.json`
 - **CSV reporter**: Writes to `{output}/results.csv`
-- **Human reporter**: Still writes to stdout/stderr
+- **Human/Simple reporters**: Still write to stdout/stderr
 
 ### When `--output` is NOT Specified
 
 - **JSON reporter**: Writes to stdout
 - **CSV reporter**: Writes to stdout
-- **Human reporter**: Writes to stdout/stderr
+- **Human/Simple reporters**: Write to stdout/stderr
 
 :::caution[Multiple Data Reporters]
 Using both JSON and CSV without `--output` will mix their output on stdout. Always use `--output` when using multiple data reporters.
 :::
 
 ### Quiet Mode
 
-The `--quiet` flag affects only the human reporter:
+The `--quiet` flag affects the human and simple reporters:
 
-- Suppresses progress bars (stderr)
-- Suppresses status messages
+- Suppresses progress bars and status messages (stderr)
 - Keeps final results output
 - Does NOT affect JSON or CSV output
 
+:::note[Simple Reporter]
+The `simple` reporter has no progress bars by default, so `--quiet` primarily affects status messages.
+:::
+
 ## Next Steps
 
 - Learn about [Configuration](/guides/configuration/) for reporter setup

site/src/content/docs/index.mdx

@@ -25,9 +25,8 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
     High-precision timing with statistical analysis powered by `tinybench`. Get reliable measurements you can trust.
   </Card>
 
-<Card title="Multiple Output Formats" icon="document">
-  Generate human-readable, JSON, and CSV reports simultaneously. Perfect for
-  CI/CD and analysis tools.
+  <Card title="Multiple Output Formats" icon="document">
+  Generate human-readable, simple text, JSON, and CSV reports simultaneously. Auto-detects environment for optimal output.
 </Card>
 
 <Card title="Historical Tracking" icon="seti:clock">

site/src/content/docs/reference/api.md

@@ -49,7 +49,8 @@ console.log(`Completed ${result.summary.totalTasks} benchmarks`);
 The main package exports:
 
 - `modestbench()` - Create a benchmark engine instance
-- `HumanReporter` - Color-coded terminal reporter
+- `HumanReporter` - Color-coded terminal reporter (TTY with colors)
+- `SimpleReporter` - Plain text reporter (non-TTY environments)
 - `JsonReporter` - Structured JSON output reporter
 - `CsvReporter` - Tabular CSV output reporter
 - Type definitions for TypeScript