← All writing
Writing

Portable Agent Ops reduces coding harness switching cost

By David PaluyAI & Agents

Switching AI coding harnesses feels expensive, and most people blame the model. Wrong culprit. What actually costs you the week or two of pain is trust: every time you move from Codex or Claude Code to OpenCode, Pi, Cursor, or Antigravity, you start over proving the tool loads the right rules, runs the right tests, and stays out of the files it shouldn't touch.

So stop keeping trust inside the harness. Put your working agreements, skills, permissions, and evals in a portable Agent Ops layer, and each harness becomes a client of the same operating system instead of the home of your workflow.

This won't make migration free. Every model and harness has quirks, and some of them only show up under load. But it changes the warm-up from "rebuild confidence from scratch" to "run the certification suite and read the failures." That's a much shorter loop.

The portable layer is six pieces:

  1. AGENTS.md as the repo-level operating manual.
  2. Tool-specific shims (CLAUDE.md, Cursor rules, OpenCode config, Pi config) that adapt to the same source of truth instead of redefining behavior.
  3. Shared skills, prompts, and plans for repeated workflows.
  4. MCP or tool wrappers for external systems.
  5. Permission policy and smoke tests that live outside any one harness.
  6. A migration eval pack that tells you whether a new harness is ready for real work.

Key findings

1. AGENTS.md is becoming the portable instruction layer

The official AGENTS.md site treats the file as a README for coding agents: build steps, tests, conventions, security constraints, and the agent-focused context that has no business in the human README. One AGENTS.md, many tools. The site names Codex, Pi, Jules, Aider, OpenCode, Zed, Warp, VS Code, Devin, Cursor, RooCode, Gemini CLI, and GitHub Copilot coding agent, among others.

Source: https://agents.md

Practical implication:

  • Use AGENTS.md as canonical.
  • Put stable project behavior there: commands, test policy, do-not-touch zones, definitions of done, review gates, naming and conventions.
  • Use nested AGENTS.md files for monorepos or subsystems where local rules differ.
  • Keep it short enough to load reliably, and push long procedures into skills and plans.

2. Codex reads AGENTS.md natively

OpenAI's Codex docs say Codex reads AGENTS.md before it starts work. It builds an instruction chain from a global ~/.codex/AGENTS.md or override files, then walks from the repo root down to your current directory. Files closer to where you're working land later and override the broader guidance. The default project doc cap is 32 KiB, and you can change it with project_doc_max_bytes.

Source: https://developers.openai.com/codex/guides/agents-md

Practical implication:

  • Codex makes a good reference implementation for the portable layer.
  • Global defaults: ~/.codex/AGENTS.md.
  • Repo rules: AGENTS.md.
  • Subsystem rules: nested AGENTS.md or AGENTS.override.md.
  • Smoke-test it: codex --ask-for-approval never "Summarize the current instructions."

3. OpenCode supports AGENTS.md, Claude fallback, project agents, and config layering

OpenCode's /init creates or updates an AGENTS.md by scanning the repo and focusing on commands, verification steps, architecture, conventions, setup quirks, and pointers to whatever instruction sources already exist. No AGENTS.md? It falls back to CLAUDE.md, and it reads ~/.claude/skills/ too.

Config is layered all the way down: remote org defaults, global config, custom config, project opencode.json, .opencode directories, inline config, and managed settings. Agents are just markdown files, project or global, each with its own model, tool, and permission access.

Sources:

Practical implication:

  • OpenCode works well as a portability testbed.
  • Use project AGENTS.md for canonical behavior.
  • Use .opencode/agents/*.md for role adapters: explorer, reviewer, worker.
  • Keep permissions in config, not in prose.

4. Pi is the interesting one for context-engineering portability

Pi bills itself as a minimal terminal coding harness, and that minimalism is the point. It loads AGENTS.md from ~/.pi/agent/, the parent directories, and the current directory, with CLAUDE.md as a fallback. On top of that it exposes SYSTEM.md or APPEND_SYSTEM.md, skills, prompt templates, extensions, dynamic context injection, custom compaction, and MCP adapters.

Sources:

Practical implication:

  • Reach for Pi as an experimentation harness, not as your daily driver.
  • Its value is that it pulls apart model, system prompt, context policy, skills, and tools, so you can see each one.
  • If the portable layer holds up in Pi, it probably isn't secretly welded to Codex or Claude.

5. Claude Code is powerful, and more proprietary unless you bridge it on purpose

Claude Code separates persistent instruction files (CLAUDE.md) from skills and auto memory. CLAUDE.md carries the stable guidance; skills carry task-specific procedures that load only when relevant. The docs are blunt about one thing: Claude reads CLAUDE.md, not AGENTS.md, and if your repo already uses AGENTS.md, you should write a CLAUDE.md that imports it.

Sources:

Practical implication:

  • Don't maintain independent CLAUDE.md content if portability matters.
  • Make CLAUDE.md a shim: "Read and follow AGENTS.md; Claude-specific notes below."
  • Keep Claude-only skills only when they genuinely need Claude-specific affordances.

6. Cursor gives you both .cursor/rules and AGENTS.md

Cursor rules provide persistent, reusable context for Agent and Inline Edit. Project rules live in .cursor/rules, can be scoped by path pattern, invoked by hand, or pulled in when relevant. Cursor also reads AGENTS.md as a simpler markdown alternative, nested files included.

Source: https://docs.cursor.com/en/context/rules

Practical implication:

  • For portability, use AGENTS.md as the shared baseline.
  • Reserve .cursor/rules for what AGENTS.md can't express: glob-scoped or manually invoked rule metadata.
  • Don't duplicate the same rules in both places. Pick one home per rule.

Proposed architecture: Portable Agent Ops

Repository:

AGENTS.md                    # canonical, portable operating manual
CLAUDE.md                    # shim: imports/points to AGENTS.md + Claude-only notes
.cursor/rules/               # Cursor-only scoped rules, if needed
.opencode/agents/            # OpenCode role adapters, if needed
.pi/                         # Pi project config/prompts/agents, if needed
.agents/skills/              # portable skills, if supported by target harnesses
.agents/plans/               # reusable execution plans / migration playbooks
.agent-evals/                # harness certification tests
scripts/agent-smoke/         # shellable smoke tasks

Global and user:

~/.codex/AGENTS.md           # general coding-agent preferences
~/.config/opencode/AGENTS.md # OpenCode global shim or symlink/managed copy
~/.pi/agent/AGENTS.md        # Pi global shim or symlink/managed copy
~/.claude/CLAUDE.md          # Claude global shim pointing to canonical content

The policy holds it together:

  • Repo rules live in AGENTS.md.
  • Harness configs only adapt loading, permissions, tools, and model routing. Nothing else.
  • Repeated workflows become skills.
  • Large multi-step workflows become plans.
  • Trust comes from an eval pack, not vibes.

Migration playbook

  1. Inventory the harness you're on now:
    • instruction files
    • global rules
    • project rules
    • skills and commands
    • MCP and tool integrations
    • permission behavior
    • the prompts you keep retyping
  2. Normalize into portable layers:
    • project rules to AGENTS.md
    • repeated procedures to .agents/skills/
    • multi-step flows to .agents/plans/
    • external systems to MCP and tool wrappers
    • safety rules to permission config and CI/pre-commit, not just prose
  3. Build the harness shims:
    • Codex: native AGENTS.md plus ~/.codex/config.toml
    • Claude: CLAUDE.md shim plus .claude/settings.json, skills only where needed
    • Cursor: AGENTS.md baseline plus .cursor/rules for scoped metadata behavior
    • OpenCode: AGENTS.md plus .opencode/agents/*.md plus opencode.json
    • Pi: AGENTS.md plus .pi/SYSTEM.md, skills, and extensions where useful
  4. Write a certification suite:
    • "summarize loaded instructions" prompt
    • read-only repo orientation task
    • small bugfix task
    • failing-test triage task
    • refactor-with-no-behavior-change task
    • docs and editing task
    • rollback / do-not-touch safety test
    • a non-code writing task, if you expect the harness to do that too
  5. Score what came back:
    • Did it load the right instructions?
    • Did it ask too often, or not enough?
    • Did it run the right tests?
    • Did it respect boundaries?
    • Did it preserve style?
    • Were the diffs clean?
    • How much did you have to steer it?

One honest caveat: this layer is only as portable as your least cooperative harness. If a tool ignores AGENTS.md and buries behavior in a proprietary format, you'll still maintain a real shim there, not a one-liner. The eval pack is what tells you which tools those are before you commit.

The bottom line

Don't just pencil in two or three weeks for a harness switch. Build the portable layer first:

  1. Canonical AGENTS.md.
  2. Thin per-harness shims.
  3. Portable skills and plans.
  4. Shared MCP and tool integrations.
  5. Permission policy outside prose.
  6. A certification suite for new harnesses.

Then make any new harness earn your trust against the suite before you give it real work.

Sources

Codex specifics: the Codex CLI config.toml Guide 2026 for the current configuration surface, the earlier Codex CLI Developer Guide for the 0.42.0 command set, and Codex is becoming a workspace, not a chatbot for where the product is heading.

Keep thinking with us

Practical AI ideas, delivered where you already are.

Get occasional field notes on choosing models, building useful AI workflows, and making better decisions with the tools.

Prefer a messaging app?

Telegram and WhatsApp are broadcast-only and carry the same posts. Pick the app you prefer.

Telegram WhatsApp