Codex Compass

Inspiration

Codex can gain useful abilities through plugins, skills, MCP servers, and open-source tools, but deciding which are safe and worthwhile often assumes comfort with package managers, configuration, OAuth, Hook trust, and provenance. Codex Compass explores a calmer, no-screen way for non-developers to discover a relevant capability, understand its boundary, try it in a clean task, and decide whether it is worth keeping.

What it does

Codex Compass has a Local Evangelist for the Mac and a Main Evangelist advisory service design. Local is the safety boundary: it presents a background-app experience, checks bounded Codex sign-in status without reading credentials, uses fixed Host-owned adapters for allowed actions, and requires fresh tasks for before/after capability comparison. The user-facing choice is deliberately simple: Keep, Use once, or Revert.

The current source flow covers local supervisor guidance and a narrow, Compass-owned companion workflow. The repository contains an isolated official-Codex-CLI demo that registers the local marketplace, installs the two repository-owned plugins in a temporary Codex home, and verifies their installation. A separately recorded local comparison trace establishes a fresh enhanced task and companion invocation; it does not assert that output quality improved.

Main is advisory only. External research, generic signed Main advice in the packaged Local flow, and production outcome aggregation remain unavailable or repository-contract paths unless a current, redacted receipt proves otherwise.

How we built it

The macOS product is an Electron application with a deterministic Host, an Electron-main-only Codex SDK adapter, fail-closed same-user Unix-socket bridge code, and first-party plugin packages. The architecture keeps the SDK read-only, network-disabled, and non-interactive; the Host independently validates capability identity, provenance, policy, consent, freshness, and compatibility before any prebuilt adapter may act.

The project also includes closed schemas and tests for capability advice, consent-separated feedback, privacy-thresholded aggregates, signed knowledge, and safety failures. Codex helped during development with repository navigation, turning product and security decisions into testable contracts, generating adversarial cases, and inspecting receipts.

Challenges we ran into

The central challenge was useful automation without silently broadening authority. A model or remote response cannot become a command, package, path, or configuration write. Plugin installation, OAuth, Hook trust, and third-party actions must remain visible, user-mediated boundaries.

We also had to resist treating a successful install as a successful result. A capability installed during a task cannot change that task, so the comparison contract requires separate baseline and enhanced tasks. Finally, the submission has to distinguish source and fixture evidence from claims about a public service, real users, or output quality.

Accomplishments that we're proud of

• A no-screen macOS design that surfaces a small status window only when setup needs the user’s attention.
• A deterministic Host that owns policy and action validation rather than delegating authority to model or remote text.
• A repository-tested, isolated official-CLI workflow for the two Compass-owned local plugins, with no access to the normal Codex home.
• Fresh-task comparison receipts that show installation/invocation boundaries without pretending to measure quality automatically.
• Consent-separated, privacy-minimized feedback contracts: no prompts, model outputs, paths, identities, OAuth material, URLs, commands, or free text enter the outcome event schema.

What we learned

Trustworthy AI assistance is as much about honest product boundaries as it is about model capability. “Unavailable” is a legitimate, safer result when evidence, credentials, or user consent are missing. We learned to make each claim match an inspectable artifact: a test, signed manifest, bounded receipt, diff, or review note—not polished prose.

What's next for Codex Compass

Before broad distribution, Compass needs an identity-bound packaged marketplace source, notarized release delivery, and fresh independent evidence for clean-user onboarding. Any live remote advisory path would require user-managed deployment and a current redacted proof of its protected request/response flow. We also want to validate the experience with real users before making claims about multi-user outcomes, retention, or capability quality.

Built With

• ajv
• better-sqlite3
• cloudflare-access
• cloudflare-tunnel
• codex-plugins
• electron
• esbuild
• fastify
• jose
• json-schema
• mcp-sdk
• model-context-protocol
• node.js
• npm
• openai-codex-sdk
• sqlite
• supabase-js
• tsx
• typebox
• typescript
• unix-domain-sockets
• zod