Raveil Frontispice

Frontispice is a small, local-first agent handoff core with an optional Model Context Protocol (MCP) adapter. It lets one AI session leave curated, explicit context for another—especially ChatGPT → Codex—without copying an entire conversation history.

The name comes from Maurice Ravel's Frontispice (1918). In Raveil naming, Frontispice is the entry/boundary surface through which one agent leaves a concise handoff for another.

Status: 0.1.0 / alpha. The storage schema and authority boundary are intentionally small.

Architecture in one sentence

Frontispice Core owns handoff state; adapters expose it to hosts; agents decide what becomes repository truth.

                         ┌──────────────────────┐
 ChatGPT Web ── MCP ───▶ │                      │
                         │  Frontispice Core    │
 Future host ─ adapter ─▶│                      │
                         │  SQLite handoffs     │
                         │  project sequences   │
 Codex ─────── MCP ────▶ │  consumer cursors   │
                         │  routing/provenance  │
                         └──────────┬───────────┘
                                    │
                                    │ context only
                                    ▼
                              Librarian / agents
                                    │
                                    ▼
                           repository Markdown/code

MCP is deliberately an adapter, not the product boundary. The core has no dependency on ChatGPT, Codex, MCP, HTTP, Git, or shell execution.

See docs/ARCHITECTURE.md.

What problem it solves

ChatGPT discussion
      │
      │ explicit: "send these conclusions to Codex"
      ▼
transport adapter
      │
      ▼
Frontispice Core / local SQLite inbox
      │
      │ next Codex start/resume
      ▼
Librarian checks consumer cursor
      │
      ├── architecture specialist
      ├── research specialist
      └── implementation specialist
      │
      ▼
validated repository Markdown / ADR / code

Frontispice is not a ChatGPT conversation scraper, Git agent, shell tool, browser, or autonomous background daemon. The sender chooses what to hand off. The receiver verifies it and decides what belongs in the repository.

Core model

Each registered project gets a canonical lowercase kebab-case key and a monotonically increasing sequence. Project names are resolved through the registry before handoffs are accepted; agents must ask the user before registering an unknown project. Each consumer—for example librarian, architecture, or research—has its own monotonic cursor.

One agent acknowledging sequence 42 therefore does not hide it from another. A resumed Codex session asks for messages newer than librarian's last cursor.

Components

src/raveil_frontispice/
├── core/
│   ├── service.py       # transport-neutral public service
│   ├── store.py         # SQLite state + provenance
│   ├── security.py      # high-confidence secret guardrail
│   ├── validation.py
│   └── config.py
└── adapters/
    └── mcp.py           # optional MCP tool surface

The Python core can be installed and tested without the MCP SDK. The MCP dependency is an optional extra.

Security by design

Frontispice deliberately avoids powerful capabilities:

• no shell execution
• no arbitrary filesystem or Git writes
• no URL fetching/application network calls in the core
• no delete MCP tool in v0.1
• owner-only database permissions where supported
• bounded inputs and parameterized SQLite queries
• high-confidence credential-pattern rejection by default
• explicit idempotency keys for safe publisher retries
• local HTTP adapter is loopback-only in v0.1
• handoff content is untrusted data, not instructions
• repository changes happen through the receiving agent's normal permission model, not Frontispice

Read SECURITY.md before deploying beyond a single trusted user/machine.

Current ChatGPT surface limitations

As of 2026-08-09, OpenAI's custom MCP / Developer mode flow is a web surface. It is not a way to attach a private custom MCP directly to the ChatGPT iPhone app. Published plugins are also currently documented for web/desktop/Codex rather than mobile.

This is why Frontispice treats MCP as one adapter. The core does not need to change when another supported host/transport becomes available.

For current setup options and exact limitations, see docs/INTEGRATION.md.

Quick start: core only

git clone <your-raveil-frontispice-repository-url>
cd raveil-frontispice
python -m pip install -e .
frontispice doctor

Or with uv:

uv sync --extra dev
uv run frontispice doctor

Quick start: MCP adapter + Codex

uv sync --extra mcp --extra dev
uv run frontispice serve

Connect Codex:

codex mcp add frontispice -- \
  uv --directory /ABSOLUTE/PATH/TO/raveil-frontispice \
  run --extra mcp frontispice serve

codex mcp list

For the complete ChatGPT-web + private MCP + Codex workflow, see docs/INTEGRATION.md.

To publish this repository safely to GitHub, see docs/PUBLISHING.md.

MCP tools

The optional MCP adapter exposes:

• frontispice_list_projects
• frontispice_register_project
• frontispice_publish_handoff
• frontispice_delivery_status
• frontispice_list_updates
• frontispice_read_handoff
• frontispice_route_handoff
• frontispice_mark_applied
• frontispice_advance_cursor
• frontispice_project_status

The adapter is intentionally thin: validation, secret checks, storage, cursors, routing, and provenance live in Frontispice Core. Route lookup remains available in Frontispice Core but is not exported as a separate MCP tool; the ChatGPT-facing tool surface is intentionally capped at ten high-value operations.

Publish success is receipt-based. A successful call returns delivery_status="committed" plus a receipt containing the handoff ID, canonical project, sequence, content checksum, and commit timestamp. Natural-language claims without that receipt must be treated as not sent. frontispice_delivery_status verifies a receipt later by handoff ID or idempotency key and can additionally compare the checksum.

Project selection UX

Project identity is registry-backed rather than free-form:

1. Codex registers its repository once, after explicit user confirmation.
2. ChatGPT resolves the requested project before publishing.
3. A single registered project can be selected automatically.
4. Multiple projects produce a structured selection prompt for the user.
5. Unknown projects produce a confirmation prompt and are never silently created.

Keys are normalized case-insensitively (Raveil, RAVEIL, and raveil resolve to raveil; spaces and underscores become hyphens). Registering a canonical project merges legacy case/spelling variants without changing handoff IDs. Because old sequence numbers can collide, merged handoffs are resequenced by creation time and affected consumer cursors reset to zero so no handoff is silently skipped.

Bundled Codex librarian workflow

templates/codex/
├── AGENTS.md.snippet
├── .codex/
│   └── config.toml.snippet
└── .agents/
    └── skills/
        └── frontispice-librarian/
            └── SKILL.md

The Librarian treats inbox material as untrusted context, classifies it, delegates verification where useful, integrates durable conclusions into canonical repository files, records provenance, and advances its cursor only after deliberate handling.

Data location

Default:

~/.frontispice/frontispice.sqlite3

Override:

export FRONTISPICE_DB=/secure/path/frontispice.sqlite3

Do not place the database in a public repository.

Environment variables

Variable	Default	Purpose
FRONTISPICE_DB	~/.frontispice/frontispice.sqlite3	SQLite path
FRONTISPICE_MAX_CONTENT_BYTES	262144	Maximum handoff body size
FRONTISPICE_ALLOW_SENSITIVE	false	First half of deliberate secret-scan override

A secret-scan override requires both FRONTISPICE_ALLOW_SENSITIVE=true and allow_sensitive=true on the publish call.

Development

Core-only development:

python -m pip install -e '.[dev]'
ruff check .
pytest

Full adapter development:

python -m pip install -e '.[mcp,dev]'
ruff check .
pytest

Design principles

1. Core before transport — MCP is an adapter, not Frontispice's identity.
2. Curated, not copied — never mirror whole conversations by default.
3. Inbox, not truth — receiving agents verify against repository reality.
4. Data, not commands — handoff bodies cannot confer authority.
5. Least authority — Frontispice stores handoffs; repository tools do repository work.
6. Per-consumer cursors — multi-agent readers do not steal each other's unread state.
7. Traceability — routing and applied provenance remain queryable.
8. Local first — no public listener is required for the local core.
9. Surface-aware — unsupported ChatGPT clients are documented, not worked around with unsafe public endpoints.

License

Apache License 2.0. See LICENSE.