Codex Bridge for protoAgent

Codex Bridge is a dedicated protoAgent plugin for migrating selected operator-owned Codex state into a new protoAgent agent.

Status: v0.2 migration candidate. Source inventory, decision-grade review, translation, snapshot export, explicit external skill roots, and acknowledged fresh-agent apply are implemented. Real-source isolated qualification and release remain later gates.

Supported v0.2 scope

Codex source	protoAgent target	Default
User-authored skills from current or legacy roots	Agent skills	Migrate after preview
Explicit repository .agents/skills	Agent skills	Migrate with repository provenance
Explicit repository AGENTS.md hierarchy	Knowledge/instructions	Preserve path and precedence
Curated MEMORY.md	Knowledge	Migrate with provenance
memory_summary.md	Knowledge candidate	Operator-selectable
MCP definitions from config.toml	Snapshot MCP configuration	Strip all values
Rules, sandbox, approvals, plugins, model/provider settings	Manual-review report	Never automatic

Source selection

Codex does not use Hermes-style profiles. Its effective agent state combines user-level and repository-level sources.

The bridge will require explicit inputs:

• Codex home, normally ~/.codex;
• current user skills root, normally ~/.agents/skills;
• legacy user skills root, normally ~/.codex/skills;
• optional explicit external skill roots for approved symlink targets;
• one or more explicit repository roots for AGENTS.md and .agents/skills.

The plugin will not crawl the user's home directory to discover repositories.

Hard exclusions

The bridge will never read or migrate:

• auth.json or credentials;
• sessions or rollout JSONL;
• SQLite databases, WAL, or SHM files;
• logs, shell snapshots, caches, temporary files, or locks;
• installation identifiers;
• downloaded plugin caches or plugin code;
• provider/model choices, approval policy, sandbox policy, or command rules as executable target policy;
• raw memories and rollout summaries by default.

Safety contract

• Disabled by default.
• No network capability.
• Explicit source roots only.
• Fenced and complete byte-capped reads.
• Dry-run preview before snapshot creation.
• Raw and translated bytes bound into a reviewed plan fingerprint.
• Fresh protoAgent agent creation only after explicit acknowledgement.
• No source mutation, in-place target merge, credential transfer, or plugin installation.

Available tools

Tool	Purpose
codex_sources	Report availability of configured user and repository roots without discovering others
codex_import_scan	Build a write-nothing human or JSON review and plan SHA-256
codex_export_snapshot	Preview or write a secret-free protoAgent snapshot archive
codex_apply_snapshot	Create a fresh protoAgent agent after exact-plan acknowledgement

Snapshot export is dry-run by default. Apply creates a fresh target and never merges into an existing agent.

Planned delivery

1. Source inventory and classification.
2. Pure skill, instruction, memory, and MCP translators.
3. Decision-grade review and protoAgent snapshot export.
4. Acknowledged fresh-agent apply.
5. Real-source isolated Linux qualification and release.

See docs/IMPLEMENTATION_PLAN.md for the source contract and acceptance boundaries.

Development

python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt ruff
.venv/bin/pytest -q
.venv/bin/ruff check .
.venv/bin/ruff format --check .

Repository layout

protoAgent external plugins use a flat repository layout. The manifest and register() entrypoint live at the repository root.

• protoagent.plugin.yaml: plugin identity, defaults, and capabilities
• __init__.py: plugin registration
• skills/codex-bridge/SKILL.md: bundled operator guidance
• docs/IMPLEMENTATION_PLAN.md: source contract and delivery plan
• tests/: host-free foundation checks

License

MIT