Contributing

GraphMind is MIT and maintained by one person. That shapes what is most useful to contribute: things that make the project cover more ground without adding maintenance surface.

Most useful contributions

1. Adapters. The single highest-leverage thing. Every framework GraphMind speaks is a framework whose users get a debugger. See writing an adapter.
2. Trace-import dialects. graphmind import is best-effort across OTel and OpenInference shapes; each dialect it recognises properly is a whole ecosystem that can at least read its runs.
3. Reproductions. A graphmind record NDJSON export attached to an issue is the actual run, not a description of one. It is worth more than a paragraph of narrative.
4. Documentation gaps. If something here was wrong, unclear, or missing when you needed it, that is a bug in the docs.

Repository layout

• Directorypackages/

  • Directoryschema/ the wire contract — protocol types, envelope, parser, JSON Schema export

    • …
  • Directoryclient/ the runtime — session, transport, gate engine, ring buffer, kill switches

    • …
  • Directoryai-sdk/ the reference adapter (Vercel AI SDK)

    • …
  • Directoryanthropic/ Anthropic SDK adapter

    • …
  • Directoryopenai/ OpenAI SDK adapter

    • …
  • Directorylanggraph/ LangChain / LangGraph adapter

    • …
  • Directorycli/ server, SQLite storage, demo, importer, MCP, bundled viewer

    • …
• Directoryapps/

  • Directoryviewer/ the debugger UI (React)

    • …
  • Directorydocs/ this site (Astro + Starlight)

    • …
  • Directoryweb/ graphmind.ai landing page

    • …
• Directoryexamples/

  • Directorydemo-agent/ the instrumented trip planner behind graphmind demo

    • …
  • Directorye2e/ full-stack smoke test against a running server

    • …

The dependency direction is strict and one-way: schema ← client ← adapters. The CLI depends on schema only. Nothing depends on an adapter.

Running it locally

git clone https://github.com/Hegazy360/GraphMind.git
cd GraphMind
pnpm install
pnpm build
pnpm test

Requires Node ≥ 22.13 and pnpm. Then:

pnpm build:viewer      # build the viewer into the CLI's bundle
node packages/cli/dist/cli.js demo

Test the floor, not just your machine

engines.node is >=22.13, and the floor is part of the contract, so it has to be executed rather than declared:

pnpm test:floor        # runs the security suite on the oldest supported Node

This exists because of a real bug: node:sqlite round-trips a string containing a NUL byte on Node 24 and mangles it on Node 22, so a run id with a NUL in it was stored under a different id than the app streamed under — on some runtimes and not others. Every suite was green on the dev machine and red in CI. If Node 22 is not installed the script says so and exits 0, because a missing optional toolchain is not a failing test.

Conventions

Language	TypeScript, strict, ESM
Build	plain tsc (ESM + .d.ts) — no bundler, no task runner
Tests	vitest
Node	≥ 22.13 (built-in node:sqlite, native WebSocket)
Dependencies	as few as possible; a hand-rolled 60-line arg parser beat adding one

The bar for a new dependency

Every dependency is surface a solo maintainer has to keep track of, and weight in a package people install to debug something. “Could this be 50 lines instead?” is a real question here, and the answer has usually been yes.

The invariants a change is reviewed against

These are the promises GraphMind makes to people who ship it in their codebase. A change that weakens one needs a very good reason:

• Never throws into the host app. Internal failures degrade to a no-op plus one rate-limited warning.
• Zero cost when detached, identity when disabled.
• Fails open. A disconnected debugger releases every held gate.
• Local-first. No payload leaves the machine. The server binds 127.0.0.1.
• Protocol tolerance. Unknown message types and unknown payload fields are absorbed, never rejected. Only an incompatible change bumps gm.

New behaviour that can hold or alter execution needs a test that asserts the fail-open path too, not just the happy one.

Changing the protocol

The schema is the contract every adapter and any third-party implementation targets, so:

• Additive changes — a new event type, a new optional payload field — do not bump PROTOCOL_VERSION. Receivers already tolerate both.
• Incompatible changes bump the major, and need a genuine argument for why tolerance cannot absorb them.
• The JSON Schema export is pinned by a golden-file test. If your change is intentional, update the golden file in the same commit so the diff is visible in review.

Filing a good issue

Include:

• what you expected and what happened;
• node -v, adapter and graphmind-ai versions, framework version;
• any [graphmind] warning (the client never throws, so warnings are the signal);
• ideally a graphmind record <runId> export.

Caution

Read the export before attaching it publicly — it contains your real prompts, tool arguments and outputs, unredacted.

GitHubIssues, discussions, and the source for everything on this site.