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.

Related MCP server: claude-sync

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 project gets a monotonically increasing sequence. 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_publish_handoff

• frontispice_list_updates

• frontispice_read_handoff

• frontispice_route_handoff

• frontispice_list_routes

• 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.

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

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.