# agent-xlsx

A small CLI for reading and editing `.xlsx` files, designed for agents. JSON
in, JSON out; A1 range notation everywhere; structured JSON errors on stderr.

> **📖 Full usage docs live in [`skills/agent-xlsx/SKILL.md`](skills/agent-xlsx/SKILL.md).**
> That file is the skill definition consumed by `npx skills add` and by
> Claude agents; it doubles as the human-readable reference.

## Install

```bash
# Latest release, to a dir on PATH
curl -fsSL https://raw.githubusercontent.com/carderne/agent-xlsx/main/install.sh \
    | bash -s -- ~/.local/bin
```

Supported targets: Apple Silicon macOS, x86_64 Linux, x86_64 Windows.


## As a Claude skill
```bash
npx skills add carderne/agent-xlsx
```

## As a pi package
```bash
pi install npm:agent-xlsx
```

## Quick taste

```bash
agent-xlsx create book.xlsx
agent-xlsx edit   book.xlsx A1:C1 '["name","age","city"]'
agent-xlsx edit   book.xlsx A2:C3 '[["Alice",30,"Berlin"],["Bob",42,"Paris"]]'
agent-xlsx read   book.xlsx A1:C3
# [["name","age","city"],["Alice",30.0,"Berlin"],["Bob",42.0,"Paris"]]
```

## Evals

Currently... it's mostly worse than just Python. Did Anthropic try this already?

| task                | model            | py-time | cli-time | py-tokens | cli-tokens | py-turns | cli-turns |
| ------------------- | ---------------- | ------: | -------: | --------: | ---------: | -------: | --------: |
| bulk_filter_bold    | claude-haiku-4-5 |   11.2s |     +81% |       914 |      +146% |        3 |      +67% |
| conditional_color   | claude-haiku-4-5 |    9.1s |     +20% |       741 |       +51% |        2 |      +50% |
| edit_formula_totals | claude-haiku-4-5 |    8.2s |      -4% |       593 |       -10% |        2 |        0% |
| edit_sparse         | claude-haiku-4-5 |   15.0s |     -26% |       858 |       -14% |        4 |        0% |
| reorder_cols        | claude-haiku-4-5 |   12.0s |     +23% |      1076 |       +13% |        2 |     +150% |
| style_header        | claude-haiku-4-5 |    7.7s |     +13% |       529 |       +16% |        2 |        0% |

## Building from source

```bash
cargo build --release
cargo test
```