connectr: Instructions file for Codex

ConnectR shared-agent protocol (managed by connectr init)

This project is worked on by multiple AI agents sharing one brain via the "connectr" MCP server. Before starting any task: call board_view to see open work, and recall for prior decisions. Claim before build: ticket_create then ticket_claim before writing any code - this prevents duplicate work. Remember durable decisions and facts with remember; search shared memory with recall before assuming. Before editing files other agents might touch, claim_files them; call release_files when done. Post evidence (test output, commit SHAs) with ticket_update; finish with ticket_close + resolution. When something fails (command error, broken test, wrong assumption), store it with remember kind='lesson': what happened + root cause in text, the corrective action in fix. Before retrying a failure or starting risky work, recall kind='lesson' so you never repeat a mistake another agent already paid for.

Codebase map (2026-08-26)

connectr-mcp v0.1.0 — TypeScript ESM, Node >=20. npm test = tsc build + vitest (incl. a two-process race test); npm run smoke = two real MCP client sessions over stdio against the built server.

• src/types.ts — store schema: AgentInfo, Fact (kind: fact|decision|lesson, optional fix), Ticket (+routedTo), FileClaim
• src/store.ts — JSON store at .connectr/store.json; cross-process lockfile (O_EXCL, 10s stale-steal) + atomic temp-rename writes; claims auto-expire (2h)
• src/memory.ts — shared-brain helpers: searchFacts (kind-aware scoring), findDuplicate (near-dup rejection), recentLessons
• src/detect.ts — tool detection (dispatch CLIs on PATH, participant IDEs by config dir, sign-in by existence of the tool's own authFile — never read; signedIn is null when unknowable, and home is injectable for tests) + suggestOrchestra (rank tools for a plan via routing-rule hits; generic terms like "build" ignored at plan scale) + the PLAN.md template
• src/planner.ts — the conversational front door's instruction: plannerTicket(intent, {planFile}) builds the ticket whose description tells an agent how to decompose an intent into routed tickets (title conventions, contracts, parallel-safety, no duplicates). One source of truth, used by connectr plan and the ticket connectr new seeds
• src/worktree.ts — parallel isolation: a git worktree per ticket on branch connectr/<id> under .connectr/trees/. copyWiring carries the gitignored init products into each tree and dispatch pins CONNECTR_STORE to the main store, or the agent would get a private brain; realChanges treats only genuine work as dirty (ConnectR's own scaffolding and untracked dirs it created are excluded); mergeWorktree refuses on dirty trees and names conflicts rather than losing a version
• src/host.ts — shared host actions used by CLI run, TUI dash and web UI: addTaskFromInput (parse + route + create), planIntent (park an intent as a planner ticket routed to the project's default/reasoning tool), planOpenTickets (route-and-copy open set, include/exclude), prepareWorkspace (the single place isolation is decided - every dispatch path must go through it), launchPlanned, recordAttempt (a failed run is written to Ticket.attempts, reopens the ticket and drops the dead owner) and sweepDeadRuns (same reconciliation for detached runs whose agent is no longer live)
• src/tools.ts — the tool registry. Every coding tool is a ToolSpec record (id, kind, bin, args template with {cwd}/{model}/{prompt}/{mode}, per-mode flags, modelArgs, prompt delivery, homeDir, init target slugs) instead of a branch. BUILTIN_TOOLS ships the three verified CLIs + three participant IDEs; normalizeToolSpec validates user declarations from config tools[]; toolRegistry merges them (same id replaces a built-in); expandArgs renders a concrete argv
• src/learn.ts — outcome-learned routing at tool:model granularity (targetKey/parseTarget/agentTarget, model taken from the agent's whoami registration): categoryOf(title, desc) matches the title first and only widens to the description when the title says nothing; learnRoutes scores targets per category from closed tickets (completions = wins, takeovers + routing-misses + failed attempts = losses (failures are counted even while the ticket is open, which is the only negative signal most boards produce), Laplace-smoothed); an override needs 3+ outcomes and the rule's own tool to have been tried (any of its models counts); a category can be won by another model of the same tool; surfaced via connectr routes and routedTo.via/reason
• src/ui/server.ts — connectr ui HTTP server (node:http, 127.0.0.1 only, zero deps): /api/state (tickets carry tree:{commits,dirty} from a 3s-cached worktree scan), /api/events (SSE, 1s change-push), /api/task, /api/dispatch (dry=plan preview), /api/log (basename-guarded tails), /api/diff + /api/merge (^t\d+$-validated review & merge), /api/sweep (reopen dead-agent tickets). Auto-continue: config.autoContinue + a tick (CONNECTR_AUTO_TICK ms, default 5s) that launches eligible open tickets (< 2 failed attempts); every child launched by this host gets an exit reconcile — unclosed ticket ⇒ failed attempt + reopen, same contract as connectr run
• src/ui/page.ts — the whole dashboard as one embedded HTML page (no build step, no CDN). Every backslash in the client JS must be doubled — the file is a template literal, and a single one is eaten before the browser sees it (see lesson f29). Notifications are client-only: noticeChanges diffs consecutive SSE pushes (closed / reopened / commits appeared), fires only when document.hasFocus() is false, title badge needs no permission, native Notification is the opt-in bell (localStorage connectr-notify). Shell-aware: when window.connectr exists (the Electron preload), it adds a Projects button and the Ctrl+K project switcher; in a browser it stays a plain page; board columns, agents, memory, claims, run tails, add + confirm-dispatch
• src/server/index.ts — the MCP server (stdio): whoami, remember/recall, ticket_create/claim/update/close, board_view, claim_files/release_files
• src/routing.ts — task→tool routing: matchRule scores each rule by how many of its alternation terms the text supports and picks the best-supported (user rules in .connectr/config.json win outright over DEFAULT_RULES: backend/auth→claude-code, cli/scripts/data→codex, docs/research→gemini), so a passing mention can't outvote the subject; parseTaskInput handles the title @tool[:model] manual-assign syntax; permissionMode (safe|auto|yolo, default auto) lives in the same config
• src/spawn.ts — headless dispatch of routed tickets: buildCommand(tool, cwd, model, mode, platform) maps tool+model+permission mode to flags (MODE_FLAGS table; safeModel guards the shell string), POSIX spawns argv directly while win32 wraps claude/gemini in powershell for the .cmd shims, launchTicket wraps prompt+log, detach mode (fd-stdio + unref) lets children outlive the dash; logs to .connectr/runs/*.log
• src/cli/index.ts — connectr CLI: serve, init, new (project creation: folder + PLAN.md + suggested orchestra, scoped wiring, seeds the planner ticket), plan (the front door: intent -> planner agent -> routed tickets, --run dispatches them), task add (auto/manual route + model, validates --tool), run (parallel dispatch = the host loop, injects planFile), routes, status, board, doctor, dash, ui
• src/cli/targets.ts — init wiring for 6 tools; only touches its own marker-wrapped blocks / connectr entries
• src/tui/dash.tsx — interactive host TUI, polls store 1×/s: a add task (auto-route or @tool[:model]), r dispatch open tickets detached, l tail newest run log, lesson badges in memory