Skip to content
ThoughtBridge
Log in

Documentation Runner

The runner

What Bridget is, how a bridge-it run works end to end, and the safety rules it enforces.

Bridget is a small open-source daemon that turns “bridge it” thoughts into pull requests. It runs on your own machine, drives your own coding agent (Claude Code, Codex CLI, or Gemini CLI) under your own subscription, and never sends your code anywhere: ThoughtBridge only sees the run’s status, branch, PR link, and any questions the agent asks.

Downloads and the quickstart live on the runner page. This page explains what the runner actually does; runner configuration covers profiles and every setting.

What you need

  • git on your PATH.
  • The GitHub CLI (gh), signed in: gh auth login.
  • At least one coding-agent CLI, installed and signed in.
  • A ThoughtBridge API key with the runner scope, created in the app under Settings > API keys.

The runner works with GitHub destinations: the pull request is the review mechanism, so the project needs a repo the agent can branch in.

How a run works

  1. You speak a thought ending with the words “bridge it” (or tap the Bridge it button on an existing thought in the app).
  2. The runner claims it. Bridget polls the queue on your machine; a short grace window after capture lets you cancel before any work starts.
  3. Fresh checkout, own branch. The runner checks out the project’s repo and creates a branch named thought/<id>. The thought is the work order; the repo’s own agent files are the context.
  4. Your agent builds it in a headless session. If the agent hits a decision only you can make, the question appears in the ThoughtBridge app; your answer resumes the same session.
  5. A pull request opens for you to review. Approving in the app merges it; nothing lands without your say-so.

The run record keeps the machine name and the agent session id, so on that machine you can drop into the live session with your agent CLI’s resume command at any point.

Pinning a project to a runner

In the app, open a project’s menu and choose Runner to pin that project to a specific runner (or a specific profile, if you run several - see runner configuration). From then on, bridge-it thoughts in that project route to that runner, with the agent and model you configured there.

Safety rules

  • The runner never commits to the default branch - branch and PR only, enforced by the runner itself, not just by prompting.
  • One run at a time per repo checkout.
  • Every run is cancellable from the app.
  • The API key is runner-scoped: it can poll and report runs and read thoughts, but it cannot modify them, and you can revoke it at any moment.

Startup checks

On every start the runner verifies its prerequisites (git, gh signed in, each profile’s agent CLI installed and signed in) before serving any work. Every failed check prints the exact fix - the install command or the auth command - so a misconfigured machine tells you what it needs instead of failing mid-run.