Finch — Local AI Coding Assistant

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

Local-first AI coding assistant · Co-Lisp + Co-Forth vocabulary · MemTree memory

WRITTEN IN RUST SINGLE BINARY CO-LISP + CO-FORTH MEMTREE MEMORY WORKS OFFLINE PRIVATE BY DEFAULT

zsh — finch — 80×24

▋

INSTALL NOW ★ VIEW ON GITHUB

// THE PROBLEM

Constant internet connection required
Every query costs API money
Your code goes to the cloud
No learning from your patterns
Ongoing API costs for every single query

// WITH FINCH

Fully offline after first model download
Zero marginal cost per query
Local models keep code on your machine
Build reusable typed Co-Lisp/Co-Forth vocabulary
Recall past context with MemTree semantic search

// 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.

GrokOpenAI APIGeminiMistralGroqClaudeLocal 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 with local neural semantic search. A compact embedding model finds relevant past context even when the wording changes, and stable recall provenance shows where remembered context came from.

⬡

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.

// 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
  ▐████████▌  Qwen-2.5-7B · ready
  ▝▜██████▛▘  ~/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"

BACKGROUND DAEMON — OPENAI-COMPATIBLE ENDPOINT

Finch starts a loopback-only daemon at 127.0.0.1:11435. VS Code and other OpenAI-compatible clients send requests to Finch first; Finch then routes them through the configured local or cloud-backed profile.

In VS Code, open Chat: Manage Language Models, choose Add Models → Custom Endpoint, select Chat Completions, and use the Finch URL and client key shown below. Let the endpoint discover model IDs instead of hardcoding one.

# 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 CUSTOM ENDPOINT

API type    Chat Completions
URL         http://127.0.0.1:11435/v1
API key     Finch client key
Models      discovered from /v1/models

Request path:
VS Code → local Finch daemon
        → selected Finch profile
        → local model or cloud provider

The API stays on loopback by default. Finch's mDNS feature advertises restricted Brain collaboration—not this model endpoint—and does not expose secrets.

// FEATURES

▣

WORKS OFFLINE

6 model families via ONNX Runtime — Qwen, Llama, Gemma, Mistral, Phi, DeepSeek. Candle backend available on Linux. No network round trip, subscriptions, or provider rate limits.

◈

NATIVE ACCELERATION

ONNX Runtime's CoreML execution provider on Apple Silicon (M1–M4) — dispatches ops to ANE or GPU where CoreML's op set allows. Linux uses CUDA, ROCm, or CPU. Candle (Metal/CPU) is available as an alternative backend on Linux; Metal is not viable on macOS for current model families.

◉

PRIVACY FIRST

No telemetry or cloud sync. Use a local model to keep code on your machine, or explicitly configure a cloud provider when you want one.

▶

INSTANT STARTUP

The REPL appears in under 100ms. When local inference is enabled, the model loads in the background; a configured cloud profile can remain available while it starts.

◆

AGENTIC TOOLS

Read, Glob, Grep, Bash, WebFetch. A multi-turn agentic loop with permission checks; use local or explicitly configured cloud models.

◇

LORA FINE-TUNING

Weighted feedback collection infrastructure is in place. LoRA adapter training and loading is the next major milestone — contributions welcome.

⬡

ITERATIVE PLANNING

/plan <task> runs an adversarial multi-persona critique loop. Seven roles review each draft; must-address issues block convergence. Compatible configured profiles can participate through normalised structured critique output.

// HOW IT WORKS

  ┌──────────────────────────────────────────────────────┐
  │                     YOUR REQUEST                     │
  └───────────────────────────┬──────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   FINCH ROUTER   │
                    └─────────┬────────┘
              CLOUD           │               LOCAL
                 ┌────────────┴─────────────────┐
                 ▼                              ▼
        ┌────────────────┐    ┌──────────────────────────────────┐
        │ CLOUD PROFILE  │    │       LOCAL MODEL PROFILE        │
        │Claude · OpenAI │    │    Qwen · Llama · Gemma · Phi    │
        │ Gemini · Grok  │    │        Mistral · DeepSeek        │
        │ Mistral · Groq │    │   ONNX Runtime / Candle backend  │
        └───────┬────────┘    └─────────────────┬────────────────┘
                │                               │
                └───────────────┬───────────────┘
                                ▼
                      ┌──────────────────┐
                      │     RESPONSE     │
                      └──────────────────┘

INSTALL & RUN

One curl command installs the binary. The REPL starts in under 100ms. Configure a provider profile or choose local inference in finch setup.

QUERY LOCALLY

Choose a local profile to keep inference on your machine. On Apple Silicon, ONNX Runtime's CoreML execution provider dispatches supported ops to ANE or GPU. Linux supports CUDA and other execution providers. Cached local models work offline.

USE AGENTIC TOOLS

Finch can read files, search your codebase, run shell commands, and fetch web pages — all with your approval. Full multi-turn agentic loop, just like Claude Code.

LORA COMING SOON

Feedback collection infrastructure is ready (Ctrl+G / Ctrl+B). LoRA fine-tuning to adapt the model to your codebase is the next major milestone.

// SUPPORTED MODELS

Local (ONNX Runtime — runs on your hardware)

FAMILY	SIZES	FORMAT	NOTES
Qwen 2.5	1.5B · 3B · 7B · 14B	ONNX	Recommended · auto-selected by RAM
Llama 3	1B · 3B · 8B	ONNX	Meta · general purpose
Gemma 2/3	1B · 2B · 9B	ONNX	Google · strong reasoning
Mistral	7B	ONNX	Mistral AI · efficient · models via microsoft/
Phi-3/4	3.8B · 14B	ONNX	Microsoft · small + capable
DeepSeek Coder	1.3B · 6.7B	ONNX	Optimised for code generation

CoreML execution provider on Apple Silicon (M1–M4) · CUDA/ROCm/CPU on Linux via ONNX Runtime · Qwen auto-selected by RAM by default

Cloud providers (bring your own API key)

PROVIDER	COST TIER	BEST FOR	NOTES
Grok (xAI)	Usage-based API	Daily use · coding · tool calls	API billing is separate from Grok/X subscriptions · console.x.ai
Groq	$	Speed · batch processing	Low-latency inference · runs open models on custom hardware
Gemini (Google)	$ (Flash) · $$ (Pro)	Long context · multimodal	Gemini Flash is extremely cost-effective · 1M token context window
Mistral	$–$$	European data residency · open weights	Mistral Large for serious work · Codestral for code
Claude (Anthropic)	$$–$$$	Complex reasoning · long tasks · plan mode	Haiku is budget · Sonnet is the sweet spot · best tool use quality
OpenAI API	Varies by model	Configurable model ID · reasoning profiles	Choose an explicit model ID supported by OpenAI Chat Completions and available to your Platform account

Switch between configured profiles with /model <name> (/provider remains a compatibility alias) · Conversation history is preserved · Streaming and tool support vary by provider and model · Conformance coverage is ongoing · OpenAI Platform API keys are supported; ChatGPT subscription login is not yet shipped

// 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.

01
Installs the binary to /usr/local/bin/finch by default; set FINCH_INSTALL_DIR to choose another directory
02
Run finch — the REPL starts in under 100ms
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 — local-first AI coding assistant