A persistent Grok companion on X’s right rail (Chrome Manifest V3). It pins the tweet you’re reading, knows who you’re looking at, and talks like a presence — not a dashboard.
Cyberpunk glass HUD · rotating Mars orb · Star-Trek command deck · Grok hero + sovereign fallbacks.
Steward Compatible v1.0 — reflection · assumption tracking · human override · evidence · growth memory · transparent uncertainty.
Protocol soil: steward-protocol.
Version 0.5.0 — SSO-first: friends + gated post work with X Client ID alone. xAI key optional (cloud Grok). Icons, 280 post gate, editable drafts, origin-locked postMessage, grok-4 default.
- Grok, hero. Default channel is live Grok (
grok-4-latestvia xAI when a key is set). Click any tweet to pin it; Grok answers with that text in context. - SSO-first. Sign in with X (Client ID only) → sync friends, pin tweets, post with your approval. No xAI key required for those flows.
- Sovereign fallbacks. Cascade:
#grok(cloud) →#mist(Aurelia) →#local(on-device Qwen2.5-0.5B) → queue.#osis its own channel with HUD tiles. - Post on your behalf — gated. Draft card is editable; you approve. (
/post <text>,/draft <idea>, or[POST] ….) Replies use a real tweet id. - Offline queue. If every channel is down, your message is held and flushed when a path returns.
- twitter-text. Vendored from X’s open-source parser for the live 280 counter.
chrome://extensions→ Developer mode → Load unpacked → this folder.- Open
x.com— the sidebar mounts on the right rail. - Toolbar icon → popup (SSO-first setup):
- Paste X OAuth Client ID (required for Sign in / friends / post)
- Optional: xAI API key (only for live cloud Grok)
- Optional: Grok model, MIST / OS localhost endpoints
- Click Save → Sign in with X
- Create an app at developer.x.com.
- Add the redirect URI shown in the popup (
https://<ext-id>.chromiumapp.org/). - Scopes:
tweet.read users.read tweet.write offline.access. - Paste Client ID in the popup → Save → Sign in w/ X in the sidebar.
- No secrets are committed to the repo.
- xAI key and X tokens are AES-GCM wrapped in
chrome.storage.local(seecrypto.js/background.js). - The AES key also lives in that store — the browser profile is the real trust boundary, not a separate HSM. This stops casual dumps/backups from showing plaintext keys; it does not stop malware with extension-storage access.
- Chat, contacts, and the offline queue are encrypted the same way.
- Nothing posts to X without an explicit Post it ✓ click.
| File | Role |
|---|---|
manifest.json |
MV3, host permissions, web-accessible panel modules |
background.js |
OAuth2 PKCE, token refresh, encrypted token store, gated SSO_POST |
content.js |
Right-rail iframe, contact scrape, click-to-pin tweet (+ text) |
panel.* |
HUB + HUD UI, routing, chat, post approval |
router.mjs |
decideTransport() cascade |
mist.js / os.js |
Local Aurelia / sovereign OS bridges |
localmodel.js |
On-device Qwen (WebGPU → WASM), load-on-demand |
crypto.js |
AES-GCM helpers for secrets + local data |
lib/twitter-text |
Vendored tweet length / entities |
lib/transformers.js |
Vendored transformers.js (weights from HF at runtime) |
| Command | Effect |
|---|---|
/post <text> |
Propose a post; approve to publish |
/draft <idea> |
Same, with ☁ prefix |
| Click a tweet | Pin it (amber outline) for context + reply target |
| Channel select | #grok / #local / #mist / #os |
Hide — |
Collapse the rail (state remembered) |
npm test
# or: node verify.mjs && node verify_bitchat_fallback.mjs && node verify_post_payload.mjsCI: .github/workflows/verify.yml on push/PR.
0.4.0 — usable companion loop. Headlessly verified (syntax, manifest, router, post-payload contracts). Visuals need a real Chrome load on x.com. Live Grok needs your xAI key; posting needs an X OAuth app; MIST/OS need your local servers; on-device model downloads weights from Hugging Face on first use.
Built for @Mellowambience. Fly responsibly.