How the CareerOps Agent Wrapper Layer Integrates with Claude, Codex, and Other AI CLIs

The CareerOps Agent Wrapper Layer enables multiple AI coding CLIs to share a single source of truth by using thin wrapper files that redirect to the canonical AGENTS.md specification.

The santifer/career-ops repository implements a sophisticated Agent Wrapper Layer that decouples core agent logic from CLI-specific implementations. This architecture allows Claude Code, Codex, OpenCode, and Gemini to operate using identical skills and prompts without duplicating configuration files. By centralizing agent definitions in AGENTS.md, CareerOps ensures that updates to scanning modes, job offer analysis, and PDF generation propagate instantly across all supported interfaces.

Why CareerOps Uses an Agent Wrapper Layer

Single Source of Truth in AGENTS.md

All core agent logic resides in AGENTS.md at the repository root. This file contains the canonical definitions for skills, prompts, and mode definitions (such as scan, oferta, and pdf). Instead of scattering configuration across multiple CLI-specific files, AGENTS.md serves as the single source of truth that every wrapper references.

CLI-Specific Entry Points

Each supported CLI maintains its own executable entry file—CLAUDE.md, CODEX.md, OPENCODE.md, or GEMINI.md. These wrapper files contain minimal logic, typically just a single @AGENTS.md redirection. When a CLI driver initializes, it reads its designated wrapper first, then follows the reference to load the shared agent specification.

Separation of Concerns

The wrapper architecture enforces a strict boundary between system-layer files and user-layer customizations. System files (AGENTS.md plus wrappers) update independently of user data stored in modes/_profile.md and config/profile.yml. According to the DATA_CONTRACT.md specifications, this guarantees that CLI upgrades never overwrite personal configurations.

How the Wrapper Files Work

Each wrapper file acts as a minimal entry point that the CLI driver reads before executing commands:

• CLAUDE.md (Claude Code) – A full-featured wrapper that imports AGENTS.md and appends Claude-specific metadata for enhanced context handling.
• CODEX.md (Codex) – A thin wrapper containing only the @AGENTS.md redirection line, enabling Codex to leverage CareerOps modes without native configuration.
• OPENCODE.md (OpenCode) – Identical thin redirection structure to CODEX.md, pointing directly to the canonical specification.
• GEMINI.md (Gemini) – A legacy wrapper that redirects to AGENTS.md while preserving backwards-compatible command structures.

When a user invokes a CLI command, the driver loads its respective wrapper, follows the @AGENTS.md reference, and executes the shared agent logic. No CLI maintains its own copy of prompts or skills.

Integration Flow Across Supported CLIs

The Agent Wrapper Layer operates through a standardized five-step pipeline:

1. CLI Startup – The user executes a CLI-specific command such as codex, claude, or opencode.
2. Wrapper Loading – The CLI driver locates and reads its corresponding wrapper file (CODEX.md, CLAUDE.md, etc.).
3. Redirect to AGENTS.md – The wrapper’s @AGENTS.md reference triggers the CLI to pull in the canonical agent definition.
4. Agent Execution – CareerOps parses the modes and prompts defined in AGENTS.md, executing the requested operation (e.g., scan, oferta).
5. Result Handling – Output generation follows unified code paths, producing reports, PDFs, or tracker updates regardless of which CLI initiated the request.

This flow is documented in ARCHITECTURE.md and the compatibility matrix in docs/SUPPORTED_CLIS.md.

Practical Usage Examples

Running a Scan with Codex

Execute a job market scan using OpenAI's Codex CLI:

# From the repository root

codex exec "career-ops scan"

The codex binary loads CODEX.md, which redirects to AGENTS.md. The scan mode executes using the shared agent logic to analyze current opportunities.

Evaluating Job Offers with Claude Code

Process a specific job description using Claude Code:

claude -p "career-ops oferta https://example.com/job/123"

Claude Code reads CLAUDE.md, imports the full AGENTS.md specification (including Claude-specific extensions), and runs the oferta mode to evaluate the JD and generate a compatibility report.

Automating Workflows with OpenCode

Integrate CareerOps into Node.js automation scripts:

// open_code_script.mjs
import { runPrompt } from 'opencode';

await runPrompt('career-ops pdf');

OpenCode loads OPENCODE.md, follows the @AGENTS.md reference, and executes the PDF generation mode to compile application materials.

Summary

• Single source of truth: All agent logic lives in AGENTS.md, preventing configuration drift across CLIs.
• Thin wrappers: Files like CODEX.md and OPENCODE.md contain only redirection logic, minimizing maintenance overhead.
• Unified execution: Modes such as scan, oferta, and pdf run identically whether invoked via Claude Code, Codex, or OpenCode.
• Safe upgrades: The separation between system wrappers (AGENTS.md) and user profiles (modes/_profile.md) ensures updates never overwrite personal data.
• Extensible design: New CLIs integrate by creating a wrapper file that references the canonical specification.

Frequently Asked Questions

What is the Agent Wrapper Layer in CareerOps?

The Agent Wrapper Layer is an architectural abstraction in santifer/career-ops that enables multiple AI CLIs to share centralized agent logic. It consists of thin wrapper files (e.g., CLAUDE.md, CODEX.md) that redirect CLI drivers to the canonical AGENTS.md specification, ensuring consistent behavior across Claude Code, Codex, OpenCode, and Gemini.

How does the wrapper layer prevent configuration duplication?

By storing all prompts, skills, and mode definitions exclusively in AGENTS.md, CareerOps eliminates the need to copy logic into CLI-specific files. Each wrapper merely references @AGENTS.md, so updates to the core specification immediately propagate to all supported CLIs without manual synchronization.

Can I use multiple CLIs simultaneously with the same agent logic?

Yes. Because all CLIs reference the same AGENTS.md file, you can run claude -p "career-ops scan" in one terminal and codex exec "career-ops scan" in another. Both commands execute identical logic from the single source of truth, producing consistent results regardless of the underlying CLI.

Where is the canonical agent specification stored?

The canonical specification resides in AGENTS.md at the repository root. This file contains the definitive implementations for all CareerOps modes, including job scanning (scan), offer analysis (oferta), and document generation (pdf). Wrapper files like CODEX.md and GEMINI.md exist solely to point their respective CLIs to this central definition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}