Drafts

A Draft is a separate copy of your project with its own chat. You and the people you invite try changes there. Nothing reaches the real project (called Main in the app) until you approve it.

Use a Draft when you want someone else, or their agent, to change your project without touching your files directly. You don’t need to know git. The app handles the copying and merging for you.

Before you start

Drafts need Git 2.40 or newer on your computer, even if your project isn’t a git repository. If Git is missing, the Drafts dialog says “Drafts need Git 2.40 or newer on this computer. Install Git, then restart the app.”

On Windows, restart TokenWork after installing Git. The app remembers where it looked for Git until it restarts.

Create a Draft

1. Open the session for the project you want to copy.
2. Click Drafts at the bottom of the message box.
3. Click New Draft.
4. Enter a Draft name, up to 40 characters. These characters are not allowed: \ / : * ? " < > |.
5. Under Files to bring from Main, check the files the Draft needs to run. See What gets copied.
6. Click Create Draft.

You should see “Draft created.” The new Draft session appears in the sidebar under the original session. Open it and chat with the agent as usual.

You can’t create a Draft while the agent is working in that project. Wait for it to finish, then try again.

What gets copied

A Draft starts from the files saved on disk at that moment. Save any files you have open in an editor first.

• Every saved project file is copied, except files your project tells git to ignore.
• node_modules/, .venv/, __pycache__/ and similar folders are skipped unless you pick them.
• Linked folders (shortcuts, junctions, symbolic links) are skipped.

Ignored files such as .env (passwords or API keys) are not copied unless you pick them under Files to bring from Main. Nothing is checked by default. Files marked may hold secrets probably contain passwords or keys. Folders marked large, usually not needed can usually stay unchecked. To copy a path that isn’t listed, type it in Other paths, separated by commas.

People you invite can read every copied file. If you plan to invite anyone, leave secrets unchecked. A file with secrets that git doesn’t ignore is copied anyway, because it isn’t in the list.

Invite people

1. Click Drafts and find your Draft in the list.
2. Click Invite and create an invite link.
3. Send the link to the person you want to work with.

Invited people can change files in the Draft, apply its settings, and ask to merge it. Only you can approve a merge into Main.

The guest opens the link in their own TokenWork, the same way as any shared session (see Agent Collaboration). From then on, what they send runs in your Draft session, one message at a time. On their side, the shared session shows a Draft panel with Apply settings and Request merge into Main.

Under the Draft, you see Active invite links with the date each link was made. Links don’t show who received them. Click Revoke to cancel a link.

A guest’s agent can’t push to git or touch folders outside the Draft. TokenWork refuses those requests on its own, so you won’t be asked about them.

Apply settings

If someone changes the Draft’s OpenCode settings (MCP servers, plugins, agents), click Apply settings on the Draft card. The changes take effect on the next turn. Main and other Drafts keep running as they are.

Merge a Draft into Main

You or a guest clicks Request merge into Main. When a guest asks, you get a notification (“Draft merge requested”), and the Drafts button shows how many requests are waiting for you.

To review a request:

1. Click Drafts, then Review merge into Main on the Draft.
2. Check the list of changed files. Each one is marked Added, Modified or Deleted. Click a file to see what changed.
3. Look closely at files with a warning mark. They change settings or scripts that run on your computer.
4. Click Approve and merge, or Reject.

After you approve, TokenWork writes only the changed files into Main, adds a short summary of the Draft’s work to the Main conversation, and closes the Draft. The Draft conversation stays in the archive. Guests see that the Draft was merged and closed. To keep working, they need an invite to a new Draft.

If the Draft changed no files, approving adds only the summary to the Main conversation.

When you reject, you can write a reason. The requester and the Draft chat see it. The Draft stays open so the work can continue.

A Draft has one open merge request at a time. You can’t approve while the agent is working in Main or in the Draft. If a merge stops partway, see Troubleshooting.

When both sides changed the same lines

If Main and the Draft changed the same part of a file, nothing is written to Main. The status changes to conflict, and both versions are written into the Draft’s copy of the file, marked with <<<<<<< and >>>>>>>.

1. Click Open Draft to resolve. The Draft session opens with a message already typed, asking the agent to keep the right content and remove the markers.
2. Send that message.
3. When the agent is done, click Retry to build a new preview.
4. Review and approve again.

Clean up

Click Clean up on a Draft to delete its files. If the Draft has changes you haven’t merged, the confirmation says how many files will be lost. Click Delete Draft files to continue. The conversation stays in the archive.

A closed Draft stays in the list until you click Remove from list.

Related

• Agent Collaboration: how guests open a shared session
• Projects: the project a Draft copies