Projects and threads
A project is a folder on your machine. A thread is one line of work inside it. Everything W1 knows is scoped by those two things.
A project is a folder#
When you open a project in W1 you are choosing a folder on your machine. That folder is both the workspace and the boundary:
- W1 reads and writes inside it. Paths that escape it are refused by the runtime, not by a prompt asking it nicely.
- Commands run with that folder as their working directory.
- Its runtime state — run traces, rewind snapshots, project memory — is kept outside the folder, under your home directory, so opening a project never adds files to it.
Nothing about the project has to be a code repository. A folder of documents, a spreadsheet and a few PDFs is a perfectly good W1 project.
W1 does not litter your project.
State is keyed to the folder's path and stored under ~/.w1/userdata/workspaces/. Older versions of W1 wrote a .w1/ folder inside the project; that location is still read for history, but nothing new is written there.
A thread is one line of work#
Inside a project you open threads. A thread is a conversation with a memory of its own work: what it has read, what it changed, what the checks said, and what you told it along the way.
Threads run independently. You can have one working through a migration while you start another to answer a question, and they will not tread on each other's context.
What a thread carries between turns#
A thread is not a transcript replay. Between turns it keeps:
- your messages, exactly as you wrote them
- the final outcome of each turn and its terminal state
- what actually changed in the workspace
- compact receipts of the work — enough to know what was established, without re-reading everything
- the usage totals for the turn
It deliberately does not carry back the model's internal reasoning, the full body of every file write, or complete command output. Those are in the local trace if you need them; keeping them in context makes every later turn slower and more expensive without making it better.
When to start a new thread#
| Situation | Do this |
|---|---|
| A follow-up to the work just done | Stay in the thread. The context is already warm and cheap. |
| A different job in the same project | New thread. |
| The thread has gone in circles twice | New thread, and say what you learned in the first line of it. |
| A different folder | New project. |
A long thread costs more per turn than a short one, because more context travels with every request. This is the single largest lever you have over what W1 costs you — see Plans and usage.
Context, and what happens when it fills#
Every model has a context limit. W1 tracks how full a thread is and compacts it when it has to: older material is summarised down to what later turns actually need, and work continues rather than stopping with an error.
You will see this happen. It is normal on long threads, and it is a reasonable moment to ask yourself whether the next job deserves a fresh one.
Where W1 keeps things#
Everything below is on your machine. None of it is uploaded.
| Path | What lives there |
|---|---|
~/.w1/userdata/workspaces/<folder>-<id>/runs/ | Full run traces for that project. See Your data and traces. |
~/.w1/userdata/workspaces/<folder>-<id>/ | Rewind snapshots and this project's memory. |
~/.w1/userdata/memory/ | Memory that applies to you across every project. See Memory. |
~/.w1/plugins/ | Installed plugin bundles. See Plugins and MCP. |
~/.w1/auth.json | Your signed-in session. Permission-protected, shared by the desktop app and the CLI. |
The <folder>-<id> name is the folder's own name plus a hash of its full path, so two projects called site in different places never share state — and moving a project starts it fresh.