chromectx: Instructions file for Codex

Micro-commits

Commit immediately after completing each logical unit of work — do not batch unrelated changes and do not wait to be asked. A "logical unit" is one self-contained change to the codebase: implementing a function, adding a command, writing a test, fixing a bug, wiring up a new module, adding a skill, etc. A unit may touch multiple files if they belong together (e.g. a module + its test, or a skill's directory of files). When in doubt, commit more often rather than less.

Keep commits atomic: commit only the files you touched and list each path explicitly. For tracked files run git commit -m "<scoped message>" -- path/to/file1 path/to/file2. For brand-new files, use the one-liner git restore --staged :/ && git add "path/to/file1" "path/to/file2" && git commit -m "<scoped message>" -- path/to/file1 path/to/file2

Project shape

This repo is a TypeScript codebase (runs on Bun) with one executable surface:

• chromectx doctor
• chromectx restore ...
• chromectx save ...
• chromectx list ...
• chromectx search ... — fast title+URL search; --deep fetches full page content
• chromectx rag ... — RAG search across tabs (JSON output for agents/scripts)
• chromectx mcp

The MCP server is local-only and uses stdio. Treat the CLI and MCP server as two transports around shared code rather than as separate applications.

Source layout

• src/bin: executable entrypoints only
• src/browser: browser-level type definitions (ChromeSession, ChromeTab, etc.) shared across commands, store, and platform
• src/commands: CLI-facing orchestration — each command is a self-contained module exporting a CommandDefinition (see "Adding a CLI command" below); types.ts defines the shared CommandDefinition, CommandRunContext, and GlobalFlags interfaces; root.ts is the registry + dispatcher — each command is a self-contained module exporting a CommandDefinition (see "Adding a CLI command" below); types.ts defines the shared CommandDefinition, CommandRunContext, and GlobalFlags interfaces; root.ts is the registry + dispatcher
• src/mcp: MCP protocol handling and tool registration
• src/platform/macos: macOS-specific integrations and checks
• src/platform/macos/chrome/: Chrome browser interaction (install detection, session/tab queries, page source retrieval)
• src/lib: shared support modules such as config, errors, output, logging, concurrent.ts (sliding-window pMap), and http.ts (shared fetchSources with concurrency 15)
• src/lib/tui/: interactive terminal UI components built on @clack/prompts — select.ts exports selectOne<T>() (and will gain selectMany<T>() later). Use these for any arrow-key selection in CLI commands; inject via deps for testing.
• src/lib/store/: session persistence — types.ts defines the schema contract (Session, SessionWindow, SessionTab); io.ts handles read/write/list to {AppPaths.sessions}/*.json
• src/lib/workflows/search/: BM25 search pipeline — preprocess.ts (HTML→markdown via turndown), chunk.ts (paragraph chunking ~500 chars), index.ts (buildIndex + SearchIndex with search and searchWithPages)
• src/lib/workflows/rag.ts: shared RAG pipeline (executeRag) used by both CLI rag command and MCP rag_search tool