Threads

Overview

Friday acts as the orchestrator (dispatch), delegating work to parallel worker threads that each operate independently. In git mode, each worker runs in an isolated git worktree on its own branch, keeping changes separate until they are ready to merge. This enables parallel task execution across multiple workers with automatic merge coordination handled by dispatch.

Quick Start

When Friday delegates tasks, it automatically creates worker threads to handle them in parallel. You can also create a worker thread manually in two ways:

  • /fork command — creates a new thread that inherits the current conversation history:
/fork implement the authentication flow

  • + New Thread button — click it in the UI to immediately create a new thread. In git mode, clicking the button shows a prompt titled "Start new thread in..." with two options:

    • Start new thread in a worktree — creates the thread in an isolated git worktree
    • Start new thread in {path} — creates the thread in the base directory without a worktree

    Outside of git mode, clicking the button immediately creates a new thread with no prompt.

To rename the current thread for easier identification:

/name auth-feature

Usage

Worker threads

Workers implement changes independently, and when a thread completes, its changes are applied back to the current branch. In git mode, each worker thread operates in an isolated git worktree on a dedicated branch named friday/thread/<id>, and changes are cherry-picked back to the current branch. This isolation ensures that parallel workers do not interfere with each other.

Thread lifecycle

Threads move through the following states:

  • RUNNING — the worker is actively executing
  • QUEUED — the thread has been accepted and is waiting to be merged
  • MERGING — dispatch is applying the thread's changes to the current branch
  • MERGED — changes have been successfully integrated

ABANDONED is an alternate terminal state for threads that are cancelled or discarded. If merge conflicts are encountered during the MERGING phase, the thread is sent back to RUNNING so the worker can resolve them.

Dispatch and workers

Dispatch coordinates all worker threads and owns git operations such as pushing branches and creating pull requests. Workers focus solely on implementation. When a worker is blocked or needs input, it can send a message to dispatch. Dispatch can also send messages to workers to provide context, redirect work, or unblock them.

Forking

The /fork [description] command creates a new worker thread that inherits the current conversation history. This is useful for exploring alternative approaches in parallel without losing the context of the original thread.

/fork try a different approach using server-side rendering

Naming

The /name <new name> command renames the current thread. Thread names appear in the UI and help distinguish between multiple active threads.

/name refactor-api-layer

Examples

Example 1: Parallel feature work

Friday spawns multiple workers to handle independent tasks simultaneously:

Dispatch → Worker A: implement the user profile page
Dispatch → Worker B: implement the settings page
Dispatch → Worker C: implement the notifications API

All three workers run in parallel. In git mode, each runs in its own worktree and branch. Dispatch merges their changes back to the current branch as each completes.

Example 2: Using /fork to try an alternative approach

# In the current thread, you've started one approach
/fork try implementing this with a REST API instead of GraphQL

A new worker thread is created with the full conversation history, allowing you to pursue both approaches simultaneously and keep whichever works better.

Example 3: A worker messaging dispatch when blocked

Worker → Dispatch: I'm blocked — the upstream API endpoint returns 404.
                   Do you want me to mock it or wait for it to be deployed?

Dispatch → Worker: Mock it for now using the schema in /docs/api-spec.md.
                   We'll swap in the real endpoint later.

The worker receives the response and continues implementation without interrupting the overall workflow.