Forkmind

ForkMind 🧠

Local-first LLM branching, debugging & context offloading

Treat your AI conversation history like a Git repository — capture every call, branch from any turn, and diff outcomes side by side. All on your machine.

Try in 10s · Features · Install · Quick start · MCP · Capsules

What you're seeing: the conversation DAG with a fork off the debug turn,

the node inspector (request/response, tokens, provenance), and the ⇄ Compare

view diffing two branches with per-token deltas. The green ● streaming

badge shows live capture — nodes appear as they're recorded.

ForkMind captures every LLM call into a local .forkmind/ directory, visualizes the conversation as a Directed Acyclic Graph (DAG), and lets you branch, diff, and replay from any point in the history. Works with any OpenAI-compatible API, defaulting to free, open-source models via Ollama — also Anthropic, Groq, OpenRouter, Together, vLLM, and LM Studio.

Static screenshot

---

Why

Debugging agentic / tool-calling flows means re-running the same prompt with tiny tweaks over and over, then scrolling through terminal logs to see what changed. ForkMind records each run as a node in a conversation tree, so instead of re-reading logs you see the whole history, branch from any turn, and compare outcomes visually.

Everything is plain JSON on disk. No database, no account, no telemetry — nothing leaves your machine except the LLM call you were already making.

---

Features

• Capture — every LLM call is recorded to a plain JSON node under .forkmind/. Works from any language via an OpenAI-compatible proxy; streaming responses are reconstructed (text and fragmented tool-call args).
• DAG dashboard — a React Flow canvas draws the whole conversation as a tree: every turn, tool call, model, and token count, with the node inspector one click away.
• Live capture stream — nodes pulse into the DAG the instant they're recorded (Server-Sent Events), so you can watch an agent think in real time.
• Branch — fork any historical turn: edit the prompt or swap the model and re-run, linked to the original as a visible branch.
• ⇄ Compare — pick any two nodes for a side-by-side, word-level diff of prompts and responses, plus a token-usage table with per-field deltas. "Git diff for LLM outputs."
• ⏪ Time-travel replay — re-run a whole chain from an edited node; the regenerated turns land as a sibling branch while your original user turns and tool results re-apply in order.
• MCP server — agents query their own .forkmind/ history mid-task (recall what they tried, trace how they got somewhere, self-correct).
• Regression testing — pin a known-good output as a baseline, re-run it after prompt/model changes, and catch drift with free offline checks (contains / regex / similarity), tool-call assertions, or an opt-in LLM judge graded against your own rubric. CI-ready.
• Trajectory regression — pin a whole multi-turn agent *path* from the captured graph and replay it, so a prompt change that reroutes an agent mid-run gets caught even when the final answer still reads fine.
• Context capsules — offload context into encrypted, immutable DAG capsules; restore in full or per segment; replicate (RAID), export/import, crypto-shred.
• `forkmind demo` — one command opens the dashboard on a pre-seeded sample DAG, zero setup and zero API key.

---

Try it in 10 seconds

npx forkmind demo

No API key, no setup: the dashboard opens with a pre-seeded conversation DAG — a coding-agent debug session that forks into a failed fix and a winning fix, plus an archived context capsule. Everything lives in a throwaway temp directory; your project is never touched. If a local Ollama is running, Fork from here works live against your local model.

Once you're in, try:

• ⇄ Compare any two nodes for a side-by-side, word-level diff of prompts, responses, and token usage — "git diff for LLM outputs".
• ⏪ Replay from here to re-run a whole chain from an edited node; the regenerated turns land as a sibling branch.
• Live capture — nodes pulse into the DAG the instant they're recorded, so you can watch an agent think in real time.

Install

# Run without installing (published on npm)

npx forkmind init npx forkmind start

…or install the CLI globally

npm install -g forkmind forkmind start

No npm registry needed either — ForkMind runs straight from the git link, and the dashboard builds automatically on install:

# Run without installing, from GitHub

npx github:medhovarsh/forkmind init npx github:medhovarsh/forkmind start

…or clone to hack on it

git clone https://github.com/medhovarsh/forkmind cd forkmind && npm install

Install as a Claude Code plugin

ForkMind ships a Claude Code plugin (skill + /forkmind command) so Claude knows when and how to drive it — same install flow as any marketplace plugin:

/plugin marketplace add Medhovarsh/forkmind

/plugin install forkmind

The plugin bundles:

• `forkmind` skill — Claude reaches for ForkMind whenever you ask it to debug a prompt, compare models, branch from a past turn, or regression-test a call.
• `/forkmind` command — start / branch / test / mcp on demand.
• `forkmind-debugger` agent — runs model/prompt comparisons in an isolated context and returns a compact verdict instead of dumping transcripts.
• MCP server, auto-wired — agents query their own .forkmind/ history (recall attempts, trace lineage, self-correct) with zero manual config.

The CLI is still what runs the proxy + dashboard; the plugin is the glue that teaches Claude to use it.

Quick start (free, no API key)

# 1. Install a free local model

(install Ollama from https://ollama.com first)

ollama pull llama3

2. Init + start ForkMind

npx github:medhovarsh/forkmind init # create .forkmind/ in your project npx github:medhovarsh/forkmind start # proxy on http://localhost:4500 + dashboard

3. Point your code at the proxy (see SDK below), make some calls

4. Open the dashboard

open http://localhost:4500

Drop-in SDK (auto-builds the tree)

npm i openai            # the wrapper extends the official SDK

const { ForkMindOpenAI } = require('forkmind');

const client = new ForkMindOpenAI({ apiKey: 'ollama', // ignored by Ollama; required by SDK upstream: 'http://localhost:11434', // free local open-source models });

// Each call is recorded; sequential calls auto-chain into a conversation tree. const res = await client.chat.completions.create({ model: 'llama3', messages: [{ role: 'user', content: 'Explain backpropagation simply.' }], });

Run the full example:

node examples/chain.js

Any language — point your client at the proxy

The SDK wrapper is convenience, not a requirement. ForkMind's proxy speaks the OpenAI-compatible wire protocol, so capture works from *any* language: set your client's base URL to http://localhost:4500/v1 and you're recorded. Chain turns into a tree by passing back the x-forkmind-node-id from the previous response as the next request's x-forkmind-parent header (the JS wrapper just automates this).

# Python — official openai client, zero ForkMind code

from openai import OpenAI

client = OpenAI(base_url="http://localhost:4500/v1", api_key="ollama") res = client.chat.completions.create( model="llama3", messages=[{"role": "user", "content": "Explain backpropagation simply."}], extra_headers={"x-forkmind-upstream": "http://localhost:11434"}, )

read res via .with_raw_response to grab x-forkmind-node-id and chain the next call

# curl — anything that can POST JSON

curl http://localhost:4500/v1/chat/completions \ -H 'content-type: application/json' \ -H 'x-forkmind-upstream: http://localhost:11434' \ -d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' -i

response header x-forkmind-node-id: → pass as x-forkmind-parent next call

Go, Ruby, Rust, Java — same deal: base URL + the two headers. The dashboard, branching, MCP, and regression testing all work regardless of source language.

---

Framework integrations

ForkMind ships thin adapters for the two biggest JS LLM ecosystems. Both route through the same proxy, so capture, branching, the dashboard, MCP, and regression all work unchanged — no model-class swap, no callbacks.

LangChain.js

npm i @langchain/openai @langchain/core

const { ChatOpenAI } = require('@langchain/openai');

const { forkmind } = require('forkmind/langchain');

const fm = forkmind({ upstream: 'http://localhost:11434' }); // free local Ollama const model = new ChatOpenAI({ apiKey: 'ollama', model: 'llama3', configuration: fm.configuration, // baseURL → proxy + chaining fetch });

await model.invoke('Explain backpropagation simply.'); // sequential calls on fm auto-chain; fm.setParent(id) to branch from a node.

Vercel AI SDK

npm i ai @ai-sdk/openai

const { generateText } = require('ai');

const { forkmindOpenAI } = require('forkmind/vercel');

const openai = forkmindOpenAI({ upstream: 'http://localhost:11434' }); const { text } = await generateText({ model: openai('llama3'), prompt: 'Explain backpropagation simply.', }); // openai.setParent(id) / openai.resetParent() control the branch point.

Both honor FORKMIND_PROXY (proxy base URL) and take an explicit baseURL / upstream per instance.

---

Using other free / open providers

ForkMind is provider-agnostic — it forwards your auth headers verbatim and lets you set the upstream per client. Anything OpenAI-compatible just works:

new ForkMindOpenAI({ apiKey: process.env.GROQ_API_KEY,

upstream: 'https://api.groq.com/openai' });

You can also override per request with the x-forkmind-upstream header if you call the proxy directly instead of