Install

Prerequisites

• macOS, Linux, or Windows. Curl portable install is macOS/Linux (arm64 / x64) only. On Windows use npx or a clone (Node.js ≥ 22.12).
• At least one agent CLI on the same machine:
• Claude Code
• opencode
• Cursor agent CLI
• Antigravity agy CLI
• Codex CLI
• GitHub Copilot CLI
• Grok Build (grok)
• Muse Code (muse)

One provider is enough. threadle detects what’s installed and hides the rest. See Providers.

Node.js is only required for the npm and clone tabs (and for Windows). The curl installer ships a portable Node 26 binary.

Windows & WSL

Setup	How
Native Windows	npx threadle or clone + build. Config: %USERPROFILE%\.config\threadle. Sees native Windows agent homes.
WSL	Install threadle + agent CLIs inside the distro (curl works). Sees WSL ~/.claude, etc.
Cross-boundary	Not supported. One process does not bridge \\wsl$\… and native Windows agent storage.

---

Install

curl npm clone

no npm · portable Node · then run threadle → http://127.0.0.1:4570

curl -fsSL https://threadle.sh/install.sh | bash

Node.js ≥ 22.12 · opens http://127.0.0.1:4570

npx threadle

dev / contrib · opens http://127.0.0.1:4570

git clone https://github.com/threadle-sh/threadle
cd threadle
npm install && npm run build && npm start

Method	What you get
curl	Platform archive from GitHub Releases, SHA256SUMS verified, ~/.local/share/threadle + ~/.local/bin/threadle
npm	Published package via npx (needs Node.js ≥ 22.12)
clone	Monorepo build for development

Pin a curl release with THREADLE_VERSION=0.1.0. Other knobs: THREADLE_INSTALL_DIR, THREADLE_BIN_DIR, THREADLE_REPO, THREADLE_PLATFORM. Re-run curl install to update. Ensure ~/.local/bin is on your PATH. There is no Homebrew formula yet.

Your existing sessions appear immediately. There is no import step.

Before relying on agent runs, verify the environment:

threadle check                 # Node, config dir, UI assets, CLIs, storage
threadle check --providers     # also probe inject-critical CLI flags

Details: CLI → Check.

Development

npm run dev      # API + Vite HMR on :5173

---

Flags

threadle [options]                       # start the UI server
threadle run <file|template|graphId>     # run a workflow (foreground)
threadle run <target> --detach           # start a server job; requires threadle already up
threadle jobs | status | logs | stop     # inspect / cancel server jobs
threadle services | providers | agents   # health and discovery
threadle sessions | graphs | models | nodes | templates
threadle check | check --providers | mcp

Flag	Meaning
--port <n>	HTTP port (default 4570)
--no-open	Don’t open a browser
--dir <path>	Project directory to highlight (default: cwd)
--detach	With run: hand the job to the live server
-h, --help	Show usage

Full inventory and run flags: CLI reference.

---

Where things live

threadle keeps all of its own state in one directory:

Path	Purpose
~/.config/threadle/settings.json	Editor opener, billing mode, examples toggle
~/.config/threadle/graphs/	Saved workflows
~/.config/threadle/payloads/	Content-addressed context library
~/.config/threadle/nodes/	Custom nodes
~/.config/threadle/runs/	Run and injection history
~/.config/threadle/search.db	Full-text search index

Portable install binary tree (curl path only): ~/.local/share/threadle/{bin,node,app}.

Override the config location with THREADLE_CONFIG_DIR (Windows default: %USERPROFILE%\.config\threadle). Full layout: Files & config.

MCP: run / connect / work. threadle mcp and the ◈ MCP tool node.

It reads your agents’ storage (~/.claude/projects, opencode’s SQLite, Cursor transcripts, Antigravity brain, Codex rollouts, Copilot session store, Grok session dirs) and never writes to it. Runs go through each tool’s CLI, which then writes new sessions as usual. See Trust model.

---

Verify it works

1. Open http://127.0.0.1:4570. The Sessions view should list real sessions.
2. Optional Workflows addon: run threadle-workflows → http://127.0.0.1:4571/addon/workflows.
3. Check Services in the UI. Or from a second terminal: threadle services. Each installed provider shows as available, with a version.
4. Run an example that costs nothing:

threadle run hello --approve-all
# with the server already up:
threadle run hello --detach && threadle jobs

If sessions are missing or a provider shows unavailable, see Troubleshooting.

---

Next

• CLI → Check. Verify Node, config, CLIs, and inject flags
• Sessions. What you get with zero wiring
• Quickstart. See sessions, then optionally a first graph
• Tour of the app. What each view does
• Workflows addon. Optional canvas and recipes