Loopweft

Loopweft and AI agents

Loopweft has no AI of its own. An AI agent you run yourself can build and check maps with its command line, by rules that keep the evidence honest.

Loopweft's command line, loopweft, can do everything the Studio does to a map: add variables and links (also as shorthand, Births -> Population (+)), name loops, add sources and cite them, tell a story step by step, check the map and export it. Every command answers in plain words or, with --json, in one JSON document, with exit codes an agent can act on. So an agent that runs commands on your computer, such as Claude Code or Codex, can do the work while you watch the map in the Studio.

The rules an agent is given

• Change maps only through loopweft commands, never by editing the file's text, and look nowhere else on your computer: the guide and the command line's own help are all it needs.
• Never guess a link's sign: take it from your brief, a source or the archetype. A link the agent suggests itself may carry the sign its reasoning gives, with the reasoning written on the link; when nothing settles it, ?, which Loopweft flags for you to decide.
• Say where every link comes from, in its Basis field: your brief, the archetype, a source, or the agent's own suggestion. You can find every suggestion in the Studio's table, and keep, change or remove it.
• Never invent evidence: add only sources you gave it, or ones it confirmed with a DOI lookup; never write a page number it has not seen. When unsure, leave a link uncited (Loopweft flags that too).
• Check the map with loopweft validate before exporting, and export only with no errors and no warnings but uncited links and ? signs, which are yours to settle; every other warning is fixed first.
• Report at the end: what it changed, which links are its own suggestions, every ?, what is still uncited, and the files it made.

How to work with one

1. Get the command line. For now it runs inside a copy of the repository (with Node 24: npm install, then npx loopweft); the desktop apps will install it for you.
2. In the Studio, save your map into a folder of its own, then choose File › Work with an AI agent… and Copy agent instructions.
3. Open your agent in that folder, paste the message, and say what you would like it to do.
4. Watch: in Chrome or Edge, the open map (opened with File › Open, saved from the Studio, or dropped on its window) follows each change the agent saves, with a note of what changed, and Undo goes back. If you have unsaved changes, the Studio asks which version to keep; it never merges.
5. Read the agent's report, and check its changes before you rely on them.

loopweft guide --install <folder> also puts the guide in a folder, where Claude Code (.claude/skills/loopweft/SKILL.md) and Codex (AGENTS.md) find it by themselves.

Keep the agent to its folder

Loopweft tells an agent to work only with its guide, the command line and what you give it, but it cannot stop an agent from looking further: many agents can read any file your account can. In Loopweft's own trials, one agent listed file names across a whole user folder, and another read files it was never pointed to.

• Give the agent a folder of its own, holding only the map and anything you want it to use, such as a source's text. Start the agent in that folder.
• Keep personal files, notes and other projects somewhere else.
• Use the agent's own limits. Claude Code asks before it reads or changes anything outside the folder it was started in: say no to anything you did not expect. Codex's sandbox keeps its changes to its folder, but it can still read elsewhere. For other agents, look in their settings for a sandbox or a way to approve each step.
• Read what the agent did: its report, and its list of commands if it shows one.