Adapter Protocol¶

Adapters provide bidirectional context transfer between the central store and tool-specific file formats. Each adapter implements AdapterProtocol, enabling import, export, and MCP registration for a specific agent tool.

AdapterProtocol¶

Defined in src/ctx/adapters/base.py:

@runtime_checkable
class AdapterProtocol(Protocol):
    name: str

    def detect(self) -> bool:
        """Check if this adapter's tool is installed and available."""

    def import_context(self, dry_run: bool = False) -> dict:
        """Extract context from the tool into the store."""

    def export_context(self, dry_run: bool = False) -> dict:
        """Inject store content into the tool's locations."""

    def mcp_config_path(self) -> Path | None:
        """Return the path to this tool's MCP config file."""

    def register_mcp(self, local: bool = False) -> dict:
        """Register context-teleport in the tool's MCP config."""

    def unregister_mcp(self) -> dict:
        """Remove context-teleport from the tool's MCP config."""

All adapters are instantiated with a ContextStore and the project root path.

Adapter registry¶

The registry in src/ctx/adapters/registry.py provides:

• detect_adapters() -- Returns a list of all adapters whose detect() returns True
• get_adapter(name) -- Instantiates a specific adapter by name

Available adapter names: claude-code, opencode, codex, gemini, cursor.

Per-adapter details¶

Claude Code¶

Import parses MEMORY.md and CLAUDE.md as knowledge entries. Rules files are imported with their filename as the key. Skills are imported as-is from .claude/skills/*/SKILL.md.

Export writes a managed section in CLAUDE.md delimited by markers:

<!-- ctx:start -->
... generated content ...
<!-- ctx:end -->

OpenCode¶

Import reads agent definitions from .opencode/agents/, command definitions from .opencode/commands/, and session history from JSON files in the OpenCode data directory. Knowledge is also imported from the AGENTS.md file.

Codex¶

Codex does not support MCP server registration. The adapter only provides import/export functionality.

Gemini¶

Export writes each knowledge entry as ctx-<key>.md and each convention as ctx-convention-<key>.md in .gemini/rules/. The ctx- prefix distinguishes managed files from user-created rules.

Cursor¶

Cursor uses MDC (Markdown with Context) format for rules files. The adapter handles parsing and generating MDC frontmatter. Export writes knowledge as ctx-<key>.mdc and conventions as ctx-convention-<key>.mdc with alwaysApply: True.

Shared modules¶

_mcp_reg.py¶

Handles JSON-based MCP config file registration. Used by Claude Code, OpenCode, Cursor, and Gemini adapters.

Core function: register_mcp_json(config_path, server_name, command, args, env) -- reads existing config, adds/updates the server entry, writes back.

When local=True, the command points to the local Python interpreter instead of uvx.

_agents_md.py¶

Handles parsing and writing AGENTS.md files with managed sections. Used by OpenCode and Codex adapters.

Managed sections are delimited by HTML comments:

<!-- ctx:start -->
## Project Context (managed by Context Teleport)
...
<!-- ctx:end -->

Content outside the markers is preserved during export.

Import/export behavior¶

Import¶

• Reads tool-specific files and creates corresponding store entries
• Each imported entry is attributed with import:<tool> as the author
• Skills are imported as-is (SKILL.md format is the cross-tool standard)
• Supports --dry-run to preview without writing

Export¶

• Writes only public-scope entries to tool locations
• Conventions are exported before knowledge in all formats (higher priority)
• Preserves existing content outside managed sections
• Skills are exported as SKILL.md files in the tool's skills directory
• Supports --dry-run to preview without writing

Convention export formats per adapter:

MCP registration¶

Registration writes the MCP server config for the tool, including:

• Command: uvx (default) or local Python path (--local)
• Args: ["context-teleport"]
• Type: stdio
• Env: {"MCP_CALLER": "mcp:<tool-name>"} for agent attribution

# Register with uvx (default)
context-teleport register claude-code

# Register with local install
context-teleport register claude-code --local

# Auto-detect and register all available tools
context-teleport register