Weft documentation

Overview

Weft is a local-first learning tool: an AI harness to learn using AI. You start a learning project and Weft renders its concept graph and its material (lessons, examples, tests, challenges, flashcards) in your browser. An AI assistant can read your graph and write new material into it through an MCP server. Everything lands on disk as plain .md and .json files, and those files are always the source of truth: the app is just a viewer and editor on top of them.

The problem it solves: an AI explanation is gone the moment the chat scrolls away. With Weft, the explanation becomes a lesson file inside a concept, the concept sits in a graph with its prerequisites, and your mistakes get recorded next to it. What you learn accumulates in one place that you own.

The design language is embroidery on linen: the screen is linen seen from above, each concept is a needle head, and prerequisites are taut burgundy threads. A solid thread means requiere (a hard prerequisite); a dashed thread means relacionado_con (a loose association).

How the pieces fit together:

• The web app: the graph canvas plus a screen per concept with six tabs of material.
• The files: a folder called WEFT-MASTER/ holds the whole project, one flat folder per concept.
• The CLI: the weft command starts and stops the server from any folder and remembers where your project lives.
• The MCP server: lets an AI assistant read the graph and write material with the same validation the web app uses.

Install & run

Prerequisites: Node.js 20 or newer (check with node --version). Weft is not published to npm yet, so everything installs from source. MIT licensed.

As a user: install once, use it anywhere

This is the recommended path if you just want to study with Weft. It builds the app once and puts a global weft command on your PATH:

git clone https://github.com/Ginescag/weft.git weft
cd weft
npm install
npm run build
npm link
npm run seed
weft

• npm run build compiles the frontend and the server into dist/. The CLI serves this build, so it has to exist.
• npm link symlinks the global weft command to your clone. A later git pull plus npm run build updates it in place. If you prefer a standalone copy that does not track the clone, use npm install -g . instead (its prepack step builds for you).
• npm run seed is optional: it creates a starter project with a small RAG roadmap so the canvas is not empty on first open.
• The first weft run with no saved project asks for a parent folder, creates WEFT-MASTER inside it and remembers the location. Pick Start Weft in the menu and open http://localhost:3131.

Verify the install from any other folder with weft help.

As a developer: two servers, hot reload

git clone https://github.com/Ginescag/weft.git weft
cd weft
npm install
npm run seed
npm run dev

• Frontend (Vite): http://localhost:5173
• Backend (Hono API): http://localhost:3131

npm run dev starts both processes with hot reload. The frontend proxies /api to the backend, and the dev backend reads ../WEFT-MASTER. Work against :5173.

Production: one process serves everything

npm run build
npm run serve

After a build, a single process serves the compiled app and the API on :3131. Deep links survive reloads (SPA fallback), so you can bookmark a concept.

Your learning project: WEFT-MASTER/

A project is just a folder of concepts on disk, self-contained and portable, like .git in a repo. Because it is a normal folder, you can back it up, sync it or version it like any other directory. There are three ways to get one:

• npm run seed copies examples/starter-master/ to WEFT-MASTER/: a small RAG roadmap (embeddings → chunking / retrieval → rag). It does nothing if the folder already exists, so it is always safe to run.
• Managed first run. Run weft with no saved project and it asks for a parent folder, creates <parent>/WEFT-MASTER inside it and remembers the location per-user. Every future weft reopens the same project.
• weft path <dir> points Weft at <dir>/WEFT-MASTER: the folder is created if missing and adopted if it already holds a project. weft path with no argument prints the current location.

WEFT-MASTER/
├── <concept>/           one flat folder per concept
│   ├── .meta            id, nombre, resumen, relaciones (prerequisites)
│   ├── .errorlog        recorded mistakes
│   ├── tests.json       multiple-choice questions
│   ├── flashcard.json   flashcards
│   └── lessons/  examples/  challenges/  notes/   (.md; lessons/examples also take .pdf)
└── .weft/              graph.json (cache) + stickies.json, arrows.json, layout.json

What each piece is for:

• .meta holds the concept's identity: its id, nombre, resumen and, crucially, its relaciones: the list of its own prerequisites.
• .errorlog accumulates every test question you missed, with the correct answer and its explanation.
• tests.json and flashcard.json hold the question bank and the flashcards for that concept.
• lessons/, examples/, challenges/ and notes/ hold markdown files; lessons/ and examples/ also accept PDFs.
• .weft/ holds derived state: graph.json (a cache of the whole graph, rebuilt from the .meta files) plus the canvas layout, stickies and arrows.

The graph canvas

The canvas is the home screen: your whole map at a glance, laid out however you like. Everything you arrange persists to .weft/, so the layout is stable across reloads.

• Explore. Pan by dragging the linen, zoom with the wheel, and use Fit to frame the whole graph. Hovering a needle shows the concept's summary; clicking it opens the concept screen.
• Search. Ctrl+K opens the command palette. Type a few letters and jump straight to any concept, however big the map gets.
• Add a concept. The Add concept button asks for a name and a short summary, and drops the new needle on the canvas.
• Draw a thread. Enter draw mode, drag from one needle to another and pick the relation type: requiere (solid) or relacionado_con (dashed).
• Select and edit. Shift plus drag box-selects needles, threads and stickies; dragging the selection moves it as a group. Tap a thread to select it and press Del to cut it.
• Sticky notes. Label a region of the map with a linen sticky: a big title with an optional body, resizable by the corner grip, with a free hex colour picked on a colour wheel. Double-click to edit. Stickies sit under the needles and never navigate anywhere.
• Roadmap arrows. Thick directed arrows you place as free stickers between regions, useful for marking a study order across areas. Drag the endpoints to reposition, double-click the mid dot to change colour and thickness, press Del to remove.

Inside a concept

Clicking a needle opens the concept screen: six tabs, each mapping directly to files in the concept's folder.

• Lessons (lessons/): the explanations. Markdown files render as formatted text; PDFs render in-app.
• Examples (examples/): worked examples, same formats as lessons.
• Tests (tests.json): multiple-choice questions. Answer and check; every miss is appended to .errorlog together with the correct answer and its explanation. The graph's Mistakes timeline collects every recorded miss across the whole project, newest first, so you can review exactly what you got wrong and why.
• Challenges (challenges/): open-ended exercises. Read the prompt and write your attempt in the embedded solution notepad; attempts are saved to challenges/.solutions/.
• Flashcards (flashcard.json): active-recall cards for the concept.
• Notes (notes/): your own markdown notes, for anything the other tabs don't cover.

PDFs in-app: drop a .pdf into a concept's lessons/ or examples/ folder and Weft renders it page by page (PDF.js) with a download link. No exporting, no external viewer.

The CLI

The nicest way to live with Weft is as the weft command: install it once (see Install) and run it from any folder. It remembers your project, so you never need the source checkout open just to study.

While serving, Weft takes over the terminal with a full-screen dashboard (like vim): an ANSI banner and a live request log. Ctrl+C hands your terminal back exactly as it was, scrollback intact. Your project pointer lives in a per-user config file: %APPDATA%/weft/config.json on Windows, ~/.config/weft/config.json elsewhere.

Update and uninstall

• Linked from source: git pull && npm install && npm run build. The link keeps working because it points at the clone.
• Standalone copy: re-run npm install -g . from the updated clone.
• Remove: npm rm -g weft (use npm unlink -g weft if you installed via npm link).

AI over MCP

MCP (Model Context Protocol) is an open protocol that lets AI clients talk to external tools. Weft ships an MCP server, started with weft mcp, that exposes your project to an assistant over stdio: the client launches the process itself, so you register the command once and forget about it. Once connected, the assistant can read the graph and write lessons, examples, tests, flashcards, whole roadmaps and canvas layout, all through the same validation the web app uses. Nothing bypasses the filesystem rules.

Claude Code

claude mcp add weft -- node /absolute/path/to/weft/bin/weft.js mcp

Tools appear as mcp__weft__* and the prompts as slash commands: type / and filter for weft. After npm link you can use weft mcp as the command instead of the node path.

Claude Desktop

{
  "mcpServers": {
    "weft": {
      "command": "node",
      "args": ["/absolute/path/to/weft/bin/weft.js", "mcp",
               "--master", "/absolute/path/to/WEFT-MASTER"]
    }
  }
}

Settings → Developer → Edit Config. Use node plus absolute paths (robust on Windows), and pass --master so the server knows where your project lives. Fully quit and reopen the app; the tools appear in the tools menu and the prompts under the + menu.

Codex (ChatGPT)

[mcp_servers.weft]
command = "node"
args = ["/absolute/path/to/weft/bin/weft.js", "mcp"]

Recent Codex CLI versions also accept codex mcp add weft -- node … mcp. Note that ChatGPT on the web only accepts remote connectors; for a local server like Weft's, Codex is the way in.

OpenCode

{
  "mcp": {
    "weft": {
      "type": "local",
      "command": ["node", "/absolute/path/to/weft/bin/weft.js", "mcp"],
      "enabled": true
    }
  }
}

Place it in the project root, or globally in ~/.config/opencode/opencode.json.

What the AI can see and do

• Resources (read): weft://graph (all concepts and relations), weft://concept/{id} (one concept), weft://concept/{id}/{folder}/{file} (one file), weft://errors (every recorded mistake), and the canvas state: weft://stickies, weft://layout, weft://arrows.
• Tools (write): lay a whole topic in one call (build_subgraph); manage concepts and relations (create_concept, add_relation, add_relations, remove_relation, update_concept); write content (create_lesson, create_example, create_challenge, create_note, edit_lesson, add_questions, add_flashcards, log_error); and arrange the canvas (set_positions, stickies and arrows).

Every write lands as real .md / .json under WEFT-MASTER/, validated exactly like a write from the web app.

Prompts: one-click workflows

Prompts are reusable workflows the server offers your client: pick one and it injects a ready-made instruction (which resources to read, which tools to call), so the assistant runs the whole task and you just confirm. You don't strictly need them: with the tools connected, plain language works too ("build me a roadmap for Kafka", "fill in the rag concept").

In Claude Code they are slash commands (/mcp__weft__build_roadmap); in Claude Desktop, the + menu. After adding or changing prompts, reconnect the server so the client reloads them: run /mcp in Claude Code, or restart the app.

The skill

A skill is a packaged set of instructions that Claude Code auto-loads when it is relevant. Weft's skill teaches the whole workflow (read the graph first, lay a topic with build_subgraph, fill concepts, curate relations, arrange the canvas) plus the conventions that keep a graph clean. With it installed you never have to re-explain how to drive Weft at the start of a session.

weft skill install

• It ships in the repo at .claude/skills/weft/SKILL.md and auto-loads whenever you run Claude Code inside the project.
• weft skill install copies it to ~/.claude/skills/weft/ so it is available from any folder. Start a new Claude Code session afterwards.
• The skill is a Claude Code feature. Claude Desktop has its own skills system and does not read ~/.claude/skills/; there, the prompts above are the equivalent one-click workflows.

Troubleshooting

• "frontend build not found": run npm run build before npm run serve. The CLI serves the compiled app, not the sources.
• Nothing renders in dev: make sure the backend is up (npm run dev starts both); the frontend needs the API on :3131.
• The port is taken: weft stop frees the port of a running server, or serve elsewhere with weft serve --port <n>.
• npm install TLS errors: the --cafile workaround described in CONTRIBUTING.md.
• Where things live: the project pointer is per-user at %APPDATA%/weft/config.json (Windows) or ~/.config/weft/config.json; the running-server record sits next to it (used by weft stop).
• Project data: everything is under your WEFT-MASTER/. Delete the folder and you have deleted the project; nothing is stored anywhere else.

Contributing

Weft is MIT licensed and built in the open: no company behind it, no telemetry. Bugs and feature requests go through the issue templates; anything bigger than a small fix starts as an issue first, so the approach is agreed before the work. Improving the docs (README, HOWTO, in-code comments) and translating are first-class contributions too.

git clone https://github.com/<you>/weft.git
cd weft
npm install
npm run seed
npm run dev

npm run typecheck && npm run build green is the whole gate: CI runs the same two commands on every PR. There is no test runner configured yet; end-to-end checks are done by hand.

Sending a pull request

• Branch off main: git checkout -b fix/short-description.
• Make your change and keep the commits focused.
• Run npm run typecheck && npm run build, both green.
• Update the docs if behavior changed (README / HOWTO).
• Push, open a PR, fill in the template and link any related issue.

The source repo, briefly

weft/
├── frontend/            Vite + React + TS (graph & concept screens)
├── server/              Hono backend + MCP server (filesystem layer in master.ts)
├── bin/weft.js         CLI entry point
├── examples/            starter-master/ (the seed for npm run seed)
├── .claude/skills/      the bundled Weft skill
├── IA-DOCS/             internal design docs (Spanish)
└── HOWTO.md             user guide (EN) · HOWTO.es.md (ES)

Conventions worth knowing before you touch code:

• The filesystem is the source of truth. Every write goes through server/src/master.ts (atomic, validated) and lands as .md / .json. graph.json is a derived cache, never primary.
• Code, UI strings and new docs are in English; the on-disk data keys stay Spanish (nombre, resumen, relaciones…). README and HOWTO ship bilingual.
• Design language "embroidery on linen": one saturated colour, calm motion, prefers-reduced-motion honoured.

Read CONTRIBUTING.md and the Code of Conduct, then open an issue. Thanks for helping weave Weft. 🧵