Install

Prerequisites

• Node.js ≥ 22.5 — threadle uses the built-in node:sqlite for read-only opencode access
• At least one agent CLI on the same machine:
  • Claude Code
  • opencode
  • Cursor agent CLI

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

---

From source

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

Opens http://127.0.0.1:4570. Your existing sessions appear immediately — there is no import step.

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

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, pricing source, 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

Override the location with THREADLE_CONFIG_DIR. Full layout: Files & config.

It reads your agents’ storage (~/.claude/projects, opencode’s SQLite, Cursor transcripts) and never writes to it. See Trust model.

---

Verify it works

1. Open http://127.0.0.1:4570 — the Sessions view should list real sessions.
2. Check Services in the UI — or from a second terminal: threadle services — each installed provider shows as available, with a version.
3. Run an example that costs nothing:

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

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

---

Next

• Quickstart — your first workflow
• Tour of the app — what each view does
• Learning path — the ordered route