@100xprompt/brain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Nipurn Agarwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Parts of src/adapters/{antigravity,devin,grok-cli,hermes,kilo-cli,mastracode,muse,omp} are ported from session-migrate
+(https://github.com/xhluca/session-migrate), used under its MIT license:
+
+MIT License
+
+Copyright (c) 2026 xhluca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# brain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One working session, any AI coding tool. Start in Claude Code, carry on in Codex, Cursor or another tool, and switch
+back, with the same session. brain also keeps what each project has learned across tools, trims what a long session
+sends back to the model, and can route your tools through the 100xprompt gateway.
+
+Nothing calls a model to do any of this, and nothing changes in your tools until you run a command that says so.
+
+Runs on [Bun](https://bun.sh) 1.3 or later. Built and tested on macOS.
+
+## Install
+
+```bash
+bun add -g @100xprompt/brain
+brain --version
+```
+
+Or run it without installing:
+
+```bash
+bunx @100xprompt/brain session list --here
+```
+
+Hooks and MCP entries installed from a `bunx` run start that same version later, so they keep working after Bun's
+temporary copy is gone. No Bun yet? `curl -fsSL https://bun.sh/install | bash`.
+
+## Quick start
+
+```bash
+brain session list --here                          # sessions from every tool, for this project, newest first
+brain session continue <id> --in codex --dry-run   # what would be written, and what would not carry over
+brain session continue <id> --in codex             # a new Codex session that picks up where that one stopped
+brain session handoff --in claude-code             # the newest session from another tool in this folder
+```
+
+`<id>` is `<tool>:<session id>` as `list` prints it, or a unique start of the session id.
+
+## Moving a session
+
+`continue` writes the session into the target the best way that target allows:
+
+- **Native** (a new session in the tool's own storage, opened like any other): Claude Code, Codex, Gemini CLI, Copilot
+  Chat in VS Code, the Copilot CLI, Cline (in VS Code, Cursor, Windsurf, and its CLI), Roo Code (in VS Code, Cursor,
+  Windsurf), Antigravity, Aider, Amazon Q (CLI and IDE), Auggie, Codebuff, Continue, Crush, Devin CLI, Factory Droid,
+  Grok CLI, Hermes Agent, iFlow CLI, Kimi Code, Kiro (CLI and IDE), Letta Code, Mastra Code, Muse Code, Oh My Pi,
+  OpenHands CLI, PearAI, Pi, Qoder CLI, Qwen Code, Tabnine CLI, Void and Zed.
+- **Import** (through the tool's own import): 100xprompt, OpenCode, Cursor, Goose, Kilo Code, Kilo CLI and Mistral Vibe.
+- **Brief**: the Cursor CLI, and any other tool (`--in any`: a Markdown file to paste).
+
+A native or import writer writes only for the tool versions its format was checked against, and some need the app
+closed (VS Code); otherwise, and whenever the tool is missing, the session goes as a brief. `brain session targets`
+shows what each tool on this machine gets right now, and `brain session list` shows every session brain can read.
+
+A **brief** is built without a model call: where the session came from, the goal, where it stands, files changed, the
+last commands, the latest requests, and as many recent turns as fit the target. It is saved as a pending handoff, copied
+to the clipboard where the system has one, and, where the session-start hook is installed (`brain session hooks
+install`, for Claude Code, Codex, Cursor and Gemini CLI), given to the model by the target's next session in the same
+project.
+
+## Saving tokens
+
+On real sessions, tool calls and their output are about four fifths of the tokens; what was said is about a tenth.
+
+- **Lean sessions.** A big tool call or result becomes a one-line digest with a short preview, and the full text stays on
+  disk (`~/.brain/blobs/`). `continue` does this by itself on long sessions (`--lean` / `--full` override; `--budget
+  <tokens>` trims in steps until the session fits). The model gets the text back only when it asks, through the
+  `brain_expand` tool (or `brain expand <id>`).
+- **Project memory.** What a session settled (decisions, constraints, preferences, files, failed approaches, commands) is
+  distilled into small items kept per project, so a session in any tool can recall them with `brain_recall`. Memory needs
+  [Chitta](https://www.npmjs.com/package/@100xprompt/chitta) (`bun add -g @100xprompt/chitta`, found next to brain, in a
+  global install, or at `$BRAIN_CHITTA`); without it everything else works, except a Teams server.
+- **What every request reloads.** `brain tokens audit` checks, without changing anything, what a project sends with every
+  request: instruction files, MCP servers, ignore files.
+
+```bash
+brain mcp install                  # brain_recall and brain_expand in Claude Code, Codex, Cursor, Gemini CLI, OpenCode, VS Code
+brain memory sync --here           # distill this project's earlier sessions (a few per run; nothing is processed twice)
+brain memory search "how do we run the tests"
+brain tokens audit
+```
+
+## The 100xprompt gateway
+
+Point a coding tool at the 100xprompt gateway, and back. Signing in works like `100xprompt auth login`: your browser opens,
+you sign in to 100xprompt and confirm, and the key comes back to brain by itself.
+
+```bash
+brain gateway login                              # sign in in the browser
+brain gateway connect --tool codex --dry-run     # show what would change
+brain gateway connect --tool codex               # Claude Code, Codex, OpenCode, Gemini CLI (signs in first if needed)
+brain gateway status
+brain gateway disconnect --tool codex            # put back exactly what was there
+brain gateway logout
+```
+
+- Connecting changes which model the tool uses: it runs on 100xprompt Pro by default (`--model flash` for 100xprompt
+  Flash), billed to your 100xprompt account. Context editing is on by default; `--no-context-edit` turns it off and is
+  remembered for later connects until `--context-edit`.
+- Before changing anything, `connect` checks that the gateway accepts your key the way that tool sends it (a free check
+  that generates nothing). If your account's quota is used up, it still connects and tells you, in the gateway's words.
+- Only the settings brain owns are written; the value each had before is recorded and put back by `disconnect`. The key
+  lives in `~/.brain/gateway.key`, readable only by you, and is never printed.
+- On a machine without a browser (SSH): `brain gateway login --no-browser` prints the address. Open it anywhere, then
+  paste the key from the page's Copy key button (input is hidden). For scripts and CI: `--key-env VAR`. To reuse the
+  100xprompt CLI's sign-in: `--from-cli`.
+- Each sign-in makes a new key on your account. Signing in again also updates the copy Codex and Gemini CLI keep in their
+  own config.
+
+## Teams
+
+Memory can live on one shared server instead of each person's machine, with who may see what enforced there.
+
+```bash
+# on the server (it needs Chitta: bun add -g @100xprompt/chitta)
+brain org admin init --db org.db --org-id acme --org-name Acme --admin-id ana --admin-name Ana   # once; prints the admin token
+brain org admin serve --db org.db --host 0.0.0.0 --allow-remote --tls-cert cert.pem --tls-key key.pem
+
+# on each person's machine
+brain org login --server https://<server>:4500 --token <token>
+brain org promote --source <session> --to team --team backend
+```
+
+Every item has a scope: `private` (the default; only its owner, not even an admin), `project`, `team` or `org`. Sharing
+is an explicit, logged act. Roles are `viewer`, `editor` and `admin`; admins set policy (widest scope, paths and terms that
+are never shared, retention) and read the audit log. Only distilled, secret-filtered memory items cross the wire: never
+full tool output, raw turns or attachments. With no login, brain stays entirely local.
+
+`admin serve` listens on 127.0.0.1 unless told otherwise: to reach it from other machines, use `--allow-remote` with TLS
+(`--tls-cert`/`--tls-key`), or keep it local behind a TLS proxy (`--trust-proxy`). An encrypted database (`init
+--encrypt`) also needs `libsql` installed next to Chitta. `brain org help` lists every option.
+
+## Safety
+
+- Reading a session never changes a tool's files: SQLite stores are copied (with their write-ahead logs) and the copy is
+  read. To see which version is installed, `targets` and `--dry-run` start each installed tool with `--version`.
+- Continuing always writes a **new** session; the source is never changed, so switching back is continuing the original.
+- Writers check the installed tool version against the one their format was verified on, and fall back to the brief otherwise.
+- `--dry-run` shows what would be written. Hooks, MCP entries and gateway settings are merged with your own, backed up
+  first, and removed exactly by the matching `uninstall` or `disconnect`.
+
+## Commands
+
+```
+brain session list | show | export | continue | handoff | targets | hooks
+brain memory ingest | search | status | forget | sync
+brain mcp serve | install | uninstall | status
+brain tokens audit | lookups
+brain gateway login | logout | connect | disconnect | status | tools
+brain org login | logout | whoami | status | promote | demote | forget | admin ...
+brain expand <id>
+brain --version
+```
+
+`brain --help` lists every command with its main options; `brain gateway`, `brain mcp` and `brain org help` show the rest
+of theirs.
+
+## Known limits
+
+- Built and tested on macOS. Linux and Windows are not tested yet.
+- Each writer is checked against specific versions, for example Claude Code 2.1.296 to 2.1.319 (a newer 2.1.x is
+  accepted with a note), Codex 0.147.0, Gemini CLI 0.33.1 and 0.67.0, Cursor 3.27 and 3.29, VS Code 1.144 with Copilot
+  Chat 0.72, OpenCode 2.2.6, Zed 1.26.2 and 1.27.0, Aider 0.86.2. A tool at another version gets the brief instead.
+- Into Codex: tool names from Claude Code (`Read`, `Grep`, `Agent`, MCP calls) stay as they are, and subagent transcripts
+  are not carried. Pasted images are.
+- Into Claude Code: reasoning and subagent transcripts are not written.
+- Cursor is reached through its own import of Claude Code sessions (for the folder it has open), not by writing to
+  Cursor's database; the brief opens in Cursor's chat when that is not possible.
+- Session-start hooks were checked against each tool's installed code, not yet inside every live tool. Codex asks you to
+  trust a new hook once.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@100xprompt/brain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "One working session, any AI coding tool: move sessions between Claude Code, Codex, Cursor, Gemini CLI, OpenCode and more, keep what projects learned, spend fewer tokens. Runs on Bun. By 100xprompt.",
+  "license": "MIT",
+  "author": "Nipurn Agarwal",
+  "homepage": "https://www.npmjs.com/package/@100xprompt/brain",
+  "keywords": [
+    "ai-coding",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+    "session",
+    "handoff",
+    "context",
+    "memory",
+    "mcp",
+    "tokens",
+    "100xprompt"
+  ],
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "bin": {
+    "brain": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "brain": "bun run src/cli.ts",
+    "test": "bun test --timeout 60000",
+    "typecheck": "tsc --noEmit -p .",
+    "wire": "bun wire/run.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "oidc-provider": "9.13.3",
+    "typescript": "5.8.2"
+  }
+}

package/src/adapters/aider/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { aiderReader } from "./reader.ts"
+import { aiderNativeWriter } from "./writer.ts"
+
+// Aider: reads each run of a project's .aider.chat.history.md as a session, and continues any session as a
+// new run in that history, which `aider --restore-chat-history` hands to the model.
+export const readers: Reader[] = [aiderReader]
+export const writers: Writer[] = [aiderNativeWriter]

package/src/adapters/aider/reader.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto"
+import { readFileSync, statSync } from "node:fs"
+import { dirname } from "node:path"
+import type { Session, Turn } from "../../session/types.ts"
+import { header, lossCounter, noteModel } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { CONTINUED_NOTE, LABEL, SUMMARY_PREFIX, TOOL, type Run, assistantText, findHistories, parseRuns, userText } from "./records.ts"
+
+// Aider sessions. Aider has no session list or ids: every project keeps one history file and each launch
+// appends a run to it, so a run ("# aider chat started at ...") is read as one session. That is also what
+// a launch without --restore-chat-history sees: a fresh chat. Ids are made from the file and the run's start.
+
+/** "2026-11-08 10:00:00" (local time, as Aider writes it) → ISO. */
+const runTime = (stamp: string | undefined) => {
+  if (!stamp) return undefined
+  const t = new Date(stamp.replace(" ", "T"))
+  return Number.isFinite(t.getTime()) ? t.toISOString() : undefined
+}
+
+const fileKey = (path: string) => createHash("sha1").update(path).digest("hex").slice(0, 8)
+
+/** The id of a run: the file's key and the run's start (YYYYMMDDhhmmss), with its index when two share a second. */
+export function runId(path: string, run: Run, runs: Run[]): string {
+  const stamp = (run.startedAt ?? "00000000000000").replace(/\D/g, "")
+  const twin = runs.filter((r) => r.startedAt === run.startedAt).length > 1
+  return `${fileKey(path)}-${stamp}${twin || !run.startedAt ? `-${run.index}` : ""}`
+}
+
+/** Runs that hold conversation, not only Aider's startup notices. */
+const talked = (run: Run) => run.messages.some((m) => m.role !== "tool")
+
+function readText(path: string): string {
+  try {
+    return readFileSync(path, "utf8")
+  } catch (e) {
+    throw new Error(`cannot read the Aider history ${path}: ${(e as Error).message}`)
+  }
+}
+
+/** One run as a portable session. */
+export function runSession(path: string, run: Run, runs: Run[], updatedAt?: string): Session {
+  const id = runId(path, run, runs)
+  const h = header(TOOL, id, { sourcePath: path, project: { cwd: dirname(path) }, startedAt: runTime(run.startedAt), updatedAt })
+  const lost = lossCounter()
+  const turns: Turn[] = []
+  for (const [i, m] of run.messages.entries()) {
+    if (m.role === "tool") {
+      // Aider's own notices: never sent to the model. Kept: the model it ran, its version, and the files it edited.
+      for (const line of m.content.split("\n")) {
+        const model = line.match(/^(?:Main model|Model): (\S+)/)?.[1]
+        if (model) noteModel(h, model)
+        const version = line.match(/^Aider v(\d+\.\d+\.\d+\S*)/)?.[1]
+        if (version) h.toolVersion ??= version
+        const edited = line.match(/^Applied edit to (.+?)\s*$/)?.[1]
+        if (edited) turns.push({ kind: "file_edit", path: edited })
+      }
+      continue
+    }
+    if (m.role === "user") {
+      const text = userText(m.content)
+      if (!text) continue
+      const note = i === run.messages.findIndex((x) => x.role === "user") ? text.match(CONTINUED_NOTE) : null
+      if (note) {
+        h.parent = { id: note[1]!.replace(/[.,]$/, ""), kind: "continued" }
+        continue
+      }
+      if (text.startsWith(SUMMARY_PREFIX.trim())) {
+        turns.push({ kind: "compaction", summary: text.slice(SUMMARY_PREFIX.trim().length).trim() })
+        continue
+      }
+      turns.push({ kind: "user", text })
+      continue
+    }
+    const text = assistantText(m.content)
+    if (text) turns.push({ kind: "assistant", text, ...(h.models.length ? { model: h.models[h.models.length - 1] } : {}) })
+  }
+  if (!turns.some((t) => t.kind === "user" || t.kind === "assistant")) lost.add("runs with only Aider's own notices")
+  lost.flush(h)
+  const first = turns.find((t) => t.kind === "user") as Extract<Turn, { kind: "user" }> | undefined
+  if (first) h.title = first.text.replace(/\s+/g, " ").trim().slice(0, 80)
+  return { header: h, turns }
+}
+
+export const aiderReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home: string): Promise<SessionRef[]> {
+    const refs: SessionRef[] = []
+    for (const path of findHistories(home)) {
+      let text: string
+      let mtime: string | undefined
+      try {
+        text = readFileSync(path, "utf8")
+        mtime = statSync(path).mtime.toISOString()
+      } catch {
+        continue
+      }
+      const runs = parseRuns(text)
+      runs.forEach((run, i) => {
+        if (!talked(run)) return
+        const next = runs.slice(i + 1).find((r) => r.startedAt)
+        const first = run.messages.find((m) => m.role === "user" && !CONTINUED_NOTE.test(userText(m.content)))
+        refs.push({
+          tool: TOOL,
+          sourceId: runId(path, run, runs),
+          path,
+          cwd: dirname(path),
+          updatedAt: (next ? runTime(next.startedAt) : mtime) ?? runTime(run.startedAt),
+          ...(first ? { title: userText(first.content).replace(/\s+/g, " ").trim().slice(0, 80) } : {}),
+          extra: { run: run.index },
+        })
+      })
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref: SessionRef): Promise<Session> {
+    const runs = parseRuns(readText(ref.path))
+    const run = runs.find((r) => runId(ref.path, r, runs) === ref.sourceId) ?? runs.find((r) => r.index === ref.extra?.run)
+    if (!run) throw new Error(`no run ${ref.sourceId} in the Aider history ${ref.path}`)
+    let updatedAt: string | undefined
+    try {
+      updatedAt = statSync(ref.path).mtime.toISOString()
+    } catch {}
+    const next = runs.slice(run.index + 1).find((r) => r.startedAt)
+    return runSession(ref.path, run, runs, next ? runTime(next.startedAt) : updatedAt)
+  },
+}

package/src/adapters/aider/records.ts

@@ -0,0 +1,220 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { exists, isDir, versionOf } from "../../fsutil.ts"
+
+// What Aider's chat history looks like, as far as this adapter relies on it. Checked against aider-chat
+// 0.86.2 (PyPI) and its source at Aider-AI/aider 5dc9490 (aider/io.py, aider/utils.py,
+// aider/coders/base_coder.py, aider/args.py, aider/history.py). Catalogue entry 13.
+//
+// Aider keeps one Markdown file per project, `.aider.chat.history.md` at the git root (else the folder it
+// runs in), and appends to it for ever: each launch writes "# aider chat started at <local time>", the
+// person's input as "#### " lines, Aider's own notices as "> " lines and the model's replies as plain
+// text. `aider --restore-chat-history` reads the whole file back with utils.split_chat_history_markdown:
+// "# " lines are skipped, "> " lines are dropped (they are its own output, never sent to the model), runs
+// of "#### " lines are one user message, and everything else is the assistant's. There are no ids, no tool
+// calls and no reasoning.
+
+export const TOOL = "aider"
+export const LABEL = "Aider"
+
+/** Aider versions whose history format the writer was checked against. */
+export const TESTED_VERSIONS = ["0.86.2"]
+
+export const HISTORY_FILE = ".aider.chat.history.md"
+export const INPUT_HISTORY_FILE = ".aider.input.history"
+
+/** The line each Aider launch starts with (io.py: datetime.now().strftime("%Y-%m-%d %H:%M:%S")). */
+export const RUN_HEADER = /^# aider chat started at (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s*$/
+
+/** What Aider's own summariser puts before a summary that replaced earlier messages (prompts.summary_prefix). */
+export const SUMMARY_PREFIX = "I spoke to you previously about a number of things.\n"
+
+/** The note a continued session opens with; the reader recognises it and records where the session came from. */
+export const continuedNote = (label: string, id: string, when: string) =>
+  `[This session continues ${label} session ${id}, carried over by brain session on ${when}. The messages below are its history; tool calls are shown as text, and reasoning and anything listed as lost did not carry over. Check files before relying on details, since they may have changed.]`
+export const CONTINUED_NOTE = /^\[This session continues .+? session (\S+), carried over by brain session/
+
+/** The installed Aider version ("aider 0.86.2" → "0.86.2"), or undefined when it is missing. */
+export const aiderVersion = (bin = "aider") => versionOf(bin)?.match(/(\d+\.\d+\.\d+(?:\.dev\d*)?)/)?.[1]
+
+/**
+ * The folder Aider keeps its history in for `cwd`: the enclosing git working tree (args.py defaults the
+ * history files to the git root; main.get_git_root searches parent folders), else `cwd` itself.
+ */
+export function historyRoot(cwd: string): string {
+  let dir = cwd.replace(/\/+$/, "") || "/"
+  for (let i = 0; i < 40; i++) {
+    if (exists(join(dir, ".git"))) return dir
+    const up = dir.slice(0, dir.lastIndexOf("/")) || "/"
+    if (up === dir) break
+    dir = up
+  }
+  return cwd
+}
+
+/** Line breaks Python's str.splitlines() splits on; the parser sees each as a new line. */
+const PY_LINE_BREAKS = /\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/
+
+/** Text split into lines the way split_chat_history_markdown splits it, without the line endings. */
+export const pyLines = (text: string) => text.split(PY_LINE_BREAKS)
+
+/** One message as Aider's parser yields it. */
+export interface MdMessage {
+  role: "user" | "assistant" | "tool"
+  content: string
+}
+
+/** One launch of Aider: its header time and its messages, tool lines included. */
+export interface Run {
+  startedAt?: string
+  /** 0-based index of the run in the file. */
+  index: number
+  messages: MdMessage[]
+}
+
+/**
+ * The file split into runs, each parsed exactly as utils.split_chat_history_markdown parses (with
+ * include_tool=True, so the reader can see Aider's notices; the model never gets the "tool" ones).
+ */
+export function parseRuns(text: string): Run[] {
+  const runs: Run[] = []
+  let run: Run = { index: 0, messages: [] }
+  let user: string[] = []
+  let assistant: string[] = []
+  let tool: string[] = []
+  const append = (role: MdMessage["role"], lines: string[]) => {
+    const content = lines.join("")
+    if (content.trim()) run.messages.push({ role, content })
+  }
+  const flushAll = () => {
+    append("assistant", assistant)
+    append("user", user)
+    append("tool", tool)
+    assistant = []
+    user = []
+    tool = []
+  }
+  const parts = text.split(/(\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029])/)
+  for (let i = 0; i < parts.length; i += 2) {
+    const body = parts[i]!
+    const line = body + (parts[i + 1] ?? "")
+    if (!line) continue
+    const header = body.match(RUN_HEADER)
+    if (header) {
+      // A new launch: Aider's parser would carry on across it, but the reader keeps each launch apart.
+      flushAll()
+      if (run.messages.length || run.startedAt) runs.push(run)
+      run = { index: runs.length, startedAt: header[1]!, messages: [] }
+      continue
+    }
+    if (line.startsWith("# ")) continue
+    if (line.startsWith("> ")) {
+      append("assistant", assistant)
+      assistant = []
+      append("user", user)
+      user = []
+      tool.push(line.slice(2))
+      continue
+    }
+    if (line.startsWith("#### ")) {
+      append("assistant", assistant)
+      assistant = []
+      append("tool", tool)
+      tool = []
+      user.push(line.slice(5))
+      continue
+    }
+    append("user", user)
+    user = []
+    append("tool", tool)
+    tool = []
+    assistant.push(line)
+  }
+  flushAll()
+  if (run.messages.length || run.startedAt) runs.push(run)
+  return runs
+}
+
+/** A user message as the person typed it: Aider ends each "#### " line with a Markdown line break ("  "). */
+export const userText = (content: string) =>
+  pyLines(content)
+    .map((l) => l.replace(/ {2}$/, ""))
+    .join("\n")
+    .replace(/^\n+|\s+$/g, "")
+    .replace(/^<blank>$/, "")
+
+/**
+ * Lines the parser would take for something else get one more leading space from the writer, and lose one
+ * in the reader; lines that already start with spaces before such a marker get one too, so the round trip
+ * is exact.
+ */
+const CLASHES = /^ *(# |#### |> )/
+const ESCAPED = /^ +(# |#### |> )/
+export const escapeLine = (line: string) => (CLASHES.test(line) ? ` ${line}` : line)
+export const unescapeLine = (line: string) => (ESCAPED.test(line) ? line.slice(1) : line)
+
+/** An assistant message as written: the escape spaces taken out, surrounding blank lines trimmed. */
+export const assistantText = (content: string) => pyLines(content).map(unescapeLine).join("\n").trim()
+
+/** Folders the history search never enters: system and package folders that hold no projects. */
+const SKIP_DIRS = new Set(["node_modules", "Library", "Applications", "Pictures", "Music", "Movies", "venv", "__pycache__", "dist", "build", "target", "vendor"])
+
+/**
+ * Every Aider history file in the folders under `home`, at most `depth` levels down. Aider keeps no index
+ * of its projects, so they are found by name; hidden and package folders are skipped and the walk stops
+ * after `budget` folders so listing stays cheap.
+ */
+export function findHistories(home: string, depth = 5, budget = 20_000): string[] {
+  const cache = join(home, ".brain", "cache", "aider-histories.json")
+  const fresh = process.env.BRAIN_NO_CACHE !== "1" ? readCache(cache) : undefined
+  const found = new Set(fresh ?? walkHistories(home, depth, budget))
+  if (!fresh && process.env.BRAIN_NO_CACHE !== "1") writeCache(cache, [...found])
+  // The folder the person is in, and the folders above it, are always checked: a project started since the cache was made is found.
+  for (let dir = process.cwd(), i = 0; i < depth && dir.startsWith(home); dir = dirname(dir), i++) {
+    const p = join(dir, HISTORY_FILE)
+    if (exists(p)) found.add(p)
+  }
+  return [...found]
+}
+
+/** How long a walk of the home folder is trusted. Aider keeps no index, so the walk is the only way to find its projects. */
+const CACHE_TTL_MS = 10 * 60_000
+
+function readCache(file: string): string[] | undefined {
+  try {
+    if (Date.now() - statSync(file).mtimeMs > CACHE_TTL_MS) return undefined
+    const j = JSON.parse(readFileSync(file, "utf8"))
+    return Array.isArray(j?.paths) ? j.paths.filter((p: unknown): p is string => typeof p === "string" && exists(p)) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function writeCache(file: string, paths: string[]) {
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, JSON.stringify({ paths }))
+  } catch {}
+}
+
+function walkHistories(home: string, depth: number, budget: number): string[] {
+  const out: string[] = []
+  let left = budget
+  const walk = (dir: string, level: number) => {
+    if (left-- <= 0) return
+    let entries: import("node:fs").Dirent[]
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) if (e.name === HISTORY_FILE && (e.isFile() || e.isSymbolicLink())) out.push(join(dir, e.name))
+    if (level >= depth) return
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name) || e.name.endsWith(".app")) continue
+      walk(join(dir, e.name), level + 1)
+    }
+  }
+  if (isDir(home)) walk(home, 0)
+  return out
+}