Skip to main content

Xlens

Ask your AI assistant why a number in an Excel financial model is what it is, and get an answer built from the workbook's real formulas, with a live one-page map beside the chat.

Xlens map: Net Operating Income traced to its inputs and the KPIs it feeds

What it does

Xlens reads an .xlsx model, builds a dependency graph from its formulas, and exposes six tools to Claude or Codex (and a CLI):

  • Map: a one-page "Row map" of the model, grouped by sheet and row, with KPIs along the top.
  • Trace: pick one cell and see what feeds it and what it feeds, with formulas and values.
  • Drivers: the typed-in inputs that a cell depends on, ranked by how many paths reach it.
  • KPIs with scenarios: IRR, NOI, DSCR, equity multiple and similar outputs, with each scenario or year column shown (Low/Base/High, Year 1 to 5).
  • Findings: hardcoded numbers typed inside calculations, and circular references.

The assistant cites cells as Sheet!Ref = value and does not estimate numbers.

Install for Claude Code

In Claude Code:

/plugin marketplace add akay126/xlens
/plugin install xlens@xlens

Or from a terminal:

claude plugin marketplace add akay126/xlens
claude plugin install xlens@xlens

The plugin adds the Xlens skill and an MCP server that runs uvx --from xlens-ai xlens mcp. The Claude Desktop Code tab uses Claude Code plugins, so the same install applies there. You need uv installed.

The xlens-ai package is available on PyPI after the first release. Until then, run the server from source by pointing an MCP config at uvx --from git+https://github.com/akay126/xlens xlens mcp.

What was checked: with a locally modified plugin copy, Claude Code connected to the server, loaded the skill, and answered questions about examples/sample_model.xlsx from the tools. See docs/install-notes.md. The opening of the map in a browser tab was not checked in that run.

Install for Codex

codex plugin marketplace add akay126/xlens
codex plugin add xlens@xlens

Codex plugins can start stdio MCP servers, and this plugin does. Install, skill discovery, MCP server discovery and a direct tool call were verified with codex-cli 0.159.3. A full model session through the installed plugin was not. The owner/repo form of the marketplace command has not been tried yet, because the repository was not public at the time.

MCP only, without the skill:

codex mcp add xlens -- uvx --from xlens-ai xlens mcp

For any other MCP host, use a stdio server with command uvx --from xlens-ai xlens mcp. These xlens-ai commands work after the first release; before that, use uvx --from git+https://github.com/akay126/xlens xlens mcp.

Claude Desktop chat (inline map)

Not yet tested. In theory, add Xlens as a manual MCP server in Claude Desktop's config so the map can show inline in chat:

{
  "mcpServers": {
    "xlens": { "command": "uvx", "args": ["--from", "xlens-ai", "xlens", "mcp"] }
  }
}

Claude Code and Codex in a terminal do not render inline apps. There the server opens the map in your browser instead (--no-browser turns that off).

Command line

pip install xlens-ai

Available after the first release. From source, use pip install git+https://github.com/akay126/xlens.

xlens analyze model.xlsx                 # full HTML report (add --output report.html)
xlens batch deal_room/                   # analyze every workbook in a folder
xlens query overview model.xlsx          # sheets, counts, flow, KPIs as JSON
xlens query find model.xlsx --text NOI
xlens query trace model.xlsx --cell "Cash Flow!G11" --direction up --depth 2
xlens query drivers model.xlsx --cell "Cash Flow!G11"
xlens query findings model.xlsx --kind hardcodes   # or circular, all
xlens mcp                                # start the MCP server over stdio

xlens query prints JSON, so scripts and agents can read it. These were run against examples/sample_model.xlsx. For example, the drivers command ranks Inputs!B8 (Rent Growth) and Inputs!B3 (Units) first for Cash Flow!G11, and findings --kind hardcodes flags the typed-in Cash Flow!F9 = 215000. xlens mcp takes --no-browser and --no-viewer.

Privacy

  • Xlens runs on your machine and does not upload your workbook.
  • What the tools return (labels, formulas, values, cell text) becomes part of your conversation, so it goes to the AI provider behind your chat app (Anthropic for Claude, OpenAI for Codex). Check that provider's terms before using confidential models.
  • The map server listens on 127.0.0.1 only, with a random token generated for each session.
  • Text in a workbook is treated as untrusted. It is escaped in the map, and the skill tells the assistant not to follow instructions found in a workbook. See SECURITY.md.

Limits

  • .xlsx only.
  • Xlens reads the values Excel cached in the file and does not recalculate. A file written by a script without opening it in a spreadsheet app has formulas but no cached values.
  • The heuristics for finding KPIs, flow blocks and assumptions are tuned for real-estate and finance models. Other kinds of workbook work, but labels may be classified less well.
  • Above 1,200 rows the map shows Trace only, without the Row map.

Development

uv sync --extra dev
uv run pytest                              # unit tests
uv run pytest e2e/ --browser chromium      # browser tests (needs: playwright install chromium)
python tests/fixtures/build_models.py      # regenerate the test workbooks

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Metadata

Release files for xlens-ai 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xlens-ai 0.2.0
File Size Uploaded Provenance Actions
xlens_ai-0.2.0.tar.gz 106.8 kB With provenance Details for xlens_ai-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xlens-ai 0.2.0
File Interpreter ABI Platform Actions
xlens_ai-0.2.0-py3-none-any.whl Python 3 none any Details for xlens_ai-0.2.0-py3-none-any.whl

Total release size: 188.5 kB

Release files / xlens_ai-0.2.0.tar.gz

Download URL xlens_ai-0.2.0.tar.gz
Size 106.8 kB
Tags Source
SHA-256 checksum
How to use checksums
6b36b0398cf53323f8991e99a84f40bb67f24f01a8215cdf05ad23c0d73b1b4a
BLAKE2b-256 checksum
How to use checksums
e365036c85c8f0d3cbb9e366928820b9bf027132f0e6f1a28410090b6bda0e6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / xlens_ai-0.2.0-py3-none-any.whl

Download URL xlens_ai-0.2.0-py3-none-any.whl
Size 81.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
45523d51d8348401ded1921828620a32d861a4a589d89ebd72eec4fb0c1f78f9
BLAKE2b-256 checksum
How to use checksums
b6a75d1b736cc8a2aa8e193fefcdd3ff37e6f0d59b8d7f9a067747f8dbe765cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for xlens-ai 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xlens_ai-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page