Repository avatar
AI Tools
v0.5.0
active

weft

io.github.chenziyaos/weft

Search local AI conversations by file or phrase and recall source turns. Four read-only tools.

Documentation

Weft logo

Weft

Make the context a model reads visible and editable.

Every exchange with a model or an agent is a node on an infinite canvas; the wires between nodes are the context.
What a node sees is exactly what flows into it along the arrows. Cut one wire, and the next answer changes.

CI License Node · 中文 · Docs · User manual

Weft in use: ask from a document, branch a conversation, and edit the connections that carry context.

Weft is for people who run long model or agent sessions (development, research, debugging over dozens of turns) and want to decide exactly what the next turn reads. It is a local web app plus a small proxy; it is not a model, an agent runtime or a hosted service.

Fork notice. Weft is a fork of ThoughtDAG by Xia Chen (MIT). It keeps the canvas and adds a packaged weft command, an agent Skill and a live canvas bridge for terminal agents. See Relationship to ThoughtDAG.

Quick start

Requires Node.js 20 or newer and git.

git clone https://github.com/chenziyaos/weft.git
cd weft
npm install
npm run server         # model proxy: "Weft proxy (Vercel AI SDK) running on http://localhost:3001"
npm run dev            # canvas: http://localhost:5173 (second terminal)

Open http://localhost:5173, click Connect a model (top right) and paste a provider key or the URL of any OpenAI-compatible endpoint. Then type a question on the start page and press Enter. To look around without a model, click Load example canvas.

Without cloning. The weft-canvas package on npm carries the built canvas, the proxy and the weft command:

npm install -g weft-canvas
weft serve                               # serves the canvas on http://localhost:3001 and opens it

npx weft-canvas serve runs it once without a global install. Canvases are saved in the browser (IndexedDB), so open the same address each time.

As a Claude Code or Codex plugin. The plugin adds the session command (/weft:weft in Claude Code, the weft Skill in Codex), the weft-canvas Skill and the read-only MCP server, which runs from the CLI bundled in the plugin (about 0.3 MB; nothing is downloaded from npm). It does not include the canvas app; start that with weft serve or the desktop app. --sparse keeps the checkout to the plugin files instead of the whole repository.

claude plugin marketplace add chenziyaos/weft --sparse .claude-plugin plugins
claude plugin install weft@weft

codex plugin marketplace add chenziyaos/weft --sparse .claude-plugin --sparse plugins
codex plugin add weft@weft

What it does

The problem it targets. Forty turns into an agent session, the model is still chasing a theory that died at turn 8, because every new turn re-reads all the turns before it. Re-explaining in a fresh window loses the evidence; compaction drops information without telling you which. In Weft the next turn's input is a set of wires you can see, cut and reconnect.

On the canvasWhat the model receives
A follow-up grows a solid-wired childThe full upstream chain, nothing else
A branch forks from an answer or a selected passageSibling branches never see each other
A dashed reference wires in a node from elsewhereThat node's own Q/A, not its ancestry
A material (note, file, PDF, image, web snapshot) is wired inIt goes first, labelled with its source
A wire is cutThat history leaves the next request; Cmd+Z brings it back
Several wires flow into one nodeMerged threads, model comparison, synthesis

1. Draw the conversation as a map

  • Follow-ups and branches from any node; select a passage to branch on just that passage.
  • References and materials: only what is wired counts.
  • Model comparison: several models answer on separate branches, then a synthesis node reads exactly those wires.

See Branch a conversation and Conversation nodes.

2. See what the model read

  • Before sending: "will send ~N tok · M messages" above the input expands into the full request, in order. The preview and the real request come from the same compiler.
  • After sending: each answer version keeps the request it was generated from; rows that differ from what the node would read now are marked Changed since.
  • When upstream changes: the answer is marked Upstream changed instead of going stale silently.

Example from the user manual walk-through (pre-send estimates, not billed tokens): cutting the wire between a branch and the first question drops the branch's next request from about 2,603 to about 1,384 tokens.

3. Edit context by editing wires

Cut (select a wire, Delete), connect and reconnect (drag a handle; cycles are refused), right-click a solid wire for Insert a step here, archive a node (it stays visible, its content leaves the context), and replay: rerun affected nodes in dependency order, each adding a new version. See Edit AI context and Versions and replay.

4. Agents follow the same rule

  • Agent nodes: pick Codex or Claude Code in the model menu; the agent works in the canvas directory and the node records the files it changed.
  • Sessions as graphs: local Claude Code, Codex, DeepSeek Harness and Pi sessions open as a live mirror you can prune, branch and condense; the original session file is never rewritten. /weft in Claude Code ($weft in Codex) opens the current session.
  • A terminal agent edits the canvas: weft setup skill --apply installs the Skill; in the host handoff panel (bottom right) tick 允许本机 Agent 编辑此画布 ("allow local agents to edit this canvas"; this panel is not translated yet). Concurrent writers get REVISION_CONFLICT and reread instead of overwriting.
  • Why layer: weft why src/lib/api.ts lists the turns that touched a file; weft mcp offers the same lookups as a read-only MCP server.

See Session Atlas, Why layer and cli/README.md.

Configuration

Model access needs one of these; any one is enough.

OptionWhereNotes
Provider keyConnect a model in the browserKept in this browser (localStorage) and the proxy's memory, never written to disk
OpenAI-compatible endpointConnect a model → Custom endpointYour own gateway, vLLM, LM Studio, a relay
Keys in .envcp .env.example .envOPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY, OPENROUTER_API_KEY, ZHIPU_API_KEY, DASHSCOPE_API_KEY; restart the proxy after editing
Local model.env: OLLAMA_MODELS=qwen3:8b,llama3.2OLLAMA_BASE_URL defaults to http://localhost:11434

Optional pieces:

  • Decision model (scores branches, ranks recall): OpenRouter Jev, TypeSafe, Cloudflare, a self-hosted /v1/systemone endpoint, or the chat model as an uncalibrated stand-in. Without one, every decision falls back to a rule. See docs/setup.md.
  • Agents: install claude (Claude Code) or codex on PATH; each runs on its own login.
  • Ports: PORT in .env for the proxy (default 3001); VITE_API_BASE if the canvas should call a proxy elsewhere; weft serve --port N.

Limitations

  • The preview and receipts cover the input the canvas compiles, not provider-side state; with an agent runner, the agent runtime's own system prompt is not in the preview.
  • Canvases and receipts live in the browser profile you used; there is no sync or account. Back up with Export backup (.json).
  • The desktop shell (desktop/) builds from source; no signed installers are published.
  • The host handoff panel is Chinese-only; the rest of the UI is English and Chinese.
  • Session mirrors read the on-disk formats of Claude Code, Codex, DeepSeek Harness and Pi as observed; a format change in those tools can break the mirror until the reader is updated.
  • Acceptance scripts were run on macOS with local Chrome; other platforms are not covered. What was run, and what it does not establish, is in VERIFICATION.md.

Troubleshooting

SymptomCause and fix
Proxy prints No LLM API key in .env — starting emptyExpected without .env. Connect a model in the browser, or add a key to .env and restart npm run server.
weft serve says the port is in useAnother program holds 3001. Run weft serve --port 3002.
Codex / Claude Code missing from the model menuThe CLI is not on PATH. The menu lists the directories it searched; install the CLI or add it to PATH, then reopen the menu.
The canvas loads but every request failsThe page is not reaching the proxy. Keep npm run server running, or set VITE_API_BASE to the proxy's URL.

More in docs/reference/troubleshooting.md.

Documentation

Start hereRead
Walk through one session step by stepUser manual · 中文
Install and connect a modeldocs/index.md · Connect a model
Look up a featureGuide map · Tutorials · Reference
CLI, why layer, MCPcli/README.md
Design and acceptanceARCHITECTURE.md · VERIFICATION.md · DEPLOYING.md

The docs render as a VitePress site with search: npm run docs:dev, or the copy the Pages workflow publishes at https://chenziyaos.github.io/weft/docs/.

Develop

CommandWhat it does
npm run buildTypecheck and production web build in dist/
npm run lintESLint
npm testCLI unit tests (builds the CLI first) plus layout, live-log and subagent checks
npm run cli:packThe weft-canvas CLI tarball (canvas, Skill and CLI together), the same artifact that is published to npm
node scripts/verify-cli-package.mjs cli/weft-canvas-<version>.tgzInstall the tarball into an empty project and drive it in Chrome
npm run docs:devDocumentation site
npm run desktopElectron shell from source
PathContents
src/React 19 + Vite canvas: components/, zustand store/, graph and context lib/, i18n/ (English, Chinese)
server.mjsExpress proxy on the Vercel AI SDK, with agentic web search
cli/ · skill/ · protocol/weft CLI, the canvas Skill, the context-bundle protocol and host adapters
runtime/Local agent runtimes (Claude Code, Codex, Pi) and the canvas bridge
desktop/ · dsh/Electron shell; DeepSeek Harness plugin
scripts/Build helpers, Skill installer, acceptance scripts (verify-*.mjs)
docs/ · website/ · video/Docs, static website, Remotion video sources
benchmark/Context-intervention benchmark: cases, gold answers, captured runs, tools

Contributions: see CONTRIBUTING.md. Security reports: see SECURITY.md.

Relationship to ThoughtDAG

Weft started from ThoughtDAG (chenxiachan/thoughtdag, MIT, © 2026 Xia Chen) and was renamed. The canvas model (nodes, wires as context, versions, replay, Session Atlas), the why layer (why, mcp) and the context-bundle protocol come from that project. This repository adds the packaged CLI (weft serve, open, graph, bundle, setup skill), the canvas Skill and its installer, the live canvas bridge that lets terminal agents edit an open canvas, and the acceptance scripts in scripts/. Its git history starts fresh; upstream's history is in the upstream repository. The two projects evolve independently: upstream changes are not merged into Weft on a schedule.

License

MIT, see LICENSE. The upstream copyright notice is retained as the license requires.

NPM
weft-canvas
Install Command
npm install weft-canvas
Runtime: npx