Branchline Docs Open Branchline

Getting started

Connect your coding agent to Branchline, then use the web workspace to approve its plan, give feedback, and accept the result.

1. Sign in and add a device

  1. Open Branchline and choose Sign in with GitHub.
  2. Open Settings → Devices, name your device, and select Add device.
  3. Select Copy file contents. Save the JSON as ~/.branchline/hosted.json and run chmod 600 ~/.branchline/hosted.json. Create the ~/.branchline directory first if needed.

2. Connect Codex

You’ll need Node.js 22.9 or newer, the Codex desktop app, and the Branchline client package from your maintainer. Install the package locally, substituting the absolute path to your tarball.

client_dir="$HOME/.local/share/branchline-client"
mkdir -p "$client_dir"
npm install --prefix "$client_dir" --ignore-scripts "/path/to/branchline-codex.tgz"
"$client_dir/node_modules/.bin/branchline" desktop install \
  --connection "$HOME/.branchline/hosted.json"

From the project you’ll work in, install the Branchline skills.

"$HOME/.local/share/branchline-client/node_modules/.bin/branchline" skills install

Restart Codex and open a new chat in that project.

Using a Branchline source checkout?

From the checkout, run npm ci and npm run pack:codex. Use the tarball path printed by the pack command in the installation step above. The source checkout also includes docs/claude-code.md for Claude Code users.

3. Start your first goal

Pick + Goal → Plan and Execute in Branchline to build a prompt, or ask your connected agent directly. Replace the example outcome with your own.

Use Branchline Plan and Execute to create a goal to add a search box to this project. Publish a plan for my review and give me the workspace link.

4. Review the plan and result

Open the workspace link your agent gives you. Approve the plan or request changes. When the agent publishes its result, review the evidence and accept the revision or send feedback.

If your agent stopped listening before you responded, your decision stays in Branchline. Return to the agent chat and ask it to resume the goal.