FXCode
SIGN IN →
Doc. 08 — Features

Branches and PRs

How to properly close tasks an agent works on in a git branch, by hand or with the GitHub webhook.

“Working” means someone is on it right now. If the work is done but lives on a branch that hasn’t been merged yet, the task isn’t “Working”: it’s “In review”.

Previously, an agent would finish on its branch and the task kept its animated sweep even though nobody was touching it. With branches and PRs, each task stores its branch and pull request, and when you finish it FXCode decides whether it goes to review or gets completed based on where you are.

The three modes

Each project picks one in Project → Advanced → Branches and PRs (owner or admin only).

Mode What finishing a task does When to pick it
Review (recommended, default) On a branch other than the main one, moves it to the review status and stores the branch. On the main branch, or with no branch, completes it. Almost always. You work with branches and close tasks when you merge.
GitHub Same as Review, plus GitHub pull request webhooks move tasks automatically: PR opened → review, PR merged into the main branch → completed. Your repo is on GitHub and you want the merge to close the task with no extra steps.
Manual Finishing always completes the task. Branch and PR are informational only. You work directly on the main branch or don’t use branches.

In the same settings you choose:

  • Main branch (main by default): finishing on it completes the task.
  • Review status: where tasks finished outside the main branch go. If you leave it on Automatic, the status named “En revisión” is used (case- and accent-insensitive); if it doesn’t exist, the task isn’t moved and only the branch is stored. Create it in Settings → Task statuses if you don’t have it yet.
  • Hours for “no activity” (24 by default). See below.

The typical flow with an agent

Several agents at once? Give each one its own worktree and branch with fxc tasks start <id> --worktree: see Parallel work (worktrees).

# 1. A branch with the task id in its name
git switch -c feat/fxc-cm4k2x9ab0001-login-github

# 2. The task moves to Working while you work
fxc tasks update cm4k2x9ab0001 -s Working

# … the agent works, commits and pushes the branch …

# 3. When done, from the branch
fxc tasks finish cm4k2x9ab0001
# ✓ Task moved to review (branch feat/fxc-cm4k2x9ab0001-login-github): En Revisión

# 4. Optional: store the PR on the task
fxc tasks update cm4k2x9ab0001 --pr https://github.com/acme/tienda/pull/42

fxc tasks finish picks up the current branch with git rev-parse --abbrev-ref HEAD when you’re inside a repo; you can also pass it with --branch. Outside a repo, or on the main branch, the task is completed.

  1. When you merge into main, the task gets closed:
    • in Review mode, you move it to the done status yourself (fxc tasks update <id> -s Terminada, or fxc tasks finish <id> --branch main);
    • in GitHub mode, the webhook closes it as soon as GitHub reports the merge.

The task list and the task detail show the branch and the PR with its state (open, merged or closed). You can edit them by hand from the task detail.

Connect the GitHub webhook

  1. In Project → Advanced → Branches and PRs, choose GitHub mode, enter the repository as owner/repo and save.
  2. Click Generate secret. Copy it right away: it’s shown only once. If you lose it, rotate a new one (the old one stops working).
  3. On GitHub, open the repository → Settings → Webhooks → Add webhook and fill in:
Payload URL     https://api.fxcode.dev/integrations/github/webhook
Content type    application/json
Secret          <the secret you generated in FXCode>
SSL verification  Enable SSL verification
Which events?   ( ) Just the push event
                ( ) Send me everything
                (•) Let me select individual events
                    [x] Pull requests      ← only this one
Active          [x]
  1. Save. GitHub sends a ping; under Recent Deliveries it should show a green check.

The exact URL for your installation appears in the settings, next to a copy button (on self-hosted it’s <your API>/integrations/github/webhook).

What each event does:

pull_request event Effect on the task
opened, reopened, ready_for_review Moves to review and stores the PR URL and number, the open state and the branch
closed with merge into the main branch Moves to the done status; PR merged
closed with merge into another branch PR merged, status unchanged
closed without merge PR closed, status unchanged

Every delivery is verified with the X-Hub-Signature-256 signature against the project’s secret: an invalid signature is rejected and nothing changes. The webhook only acts if the project is in GitHub mode, and only on that project’s tasks. The secret is stored encrypted and never appears in API responses.

How a PR is matched to a task

The webhook looks for the task’s id in the PR’s branch name, title or body, in either of these two formats:

Format Where Example
fxc-<taskId> Branch name (or title/body) feat/fxc-cm4k2x9ab0001-login-github
[fxc:<taskId>] PR title or body Login con GitHub [fxc:cm4k2x9ab0001]

It also recognizes the PR if the task already had it stored (same prUrl) or if the task’s branch matches the PR’s (head.ref). A PR can reference several tasks: all of them move.

Rama:    fix/fxc-cm4k2x9ab0001-carrito-vacio
Título:  Arregla el carrito vacío [fxc:cm4k2x9ab0001]
Cuerpo:  También cierra fxc-cm4k3abcd0002.

You’ll find a task’s id in its URL, with fxc tasks list --json, or with list_tasks over MCP.

No activity

A task in a status with the progress animation (“Working”) that hasn’t changed for longer than the configured hours stops showing the sweep and displays a subtle label instead: no activity · 3 days ago. Hovering over it explains what it means.

  • The status doesn’t change: it just looks different. Touching the task (editing it, finishing it) brings it back to normal.
  • Configure it per project in Branches and PRs → Hours for “no activity”; 0 turns it off.
  • The API returns it as stale: true on each task, so scripts and agents can use it.

The golden rule: never leave a task in Working if you’re no longer on it. Finish it with fxc tasks finish or move it back to its previous status.

From an agent over MCP

The same actions are available as tools in the MCP server, both local and remote:

Tool What it does
finish_task taskId and branch?. Applies the project’s mode: on a working branch, to review; on the main branch, completed. In the local MCP, without branch it uses the current git branch
update_task On top of the usual fields, branch, prUrl and prNumber (an empty string clears them; the number is taken from the URL)

Tasks returned by the tools include branch, prUrl, prState and stale.

From the API

# Finish according to the project's mode
curl -X POST https://api.fxcode.dev/tasks/<id>/finish \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"branch":"feat/fxc-<id>-login"}'
# → the task, with "outcome": "review" | "completed" | "unchanged"

# Store branch and PR
curl -X PATCH https://api.fxcode.dev/tasks/<id> \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"branch":"feat/fxc-<id>-login","prUrl":"https://github.com/acme/tienda/pull/42"}'

Project settings live at GET/PATCH /projects/<id>/branch-settings and the secret at POST/DELETE /projects/<id>/branch-settings/webhook-secret, for the owner or an admin only.