TerraFin

TerraFin is terraform for financial research and investment decisions. It has four parts:

• Skills that give any AI agent (Claude Code, Codex, opencode) a financial analyst's toolkit.
• TerraFin Terminal, a web dashboard for browsing markets and companies.
  • Try it on the public demo Space, a maintainer-operated deployment.
• Its own agent, built on the same skills, that sees what you have open in the dashboard.
  • Ask "is this cheap?" on a stock page and it knows which ticker you mean.
  • In the filing reader it works from the section you are reading. In the DCF workbench it reads the inputs you entered.
• A data pipeline that fetches, caches and normalizes each source once, so one agent can sweep a whole watchlist or search a stock universe in a few calls.

Architecture

The skills and the harness read one capability registry, which runs on the data pipeline:

                    capability registry
                             │
          ┌──────────────────┴──────────────────┐
     skill layer                         TerraFin agent harness
     SKILL.md · /agent/api/* ·           sessions, model providers,
     terrafin-agent CLI · Python client  tool loop, view context
     → Claude Code, Codex, opencode      → chat panel on every page

Another agent can also call TerraFin's agent as a sub-agent: open a session and send it a question over HTTP (/agent/api/runtime/*) or the terrafin-agent CLI. It answers with the model configured in TerraFin.

git clone https://github.com/KiUngSong/TerraFin
cd TerraFin
./setup   # auto-detects Claude Code / Codex / opencode on PATH

Install pattern adapted from gstack: symlink-based, so git pull upgrades every host at once.

Pick your track

Use TerraFin's skills from your agentRun TerraFin's own agentContribute to TerraFin

Your agent (Claude Code, Codex, opencode, or anything that speaks HTTP) keeps its own model and loop, and calls TerraFin for data, valuation, and filings.

./setup --host claude    # or codex, opencode, auto

• Skills: what the skill layer is, install, the surfaces, discovery.
• Route summary: every capability with a route, grouped by kind.
• For External Agents: base URL, discovery, finding a series by name.
• Usage: request policy, route summary, the view-context read-only contract.

TerraFin's harness owns the loop: sessions, model providers, the tool loop, and view context, behind a chat panel on every page. Guru personas (Buffett, Marks, Druckenmiller) run as hidden subagents. Run it locally or as a public deployment.

• Getting Started: install, set a model key, run the server.
• Model Management: choose a provider and model.

How it works, for contributors: Agent Harness, The Agent Loop, Hosted Runtime, Architecture and Personas.

Working on TerraFin's internals? Start with the architecture and feature-integration rules so your change lands in the right layer.

• AGENTS.md: the entry point for agents and people working in this codebase.
• Feature Integration: where new logic lives across the data, analytics, interface and agent layers.
• Data Layer, Analytics, Analytics Notes: DCF cascade, turnaround math, indicator contract.
• Chart Architecture, Caching, Development Guide.

Also Useful

• Configuration
• Deployment & Operations
• Examples & Workflows
• License & Data Rights

Software rights are not data rights

TerraFin's code is MIT-licensed. That does not grant rights to Yahoo, SEC, FRED, private endpoints, or other upstream data sources. Read License & Data Rights before running a public deployment.

Read By Goal

If you want to...	Start here
install TerraFin and try it locally	Getting Started
understand the page routes and APIs	Interface Overview
call TerraFin from your own agent	Skills
run TerraFin's own agent	Agent Harness
add a provider, indicator, or feature	Data Layer and Feature Integration
operate the server in demo or private mode	Deployment & Operations
work on the repo itself	Development Guide