For developers

For developers

Where to start if you want to build ThoughtKnot, write a plug-in for it, or put it inside another app.

This page describes main, which the nightly build is made from. The latest release is 0.7.0: ✅ is in it, 🌙 is only in the nightly build, 🟡 is being built and ⏳ is planned.

The big picture

ThoughtKnot is built in layers. Each layer uses only the ones below it, so a new app or plug-in is added on top without changing what is underneath. The drawing below is made from requirements/architecture.gql, which is itself a graph note. A dashed box is planned and not built yet, as ThoughtKnot draws a suggested thing.

flowchart TB
  subgraph plugins["Plug-ins"]
    built_in_exports["Built-in data exports<br/><i>:Part</i>"]
  end
  subgraph apps["Apps"]
    obsidian["Obsidian plugin<br/><i>:Part</i>"]
    claude_code["Browser editor, from Claude Code<br/><i>:Part</i>"]
    standalone["Standalone app (Tauri)<br/><i>:Part</i>"]
    vscode["VS Code plugin<br/><i>:Part</i>"]
  end
  subgraph display["Display layer"]
    display_part["Display layer<br/><i>:Part</i>"]
  end
  subgraph core["Core"]
    core_part["Core<br/><i>:Part</i>"]
  end
  subgraph library["Graph format library"]
    graph_spec_js["Graph format library (JavaScript)<br/><i>:Part</i>"]
    graph_spec_py["Graph format library (Python)<br/><i>:Part</i>"]
  end
  host_interface{{"Host interface (DisplayHost)<br/><i>:Interface</i>"}}
  plugin_interface{{"Plug-in interface<br/><i>:Interface</i>"}}
  storage_interface{{"Storage interface<br/><i>:Interface</i>"}}
  problem_shapes{{"Problems and fixes (Language Server Protocol shapes)<br/><i>:Interface</i>"}}
  plugins -->|uses| display
  apps -->|uses| display
  display -->|uses| core
  core -->|uses| library
  graph_spec_js -.-|offers| problem_shapes
  core_part -.-|offers| plugin_interface
  core_part -.-|offers| storage_interface
  display_part -.-|offers| host_interface
  obsidian -->|implements| host_interface
  claude_code -->|implements| host_interface
  standalone -->|implements| host_interface
  vscode -->|implements| host_interface
  built_in_exports -->|implements| plugin_interface
  classDef planned stroke-dasharray: 5 5,opacity:0.7
  class standalone,vscode planned

Loading

More on each layer is on the Architecture page.

What do you want to do?

I want to	Read
Understand how it fits together	Architecture
Add an export, colours or, later, a diagram type	Writing a plug-in
Put the editor inside another app	Adding a host
Look up a problem code, a version or a schema	Developer reference
Change ThoughtKnot itself	CONTRIBUTING

Getting set up

You need Node 24 and, for the Python library, uv.

git clone https://github.com/rogerbucks/thoughtknot.git
cd thoughtknot
npm ci
npm run test:ai        # every JavaScript test, quietly
npm run test:changed   # only the tests your change reaches
npm run build          # the Obsidian plugin and the libraries

Before a pull request, run the full gate: npm test, npm run typecheck, npm run lint and npm run format:check. CI runs them all again.

How a change is made

1. Spec. Write the requirement in requirements/editor-requirements.gql.
2. Test. Write its test and see it fail. CI checks that each new test failed before its code existed.
3. Code. Write the code that makes it pass.
4. Sign off. Commit with git commit -s, and open a pull request.

How these pages stay current

Every list and drawing on the developer pages is made from the code or the requirements each time main changes. The interfaces, the extension points, the contract checks, the design tokens and the problem codes all come from the files that define them. A marker shows where each item stands:

Mark	Means
✅ Released	In the latest release
🌙 Nightly only	On main, in the nightly build, and in the next release
🟡 Being built	Started, not yet proved by its tests
⏳ Planned	In the requirements, not started