Abellegese/caseflow

Desktop-first finance operations with auditable agent workflows

Review exceptions, investigate vendor exposure, ingest evidence, call finance tools, and generate report artifacts from a local Tauri desktop workspace.

Why CaseFlow? · Architecture · Installation · Desktop · Agent Runtime · Release · Docs · Contributing

CaseFlow is a local-first finance workspace for teams that need more than a chat box over accounting data. It combines deterministic finance workflows with a bounded agent runtime so operators can review source evidence, inspect every tool call, approve risky actions, and keep the final report tied to the conversation that produced it.

CaseFlow helps finance operators:

• Review open exceptions across invoices, vendors, customers, reconciliations, documents, and risk signals.
• Investigate with evidence using uploaded PDFs, office files, images, extracted document layouts, citations, and stored artifacts.
• Stream agent progress cleanly through one Agent Progress accordion that records thinking, tool calls, results, approvals, and report artifacts.
• Connect finance systems through typed connector contracts and MCP resources for ERPNext, Odoo, Google Workspace, custom ledgers, market references, cap tables, and SQL databases.
• Package the full workspace as a Linux desktop app with a Tauri host, local backend, React UI, document-ingestion sidecar, and finance extension resources.

Desktop runtime: Tauri host -> document-ingestion sidecar -> Fastify backend -> React UI

The desktop host starts local services, injects a per-launch session token, resolves packaged resources, and serves the built React app against the loopback backend.

Agent workflow: Conversation -> planning -> tools/MCP/connectors/documents -> approvals -> artifacts

Agent actions are bounded by ordinary TypeScript services. Tool calls, tool results, progress events, approvals, and report files are persisted with the active conversation.

Extension boundary: runtime packages -> finance extension -> installed plugin/MCP capabilities

The platform runtime lives in src/, reusable contracts live in packages/runtime-api and packages/runtime-sdk, and finance-specific behavior lives in extensions/finance.

See the deep dive: Architecture ->

Install these before running CaseFlow locally:

• Node.js 22 recommended; Node.js 20 is the practical minimum for most scripts.
• pnpm for workspace packages, UI, desktop, docs, and extensions.
• npm for the backend package in src/.
• Rust stable for the Tauri desktop host.
• Python 3.12 and uv for the document-ingestion sidecar.
• Linux desktop packaging dependencies required by Tauri when building .deb.
• Git submodules for vendored MCP resources.

On Ubuntu/Debian release hosts, install the Tauri packaging libraries:

sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev

Initialize submodules:

git submodule update --init --recursive

Install workspace dependencies:

pnpm install
cd src && npm install

Allow the native sqlite binding to build:

pnpm --filter caseflow-backend rebuild better-sqlite3

make tauri-dev

This starts the Vite UI when needed, prepares desktop resources, launches Tauri, and lets the Rust host start the backend and document-ingestion sidecar.

make tauri-package-deb

The artifact is written to:

desktop/src-tauri/target/release/bundle/deb/

Find the newest Debian package:

find desktop/src-tauri/target/release/bundle -maxdepth 3 -type f -name 'CaseFlow*.deb' | sort

Install locally:

sudo apt install ./desktop/src-tauri/target/release/bundle/deb/CaseFlow_0.5.0_amd64.deb

More details: Tauri Desktop Runtime ->

Run the backend:

cd src
npm run dev

Run the React app:

cd ui
pnpm run dev

Default local endpoints:

• UI: http://localhost:3000
• Backend: http://localhost:8000

The agent web search tool uses SearXNG by default. Start the local JSON-enabled instance with:

docker compose up -d searxng

The backend default SEARXNG_URL is http://localhost:8080 for local runs. In Docker Compose, the app container uses http://searxng:8080.

• Document-ingestion sidecar: http://localhost:8002 when enabled

CaseFlow uses a bounded DeepAgents/LangGraph runtime for finance investigations. The agent can read conversation context, call typed tools, query MCP resources, inspect documents, request approvals, and write report artifacts.

Progress is intentionally one stream:

• the active thinking message belongs in the Agent Progress accordion header
• new live thinking replaces the previous live thinking text while the response is running
• tool calls and tool results append to the same progress history
• completed progress events and report artifacts persist with the conversation
• the accordion collapses by default after the final answer is ready

Runtime docs:

• Agent Runtime ->
• Frontend Agent Experience ->
• Agent Guardrails ->

CaseFlow reads runtime configuration from environment variables and persisted settings at CASEFLOW_SETTINGS_FILE, which defaults to CASEFLOW_HOME/settings.json.

Common variables:

CASEFLOW_BACKEND_HOST=127.0.0.1
PORT=8000
CASEFLOW_HOME=$HOME/.caseflow
DATABASE_URL=sqlite://$HOME/.caseflow/data/caseflow.db
CASEFLOW_BACKEND_DATA_DIR=$HOME/.caseflow/data
CASEFLOW_SETTINGS_FILE=$HOME/.caseflow/settings.json
DOCUMENT_INGESTION_ENABLED=true
DOCUMENT_INGESTION_URL=http://127.0.0.1:8002
OPENAI_API_KEY="<key>"
ANTHROPIC_API_KEY="<key>"
SEARXNG_URL="http://127.0.0.1:8080"

Desktop mode also sets runtime paths such as:

CASEFLOW_DESKTOP_SESSION_TOKEN="<generated-per-launch>"
CASEFLOW_PACKAGE_ROOT="<resources>/backend"
CASEFLOW_MCP_ROOT="$HOME/.caseflow/mcp-servers"
CASEFLOW_BACKEND_DATA_DIR="<app-data>/data"

See the full configuration guide: Configuration ->

Installed MCP server packages live under:

~/.caseflow/mcp-servers/<server-id>/

Installed packages can cover:

• ERPNext and ERPNext CRM
• Odoo
• Google Workspace
• custom ledger data
• market price references
• equity cap table references
• Google MCP Toolbox
• Fayda platform demo

Connector docs: Connectors ->

Run these checks before merging or releasing:

cd src && npm run build
cd src && npm test
cd ui && pnpm run test && pnpm run build
cd docs-site && pnpm run test:search && pnpm run build && pnpm run typecheck
cd desktop && pnpm test

Check desktop resource staging and sqlite native binding:

pnpm --filter caseflow-desktop run prepare:resources
node -e "const Database=require('./desktop/resources/backend/node_modules/better-sqlite3'); const db=new Database(':memory:'); db.close(); console.log('desktop resource binding ok')"

Create the 0.5.0 release commit and tag from staged changes:

git add -A
./scripts/create-release.sh 0.5.0

Build the Linux package:

./scripts/tauri-package.sh --deb

Merge and publish:

git checkout main
git pull origin main
git merge refactor/core-sdk-extension-boundary
git push origin main
git push origin v0.5.0
gh release create v0.5.0 \
  desktop/src-tauri/target/release/bundle/deb/CaseFlow_0.5.0_amd64.deb \
  --notes-file RELEASE_NOTES.md

Release docs:

• Release Notes ->
• Release Notes 0.5.0 ->
• Release and Installation ->

Start the docs site:

cd docs-site
pnpm run start

Useful pages:

• Overview
• Architecture
• Desktop Runtime
• Release and Installation
• Agent Runtime
• Configuration
• Operations
• API Reference

CaseFlow 0.5.0 is packaged for local desktop-first use. Before exposing the backend beyond loopback or running a hosted multi-user deployment, add:

• route-level authentication and authorization
• encrypted secret storage
• database backup and artifact retention policy
• central logs and traces
• connector-specific rate limiting and retry policy
• signed installers for target platforms

Keep changes inside the relevant boundary:

• platform runtime changes in src/
• React UI changes in ui/
• desktop host and package changes in desktop/
• finance behavior in extensions/finance/
• shared extension contracts in packages/runtime-api and packages/runtime-sdk

Before pushing, run the verification commands for the area you changed and update docs when behavior or release workflow changes.