# 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.

```bash
npm install -g threadwell
thread
```

Package: [`threadwell`](https://www.npmjs.com/package/threadwell)  
Repository: [`EngramResearch/threadwell`](https://github.com/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:

```bash
npm install -g threadwell
```

Run interactively:

```bash
thread
```

Run with an initial prompt:

```bash
thread "Review this repository and summarize the architecture"
```

Run non-interactively:

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

Use a specific model:

```bash
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:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
thread
```

Interactive login:

```text
/login
```

Auth is stored under:

```text
~/.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`](docs/providers.md) and [`docs/models.md`](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`](docs/keybindings.md) and [`docs/tui.md`](docs/tui.md).

## Sessions and continuity

Sessions are JSONL files stored under:

```text
~/.threadwell/agent/sessions/
```

Useful CLI flags:

```bash
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:

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

See [`docs/memory.md`](docs/memory.md), [`docs/settings.md`](docs/settings.md), and the [ADR guide](https://github.com/EngramResearch/threadwell/tree/main/docs/adr).

## Configuration

Global config:

```text
~/.threadwell/agent/settings.json
```

Project config:

```text
.threadwell/settings.json
```

Example:

```json
{
  "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`](docs/settings.md).

## Extensions, skills, and prompts

Threadwell can be extended without changing core code.

Resource locations:

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

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

Package commands:

```bash
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/extensions.md)
- [`docs/skills.md`](docs/skills.md)
- [`docs/prompt-templates.md`](docs/prompt-templates.md)
- [`docs/packages.md`](docs/packages.md)

## Programmatic usage

Threadwell can be embedded from Node.js:

```typescript
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:

```bash
thread --mode rpc
```

See [`docs/sdk.md`](docs/sdk.md), [`docs/rpc.md`](docs/rpc.md), and [`docs/json.md`](docs/json.md).

## CLI reference

```bash
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 `@`:

```bash
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:

```text
https://github.com/EngramResearch/threadwell
```

Useful commands:

```bash
npm install
npm run check
npm run build
```

## Related packages

- [`@threadwell/ai`](https://www.npmjs.com/package/@threadwell/ai)
- [`@threadwell/agent-core`](https://www.npmjs.com/package/@threadwell/agent-core)
- [`@threadwell/tui`](https://www.npmjs.com/package/@threadwell/tui)

## License and attribution

MIT. See the repository [`LICENSE`](https://github.com/EngramResearch/threadwell/blob/main/LICENSE) and [`NOTICE.md`](https://github.com/EngramResearch/threadwell/blob/main/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>
