Build a feature & open a PR

The single-session happy path: one new branch, one Friday session, one PR. Describe what you want, Friday spawns a thread to do it, you review, you ship.

Friday is designed as one session per branch and PR. To work on a different feature concurrently, launch a separate Friday session in a worktree (see Variants).

Before you start

  • You're in GIT mode. See Modes.
  • The gh CLI is authenticated. Check with gh auth status.

1. Start Friday on a new feature branch

Create the branch, then launch Friday from it:

git checkout -b add-healthz-endpoint
friday

The session's current branch becomes add-healthz-endpoint. Threads spawn from it (each in its own friday/thread/<id> worktree) and cherry-pick their commits back onto it when you accept.

The base branch (the PR target and the reference Friday uses to describe what's already on the branch) stays at whatever you launched from, typically main. Change it with /base-branch if your PR should target something else, like the previous PR in a stack. See Branches for the two-branch model.

If you've already launched Friday on the wrong branch, the cleanest fix is to exit and relaunch from the right one. You can also ! git checkout -b <name> from Bash mode; the indicator updates after the next agent turn.

2. Describe the feature

(Skip this step if you used the Autostart variant; Dispatch is already running.)

In Dispatch, type what you want. The clearer the description, the less back-and-forth:

Add a /healthz endpoint that returns {"status": "ok"} and the version
from package.json. Add a test for it.

Drag image or PDF files into the input if you have a mockup or spec.

For multi-step tasks, Friday often calls the Plan tool on its own before writing any code. In Collaborative mode you'll see a numbered plan and a "Shall I proceed?" prompt. Read it, redirect, or approve. See Plan, then execute.

3. Watch the work

Dispatch will likely spawn a thread (you'll see a CreateWorkerThreadForTask call and a new row in the ThreadList). Click into the thread's pane to watch. You'll see tool calls streaming (Read, Bash, Edit, Write) and a "review changes" link after edits.

If Friday is moving faster than you want, switch Working Style to Supervised in /settings, or relaunch with --2x to require approval before each command. See Working style and Approval modes.

4. Review what got done

Stay inside the thread's pane and run /diff to see the changes. See Review thread changes for the four ways to do it.

If you want changes, type into the thread: "the response should also include uptime in seconds." It'll iterate without losing the thread of work.

5. Accept and merge

When the thread says it's done, it calls AcceptThread on its own. The merge queue cherry-picks its commits onto your feature branch (the one you created in step 1). In Collaborative mode you'll see a "Ready to accept this thread?" prompt the first time; Supervised and Autonomous skip it. See Dispatch / Accepting a thread's changes for the full breakdown.

After merge, the thread's internal friday/thread/<id> branch is deleted. Your feature branch now has the commits, ready to push.

6. Push and open the PR

Switch back to Dispatch and tell it: "push and open a PR." Dispatch will run git push origin <branch> and call GithubPrCreate. The PR title and body are drafted from the conversation; Friday will show them before opening.

Read the title and body before you approve. Friday is decent at summaries but not always right; you may want to tweak the framing.

If Friday tries to push to a branch other than your configured feature branch, it asks first. That safeguard catches "you accidentally tried to push to main."

7. Iterate on review

When the PR has review comments:

  • Tell Dispatch: "address the PR comments." Dispatch will fetch them with gh and work them.
  • Or define a custom command for this flow. See the address-pr-comments example in Custom commands.

Variants

  • Plan first. Set Working Style to Supervised before describing the feature. Friday plans, asks you to confirm, then executes end-to-end. See Plan, then execute.
  • Autostart. friday --prompt "..." auto-generates a feature branch name from the prompt and runs the work end-to-end. Add --one-shot to run to completion and exit (useful for scripting). See Autostart mode.
  • A different feature in parallel. Friday is one session per branch. To work on a second feature concurrently, launch another Friday session in its own worktree: friday --wt. See Parallelize work with worktrees.
  • Multiple PRs from one branch. If a single thread produced several logical changes, use /pr-stack to split them into a stack. See PR stack.

Common pitfalls

  • Commits ended up on main directly, no PR. You launched Friday on main and described work without first creating a feature branch. Recovery: branch off the current state with git checkout -b <name>, then reset main locally with git checkout main && git reset --hard origin/main. Avoid next time by checking out a feature branch before launching Friday.
  • PR opened against the wrong base. Use /base-branch before describing the feature, or set a default for the project. PRs opened against main when you wanted develop are the typical case.
  • Friday pushed to the wrong remote. It asks before pushing to anything other than your configured feature branch. If you approved by mistake, delete the remote ref with git push origin :<branch> and reset locally.
  • The PR title or body is wrong. Tell Dispatch: "update the PR with title X and body Y." It'll use GithubPrUpdate.
  • The thread stalled on a question. Look for the ● badge in the ThreadList. Click into the thread and answer.
  • You changed your mind partway through. Abandon the thread (AbandonWorkerThread from Dispatch, or the abandon flow inside the thread's pane) and start over. The branch is kept around if there were any commits ahead, in case you want to recover.

Read next