Open for commentsSelect text to comment

Beads in Claude cloud sessions

Beads in Claude cloud sessions

TL;DR. Configure a Claude Code cloud environment once and every session in it gets Beads. Three pieces, all in this repo: a setup script that installs bd, three environment variables, and a SessionStart hook that builds the local database. Pulling should work. Pushing is untested: cloud sessions send all GitHub traffic through a proxy that rejects pushes of anything but a branch, and Dolt stores data under refs/dolt/data. We will try bd dolt push as is and see (decision: Rufus, 2026-10-17; no ref change).

One-time setup (per cloud environment)

Open claude.ai/code, edit the environment, then:

  1. Setup script: paste scripts/cloud-setup.sh. Installs bd with npm; the result is cached.

  2. Environment variables (.env format):

    BD_SYNC_REMOTE=git+https://github.com/life-itself/planning.git
BD_NON_INTERACTIVE=1
BEADS_ACTOR=<your first name>

    BD_SYNC_REMOTE overrides the git+ssh:// remote in .beads/config.yaml; SSH is unlikely to work because cloud traffic goes through an HTTP proxy. Do not put tokens here: anyone who can use the environment can read these values.

  3. Repository: .claude/settings.json runs scripts/cloud-bootstrap.sh at session start. It does nothing outside cloud sessions, and otherwise runs bd bootstrap --yes, which clones the Dolt data from the remote.

Why no deploy key or token

In Anthropic-hosted environments GitHub credentials stay outside the container. The git client gets a scoped credential, and a proxy swaps in your real token. Network secrets exclude GitHub for the same reason. Source: Cloud environments.

Known risks

  • The proxy rejects pushes that are not branches, so bd dolt push may fail. If it does, fallbacks: pull-only in the cloud (a local session pushes), a DoltHub or S3/GCS remote, or the .beads/issues.jsonl commit route (it cannot reconcile deletes).
  • bd bootstrap against an HTTPS remote is untested.
  • Concurrent writers on one Dolt ref can conflict. Run bd dolt commit before bd dolt pull.

Test procedure

In a new cloud session on this repo: bd list, create a throwaway bead, bd dolt push, then bd dolt pull in a local clone and check it arrived. Record the result here and in lip-tqk.1.

Sources

Edit this page
Built with LogoFlowershow