FinCo is an AI-powered financial analyst that operates inside your live Excel workbook. You keep Excel open, chat with FinCo through a companion window, and analysis results appear directly in your spreadsheet -- formatted, formula-driven, and ready for presentation.
FinCo never touches your sheets. It reads your data and writes its work to clearly separated output sheets prefixed with FC -. Your workbook, your control.
+------------------------------------------------------+
| Your Workbook.xlsx |
| |
| [ Sheet1 ] [ Sheet2 ] [ FC - IRR ] [ FC - DCF ] |
| (yours) (yours) (FinCo) (FinCo) |
+------------------------------------------------------+
| ^
| reads | writes
v |
+------------------------------------+
| FinCo Engine |
| Claude API + xlwings (COM) |
+----------------+-------------------+
^
| chat
+----+----+
| You |
+---------+
- Your sheets (no prefix): your data, your formatting, your formulas. FinCo reads them but never modifies them.
- FC sheets (
FC -prefix): FinCo's work product. Professionally formatted with live formulas referencing your source data. You can view, edit, copy, or delete them.
- Live Excel integration -- works with your open workbook in real-time via COM automation
- Formula-driven outputs -- results use
=Sheet1!B5references, not hardcoded values. Change your data and outputs update automatically - Professional formatting -- navy headers, clean borders, proper number formats. Output that a senior banker could put in a pitch book
- Multi-turn conversations -- FinCo remembers context within a session. "Now add NPV to that sheet" just works
- Full audit trail -- every successful script is timestamped and saved
- Sheet management -- FinCo creates, updates, and cleans up its own sheets. Failed attempts are rolled back automatically
- Broad financial expertise -- cash flow analysis, IRR/NPV, sensitivity tables, forecasting, fixed income, basic options pricing, and more
The examples/ folder contains a demo workbook with FinCo-generated analysis:
- FC - Project Evaluation: IRR and NPV comparison of two investment projects with sensitivity analysis across discount rates
- FC - Extrapolated Evaluation: Linear trend extrapolation of revenues and costs with 10-year cash flow projections
- FC - Revenue & Cost Trends: Charts showing actual vs. trend data for both projects
All outputs use live Excel formulas where possible and professional formatting throughout.
- Windows with Microsoft Excel (desktop, not web)
- Python 3.10+ (64-bit recommended)
- An Anthropic API key
# Clone the repo
git clone https://github.com/YOUR_USERNAME/finco.git
cd finco
# Install dependencies
pip install anthropic xlwings numpy
# Set your API key (one time, permanent)
# In PowerShell:
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")
# Then close and reopen PowerShell- Open any
.xlsxworkbook in Excel - Double-click
FinCo.bat(or runpython engine.py) - FinCo automatically connects to your open workbook
- Type your requests in plain English
You: Compute IRR and NPV for the cash flows on Sheet1
Computing... Done.
FinCo: IRR: 6.18%. NPV at 10%: $12,450. Written to FC - IRR Analysis.
You: Add a sensitivity table for discount rates 5% to 20%
Computing... Done.
FinCo: Sensitivity table added to FC - IRR Analysis.
You: Compare the two projects on Sheet2 and recommend the better investment
Computing... Done.
FinCo: Project 2 dominates on IRR (14.2% vs 8.7%) and NPV at all tested
rates. Written to FC - Project Comparison.
FinCo is a tool-using AI agent built on the Claude API. On each prompt:
- Read: The engine reads the current state of every sheet in the workbook
- Reason: Claude receives the workbook state, conversation history, and your request
- Act: Claude generates a Python script using xlwings to manipulate the workbook
- Execute: The script runs in-process (sharing the live COM connection to Excel)
- Verify: Failed scripts are rolled back (any sheets they created are deleted)
- Respond: Claude reports the result tersely
Scripts execute in-process via exec() with pre-injected xw (xlwings) and wb (workbook) objects. This avoids subprocess COM registration issues and allows direct manipulation of the live Excel instance.
- Sheet ownership model: Clear separation via the
FC -prefix. FinCo never modifies user sheets. - In-process execution: Scripts run in the same process as the engine, sharing the COM connection. No subprocess overhead or COM re-registration.
- Rollback on failure: Sheet state is snapshotted before each script. Failed scripts have their sheets automatically deleted.
- Conversation memory: Full conversation history is maintained within a session, enabling coherent multi-turn workflows.
- Audit trail: Only successful scripts are saved (with timestamps) to
.finco_<workbook>/scripts/.
finco/
engine.py # Core engine: agent loop, tool execution, Excel I/O
FinCo.bat # Windows launcher (double-click to start)
examples/
demo_workbook.xlsx # Example workbook with FinCo-generated analysis
docs/
SYSTEM_PROMPT_SPEC.md # Full behavioural specification (the "soul" of FinCo)
- Windows only -- relies on COM automation for live Excel interaction
- Requires desktop Excel -- does not work with Excel Online or LibreOffice
- API costs -- uses Claude Opus 4.6 (~$0.50-1.00 per prompt depending on workbook size)
- COM fragility -- some Excel installations have broken COM type libraries. Running an Office Online Repair usually fixes this
- No undo -- Excel's undo stack doesn't capture COM writes. FinCo can delete its own sheets, but fine-grained undo isn't available
The full system prompt that defines FinCo's personality, expertise, and constraints is in docs/SYSTEM_PROMPT_SPEC.md. This document covers:
- Sheet ownership and management rules
- How FinCo handles user edits on its sheets
- Formula integrity requirements
- Output formatting standards
- Communication style (terse by default, graduated transparency)
- Expertise scope and boundary behaviour
- Defensive verification principles
- Claude API (Anthropic) -- reasoning and script generation
- xlwings -- Python-Excel integration via COM
- NumPy -- numerical computation
MIT License. See LICENSE.
This project was designed and built in a single extended session as an exploration of AI-augmented financial workflows. It serves as a working prototype and personal tool, not a production product. The financial analysis space is rapidly evolving -- see the docs/SYSTEM_PROMPT_SPEC.md for the thinking behind the design decisions.