ChatRelay Docs
Developers›Adapter guide

Adapter guide

Add another AI tool.

  1. Verify the storage format on a real machine first: where sessions live, the line/record format, any index database and its schema, how the tool lists sessions, how it stores paths, which processes mean "running". Write it down at the top of the adapter file.
  2. Add a ProviderId in crates/core/src/providers/mod.rs and a file providers/<tool>.rs implementing ProviderAdapter: detect, list_projects, list_sessions, read_session, export_session, import_session, optionally append_session, context_file_name, process_names.
  3. Rules every adapter follows: refuse to write while the tool runs (ensure_not_running), back up every file before writing (ImportOptions.backups), honour dry_run, honour keep_both (save a diverged incoming session under a new id), and turn import off (with a warning in ProviderStatus) on any format it doesn't recognise.
  4. Put pure parsing in a file without file-system access (like codex_format.rs) so the web viewer can use it, and add it to messages_from_bundle.
  5. Add fixture files under crates/core/tests/fixtures/<tool>/ and tests: detect, list, read, export → import on a second fake machine (paths rewritten), update, local-ahead, conflict, running-process refusal, unknown format.
  6. Add the label in src/shared/types.ts (PROVIDER_LABELS). Badges, filters, push/pull, summaries and the viewer pick it up from there.