Finch — Experimental Terminal Agent Runtime

██████╗ ██╗███╗   ██╗ ██████╗██╗  ██╗
██╔════╝██║████╗  ██║██╔════╝██║  ██║
█████╗  ██║██╔██╗ ██║██║     ███████║
██╔══╝  ██║██║╚██╗██║██║     ██╔══██║
██║     ██║██║ ╚████║╚██████╗██║  ██║
╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝

Experimental terminal coding assistant · typed Lisp + Co-Forth · durable named Brains

WRITTEN IN RUSTSINGLE BINARYTYPED LISP + CO-FORTHDURABLE BRAINSCAPABILITY-CHECKED TOOLSMCP CLIENTBOUNDED HTTP APIEXPERIMENTAL

zsh — finch — 80×24

▋

INSTALL NOW ★ VIEW ON GITHUB

// THE PROBLEM

Opaque one-tool-at-a-time agent actions
Conversation history disconnected from executable state
Different workflows for every provider and tool
Implicit host access that is hard to audit
Configuration mistaken for tested integration support

// WITH FINCH

Typed programs validate before host effects run
Named Brains preserve conversation and VM state
Configured providers share one terminal workflow
Tool effects cross an explicit approval boundary
Experimental integrations are labeled honestly

// PROGRAMS, NOT PROMISES

Finch and its models share an executable vocabulary.
Co-Lisp and Co-Forth turn an agent's intent into typed, verified programs instead of prose that merely describes an action.

◉

ONE SHARED PROGRAM RUNTIME

Readable Co-Lisp and compact, concatenative Co-Forth lower into the same typed IR, verifier, and runtime. Finch checks stack shapes, types, and declared effects before execution, then records program output and diagnostics in the conversation.

◆

WHY THIS HELPS AGENTS

Exact signatures and a searchable vocabulary give a model concrete operations to compose. Invalid programs fail before host effects run, with structured compiler diagnostics the same model can use for one bounded repair. That makes mistakes visible and reviewable without pretending every provider is equally conformant.

▤

VOCABULARY THAT PERSISTS

Define and inspect typed words, then reuse them in later programs. Named Brains can preserve committed definitions and restore reducible VM checkpoints across daemon restarts.

◈

CAPABILITIES, NOT AMBIENT ACCESS

File, process, network, MCP, and agent operations cross explicit typed host boundaries. The runtime infers capability requirements and preserves approval and effect identity through suspend and resume.

⬡

MODEL-FACING DISCOVERY

Models can search the compact vocabulary and inspect exact signatures, documentation, effects, and source before composing a program. A bounded repair turn can correct rejected source without hiding the original diagnostic.

// THE OPEN AGENT

Claude Code is great — if you're on Claude.
Finch gives configured cloud and local models one consistent terminal workflow.

ClaudeOpenAI APIChatGPT sub.GrokGeminiMistralGroqLocal ONNX

⬡

COMMON CONVERSATION INTERFACE

Configured provider profiles use the same multi-turn conversation interface. Streaming and tool support vary by provider, model, and adapter, and cross-provider conformance coverage is still expanding. Switch profiles with /model <name>.

▤

CLAUDE.MD + FINCH.MD

Auto-loads project instructions by walking the filesystem from root to your working directory — exactly like Claude Code. FINCH.md is a vendor-neutral alias: one instruction file that works with Finch, Claude Code, Cursor, or any assistant that respects it.

◫

MEMTREE MEMORY

Persistent hierarchical memory in local SQLite, searched by embedding similarity so recall survives a change of wording, with provenance showing where remembered context came from. A compact neural embedding model is used when it is already in the Hugging Face cache; otherwise Finch falls back to TF-IDF over word and character n-grams.

⬡

MCP TOOLS

Finch is an MCP client: configure stdio servers for databases, APIs, or internal tools. Discovered operations become typed, namespaced vocabulary with schema validation and capability checks.

▶

AUTONOMOUS MODE

Run headlessly on a task backlog — a named agent identity commits its own work, logs everything to JSONL, and can reflect on completed work to update its own system prompt. Data structures and CLI command are in place; end-to-end testing in progress.

// HOW FINCH DIFFERS

An evidence-backed comparison across eighteen capabilities and nine coding agents.
Every mark is explained and sourced, including the rows Finch does not win.

EXPLORE THE FULL COMPARISON

// BRAINS: MORE THAN A NAMED SESSION

A named session gives a conversation a name so you can find it again. A Finch Brain keeps the working state behind that conversation, too.

Think of it as a durable room for a piece of work. Close Finch, restart the daemon, or attach from another permitted console: the Brain keeps its identity and resumes from its recorded state instead of asking the model to reconstruct everything from a summary.

NAMED SESSION

A LABEL FOR A CONVERSATION

A recognizable name
Conversation history you can reopen
Continuity for your next chat

A FINCH BRAIN ADDS

THE STATE NEEDED TO KEEP WORKING

An ordered, durable event log
Committed Co-Lisp/Co-Forth definitions and VM checkpoints
Queued, active, completed, and interrupted runs
A binding to the machine and workspace that own its tools
Role-based attachments for collaborators

↻

RESUME, DON'T RECREATE

A Brain survives client exits and daemon restarts. Reattach to recover its visible history, committed runtime state, and any work that needs attention.

⌘

ONE WORKSPACE, CLEAR AUTHORITY

The Brain remembers which environment owns the workspace. If that runner is offline, work waits visibly instead of running on the wrong machine or inventing a result.

◎

SHARE THE SAME CONTEXT

Drivers, consultants, and observers can attach with distinct roles. Everyone sees the same ordered record, while workspace access and approvals remain explicit.

THE BASIC FLOW

CREATE IT ONCE. ATTACH WHEN YOU NEED IT.

Your normal console already has a home Brain. Create another when you want a durable context for a project, investigation, or long-running task.

# Create a Brain in the current environment
> /brain create parser-refactor

# Work in it, inspect its runs, or return later
> /brain attach parser-refactor
> /brain runs
> /brain detach

# See every named Brain
> /brains

Brains and MemTree solve different problems: a Brain preserves the exact state of one continuing body of work. MemTree searches across past conversations to recall relevant knowledge, even when you use different words.

// USE IT YOUR WAY

INTERACTIVE REPL

Full TUI with scrollback, streaming, plan mode, and agentic tool use. Ghost text autocomplete. Session history. Inline dialogs with keyboard navigation and custom-response text entry.

$ finch

      ▄▄▄▄▄▄
    ▗▟█●██▙►  finch v0.7.30
  ▐████████▌  claude-sonnet-4-5 · work
  ▝▜██████▛▘  ~/repos/myproject
      ╥  ╥
     ╱    ╲

> How do I use lifetimes in Rust?▋

SINGLE QUERY + PIPE

Scriptable one-shot queries. Pipe stdin directly into finch. Works great in shell scripts, CI, and editor integrations.

$ finch query "What is a Rust lifetime?"

$ echo "Explain this error" | finch

$ cat error.log | finch "what went wrong?"

$ git diff | finch "write a commit message"

OPENAI-SHAPED API — A BOUNDED SUBSET

Finch starts a loopback-only daemon at 127.0.0.1:11435 serving GET /v1/models, POST /v1/chat/completions, and POST /v1/messages, plus health, metrics, and Finch-specific feedback, node, and Brain routes. Clients send requests to Finch first; Finch routes them through the selected profile. This is not the full OpenAI API and does not implement /v1/responses; a client that needs a route outside this set will not work.

VS CODE · SETUP BELOWCURL · TWO ROUTESOPENAI SDKs · SUBSET ONLYCONFORMANCE · IN PROGRESS

VS Code setup: run Chat: Manage Language Models, choose Add Models → Custom Endpoint, name the group Finch, enter the client key from finch setup → Settings, and select Chat Completions. Use the provider configuration below so VS Code discovers your Finch profile IDs automatically.

# Finch's managed local endpoint
URL=http://127.0.0.1:11435/v1

# Find the client key in `finch setup` → Settings.
# Then verify Finch and discover configured profiles:
$ curl -sS -H "Authorization: Bearer $FINCH_CLIENT_KEY" \
    "$URL/models"

// VS Code: chatLanguageModels.json
[
  {
    "name": "Finch",
    "vendor": "customendpoint",
    "apiKey": "${input:finchClientKey}",
    "apiType": "chat-completions",
    "url": "http://127.0.0.1:11435/v1"
  }
]

Request path: VS Code → local Finch daemon → selected Finch profile → local model or cloud provider. “Custom Endpoint” is VS Code's name for this setup; Finch exposes the OpenAI-compatible API. VS Code's BYOK chat does not require a Copilot plan, but some separate VS Code features still do. The API stays on loopback by default, and Finch's mDNS feature advertises restricted Brain collaboration—not this model endpoint. VS Code language model documentation ↗

// FEATURES

▣

LOCAL MODEL LOADERS EXPERIMENTAL

ONNX Runtime and Candle loaders, plus local profiles for several model families, are in the source. A configured local profile does not yet guarantee a query is routed locally. Use --cloud-only to skip local loading entirely.

◈

EXECUTION PROVIDERS EXPERIMENTAL

The loaders select CoreML on Apple Silicon and CUDA, ROCm, or CPU on Linux. Which operations actually reach a given accelerator depends on the model and the runtime's op coverage; Finch publishes no measured throughput.

◉

NO TELEMETRY

Finch has no telemetry or cloud sync of its own. That is not the same as offline: prompts, selected context, and tool results sent to a configured cloud provider leave the machine and are governed by that provider.

▶

MEASURED STARTUP

Finch times its own path from main to the first keystroke it will act on. Set FINCH_STARTUP_TIMINGS to get the phase timeline, with anything over a 150 ms budget flagged. The number excludes loader and Tokio runtime construction, so it is a proxy for process entry, not process entry.

◆

AGENTIC TOOLS

Read, glob, grep, edit, patch, write, bash, web fetch, spreadsheets, plan, and todo. A multi-turn loop where known read-only operations can run unprompted and mutating ones are reviewed or denied by policy.

◇

LORA TRAINING DISABLED

Automatic LoRA training is switched off. Weighted Ctrl+G/Ctrl+B feedback is stored privately and is never a training trigger. Preserved legacy queues and adapters are not processed.

⬡

ITERATIVE PLANNING

/plan <task> runs an adversarial multi-persona critique loop. Six critique personas activate by deterministic keyword rules and review each draft; must-address issues block convergence. Compatible configured profiles participate through normalised structured critique output.

// HOW IT WORKS

  ┌──────────────────────────────────────────────────────┐
  │                     YOUR REQUEST                     │
  └───────────────────────────┬──────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   FINCH ROUTER   │
                    └─────────┬────────┘
              CLOUD           │               LOCAL
                 ┌────────────┴─────────────────┐
                 ▼                              ▼
        ┌────────────────┐    ┌──────────────────────────────────┐
        │ CLOUD PROFILE  │    │  LOCAL PROFILE  ·  EXPERIMENTAL  │
        │Claude · OpenAI │    │    Qwen · Llama · Gemma · Phi    │
        │ Gemini · Grok  │    │        Mistral · DeepSeek        │
        │ Mistral · Groq │    │   ONNX Runtime / Candle loaders  │
        │  ChatGPT sub.  │    │  routing not yet guaranteed (#74)│
        └───────┬────────┘    └─────────────────┬────────────────┘
                │                               │
                └───────────────┬───────────────┘
                                ▼
                      ┌──────────────────┐
                      │     RESPONSE     │
                      └──────────────────┘

INSTALL & RUN

Build from a clean checkout, or install a release artifact. Configure a provider profile — API key, ChatGPT subscription device login, or local inference — in finch setup.

OR TRY A LOCAL PROFILE

Configure a local profile to attempt inference on your own hardware, via ONNX Runtime (CoreML on Apple Silicon, CUDA/ROCm/CPU on Linux) or Candle. Local bootstrap and selection are experimental; verify where a query actually ran before relying on it.

USE AGENTIC TOOLS

Finch reads files, searches your codebase, proposes edits, runs shell commands, and fetches web pages. Mutating and otherwise sensitive operations cross an explicit approval boundary; treat generated diffs and commands as untrusted until you have reviewed them.

KEEP WORK IN A BRAIN

Give a long-running piece of work a named Brain so its conversation, committed Co-Lisp/Co-Forth definitions, and VM checkpoints survive closing the terminal or restarting the daemon.

// SUPPORTED MODELS

Cloud providers, subscription access, and experimental local ONNX profiles.
Support levels and routing limitations are documented without treating configuration as conformance.

VIEW MODEL AND PROVIDER SUPPORT

// CONFIGURE WITH `finch setup`

When Finch needs configuration and cannot detect provider credentials, it opens the terminal setup wizard automatically.
Run finch setup later—or /setup inside the REPL—to review and change the saved configuration.

LOOK & FEEL

Choose the terminal theme and preview Finch's presentation before saving.

MODEL SETUP

Configure a primary profile plus optional tool profiles across cloud APIs, discovered remote Finch daemons, and local inference. Enter an explicit model ID or refresh a provider's authenticated catalogue where supported; existing Ollama profiles are preserved when setup is reopened.

STYLE & SETTINGS

Select a persona and review tool approval, streaming, local-model, daemon, discovery, API-access, and memory display settings in one place.

✓

SAVE WITHOUT LOSING YOUR WORK

After closing any nested editor or overlay, press Ctrl+S to save from any top-level wizard tab. Escape closes the current interaction or moves back first; leaving the wizard asks before discarding unsaved changes. Finch writes the result to ~/.finch/config.toml.

// INSTALL

$curl -fsSL https://raw.githubusercontent.com/darwin-finch/finch/main/scripts/install.sh | bash

macOS Apple Silicon · Linux x86_64 · PolyForm Noncommercial ·view script ↗

One self-contained binary — no Node, no Python, no Docker, no runtime dependencies.

Release artifacts can lag behind main, and installer reliability is still being worked on. Building from a clean checkout is the most reliable way to try the current code.

01
Installs the binary to /usr/local/bin/finch by default; set FINCH_INSTALL_DIR to choose another directory
02
Run finch — set FINCH_STARTUP_TIMINGS if you want its measured time-to-ready
03
Run finch setup to choose model profiles, theme, persona, and runtime settings
04
If you enable local inference, Finch downloads the selected model in the background on first run

// or build from source

$git clone https://github.com/darwin-finch/finch && cd finch && cargo build --release

// CONTRIBUTE

Finch is early-stage and actively looking for contributors. All issues are tracked on GitHub.

good first issue

Finch — experimental terminal agent runtime and coding assistant