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

> Learn how the CareerOps Agent Wrapper Layer integrates Claude, Codex, and AI CLIs using wrapper files that redirect to the AGENTS.md specification. Streamline AI access.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: internals
- Published: 2026-08-22

---

**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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/CLAUDE.md), [`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md), [`OPENCODE.md`](https://github.com/santifer/career-ops/blob/main/OPENCODE.md), or [`GEMINI.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) plus wrappers) update independently of user data stored in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) and [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml). According to the [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/CLAUDE.md)** (Claude Code) – A full-featured wrapper that imports [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) and appends Claude-specific metadata for enhanced context handling.
- **[`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md)** (Codex) – A thin wrapper containing only the `@AGENTS.md` redirection line, enabling Codex to leverage CareerOps modes without native configuration.
- **[`OPENCODE.md`](https://github.com/santifer/career-ops/blob/main/OPENCODE.md)** (OpenCode) – Identical thin redirection structure to [`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md), pointing directly to the canonical specification.
- **[`GEMINI.md`](https://github.com/santifer/career-ops/blob/main/GEMINI.md)** (Gemini) – A legacy wrapper that redirects to [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/CODEX.md), [`CLAUDE.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/ARCHITECTURE.md) and the compatibility matrix in [`docs/SUPPORTED_CLIS.md`](https://github.com/santifer/career-ops/blob/main/docs/SUPPORTED_CLIS.md).

## Practical Usage Examples

### Running a Scan with Codex

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

```bash

# From the repository root

codex exec "career-ops scan"

```

The `codex` binary loads [`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md), which redirects to [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/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:

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

```

Claude Code reads [`CLAUDE.md`](https://github.com/santifer/career-ops/blob/main/CLAUDE.md), imports the full [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/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:

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

await runPrompt('career-ops pdf');

```

OpenCode loads [`OPENCODE.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/AGENTS.md), preventing configuration drift across CLIs.
- **Thin wrappers**: Files like [`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md) and [`OPENCODE.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/AGENTS.md)) and user profiles ([`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/CLAUDE.md), [`CODEX.md`](https://github.com/santifer/career-ops/blob/main/CODEX.md)) that redirect CLI drivers to the canonical [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/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`](https://github.com/santifer/career-ops/blob/main/CODEX.md) and [`GEMINI.md`](https://github.com/santifer/career-ops/blob/main/GEMINI.md) exist solely to point their respective CLIs to this central definition.