ClipBrain: Instructions file for Codex

ClipBrain Agent Instructions

This file is for Codex and other coding agents working in this repo. Claude Code can use CLAUDE.md; keep this file shorter and focused on operational rules.

Project Shape

ClipBrain is a Chrome extension plus a local Bun HTTP server. The extension captures web pages, Kindle highlights, Gmail threads, YouTube transcripts, and PDFs. The server writes captures to the user's local knowledge base through the installed gbrain CLI and optionally syncs markdown to Obsidian.

Important files:

• server.ts: local HTTP API, dashboard routes, capture handling, diagnostics
• clipbrain-mcp.ts: ClipBrain-specific MCP tools that call the local server
• backfill.ts: controlled Knowledge Compiler backfill for legacy captures
• corpus-report.ts: read-only corpus quality report for junk/duplicate audit
• cleanup-plan.ts: read-only cleanup recommendations; never deletes or writes
• cleanup-apply.ts: explicit approval-gated cleanup executor with backups/logs
• gbrain-list.ts: shared robust gbrain list scanner used by server, corpus, and cleanup flows
• doctor.ts: first-run diagnostics for launch readiness and local setup issues
• twitter-agent.ts: draft-only building-in-public generator; never posts to X
• service-worker.js: MV3 background worker, capture dispatch, offline queue
• content-script.js, kindle-content-script.js, gmail-content-script.js: page extractors
• post-process.ts: optional OpenAI enrichment after a capture is saved
• dashboard.html, popup.html, popup.js: local UI surfaces
• setup.sh, setup-mcp.sh: local install and MCP configuration
• test/: Bun tests for server and post-processing behavior

Runtime Facts

• Use Bun. Primary checks are bun run doctor, bun test, bun audit, and shell syntax checks for setup scripts.
• The server binds to 127.0.0.1:19285 by default. It can be overridden with --host, --port, GBRAIN_CAPTURE_HOST, and GBRAIN_CAPTURE_PORT.
• MCP setup registers both gbrain (gbrain serve) and clipbrain (bun clipbrain-mcp.ts). Keep gbrain for broad brain tools; use clipbrain for ClipBrain-specific agent handoffs such as context_pack.
• Do not reintroduce a vendored gbrain dependency or local ./bin/gbrain build path. The app should use GBRAIN_BIN when set, then gbrain from PATH.
• package-lock.json is intentionally absent. This repo uses bun.lock.
• Runtime data files such as .captures.jsonl, .highlight-count, .highlight-counts.json, .clipbrain.json, .cleanup-actions.jsonl, and .cleanup-backups/ must stay out of commits. Tests should use CLIPBRAIN_DATA_DIR for isolated state.
• Use bun run backfill --limit N for a dry-run before applying compiler upgrades with bun run backfill --apply --limit N.
• Use bun run corpus to inspect likely junk, duplicate titles, and pending compiler upgrades. It is read-only.
• Use bun run cleanup-plan to turn the corpus audit into a read-only keep/delete/merge/title-fix proposal before any manual cleanup.
• Use bun run cleanup-apply for a dry-run of executable cleanup operations. Never run it with --execute unless the user has approved exact --approve action:slug tokens.