Write Weft by hand

Weft was designed to be written by an AI builder. Most of the syntax choices exist to make the AI faster, not to make humans happier. That said, the language is dense enough and consistent enough that writing it by hand is perfectly fine, and sometimes faster than explaining what you want to Tangle.

This page is a short practical guide for the cases where you want to skip the chat. For the full reference, see Nodes and ports, Connections, and Types.

The code panel

In the Builder, there is a Code button in the toolbar that toggles the Weft code panel as a side view alongside the graph. It is a CodeMirror editor with Weft syntax highlighting and all the usual shortcuts (find, replace, undo, multi-cursor). The weft source is the source of truth: graph edits patch the text in place, code edits re-parse the text and sync the graph back about half a second after you stop typing.

Because the text is authoritative, formatting you write by hand is preserved. Comments stay where you put them, line breaks stay, extra blank lines stay. Graph edits surgically patch specific lines via updateNodeConfig rather than re-serializing the whole file.

Minimum viable project

Every project starts with a header (# comments, parsed by the compiler). Then a series of node declarations and connections. That is the whole syntax.

Node declaration cheat sheet

Every form, shortest to longest.

Connection cheat sheet

Config value formats

• Strings: always double-quoted. label: "My Node"
• Numbers: bare, no quotes, in general. In practice, LLM config numbers (temperature, top_p, etc.) are typically written as quoted strings (temperature: "0.3"), and the compiler accepts that form. When in doubt, copy from the catalog examples or ask Tangle.
• Booleans: true / false
• JSON arrays / objects: written directly, not wrapped in quotes. value: ["a", "b"], data: {"key": "val"}
• Multi-line strings: triple backticks on the same line as the key, content starts at column 0 on the next line, closing triple backticks on their own line.
• Comments: lines starting with #. Anywhere. Comments inside groups can double as the group's description (see groups).

Groups

Inside a group, self refers to the group's interface: self.raw on the right side is "data coming into this group's raw input", self.result on the left is "send this out through the group's result output".

Tips for typing Weft fast

• Use the graph view to add nodes. Press Ctrl+P in the graph to open the node search. Picking a node inserts a full template with the right config fields, so you do not have to remember ports by heart.
• Let the compiler lead. The compiler validates on every keystroke. If you are not sure what type a port takes, write something, read the error message, fix it. Faster than looking it up in the catalog.
• Inline nodes for one-offs. If a Template feeds exactly one downstream port, declare it inline at the point of use, not as a separate block. Less noise.
• Edit in code, browse in graph. Most structural edits (rename a node, change a type, add a port) are faster in text. Most navigation (jump to a specific node, see the architecture, debug a path) is faster in the graph.
• Your formatting is preserved. There is no canonical formatter that rewrites your code. The parser reads the text, the graph edits patch specific lines in place, comments and layout stay where you put them. So write it how you like it.

When to fall back to Tangle

Writing Weft by hand is great for small edits, quick experiments, and anything you already have in your head. Tangle is better for:

• Starting a new project from a vague idea.
• Figuring out which nodes to use from the catalog when you do not know by name.
• Setting up a deployment Loom page.
• Building test configs.
• Debugging a compilation error you cannot figure out yourself. Paste the error, ask Tangle.

The two modes compose. Ask Tangle to scaffold a project, hand-edit the parts you care about, ask Tangle to extend it further. Nothing is locked in.