flatland-agent

Flatland Agent — describe a decision in your terminal, get a compiled financial model with live Excel export. Purpose-built for modeling, not a general-purpose assistant.

npx flatland-agent

What it is

A terminal client for the Flatland engine, scoped to financial modeling and quantitative reasoning. You describe a decision; your LLM decomposes it into typed drivers; the Flatland engine compiles it deterministically — types checked, assertions run, every formula live.

• Bring your own LLM key (Anthropic or OpenAI). Inference is billed to you, by your provider. Your provider key never touches Flatland servers — it is sent only to the provider you chose.
• Zero local computation. Every number you see is computed by the Flatland engine over HTTPS — the same public API any client uses. The terminal labels engine output (✓ … · engine output tables) distinctly from AI commentary (plain text), so you always know what the engine stands behind.
• Server-served scope. The agent's system prompt and tool surface are fetched from the Flatland API at launch — improvements ship without you reinstalling.

Scope (what Flatland Agent will and won't do)

Flatland Agent is fenced to financial modeling and quantitative decision support. It builds, compiles, and explains structured financial models, runs sensitivity and scenario analysis, and exports institutional spreadsheets. It will decline work outside that scope — it is not a general chatbot, not a code assistant, and not a substitute for professional financial, legal, or tax advice. Every figure it presents is engine output you can re-derive; every claim it cannot stand behind is labeled as commentary, not result.

Setup (~2 minutes)

1. Get a Flatland API key: https://flatlandfi.com/install (50 free answers, no card)
2. Run npx flatland-agent — the first-run wizard asks for:
   • your Flatland API key (fl_live_…), validated live before it is stored
   • your AI provider — Anthropic (default) or OpenAI
   • your provider API key, validated live before it is stored

Both keys are stored only in ~/.flatland/config.json (mode 0600), on your machine, nowhere else. Re-run setup any time with flatland-agent --setup.

Use

Flatland Agent opens as an open workspace — describe a decision, return to a saved model, and ask anything about it. There are no forced stages.

Starting up. If you have saved models, you'll get a quick menu:

What would you like to do?
  [1] New decision  — start from scratch
  [2] Load model    — continue working on an existing model
  or type a description to start immediately

Type a number, pick a saved model to reopen, or just start describing your decision — whatever you type becomes the first turn. With no saved models, the agent goes straight into a new session.

A new decision is framed first (what you're deciding, what makes it a clear go / no-go), then the agent builds and compiles the model. A loaded model opens directly in the workspace — no re-framing — with its decision brief restored so the agent stays oriented.

flatland> a DTC coffee brand: 3,000 subscribers at $24/mo, 35% COGS, ...
  ✓ Compiled — dtc_coffee · scenario: base · engine output
  ...

flatland> what matters most for gross profit?
  ✓ Sensitivity — target: gross_profit · ±10% · engine output
  ...

flatland> update CAC to $180
  ✓ Compiled — dtc_coffee · scenario: base · engine output
  ...

flatland> /export
  ✓ Exported — dtc_coffee.xlsx · saved to ./flatland/exports/ · live formulas

Commands: /save /load <name> /export [name] /sensitivity <target> /scenarios /model [id] /help /quit

Configuration

~/.flatland/config.json:

| key | meaning | |---|---| | provider | anthropic (default) or openai | | model | override the server-suggested model (e.g. gpt-4o) |

One-off model override: flatland-agent --model openai:gpt-4o

Requirements

• Node.js 18 or newer
• A Flatland API key and an Anthropic or OpenAI API key

Three ways to use Flatland

1. MCP plugin — Claude Code / Cursor: npx flatland-setup <key>
2. Flatland Agent CLI — this package: standalone terminal agent (npx flatland-agent)
3. HTTP API — programmatic: https://flatlandfi.com/docs/quickstart

MIT licensed (terminal client only; the Flatland engine/API is a separate proprietary service — see LICENSE).

Questions: [email protected] · https://flatlandfi.com/harness