XLSX Editor Plugin

The XLSX Editor plugin provides Excel workbook editing (.xlsx / .xlsm) through the same dynamic tool-injection pattern as the Document Editor. The agent always has an xlsx_open tool; opening a workbook injects a full suite of editing tools, which are removed again when the workbook is closed. All workbook manipulation happens in an isolated openpyxl worker subprocess designed to run inside the Workspace Isolation sandbox.

Configuration

plugins:
  - module: codumentor.plugins.xlsx_editor
    class: XlsxEditorPlugin
    args:
      enabled: true
      target_agents: "main"  # "main", "subagent", or "all" (default: "main")

Parameters

enabled (optional): Whether the plugin is enabled (default: true)
target_agents (optional): Which agents receive the tools — "main", "subagent", or "all" (default: "main")

Tool Reference

Always Available

Tool	Description
`xlsx_open`	Open an `.xlsx`/`.xlsm` workbook (in place or as a copy), or create a new blank one. Triggers injection of the editing tools.

Injected When a Workbook Is Open

Tool	Description
`xlsx_read_workbook`	Workbook outline: sheets, dimensions, named ranges, tables, active sheet
`xlsx_read_range`	Read a 2D range (A1 notation), formulas or cached values
`xlsx_search`	Regex search across sheets (up to 50 matches)
`xlsx_write_cell`	Write a single cell (a leading `=` is treated as a formula)
`xlsx_write_range`	Write a 2D array of values in one call
`xlsx_list_sheets`	Per-sheet metadata (dimensions, tab colour, visibility)
`xlsx_create_sheet` / `xlsx_delete_sheet` / `xlsx_rename_sheet`	Add, remove, or rename worksheets
`xlsx_insert_rows` / `xlsx_delete_rows`	Insert or delete rows
`xlsx_insert_cols` / `xlsx_delete_cols`	Insert or delete columns
`xlsx_replace_text`	Find/replace across the workbook, a sheet, or a range
`xlsx_set_cell_format`	Set a cell/range number format
`xlsx_set_style`	Apply font, fill, border, and alignment styles
`xlsx_set_property`	Set a workbook core property (title, author, …)
`xlsx_read_print_settings`	Read per-sheet page setup, margins, headers/footers
`xlsx_python`	Sandboxed `openpyxl` access for advanced operations
`xlsx_save`	Save the workbook (emits a UI download card)
`xlsx_close`	Close the workbook (optionally saving first)

How It Works

An onPromptAssemble hook (priority 10) tracks which sessions have an open workbook. Only xlsx_open is visible until a workbook is opened; on the next turn the editing tools are injected, and they are removed again after xlsx_close. This keeps the tool set relevant to what the agent is doing — the same pattern documented for the Document Editor.

Saved workbooks are downloadable through the UI (a plugin.xlsx_editor.file_saved event renders a download card); the download endpoint is provided by the File Links plugin.

Notes

Requirements: openpyxl >= 3.1. The editing worker is a JSON-Lines subprocess that holds the workbook in memory and is meant to run inside the bwrap sandbox.
Cached values: The worker keeps both an editable workbook (with formula strings) and a read-only data_only snapshot refreshed on save, so formula results reflect the values as of the last save.
Limits: Maximum file size 50 MB; search returns at most 50 matches (flagged when truncated).
See also the Document Editor and PPTX Editor plugins, which share this architecture.