spreadsheet-peek

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:

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:

   wolfxl peek <file> -n 15
   

2. Large or unfamiliar workbook briefing:

   wolfxl agent <file> --max-tokens 800
   

3. Repeat previews or context-sensitive work:

   wolfxl peek <file> --export text | sed -n '1,20p'
   

4. Sheet structure before cell values:

   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

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:

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:

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:

wolfxl peek file.xls -n 15
wolfxl peek file.xlsb -n 15
wolfxl peek file.ods -n 15

These formats expose values reliably but not full Excel style metadata. If you need high-fidelity styling, convert a temporary copy to .xlsx first:

mkdir -p /tmp/spreadsheet-peek
soffice --headless --convert-to xlsx --outdir /tmp/spreadsheet-peek file.xls
wolfxl peek /tmp/spreadsheet-peek/file.xlsx -n 15

If LibreOffice is not installed, use the direct preview and say legacy style fidelity is limited. If an older wolfxl rejects these inputs, upgrade with cargo install wolfxl-cli --version 0.9.0 --force.

Multi-Sheet Workflow

When previewing a multi-sheet workbook:

1. First run shows the first sheet and lists available sheets in the output header (Available sheets: line)
2. If the workbook has multiple sheets, preview ALL relevant sheets (financial workbooks typically have 2-5 sheets that matter)
3. For repeated sheet previews, use text export to save tokens

# First sheet (readable, box-drawing)
wolfxl peek file.xlsx -n 15

# Subsequent sheets (token-efficient)
wolfxl peek file.xlsx --sheet "Balance Sheet" --export text | sed -n '1,20p'
wolfxl peek file.xlsx --sheet "Cash Flow" --export text | sed -n '1,20p'

Python Fallback

If wolfxl is unavailable, use openpyxl + tabulate:

import openpyxl, tabulate
wb = openpyxl.load_workbook('file.xlsx', data_only=True)
ws = wb.active
rows = [[cell.value for cell in row] for row in ws.iter_rows()]
print(tabulate.tabulate(rows[1:], headers=rows[0] or [], tablefmt='grid'))

Why wolfxl peek Over Disposable Python Scripts

wolfxl peek saves the agent from generating throwaway Python every time a workbook appears. The tradeoff:

• Box-drawing output is ~3-4x larger than text export for equal preview slices (Unicode borders cost tokens on the context side)
• --export text | sed -n '1,Np' is the most token-efficient repeat-preview mode (~148 tokens for 5 financial rows; tiny raw openpyxl tuple dumps can be similar in output tokens but require generated code and are harder to read)
• Reliability: wolfxl peek avoids import errors, env issues, and edge cases in ad-hoc parsing code
• Speed: Rust binary parses instantly vs ~0.5-1s openpyxl startup
• Readable formatting: Date cells render as ISO dates, common currency/percentage formats render in human-facing previews, and numeric cells are grouped for scanning. Style fidelity is strongest for .xlsx / .xlsm.

Never write disposable Python to view a spreadsheet. Use wolfxl peek.

Output Interpretation Notes

• Empty cells show as blank (no value in the cell)
• Numeric cells are grouped for readability (e.g., 1,200 instead of 1200)
• Date cells render as ISO YYYY-MM-DD; common currency and percentage number formats render in human-facing .xlsx / .xlsm previews
• The header line Sheet: SheetName (N rows × M columns) tells you the full dimensions
• Available sheets: line appears when the workbook has multiple tabs
• The banner wolfxl peek - Excel preview confirms you're getting wolfxl output (vs a manual openpyxl dump)