| name | x-builder-operator |
| description | Operate and explain the local x-builder system. Use when Codex needs to run the overlay runner, attach to Chrome over CDP, inspect local engine/storage state, explain archive import, active context, feedback-loop linking, live capture, or safety boundaries in the x-builder repo. |
X Builder Operator
Start Here
Confirm the working directory is the live x-builder checkout, then read repo-local truth before answering:
pwd
git status --short
sed -n '1,220p' AGENTS.md
sed -n '1,220p' docs/features/agent-operator-skill/README.md
If the task concerns failures or environment health, use $x-builder-doctor first. If docs conflict, prefer current code and newer storage docs over older feature text; docs/features/my-x-archive-import/README.md still contains historical JSON wording, while current storage is SQLite.
Run The Local System
Build before using the runner bin; runner/bin/x-builder.js imports built runner/dist/* and the runner injects the built overlay bundle.
pnpm build
XB_CDP_ENDPOINT=http://127.0.0.1:9222 node runner/bin/x-builder.js
Use reconnect mode when the user already has an authenticated Chrome session:
- Chrome must be running with a remote debugging endpoint, commonly
--remote-debugging-port=9222.
- The endpoint comes from
XB_CDP_ENDPOINT; an empty value is treated as unset.
- The runner attaches with
chromium.connectOverCDP, prefers an existing x.com tab, injects the overlay, binds window.__xbTransport, and observes already-fetched X GraphQL responses.
- Stopping the runner in reconnect mode disconnects the CDP session; it must not close the user's Chrome or tabs.
Use launch mode only when reconnect is not requested. Launch mode opens the dedicated profile at ~/.x-builder/browser-profile, where the user logs into X separately.
Verify Readiness
Prefer direct, bounded checks:
node docs/features/agent-operator-skill/skills/x-builder-doctor/scripts/doctor.mjs
pnpm test
pnpm typecheck
pnpm lint
For a running HTTP engine fallback, the default endpoint is http://127.0.0.1:8787 unless X_BUILDER_ENGINE_HOST or X_BUILDER_ENGINE_PORT override it. Useful routes:
curl -s http://127.0.0.1:8787/health
curl -s http://127.0.0.1:8787/status
curl -s http://127.0.0.1:8787/archive/context/active
curl -s http://127.0.0.1:8787/capture/summary
The overlay path usually uses in-process runner bindings, not HTTP. In the browser, inspect these only as diagnostics:
document.getElementById("xb-overlay-root")
window.__xbTransport
window.__xbuilder_getOverlayReadiness?.()
Do not treat first mount as enough when the user reports refresh issues; verify the overlay survives reload/navigation.
Storage Rules
Current local data lives under:
~/.x-builder/engine-settings/
~/.x-builder/engine-settings/storage/x-builder.db
Operational rules:
- Treat the SQLite database as internal storage. Do not hand-edit it or write SQL except through supported migrations, repositories, or app APIs.
- The database contains the canonical own-post corpus, metric observations, provenance, profile snapshots, import runs, derived insights, active context, feedback predictions/links, external X signals, and rebuildable voice embeddings.
- On startup, the runner/engine opens
storage/x-builder.db, runs append-only migrations, and imports an old storage/post-library.json once, renaming it to post-library.json.migrated.
- The voice index is a rebuildable projection. If it is missing or stale, generation should fall back to recent original posts.
Archive And Active Context
Archive import is an optional fast-start source. The user selects data/tweets.js from their X archive; x-builder parses it without executing JavaScript.
Remember these distinctions:
- Archive import is user-triggered; JSON-to-SQLite migration is automatic startup maintenance.
tweets.js has likes/retweets but not reliable impressions. It provides weak historical proxies, not true reach actuals.- Active context is local personalization from archive/local history: reach baseline, cadence/rotation, voice, and audience hints.
- Active context is not Home-feed learning and not a license to scrape unrelated feeds.
- Import and activation flow through the overlay settings panel and engine/transport APIs.
Feedback Loop
My Feedback Loop stores deliberate prediction snapshots only. Normal typing and debounce scoring are not stored automatically.
Predictions are recorded when the overlay writes a generated draft, applies all suggestions and keeps the rewrite, or the user clicks Record posted draft. Actuals come later from the local post library via live capture or archive/imported records.
Linking rules:
- Exact single normalized match can auto-link.
- Known X post id can link from a captured post.
- Manual link accepts a numeric post id or
/status/<id> URL in settings.
- Multiple matches fail closed; the system must not guess.
- Linking does not fetch from X, publish, edit, or mutate the post.
Live Capture Boundary
The runner may observe responses X already fetched for visible pages, normalize supported own-post/profile operations, and ingest them into local storage.
Allowed:
- Analyze visible content and already-fetched GraphQL responses.
- Suggest, judge, score, generate, and fill the composer after an explicit user click.
- Capture the logged-in user's own authored posts and public metrics as the user navigates.
Forbidden:
- Direct X posting, liking, following, reposting, DMs, or publish confirmation.
- Bypassing login, browser consent, or user confirmation.
- Crafting authenticated GraphQL calls, replaying auth headers, auto-pagination, or auto-scroll harvesting.
- Using the Home feed as a learning source.
- Cloud sync, hosted analytics, external credentials, or direct SQLite writes outside supported paths.
Explain The System
When explaining behavior, name the boundary:
overlay/: React shadow-DOM UI injected into x.com.runner/: Playwright/CDP lifecycle, overlay injection, transport bindings, passive GraphQL observation.engine/: local services, Fastify fallback API, SQLite repositories, archive/feedback/generation/judge services.shared/: Zod contracts used across runner, engine, and overlay.
Tie claims to exact files when possible: runner/src/runner-app.ts, engine/src/server/server.ts, engine/src/server/open-engine-database.ts, docs/local-data-storage.md, and docs/how-to/use-my-feedback-loop.md.
