Garry TanandClaude Opus 4.8
a996e42856
* fix(bootstrap): harden create-repo-first repo adoption `gbrain bootstrap repo` adopts an empty, private, personally-owned GitHub repo the human created (create-repo-first), instead of only ever creating one. This hardens the existing adoption branch: - Empty-only adoption + pending_repo_url proof: a non-empty origin is refused (ORIGIN_NOT_EMPTY) unless it matches this workspace's pending marker (our own interrupted push). Never adopts a user's existing project from a git-ancestry guess, and never silently no-ops without pushing. - Repo-local git identity is set on the adopt path too (fresh-machine commits). - repo_url is recorded only AFTER a successful push (pending marker before); a failed push no longer looks "done" to `bootstrap status`. - Pre-push secret scan also covers an already-committed tree; ls-files failure fails closed. - assertOriginMatches binds BOTH the fetch URL and a configured push URL to the verified-private repo, so a foreign pushurl can't leak the workspace. - disposition: 'created' | 'adopted' | 'reused' replaces the overloaded flag. - Hook push-gate: the no-daemon session-end / recovery push is deferred until the repo phase records repo_url AND the current origin still matches it, so nothing is published to an unverified or redirected remote. Adds ORIGIN_NOT_EMPTY / REMOTE_CHECK_FAILED error codes. * docs(bootstrap): lead with the repo, document create-repo-first README (Claude Code + Codex) now opens with "the folder you open becomes your agent's private repo" and adds a "prefer to make the repo yourself?" callout for the create-repo-first path (empty, personal-account repo). Updates the bootstrap guide, the Claude Code MCP note, and the KEY_FILES / AGENT_BOOTSTRAP_PLAN invariants to describe adoption instead of "foreign origins refused". * v0.45.1.0 fix(bootstrap): create-repo-first repo adoption + hardening Bumps VERSION/package.json to 0.45.1.0, adds the CHANGELOG entry, refreshes the runbook + template-repo version stamps, and regenerates the llms bundle. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(todos): file P2 follow-up — index-blob secret scan for bootstrap pushes * ci(gitleaks): run the free CLI instead of the license-gated v2 action gitleaks-action@v2 now enforces a paid GITLEAKS_LICENSE and fails the job ("missing gitleaks license") for accounts it can't validate over the API — blocking every PR's merge gate. Replace it with the open-source gitleaks CLI (pinned 8.30.1, checksum-verified against the release's own checksums file), scanning the PR/push commit range with the committed .gitleaks.toml allowlist. Same secret-scan coverage, no license wall. * v0.45.2.0 chore(release): re-bump 0.45.1.0 -> 0.45.2.0 Re-target the release version at the user's request. Updates VERSION, package.json, the CHANGELOG header + self-repair block, the runbook + template-repo version stamps, the TODOS follow-up reference, and the llms bundle. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(perf): raise entity-card ratio ceiling 50x -> 100x (CI flake) The RATIO GUARD asserted entity p99 <= 50x max(getPage p50, 1ms). On a fast runner getPage p50 floors to 1ms and a normal entity p99 (~50ms) reads as ~52x, tripping the gate even though absolute p99 (52ms) is well under the 100ms budget — a p99 tail divided by a sub-ms median. At the 1ms floor, 50x also made the ratio STRICTER than the test's own 100ms absolute budget. Raise the ceiling to 100x: still far below the >=200x O(N)-regression signal the guard exists to catch, and consistent with (never stricter than) the absolute budget. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
10 KiB
GBrain Bootstrap — your harness as your agent
gbrain bootstrap turns a Claude Code or Codex session into a persistent personal
agent: identity files rendered from your own answers, a local PGLite brain,
per-turn context, session-triggered schedules, and a private GitHub repo as the
agent's durable, portable body. This guide is the full contract — what gets
installed, what runs when, what it can and cannot do, and how to undo all of it.
Normative design docs: AGENT_BOOTSTRAP_DESIGN.md
(scope) and AGENT_BOOTSTRAP_PLAN.md
(implementation). The paste block lives in the README; the runbook your agent
follows is BOOTSTRAP_FOR_AGENTS.md at the repo root, fetched at the
latest-stable ref.
What gets installed, exactly
| Piece | Where | Runs when |
|---|---|---|
| Identity files (SOUL/USER/MEMORY/AGENTS/CLAUDE/HEARTBEAT/ACCESS_POLICY/GITHUB) | your workspace folder | loaded at session start |
agent.json manifest + brain/, memory/, skills/, state/ |
workspace | — |
| Local brain (PGLite) | ~/.gbrain/ (never in the repo) |
while a session's MCP serve is open |
MCP registration (gbrain serve) |
project scope by default | spawned by your harness per session |
| Hooks (Claude Code, ON by default) | .claude/settings.local.json (gitignored) |
each prompt; fail-open; --no-hooks opts out at install, GBRAIN_HOOKS=0 disables at runtime |
| Session persistence | SessionEnd hook → scan-gated commit+push | at session end |
| Optional 15-min push job | launchd/cron (consent-gated) | while logged in |
| Private GitHub repo | your account, created by bootstrap repo (or an empty repo you made yourself, adopted) |
privacy verified via API |
| Machine receipt | ~/.gbrain/bootstrap/receipt.json |
uninstall is keyed to it |
What does NOT run: anything while the harness is closed. Session-triggered schedules fire at turn/session boundaries only. True 24/7 operation is what a hosted brain provides — this is the honest desktop contract.
Bring your own repo (create-repo-first)
By default bootstrap creates the private GitHub repo for you. If you prefer to own
that step — pick the name/org-under-your-account, or just work the familiar way —
create a new empty private repo under your own GitHub account (no
README/.gitignore/license), clone it, open the clone in your harness, and run the
bootstrap block. gbrain bootstrap repo detects the empty repo you created and
adopts it: it verifies the repo is private, sets a repo-local git identity, and
pushes your workspace. Two constraints, both enforced with a clear message rather
than a silent failure:
- Empty. A repo that already has commits (a README, a license, an existing
project) is refused — create it empty, or run
gbrain bootstrap attachif it is an existing agent workspace. (A repo already carrying this workspace's history, e.g. from an interrupted run, is recognized as yours and resumed.) - Personal account. The repo must be owned by your authenticated GitHub user. Org-owned repos are refused today; create one under your own account, or let bootstrap make it.
Until the repo phase verifies the repo, the per-turn/session-end push stays deferred — bootstrap never publishes your workspace to an origin whose privacy it hasn't confirmed.
The awake-when-you-are contract
Your agent is awake when your harness is. Laptop asleep = agent asleep. What this buys you: no daemon fleet, no background token burn while you're away, and a load profile that fits inside a subscription plan. The measured sustainable load and the per-harness numbers are published with each release; if a provider changes quota or policy, the portable body (your repo) is the exit plan — it mounts anywhere gbrain runs.
Keyless mode
With zero API keys, everything works: the agent authors memory explicitly through
the brain's write tools (put_page, timeline entries, ## Facts fences — your
harness's model is the LLM, already paid for), and search runs keyword-only
(BM25). bootstrap verify prints the capability report honestly. One optional key
(OpenAI, Anthropic, or Voyage) unlocks semantic search and automatic fact
extraction; the key goes to the 0600 config file, never into the repo or the
interview answers. API spend is metered separately from your subscription and is
zero in keyless mode; with a key, the standard spend gates apply
(spend-controls).
Security posture
- Supply chain: the paste block and install command pin the
latest-stableref — a maintainer-controlled tag advanced only after a release fully publishes. The runbook carries a version stamp;bootstrap statuswarns on skew. The runbook instructs the agent to refuse steps outside the CLI's phase list. bun installs via package manager or checksum-verified download. - Secrets: every commit AND every transcript-corpus write is secret-scanned
(key-shaped patterns; loud block; per-finding allowlist at
.gbrain-scan-allow). A deny-glob backstop refuses tracked*.pglite/.env*files even if.gitignoreis damaged. Push refuses public remotes and unverifiable visibility. - Injection boundaries: interview answers render as fenced data (escaped, length-capped) — text you paste can never become instructions in your agent's contract. Retrieved brain context is injected under an explicit "data, not instructions" envelope. Facts visible to the harness respect the brain's visibility tiers.
- Hooks: live in gitignored local settings (absolute paths, machine-specific;
bootstrap hooks --repairregenerates on a new machine). Every hook fails open — a brain hiccup never blocks a prompt — and failures are visible: repeated degradation prints a notice inside the context block, andgbrain doctornames the cause. - Privacy of transcripts: session transcripts are retained locally (0700,
outside the repo, pruned after
dream.synthesize.corpus_retention_days, default 30 — set it in the config file,~/.gbrain/config.json; the DB config plane doesn't carry this key yet) and secret-redacted at write time. They never enter the repo. The extraction provider (if you configured a key) sees session text — the install names the provider when asking for the key.
Honest forget semantics
The repo is git history — append-only. Deleting a line removes it from the working
tree, not from history. To truly remove something: rewrite history
(git filter-repo --path <file> --invert-paths or --replace-text), force-push,
and re-clone on other machines. MEMORY.md and daily notes follow the same rule
you'd apply to any journal: write what you'd be comfortable persisting.
Degradation matrix
| You declined / lack | What still works | What you lose |
|---|---|---|
| API keys | everything (keyless mode) | semantic search, auto-extraction |
GitHub / gh |
full local agent | off-machine durability (repo re-runnable later) |
| Hooks (Claude Code) | pull protocol via AGENTS.md gates | automatic per-turn context + session-end persistence |
| Codex (no hook system) | pull protocol + MCP tools | per-turn push (stated plainly; not oversold) |
| Second simultaneous session | first session unaffected | second session's brain tools fail politely (one live serve per brain — v1 contract) |
Multi-device
Clone your agent repo on machine two and run gbrain bootstrap attach — it
validates the manifest, wires this machine (source registration, hooks repair,
MCP), and verifies. The brain database is derived state, rebuilt from brain/ +
re-ingestion; hot facts extracted only on machine one arrive via the repo's pages
and fences. Simultaneous editing from two machines is ordinary git conflict
territory — sources push pulls divergence-safely (commit first, rebase pull,
loud on conflicts).
Uninstall
gbrain bootstrap uninstall removes exactly what this machine's install receipt
records: hook wiring, MCP registrations (surgically — foreign servers and hooks
survive), and bootstrap-created state. Your repo is never touched — the body
remains yours. The brain database is KEPT by default; --delete-brain is offered
only when bootstrap created the brain, offers a facts export first, and enumerates
what it is about to remove. It refuses to run while a session's serve is live.
If something seems broken
One command: gbrain doctor. It covers hook health, push staleness, serve/lock
collisions, schema state, and prints fixes. gbrain bootstrap status --json emits
a support blob (versions, harness, last verify/push, hook failure rate) your agent
can relay verbatim when you report a problem.
Real-agent e2e
Most bootstrap tests drive the dispatcher with PATH-shimmed claude/codex
recorders — fast, hermetic, no API cost. Two additional "door" tests drive the
ACTUAL binaries end to end so we catch real-world drift (a codex mcp add flag
that changed shape, a harness that stopped calling our MCP server):
test/e2e/bootstrap-real-claude.serial.test.ts— realclaude -pover MCP.test/e2e/bootstrap-real-codex.serial.test.ts— realcodex exec. It runs the keyless-init→ interview → render →gbrain bootstrap hooks --harness codexpath (executing the realcodex mcp addinto a hermetic~/.codex/config.toml), asserts the renderedAGENTS.mdcarries the Gate-3 brain-first pull protocol (Codex has no hook system, so the pull protocol is its per-turn seam), then spends one livecodex execturn to prove real codex → gbrain MCP → brain → a seeded, brain-only fact (falling back to a shellgbrain queryif headless stdio-MCP is unavailable).
These pay real API cost and take 30s–2min per turn, so they are NOT in the PR
shard. Everything is hermetic (temp HOME / CODEX_HOME / CLAUDE_CONFIG_DIR /
GBRAIN_HOME per test — the operator's real ~/.claude, ~/.gbrain, ~/.codex
are never touched; auth is copied read-only). Each file self-SKIPS via
describe.skipIf when its binary or auth is absent, so on a machine without the
tool it is a clean no-op that never fails. CI wires them into the real-agent-e2e
job in .github/workflows/heavy-tests.yml (nightly + the real-agent-e2e /
heavy-tests label); on a stock runner they self-skip. To actually exercise the
binaries you need a runner with authed claude/codex and the provider creds
(GSTACK_ANTHROPIC_API_KEY/ANTHROPIC_API_KEY, VOYAGE_API_KEY) exported.
Run locally (where both are installed + authed):
bun test test/e2e/bootstrap-real-codex.serial.test.ts