Threadwell

Threadwell is a standalone, terminal-native coding harness for long-running software work. It focuses on continuity, project memory, durable decisions, and low-friction coding workflows.

npm install -g threadwell
thread

Package: threadwell
Repository: EngramResearch/threadwell
Command: thread

Status

Threadwell is early. Version 0.0.x is intended for real local use, but the public package and documentation are still being cleaned up after the fork and rebrand.

The product identity is Threadwell:

• CLI command: thread
• npm package: threadwell
• project config: .threadwell/
• global config: ~/.threadwell/agent/
• env prefix: THREADWELL_*

What Threadwell does

Threadwell gives an LLM a project-aware coding harness with:

• terminal-native interactive TUI;
• file tools: read, write, edit, grep, find, ls;
• shell execution via bash;
• persistent sessions with branching and compaction;
• native continuity state;
• semantic project memory;
• CONTEXT.md project vocabulary and operating context;
• architecture decision records via ADR support;
• optional prompt templates, skills, and TypeScript extensions for local customization;
• JSON/RPC/SDK modes for advanced automation and embedding.

Threadwell is not a browser IDE and does not ship a Web UI. It is a local coding harness that keeps the terminal workflow while adding durable project context.

Quick start

Install:

npm install -g threadwell

Run interactively:

thread

Run with an initial prompt:

thread "Review this repository and summarize the architecture"

Run non-interactively:

thread -p "List likely bugs in this file" @src/index.ts

Use a specific model:

thread --provider anthropic --model claude-sonnet-4-5
thread --model openai/gpt-4o
thread --model sonnet:high

Authentication

Threadwell supports API-key and OAuth/subscription login flows, depending on provider.

API-key example:

export ANTHROPIC_API_KEY=sk-ant-...
thread

Interactive login:

/login

Auth is stored under:

~/.threadwell/agent/auth.json

After the Threadwell rebrand, old Pi/Engram auth files are not silently migrated. Log in again if needed.

Providers and models

Built-in provider support includes:

• Anthropic
• OpenAI
• OpenAI Codex
• GitHub Copilot
• Google Gemini
• Google Vertex
• Azure OpenAI
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• Cloudflare AI Gateway / Workers AI
• xAI
• OpenRouter
• Vercel AI Gateway
• Hugging Face
• Fireworks
• DeepSeek
• Kimi / Moonshot
• MiniMax
• Xiaomi MiMo
• OpenCode-compatible providers

See docs/providers.md and docs/models.md.

Interactive mode

The TUI includes:

• transcript of user/assistant/tool messages;
• multiline editor;
• model and thinking controls;
• session resume/fork/tree navigation;
• tool output folding;
• image paste support;
• command palette via / commands;
• status/footer with project and model state.

Common commands:

| Command | Description | | --- | --- | | /login, /logout | Manage provider auth | | /model | Switch model | | /settings | Edit runtime settings | | /resume | Resume previous session | | /new | Start a new session | | /session | Show session info | | /tree | Navigate/fork the session tree | | /compact | Compact long context | | /memory ... | Inspect/search/manage memory | | /context ... | Review CONTEXT.md candidates | | /adr ... | Manage architecture decision records | | /review | Review memory/context/ADR candidates | | /feature ... | Create Threadwell feature packets | | /queue [long] | Show continuity queue tasks | | /fast <prompt> | Ask one quick low-latency question without changing normal settings | | /copy | Copy last assistant message | | /export | Export session to HTML | | /hotkeys | Show keybindings | | /quit | Exit |

Common shortcuts:

| Key | Action | | --- | --- | | Ctrl+C | Clear editor | | Ctrl+C twice | Quit | | Escape | Cancel/abort | | Ctrl+L | Model selector | | Ctrl+P / Shift+Ctrl+P | Cycle scoped models | | Shift+Tab | Cycle thinking level | | Ctrl+O | Collapse/expand tool output | | Ctrl+T | Collapse/expand thinking blocks |

See docs/keybindings.md and docs/tui.md.

Sessions and continuity

Sessions are JSONL files stored under:

~/.threadwell/agent/sessions/

Useful CLI flags:

thread -c                  # continue most recent session
thread -r                  # select previous session
thread --session <path|id> # use specific session
thread --fork <path|id>    # fork from specific session
thread --no-session        # ephemeral mode

Threadwell also maintains project continuity state under .threadwell/ so work can be resumed across sessions without relying only on chat history.

Memory layer

Threadwell includes a native memory layer for project work:

• structured event storage;
• redaction and ignore rules;
• retrieval capsules injected into context;
• CONTEXT.md semantic project vocabulary;
• ADR files for durable decisions;
• review flows for proposed memory/context/ADR updates.

Primary commands:

/memory status
/memory search <query>
/memory recent
/memory why
/memory doctor
/context review
/adr list
/review

See docs/memory.md, docs/settings.md, and the ADR guide.

Configuration

Global config:

~/.threadwell/agent/settings.json

Project config:

.threadwell/settings.json

Example:

{
  "continuity": true,
  "memory": {
    "enabled": true,
    "inject": true,
    "store": "sqlite"
  }
}

Important env vars:

| Variable | Description | | --- | --- | | THREADWELL_CODING_AGENT_DIR | Override global config dir | | THREADWELL_CODING_AGENT_SESSION_DIR | Override session dir | | THREADWELL_PACKAGE_DIR | Override package install dir | | THREADWELL_OFFLINE | Disable startup network operations | | THREADWELL_SKIP_VERSION_CHECK | Skip version checks | | THREADWELL_TELEMETRY | Enable/disable install/update telemetry | | THREADWELL_CACHE_RETENTION | Set extended prompt cache behavior | | VISUAL, EDITOR | External editor |

See docs/settings.md.

Extensions, skills, and prompts

Threadwell can be extended without changing core code.

Resource locations:

~/.threadwell/agent/extensions/
~/.threadwell/agent/skills/
~/.threadwell/agent/prompts/

.threadwell/extensions/
.threadwell/skills/
.threadwell/prompts/

Package commands:

thread install npm:@scope/threadwell-tools
thread install git:github.com/user/repo
thread remove npm:@scope/threadwell-tools
thread list
thread update
thread config

Security note: extensions and third-party packages execute code locally. Review what you install.

Docs:

• docs/extensions.md
• docs/skills.md
• docs/prompt-templates.md
• docs/packages.md

Programmatic usage

Threadwell can be embedded from Node.js:

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "threadwell";

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

await session.prompt("What files are in the current directory?");

For non-Node integrations, use RPC mode:

thread --mode rpc

See docs/sdk.md, docs/rpc.md, and docs/json.md.

CLI reference

thread [options] [@files...] [messages...]

Selected options:

| Option | Description | | --- | --- | | -p, --print | Print response and exit | | --mode json | JSON event output | | --mode rpc | RPC mode | | --provider <name> | Provider | | --model <pattern> | Model pattern/id | | --api-key <key> | Runtime API key | | --thinking <level> | off, minimal, low, medium, high, xhigh | | --tools <list> | Allowlist tools | | --no-tools | Disable all tools | | --no-builtin-tools | Disable built-in tools only | | --extension <path> | Load extension | | --skill <path> | Load skill | | --no-context-files | Disable AGENTS.md/CLAUDE.md discovery | | --export <file> | Export session HTML | | --list-models [search] | List models | | --offline | Disable startup network operations | | --help | Show help | | --version | Show version |

File arguments can be attached with @:

thread @README.md "Summarize this"
thread @screenshot.png "What is shown here?"
thread @src/index.ts @src/index.test.ts "Review these together"

Development

Repository:

https://github.com/EngramResearch/threadwell

Useful commands:

npm install
npm run check
npm run build

Related packages

• @threadwell/ai
• @threadwell/agent-core
• @threadwell/tui

License and attribution

MIT. See the repository LICENSE and NOTICE.md.

Threadwell is derived from Pi, originally developed by Mario Zechner and contributors. Pi is licensed under the MIT License; the original copyright and license notice are preserved in this repository.

Original project: https://github.com/earendil-works/pi