# Using Threadwell

This page collects day-to-day usage details that do not fit on the quickstart page.

## Interactive Mode

<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>

The interface has four main areas:

- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
- **Editor** - where you type; border color indicates the current thinking level
- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model

The editor can be replaced temporarily by built-in UI such as `/settings` and other terminal-native overlays.

The chat transcript uses a barebones Pi-like renderer by default: assistant thinking and tool output stay in the natural transcript flow without rich cards. Threadwell features such as image attachments, attach, revert/change commands, ThreadSuite, diagnostics, footer, and settings remain available around that simple transcript.

### Editor Features

| Feature | How |
|---------|-----|
| File reference | Type `@` to fuzzy-search project files |
| Path completion | Press Tab to complete paths |
| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
| Shell command | `!command` runs and sends output to the model |
| Hidden shell command | `!!command` runs without sending output to the model |
| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |

See [Keybindings](keybindings.md) for all shortcuts and customization.

## Slash Commands

Type `/` in the editor to open command completion. Built-in commands cover model selection, settings, sessions, memory, context, and exports. Skills and prompt templates can also appear as slash commands when configured.

| Command | Description |
|---------|-------------|
| `/login`, `/logout` | Manage OAuth or API-key credentials |
| `/model` | Switch models |
| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
| `/settings` | Thinking level, message delivery, transport |
| `/resume` | Pick from previous sessions |
| `/new` | Start a new session |
| `/name <name>` | Set session display name |
| `/session` | Show session file, ID, messages, tokens, and cost |
| `/tree` | Jump to any point in the session and continue from there |
| `/fork` | Create a new session from a previous user message |
| `/clone` | Duplicate the current active branch into a new session |
| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
| `/fast <prompt>` | Ask one quick low-latency question with reasoning off and bounded read-only inspection for that turn only |
| `/changes [id\|last N\|A..B]` | Inspect recent Threadwell change sets and diffs |
| `/revert [id\|last N\|A..B]`, `/rev ...` | Select, preview, and safely revert change sets |
| `/revert to <id>`, `/rev to <id>` | Return the worktree to a previous change-set point |
| `/unrevert` | Re-apply the most recent safe revert when no conflicts are present |
| `/copy` | Copy last assistant message to clipboard |
| `/export [file]` | Export session to HTML |
| `/share` | Upload as private GitHub gist with shareable HTML link |
| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
| `/hotkeys` | Show all keyboard shortcuts |
| `/changelog` | Display version history |
| `/quit` | Quit Threadwell |

## Change Sets and Safe Revert

Threadwell records project-local change sets for agent turns that modify files. Change sets are stored under `.threadwell/snapshots/` as content-addressed blobs plus JSONL metadata. They are independent of your Git repository and do not commit, reset, checkout, or mutate `.git`.

Use `/changes` to inspect the timeline:

```text
/changes          # recent change sets
/changes 12       # one change set with diff
/changes last 3   # last three active change sets
/changes 10..12   # range with diffs
```

Use `/revert` or `/rev` to undo recorded file changes:

```text
/revert           # open a selector for active change sets
/revert 12        # revert one change set
/rev last 2       # revert the last two active change sets
/revert 10..12    # revert a range, newest first
/revert to 10     # return to change set 10 by reverting later active change sets
/unrevert         # undo the most recent safe revert
```

Revert always previews the affected change sets and requires exact confirmation (`REVERT`, or `UNREVERT` for `/unrevert`). If current file contents no longer match the recorded after-state, Threadwell blocks instead of overwriting your work.

Supported file operations:

- created files are removed on revert;
- modified files are restored from their before snapshot;
- deleted files are recreated from their before snapshot;
- skipped files, large files, binary files, unsafe paths, and conflicts are not force-reverted.

Limits:

- Revert is worktree-only. It does not undo external side effects such as commands that changed services, databases, network resources, or files outside the project.
- Bash deletion snapshots cover simple deletion commands such as `rm file`, `del file`, `erase file`, and `remove-item file`. Complex shell scripts, globs, generated paths, and external tools may not be fully attributable.
- `.threadwell/`, `.engram/`, `.git/`, dependencies, build outputs, caches, and other runtime/generated directories are excluded from snapshots.

## Message Queue

You can submit messages while the agent is still working:

- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
- **Escape** aborts and restores queued messages to the editor.
- **Alt+Up** retrieves queued messages back to the editor.

On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want Threadwell to receive the shortcut.

Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.

## Sessions

Sessions are saved automatically to `~/.threadwell/agent/sessions/`, organized by working directory.

```bash
thread -c                  # Continue most recent session
thread -r                  # Browse and select a session
thread --no-session        # Ephemeral mode; do not save
thread --session <path|id> # Use a specific session file or session ID
thread --fork <path|id>    # Fork a session into a new session file
```

Useful session commands:

- `/session` shows the current session file and ID.
- `/tree` navigates the in-file session tree and can summarize abandoned branches.
- `/fork` creates a new session from an earlier user message.
- `/clone` duplicates the current active branch into a new session file.
- `/compact` summarizes older messages to free context.
- `/compact status` shows current context usage, active compaction threshold, and whether manual compaction is recommended.

Long sessions keep durable session history on disk, but the active terminal transcript may collapse old rendered blocks after compaction or after very long conversations so streaming stays responsive. Use `/tree` or resume/fork commands when you need to navigate older saved history.

See [Sessions](sessions.md) and [Compaction](compaction.md) for details.

## Context Files

Threadwell loads `AGENTS.md` or `CLAUDE.md` at startup from:

- `~/.threadwell/agent/AGENTS.md` for global instructions
- parent directories, walking up from the current working directory
- the current directory

Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.

### System Prompt Files

Replace the default system prompt with:

- `.threadwell/SYSTEM.md` for a project
- `~/.threadwell/agent/SYSTEM.md` globally

Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.

## Exporting and Sharing Sessions

Use `/export [file]` to write a session to HTML.

Use `/share` to upload a private GitHub gist with a shareable HTML link.

If you use Threadwell for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/threadwell-share-hf`](https://github.com/badlogic/threadwell-share-hf). It publishes sessions to Hugging Face datasets.

## CLI Reference

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

### Package Commands

```bash
thread update                  # Update Threadwell and packages; skips pinned packages
thread update --self           # Update Threadwell only
thread list                    # List installed packages

# Advanced local package management
thread install <source> [-l]   # Install package, -l for project-local
thread remove <source> [-l]    # Remove package
thread config                  # Enable/disable package resources
```

See [Threadwell Packages](packages.md) for package sources and security notes.

### Modes

| Flag | Description |
|------|-------------|
| default | Interactive mode |
| `-p`, `--print` | Print response and exit |
| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
| `--attach` | Start a token-auth HTTP/SSE attach server for the open interactive session |
| `--attach-host <host>` | Attach server bind host, default `127.0.0.1` |
| `--attach-port <port>` | Attach server port, default `0` for an available port |
| `--attach-token <token>` | Attach server bearer token, default generated per start |
| `--export <in> [out]` | Export a session to HTML |

In print mode, Threadwell also reads piped stdin and merges it into the initial prompt:

```bash
cat README.md | Threadwell -p "Summarize this text"
```

### Attach Server

Attach mode lets another local process or trusted LAN client observe and control the currently open interactive session. It is off by default and only starts when explicitly requested.

```bash
thread --attach
thread --attach --attach-port 8787
thread --attach --attach-host 0.0.0.0 --attach-token <secret>

# Or start a secure trusted-LAN headless host with no local TUI:
thread host
thread host --attach-port 8787

# Localhost-only host mode for same-machine testing:
thread host --local

# Or start attach mode from inside the TUI:
/attach          # localhost/same-machine
/attach lan      # trusted LAN + strict pairing + QR
/attach stop

# From another local terminal, use the URL printed by the host:
thread attach "http://127.0.0.1:8787/state?token=<token>"
```

When enabled, the startup header shows a redacted attach host/port status, not the token. Use `/attach` inside the TUI to show the tokenized URL and copyable `thread attach` command. The server exposes:

- `GET /state` - current session state;
- `GET /messages` - current session messages;
- `GET /events` - Server-Sent Events stream for state and agent events;
- `POST /command` - remote commands: `prompt`, `steer`, `follow_up`, and `abort`.

Authentication is required with either `Authorization: Bearer <token>` or `?token=<token>`. Command request bodies are bounded and oversized requests are rejected. The default bind address is localhost. Binding to `0.0.0.0` or another LAN address exposes a shell-capable agent control surface to the network; use only on trusted networks with a strong token.

Attach mode does not mirror the terminal framebuffer. It streams structured session events and routes commands into the live session while the local TUI remains the primary owner. `thread host` uses the same attach server without opening the local TUI. Bare `thread host` is the personal trusted-LAN workflow: it binds for LAN access, enables strict pairing by default, prints API and Mobile URLs, auto-detects likely LAN Mobile URLs when bound to `0.0.0.0`, renders a terminal QR for the preferred Mobile URL, and accepts host commands such as `approve <code>`, `deny <code>`, `clients`, `audit`, `revoke <id>`, and `quit`. Use `thread host --local` for localhost-only testing.

The attach client accepts normal prompt lines plus client commands:

- `/abort`
- `/steer <text>`
- `/follow-up <text>`
- `/quit`

Detaching the client does not stop the host session.

A lightweight full-screen mobile chat page is served at the attach URL. Open the tokenized URL in a phone browser on a trusted network to view user/assistant messages as chat bubbles, request pairing, and send prompts after approval. Pairing foundation exists for strict attach flows: start with `--attach-pairing strict` or `/attach strict`, request pairing through the page/API, approve/deny/revoke/list with `/attach approve <code>`, `/attach deny <code>`, `/attach revoke <id>`, `/attach clients`, and inspect recent local audit events with `/attach audit`. In headless `thread host`, use `approve <code>` or `deny <code>` directly in the host terminal. Pass the approved session client token to the terminal client with `--client-token <token>` if using `thread attach`.

Security limits in the current MVP:

- attach is off by default;
- localhost is the default bind address;
- LAN bind must be explicit and should only be used on trusted networks;
- the token is generated per start unless explicitly provided;
- local pairing audit events are in memory only and capped;
- no TLS, public relay, UPnP, persistent pairing, or internet exposure is provided by Threadwell;
- for remote access outside the local machine, prefer SSH tunnels, Tailscale/WireGuard, or another authenticated private network layer.

### Model Options

| Option | Description |
|--------|-------------|
| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
| `--api-key <key>` | API key, overriding environment variables |
| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
| `--list-models [search]` | List available models |

### Session Options

| Option | Description |
|--------|-------------|
| `-c`, `--continue` | Continue the most recent session |
| `-r`, `--resume` | Browse and select a session |
| `--session <path\|id>` | Use a specific session file or partial UUID |
| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
| `--session-dir <dir>` | Custom session storage directory |
| `--no-session` | Ephemeral mode; do not save |

### Tool Options

| Option | Description |
|--------|-------------|
| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
| `--no-tools`, `-nt` | Disable all tools |

Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.

### Advanced Resource Options

| Option | Description |
|--------|-------------|
| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
| `--no-extensions` | Disable extension discovery |
| `--skill <path>` | Load a skill; repeatable |
| `--no-skills` | Disable skill discovery |
| `--prompt-template <path>` | Load a prompt template; repeatable |
| `--no-prompt-templates` | Disable prompt template discovery |
| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |

These are mainly for extension/package development and troubleshooting. Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:

```bash
thread --no-extensions -e ./my-extension.ts
```

### Other Options

| Option | Description |
|--------|-------------|
| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
| `--append-system-prompt <text>` | Append to system prompt |
| `--verbose` | Force verbose startup |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show version |

### File Arguments

Prefix files with `@` to include them in the message:

```bash
thread @prompt.md "Answer this"
thread -p @screenshot.png "What's in this image?"
thread @code.ts @test.ts "Review these files"
```

### Examples

```bash
# Interactive with initial prompt
thread "List all .ts files in src/"

# Non-interactive
thread -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | Threadwell -p "Summarize this text"

# Different model
thread --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
thread --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
thread --model sonnet:high "Solve this complex problem"

# Limit model cycling
thread --models "claude-*,gpt-4o"

# Read-only mode
thread --tools read,grep,find,ls -p "Review the code"
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `THREADWELL_CODING_AGENT_DIR` | Override config directory; default is `~/.threadwell/agent` |
| `THREADWELL_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
| `THREADWELL_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
| `THREADWELL_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
| `THREADWELL_SKIP_VERSION_CHECK` | Skip the Threadwell version update check at startup. This prevents the npm registry latest-version request |
| `THREADWELL_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
| `THREADWELL_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
| `VISUAL`, `EDITOR` | External editor for Ctrl+G |

## Design Principles

Threadwell keeps the day-to-day surface small and terminal-native. Advanced workflow-specific behavior can still live in extensions, skills, prompt templates, and packages.

It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.

For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-threadwell-coding-agent/).
