spreadsheet-peek

Files (81)

• marketplace.json · .claude-plugin/
• plugin.json · .claude-plugin/
• marketplace.json · .codex-plugin/
• plugin.json · .codex-plugin/
• bug_report.yml · .github/ISSUE_TEMPLATE/
• config.yml · .github/ISSUE_TEMPLATE/
• feature_request.yml · .github/ISSUE_TEMPLATE/
• question.yml · .github/ISSUE_TEMPLATE/
• pull_request_template.md · .github/
• benchmark.yml · .github/workflows/
• mcp-app.yml · .github/workflows/
• .gitignore
• .mcp.json
• CHANGELOG.md
• CLAUDE.md
• CONTRIBUTING.md
• LICENSE
• README.md
• SKILL.md
• agent-preview.gif · assets/
• contrast.gif · assets/
• og-card.png · assets/
• screencast.gif · assets/
• screencast.mp4 · assets/
• README.md · benchmarks/
• compare_converters.py · benchmarks/
• measure_tokens.py · benchmarks/
• verify_claims.py · benchmarks/
• agent-setup.md · docs/
• how-it-works.md · docs/
• release-checklist.md · docs/
• README.md · examples/
• demo.gif · examples/
• demo.tape · examples/
• generate_delimited_samples.py · examples/
• generate_messy_csv.py · examples/
• generate_sample.py · examples/
• generate_tall_ledger.py · examples/
• generate_wide_table.py · examples/
• messy.csv · examples/
• quoted-multiline.csv · examples/
• sample-date.xlsb · examples/
• sample-financials.xlsx · examples/
• sample-ledger.csv · examples/
• sample-ledger.tsv · examples/
• sample-ledger.txt · examples/
• sample-minimal.ods · examples/
• sample-minimal.xls · examples/
• tall-ledger.xlsx · examples/
• wide-table.xlsx · examples/
• install.sh
• .mcpbignore · mcp-app/
• README.md · mcp-app/
• run-server.mjs · mcp-app/bin/
• run-server.sh · mcp-app/bin/
• server.js · mcp-app/dist/
• index.html · mcp-app/dist/viewer/
• index.html · mcp-app/
• manifest.json · mcp-app/
• package-lock.json · mcp-app/
• …and 21 more

SKILL.md (first lines)

# Spreadsheet Peek

Show inline previews of spreadsheet files. Prefer the Spreadsheet Peek MCP viewer when available; otherwise use terminal `wolfxl peek`. This skill is **proactive** - invoke it at the right moments without waiting for the user to ask.

## Prerequisites

- `wolfxl` must be installed: `cargo install wolfxl-cli`
- `wolfxl-cli >= 0.9.0` supports `.xlsx`, `.xlsm`, `.xls`, `.xlsb`, `.ods`, `.csv`, `.tsv`, and comma-delimited `.txt`, plus Markdown export
- Formatting fidelity is strongest for `.xlsx` and `.xlsm`; legacy workbook and delimited inputs are value-first previews with limited style metadata

## MCP Viewer (When Available)

If the `spreadsheet-peek` MCP server is enabled, use it for user-visible previews before terminal output:

```text
open_workbook_viewer(path="/absolute/path/to/file.xlsx", sheet="P&L", maxRows=50, maxColumns=40)
```

Use `preview_workbook` when the host selects it for a natural "preview this spreadsheet" request or when you need structured data without explicitly opening the grid. MCP tools return a bounded preview, sheet metadata, and text summary. The viewer supports sheet tabs, sticky headers, search, range selection, and selected-range handoff.

Use terminal `wolfxl peek` when MCP is unavailable, the agent is shell-only, or you need a copy-pasteable transcript.

## When to Invoke (Proactive Triggers)

### Always preview when:

1. **Before data processing**: preview inputs before running pipelines, ETL jobs, or scripts that read a spreadsheet.
2. **After fixture changes**: preview generated or modified spreadsheet and delimited fixtures.
3. **When the user references a file**: if they mention a spreadsheet, CSV, TSV, or table-like text path, show it before discussing it.
4. **When debugging parsing**: preview the raw input so parser behavior is grounded in the visible file.
5. **When comparing before/after**: show the input and transformed output with the same preview habit.

### Skip preview when:

- The file has already been previewed in the current conversation
- The file is being read programmatically (e.g., openpyxl/pandas in Python) and the code output already shows the data
- The user explicitly says they don't need to see it
- The file is enormous (>10K rows) and the user didn't ask - mention it exists and offer to preview a slice

## Preview Ladder

Use the smallest preview that answers the question:

1. First human-readable look:
   ```bash
   wolfxl peek <file> -n 15
   ```
2. Large or unfamiliar workbook briefing:
   ```bash
   wolfxl agent <file> --max-tokens 800
   ```
3. Repeat previews or context-sensitive work:
   ```bash
   wolfxl peek <file> --export text | sed -n '1,20p'
   ```
4. Sheet structure before cell values:
   ```bash
   wolfxl map <file> --format text
   ```

## Token Efficiency (IMPORTANT)

`wolfxl peek`'s box-drawing output uses Unicode border characters that cost real tokens. Choose the right mode based on context:

| Mode | When to use | Token cost (5 data rows) |
|------|-------------|---------------------|
| **Box-drawing** (`wolfxl peek file -n 5`) | User is looking, readability matters | ~573 tokens (~115/row) |
| **Text export** (`wolfxl peek file --export text \| sed -n '1,6p'`) | Context-sensitive, large files, repeated previews | ~148 tokens (~30/row) |

**Default rule**: Use box-drawing for the FIRST preview in a conversation (readability). Switch to `--export text | sed -n '1,Np'` for subsequent previews or when context is getting long.

**Measured ratio**: box-drawing is ~3.9x more expensive per row than text export on a 7-column financial workbook, ~3.6x on an 8-column tall ledger, and ~3.0x on a 29-column wide table. The overhead is mostly fixed (header/border lines), so the per-row cost improves with more rows - but text export is still cheaper at every size.

**Delimited fixtures**: CSV/TSV/TXT ledger previews cost ~524 box tokens and ~145 text tokens; quoted multiline CSV costs ~401 and ~116.

**Note**: `--export text` ignores the `-n` flag and dumps ALL rows. Always pipe through `sed -n '1,Np'` to limit what enters the conversation. Prefer `sed` over `head` with current `wolfxl-cli` releases because `head` can close the pipe early and make `wolfxl` print a broken-pipe warning.

## Command Variants

```bash
wolfxl peek <file> -n 0                              # full readable dump, use sparingly
wolfxl peek <file> --sheet "Balance Sheet" -n 15     # specific sheet
wolfxl peek <file> -n 15 -w 60                       # wider cells for long text
wolfxl peek <file> --export text                     # clean text for diffing or piping
wolfxl peek <file> --export markdown | sed -n '1,20p' # Markdown table for context converters
wolfxl peek <file> --export csv                      # CSV export
wolfxl peek <file> --export json                     # JSON export
```

## Delimited File Notes

`wolfxl peek` reads `.csv`, `.tsv`, and comma-delimited `.txt` files directly in `wolfxl-cli >= 0.9.0`:

```bash
wolfxl peek file.csv -n 15
wolfxl peek file.tsv -n 15
wolfxl peek file.txt -n 15
```

For raw inspection, custom delimiters, dimensions, or older installed `wolfxl` binaries:

```bash
head -15 file.csv                                # raw sniff
head -15 file.csv | column -s, -t                # simple CSV only
mlr --icsv --opprint head -n 15 file.csv         # CSV-aware
csvlook --max-rows 15 file.csv                   # CSV-aware
mlr --icsv --opprint count file.csv              # row count
mlr --icsv --opprint put '$columns = NF' then head -n 1 file.csv
```

**Which to use**: default to `wolfxl peek` for conversation-visible previews. Use `head` only for a raw text sniff, `column -s, -t` only on simple CSVs, and `mlr`/`csvkit` for custom delimiters, encodings outside UTF-8, or CSV-aware dimensions.

**Known caveat**: `wolfxl-cli 0.9.0` is UTF-8 only and does not strip BOMs or detect arbitrary delimiters. A UTF-8 BOM may show in the first header cell; non-comma `.txt` files need a CSV-aware tool or a temporary conversion.

**If you must use Python** (CSV too messy for shell tools), reach for `csv.DictReader` + `tabulate`, not pandas - pandas has a ~1s import cost and is overkill for a preview.

## Legacy Workbook Notes

`wolfxl-cli >= 0.9.0` reads `.xls`, `.xlsb`, and `.ods` directly:

From wolfiesch/spreadsheet-peek, MIT.