Architecture

Finn is a server and its clients, written in Agentica. The repository is an Agentica workspace: one folder per package.

finn      ─┐                        ┌─ LLM APIs (Anthropic, OpenAI, ...)
finn chat ─┼─ HTTP + SSE ── core ───┼─ tools: files, bash, Monty
your app  ─┘   (localhost)          └─ MCP servers (stdio, HTTP)

The server #

core is the server. It runs on 127.0.0.1, owns the sessions, and runs the agent loop of each: it sends the history to the model, runs the tool calls the model asks for, and streams every event to the clients that are attached.

  • One session is one actor. A turn runs in its own task, so a client that closes stops nothing.
  • A session is one file of JSON Lines (Sessions).
  • Extensions, skills, MCP tools and the approval are all extensions of the core, on one registry (Extensions).

One server runs per state folder: it holds a lock there, and a client that finds none starts one in the background.

The clients #

finn (tui_client) and finn chat (the cli package) are separate programs. They reach the server only through the client, protocol and sse packages, never through core. Any program that speaks the HTTP API is a client too.

The packages #

PackageWhat
sseServer-Sent Events: a parser and a writer
llmthe client for LLM APIs: OpenAI chat completions, OpenAI Responses and Anthropic Messages behind one API
mcpthe client for MCP servers, on stdio and streamable HTTP
protocolthe commands, replies and events between the server and its clients, with JSON codecs
montyPython scripts in pydantic's Monty sandbox, for code mode
bashthe simple commands of a bash line, read by tree-sitter-bash (a native module built on first use)
corethe server: agent loop, tools, approval, sessions, extensions
clientwhat the clients share: finding or starting the server, the HTTP calls, the event reader
clithe line-mode client
tui_clientthe full-screen client, on agentica-tui
examples/extensiona program that serves core with its own tool, wrapper and service

sse, llm, mcp, protocol, monty and bash depend on no server or client package, so each could move to a repository of its own. make coupling checks these rules.

For agents #

The guide is also published as Markdown: every page has a .md version, llms.txt lists the pages, and llms-full.txt holds all of them in one file.