Build Your Own HEARTH

When Claude Code (or any frontier agent) works on your machine today, it reaches for tools ad hoc — a shell command here, a file edit there — and none of it is captured anywhere you control. Two things are wrong with that picture:

• You're paying frontier prices for grunt work. Summarizing a log, drafting boilerplate, extracting fields from text — a local model on your own GPU does these at the cost of electricity, and your GPU is sitting right there.
• You have no record. When something goes sideways, or when you want to know what your agent actually did, there's nothing to query.

HEARTH fixes both with one small daemon: a local MCP gateway that exposes tools (file ops, a local-model generate, whatever you add) to Claude Code over HTTP, and writes every single call to a ledger — a JSONL file plus a SQLite index you can query. Claude does the thinking; your machine does the hands; the ledger is the receipts.

MCP (Model Context Protocol) is the open standard that makes this plug-and-play: Claude Code natively speaks it, so once your gateway is up, its tools appear in Claude like built-ins.

1. Download and run the Windows installer from https://ollama.com/download. It installs a background server on port 11434 that starts when you log in.
2. Open PowerShell and pull the model (~9 GB download):

ollama pull qwen2.5-coder:14b

mkdir C:\hearth
cd C:\hearth
python -m venv venv
.\venv\Scripts\pip install "mcp[cli]" httpx

Save this as C:\hearth\hearth_gateway.py. It exposes five tools over MCP and logs every call to both ledger.jsonl (append-only, human-readable) and ledger.sqlite (queryable). The logging decorator is the heart of HEARTH — everything that passes through the fire is remembered.

"""HEARTH: a minimal local MCP gateway with a tool-call ledger.

Tools appear in Claude Code automatically once wired via .mcp.json.
Every call is appended to ledger.jsonl and indexed in ledger.sqlite.
"""
import functools
import hashlib
import json
import sqlite3
import subprocess
import time
import uuid
from datetime import datetime, timezone
from pathlib import Path

import httpx
from mcp.server.fastmcp import FastMCP

HOME = Path(__file__).parent
SCOPE = Path("C:/")           # tools may only touch paths under here — tighten to your projects dir!
OLLAMA = "http://127.0.0.1:11434"
MODEL = "qwen2.5-coder:14b"

mcp = FastMCP("hearth")

# ---------- the ledger ----------
_db = sqlite3.connect(HOME / "ledger.sqlite", check_same_thread=False)
_db.execute("""CREATE TABLE IF NOT EXISTS events(
    id TEXT PRIMARY KEY, ts TEXT, tool TEXT, ok INTEGER,
    duration_ms REAL, args_preview TEXT, error TEXT)""")
_db.commit()


def _digest(obj) -> str:
    return "sha256:" + hashlib.sha256(
        json.dumps(obj, default=str, sort_keys=True).encode()).hexdigest()[:16]


def ledgered(fn):
    """Every tool call becomes one ledger event. This is the whole trick."""
    @functools.wraps(fn)
    def wrapper(*args, **kwargs):
        started = time.perf_counter()
        event = {
            "event_id": str(uuid.uuid4()),
            "ts": datetime.now(timezone.utc).isoformat(),
            "tool": fn.__name__,
            "args_preview": json.dumps(kwargs, default=str)[:300],
            "args_digest": _digest(kwargs),
            "ok": True, "error": None,
        }
        try:
            result = fn(*args, **kwargs)
            event["result_digest"] = _digest(result)
            return result
        except Exception as exc:
            event.update(ok=False, error=f"{type(exc).__name__}: {exc}")
            raise
        finally:
            event["duration_ms"] = round((time.perf_counter() - started) * 1000, 2)
            with open(HOME / "ledger.jsonl", "a", encoding="utf-8") as f:
                f.write(json.dumps(event) + "\n")
            _db.execute("INSERT INTO events VALUES(?,?,?,?,?,?,?)",
                        (event["event_id"], event["ts"], event["tool"],
                         int(event["ok"]), event["duration_ms"],
                         event["args_preview"], event["error"]))
            _db.commit()
    return wrapper


def _in_scope(path: str) -> Path:
    p = (SCOPE / path).resolve() if not Path(path).is_absolute() else Path(path).resolve()
    if not str(p).lower().startswith(str(SCOPE.resolve()).lower()):
        raise ValueError(f"path {p} is outside HEARTH scope {SCOPE}")
    return p


# ---------- the tools ----------
@mcp.tool()
@ledgered
def hearth_status() -> dict:
    """HEARTH self-test: ledger location and total event count."""
    n = _db.execute("SELECT COUNT(*) FROM events").fetchone()[0]
    return {"hearth": "burning", "ledger": str(HOME / "ledger.jsonl"), "events": n}


@mcp.tool()
@ledgered
def read_file(path: str, max_bytes: int = 200_000) -> dict:
    """Read a text file (scope-checked)."""
    data = _in_scope(path).read_text(encoding="utf-8", errors="replace")
    return {"path": path, "truncated": len(data) > max_bytes, "content": data[:max_bytes]}


@mcp.tool()
@ledgered
def write_file(path: str, content: str) -> dict:
    """Write a text file (scope-checked); creates parent dirs."""
    p = _in_scope(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(content, encoding="utf-8")
    return {"path": str(p), "bytes": len(content)}


@mcp.tool()
@ledgered
def run_tests(directory: str, command: str = "python -m pytest -q --tb=short") -> dict:
    """Run a test command in a directory; returns a compact digest, never full output."""
    p = subprocess.run(command, cwd=_in_scope(directory), shell=True,
                       capture_output=True, text=True, timeout=600)
    tail = (p.stdout + p.stderr).strip().splitlines()[-15:]
    return {"exit_code": p.returncode, "ok": p.returncode == 0, "tail": tail}


@mcp.tool()
@ledgered
def local_generate(prompt: str, system: str = "", max_tokens: int = 1024) -> dict:
    """Generate text with the LOCAL model (free, runs on your GPU).
    Use for: summarizing, extracting, boilerplate, drafts, classification."""
    r = httpx.post(f"{OLLAMA}/api/generate", json={
        "model": MODEL, "prompt": prompt, "system": system or None,
        "stream": False, "options": {"num_predict": max_tokens}}, timeout=300)
    r.raise_for_status()
    body = r.json()
    return {"text": body.get("response", ""),
            "model": MODEL,
            "tokens_in": body.get("prompt_eval_count"),
            "tokens_out": body.get("eval_count"),
            "duration_ms": round(body.get("total_duration", 0) / 1e6)}


if __name__ == "__main__":
    mcp.settings.host = "127.0.0.1"
    mcp.settings.port = 8710
    mcp.run(transport="streamable-http")

Before running: change SCOPE from C:/ to the folder your projects live in (e.g. C:/work). The scope check is your seatbelt — tools refuse to touch anything outside it.

Two small files in the project folder where you use Claude Code (e.g. C:\work\myproject):

1 · .mcp.json — tells Claude Code the gateway exists:

{
  "mcpServers": {
    "hearth": {
      "type": "http",
      "url": "http://127.0.0.1:8710/mcp"
    }
  }
}

2 · CLAUDE.md — add a section telling Claude when to use it. Without this, Claude has the tools but no habit:

## Local-first offload (HEARTH)

A local model is available via the `hearth` MCP server's `local_generate`
tool, plus ledgered file/test tools. Before spending frontier tokens on a
self-contained sub-task, delegate it to the local model:

- summarizing / condensing a file, log, or diff you have already read
- extracting structured data (fields, lists, JSON) from unstructured text
- generating boilerplate (config, test scaffold, docstring, commit draft)
- classifying / labeling / yes-no triage over a chunk of text

Rules: the local model has NO repo access — pass all needed context in the
prompt. If the output is unusable, do the task yourself; one retry max.
First call after boot pays a model-load tax (~10s) — that is not a failure.

Save as C:\hearth\start-hearth.cmd:

@echo off
cd /d C:\hearth
echo [%date% %time%] HEARTH starting >> hearth.log
venv\Scripts\python.exe hearth_gateway.py >> hearth.log 2>&1

Register it to run at logon (plain PowerShell, no admin needed):

$action  = New-ScheduledTaskAction -Execute 'C:\hearth\start-hearth.cmd'
$trigger = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"
Register-ScheduledTask -TaskName 'Hearth' -Action $action -Trigger $trigger

You now have the kernel of something bigger. In rough order of payoff:

• Add per-caller keys — an X-Hearth-Key header and a callers.json turn "who did what" from a guess into a ledger field.
• Add coarser tools — a git_commit_push that stages/commits/pushes in one audited call; a lint digest; whatever your inner loop repeats.
• Query your economics — the SQLite ledger already knows how many calls went to the local model vs. how long they took. One evening of SQL gives you a dashboard proving what your GPU is saving you.
• The learning loop — in the full HEARTH design, the ledger feeds a projection layer that derives what your machines are actually capable of from evidence, and routes each task to the cheapest runner that can do it. That's a bigger story — the ledger you built today is its foundation.

Light it, keep it lit, and let everything cook on the same fire.