Osaurus XLSX

This plugin reads, creates, and modifies Excel (.xlsx) files. It uses a stateful in-memory model — you load or create a workbook, manipulate it, then save it to disk.

Workflow

Always follow this sequence:

1. •read_xlsx(path) or create_xlsx(sheets) — get a workbook_id
2. •write_cells / modify_xlsx — mutate the workbook in memory (optional, repeat as needed)
3. •save_xlsx(workbook_id, path) — write the final .xlsx file to disk

For one-shot read operations, list_sheets and xlsx_to_csv read directly from disk without needing the full workflow.

Quick Reference

Reading

Writing

Transformation

Cell References

All cell references use standard Excel notation:

• •Single cell: A1, B5, Z100
• •Range: A1:D10, B2:B50
• •Column letters: A=1, Z=26, AA=27, AZ=52, etc.

Value Types

When writing cell values, types are auto-detected from the string value:

You can override auto-detection with the type parameter in write_cells:

• •"string" — force string
• •"number" — force number
• •"boolean" — force boolean
• •"formula" — force formula (adds = prefix if missing)

Tool Tips

read_xlsx

• •Returns all sheets by default. Use sheet_name to read a single sheet.
• •Use range (e.g. "A1:D10") to limit the data returned — useful for large files.
• •The returned workbook_id is needed for write_cells, modify_xlsx, get_cell_value, and save_xlsx.
• •Sheet name matching is case-insensitive.

get_cell_value

• •Requires a workbook_id from a prior read_xlsx or create_xlsx call.
• •You must provide either cell (e.g. "B5") or range (e.g. "A1:C3") — omitting both returns an error.
• •Sheet name matching is case-insensitive.

list_sheets

• •Reads sheet names directly from disk — no workbook_id needed.
• •Useful for discovering sheet names before calling read_xlsx with a specific sheet_name.

create_xlsx

• •Pass an array of sheet definitions, each with a name, optional headers, and optional rows.
• •headers are always stored as strings.
• •rows values are auto-detected (numbers, booleans, strings).
• •Remember to call save_xlsx afterwards — nothing is written to disk until you save.

write_cells

• •If the specified sheet_name doesn't exist, a new sheet is created automatically.
• •Each cell in the cells array needs a ref (e.g. "B5") and a value.
• •Use type to force a specific value type if auto-detection isn't what you want.

save_xlsx

• •The .xlsx extension is added automatically if missing.
• •Always call this when you're done. The workbook only exists in memory until saved.

xlsx_to_csv

• •Reads directly from a file on disk — no need to read_xlsx first.
• •Defaults to the first sheet. Use sheet_name to specify a different one.
• •Set format to "tsv" for tab-separated output.

csv_to_xlsx

• •Accepts raw CSV/TSV text in the csv_data parameter.
• •Set has_header: true to keep the first row as strings (prevents number detection on headers).
• •Set delimiter to "tab" or "\t" for TSV input.
• •Returns a workbook_id — call save_xlsx to write to disk.

modify_xlsx

• •Batch multiple operations in a single call for efficiency.
• •If sheet_name is omitted, operations target the first sheet in the workbook.
• •Available operations:
  • •set_cell — set a cell value (ref + value)
  • •set_formula — set a formula (ref + formula)
  • •delete_row — delete a row by number and shift rows up (row)
  • •delete_column — delete a column by letter and shift columns left (column)
  • •rename_sheet — rename the target sheet (new_name)
  • •add_sheet — add a new empty sheet (name)

Limitations

1. •

   No cell formatting. The plugin reads and writes cell values only. Fonts, colors, borders, and other formatting from existing files are not preserved.

2. •

   No images or charts. Embedded objects in existing files are not read or preserved.

3. •

   Formulas are stored, not evaluated. When you write =SUM(A1:A10), the formula text is saved. Excel will evaluate it when the file is opened.

4. •

   Large files. Reading very large spreadsheets (100k+ rows) loads all data into memory. Use the range parameter with read_xlsx to limit data.

5. •

   Round-trip fidelity. Reading an existing .xlsx and saving it back will preserve cell values but may lose formatting, charts, images, and other advanced features.

Example: Read and Summarize

1. read_xlsx(path="sales.xlsx")
   → workbook_id, sheets with cell data

2. Agent analyzes the data and responds with a summary

Example: Create a New Spreadsheet

1. create_xlsx(sheets=[
     {name: "Employees", headers: ["Name", "Department", "Salary"],
      rows: [["Alice", "Engineering", "120000"],
             ["Bob", "Marketing", "95000"]]}
   ])
   → workbook_id

2. save_xlsx(workbook_id, path="employees.xlsx")
   → file written to disk

Example: Read, Modify, and Save

1. read_xlsx(path="budget.xlsx")
   → workbook_id

2. write_cells(workbook_id, sheet_name="Q4",
     cells=[{ref: "B10", value: "=SUM(B1:B9)", type: "formula"}])
   → cell written

3. save_xlsx(workbook_id, path="budget_updated.xlsx")
   → file written to disk

Example: CSV to Excel

1. csv_to_xlsx(csv_data="Name,Age\nAlice,30\nBob,25", has_header=true)
   → workbook_id

2. save_xlsx(workbook_id, path="people.xlsx")
   → file written to disk

Example: Batch Modifications

1. read_xlsx(path="data.xlsx")
   → workbook_id

2. modify_xlsx(workbook_id, sheet_name="Sheet1", operations=[
     {type: "set_cell", ref: "A1", value: "Updated Title"},
     {type: "set_formula", ref: "D10", formula: "=AVERAGE(D1:D9)"},
     {type: "delete_row", row: 5},
     {type: "add_sheet", name: "Summary"},
     {type: "rename_sheet", new_name: "Data"}
   ])
   → 5 operations applied

3. save_xlsx(workbook_id, path="data_modified.xlsx")
   → file written to disk