Onboarding

Get up and running with Knot in minutes. Install the extension, open a Twine project, build and play, and explore the Story Map.

1. Install Knot

Install from the VS Code Marketplace or by searching "Knot" in the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X). No other setup is required — Knot manages its own dependencies.

2. Open a Twine project

Open a folder containing .tw or .twee files. If you don't have a project yet, Knot will detect the empty workspace and offer to initialize one for you via the Knot: Initialize Project command.

A minimal Twine project needs at least two passages:

:: StoryData
{
    "ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
    "format": "SugarCube",
    "format-version": "2.37.0"
}

:: Start
Welcome to your story. [[Continue]].

:: Continue
You made it!

The StoryData passage tells Knot (and Tweego) which story format to use. The Start passage is where the player begins. Knot auto-detects the format from StoryData and activates the right language features.

3. Build and play

Click Build in the status bar to compile your project into an HTML file. The first build will prompt Knot to download Tweego and the required story format — this happens automatically, no manual setup needed.

Click Play to open the compiled story in your default browser. If Watch is off, Play builds first; if Watch is on, Play just opens the already-fresh HTML.

Triggering actions. All Knot actions are triggered through the status bar buttons at the bottom of the window or the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), prefixed with "Knot:". Knot intentionally does not ship default keyboard shortcuts — they tended to clash with VS Code defaults and other extensions. You can always bind your own via VS Code's Keyboard Shortcuts editor.

4. Enable Watch (optional, recommended)

Click Watch in the status bar to toggle auto-rebuild on save. When Watch is on, every save of a .tw, .twee, .js, or .css file triggers a rebuild in the background. Build progress appears in the "Knot Build" output channel.

This is the recommended workflow for active development: turn Watch on, open Play in your browser, edit, save, and refresh the browser.

5. Explore the Story Map

Click Story Map in the status bar to open an interactive graph of your project. Nodes are passages, edges are links. Click any node to jump to that passage in the editor. The map updates in real time as you edit.

The Story Map is primarily for visualization and navigation at this time; deeper structural editing from the map is on the roadmap.

Status bar reference

Knot adds five items to the left side of the status bar:

Item	Icon	Action
Story Map	compass	Open the graph visualization
Build	tools	Compile the project with Tweego
Watch	eye / eye-closed	Toggle auto-rebuild on save
Play	play	Open compiled HTML in browser
Settings	gear	Open Knot settings

Next steps

Read the feature deep-dive to learn what Knot can do today.
Join the Discord to ask questions and follow development.
If you run into trouble, see the troubleshooting section of the extension README.