🛠️ Hands-on

The inematds/agente-claude-codex repo gathers scripts, prompts and the portable core template. You clone it once and run everything from inside it.

Without the kit you redo by hand what is already automated and tested on this machine (readback approved in Claude and Codex).

git clone https://github.com/inematds/agente-claude-codex, the scripts/, prompts/, template/ folders.

A read-only script that checks git, python3, node, Claude Code, Codex CLI (skills, config, sandbox, MCP), polyskill and the kit's own files. Each item comes out as [ok], [aviso] or [FALTA] with the command to fix it.

It answers "is my environment ready?" in seconds and exits with code 1 if something essential is missing, which makes automation possible.

scripts/doctor.sh, exit code, warning ≠ missing, without Claude or Codex the step becomes "not run".

Lists versions, skills, commands, subagents, hooks, plugins and MCP of both runtimes and writes a Markdown report to relatorios/auditoria-<data>.md.

It is step 2 of the mega-prompts (MODE: audit): you see what exists before deciding what migrates.

scripts/audit.sh, Claude → Codex gap, dated report, project × global separation.

The audit classifies by heuristic (grep) every skill that exists only in Claude: reusable (pure Markdown), adapter (depends on a Claude MCP or plugin), native (depends on a hook) or unresolved. On this machine: 72 / 15 / 2 / 1.

The matrix tells you where the effort is: 72 skills migrate without changes; the real blocker is the 15 MCPs, not the format.

Heuristic classification, review case by case, MCP as the bottleneck, subagents and plugins do not migrate.

On this host AppArmor restricts user namespaces and Codex's bwrap fails ("loopback: RTM_NEWADDR"). The readback that forced -s read-only broke; the minimal fix was to respect the sandbox_mode from config.toml.

You will run into this on any similar Linux machine; doctor.sh already warns about it and the failure is in FALHAS.md with the smallest fix.

bwrap, AppArmor, sandbox_mode = "danger-full-access", FALHAS.md (date, what broke, smallest fix, prompt or infra).

The report in relatorios/ is not the end: each line becomes a decision (port, adapt, leave as Claude residue) that feeds the phased migration plan.

Without turning the inventory into a plan you only have a pretty list; the source text insists that a file existing proves nothing.

Dated report, matrix → phases, passed / failed / not run, versioned evidence.

Publishing rules, commit author, where the keys live, semver versioning, artifact destination: all of that is text any agent understands.

It is most of your CLAUDE.md (71 of 78 lines in this machine's global one) and travels unchanged.

Stable rule, path, convention, AGENTS.md as the source.

Mentions of AskUserQuestion, superpowers, context-mode, claude-mem, fable-mindset, Artifact, advisor and hooks only make sense in Claude Code.

If that goes into AGENTS.md, Codex reads instructions it cannot follow and the noise grows.

Residue, plugin, hook, exclusive tool, 7 lines in the global file.

The script reads the project's CLAUDE.md and writes AGENTS.proposto.md and CLAUDE.proposto.md next to it, for review. Nothing existing is touched.

Reversible by construction: you review, rename, and only then does the project change.

scripts/adapt-instructions.sh ~/projetos/meu-projeto, --dry-run, .proposto.md.

The new CLAUDE.md starts with the line @AGENTS.md and only then brings the residue. Claude reads both; Codex reads only AGENTS.md.

One source of truth for the portable rules, with no diverging copy.

@ import, one source, residue kept separate, no duplication.

AGENTS.md opens with "read 1) this file, 2) context/overview.md, 3) context/current-state.md, 4) tasks/current.md, 5) handoffs/latest.md". Those names are a repo convention; they are not loaded on their own.

Prompt B is explicit: tell the agent what to read; do not assume auto-load.

Reading order, convention ≠ auto-load, small briefing at the start.

The script replaces every mention of "CLAUDE.md" with "AGENTS.md" in the portable part, including when the text is talking about another project's CLAUDE.md. That changes the meaning.

That is why the output is .proposto.md: human review catches this case.

Blind renaming, review references, sed is dumb, a human approves.

Copies template/ into the project file by file; if it already exists, it keeps it and reports [mantido]; if not, it creates it and reports [criado].

The first version of the kit used cp -r and overwrote README and CLAUDE.md; the fix was the "never overwrite" rule.

scripts/init-core.sh ~/projetos/meu-projeto, created, kept, reversible.

context/overview.md has a header (ID, scope, source, date, status, review by) and sections: what it is, verified facts, preferences, hypotheses.

Separating fact from hypothesis is what settles "which version is the right one" later.

ID, scope, source, observation date, status, fact × preference × hypothesis.

A file that says what is being done right now, who owns it, what the verifiable definition of done is and the concrete next action.

It is what makes the agent understand the current work, not just the history.

Goal, owner, definition of done, next action, blockers.

Each accepted decision becomes a dated file in context/decisions/ with context, decision and consequences. Status: proposed, accepted, revoked.

An accepted decision beats a timestamp: that is the plan's conflict rule.

Dated decision, status, provenance, never delete, revoke.

An 8-line check: the required files exist and are not empty. Exits 0 or 1.

A small, real check is worth more than a pretty structure nobody validates.

bash scripts/check.sh, [ok] / [FALTA], exit code.

Clone the project on its own into a clean folder and run the check. Prompt B requires it: essential context inside the project, without depending on ../../knowledge.

Proof of portability: if it depends on a parent folder, it is not portable.

Clean clone, no dependency on a parent folder, check passes, evidence.

On this machine, dsh-sandbox has 3 skills hand-copied from formato-curso-inema. Every edit at the source never reaches the copies: guaranteed drift.

Four consumers (Claude 117, Codex 27, dsh 3, openpcbotv3 16) without a single source drift on their own.

Drift, manual copy, canonical source, adapter at the edges.

scripts/sync-skills.sh import session-handoff reads ~/.claude/skills/session-handoff and writes skills/session-handoff/ in the portable format.

The skill stops being "Claude's" and becomes a neutral source.

polyskill import --from claude, definition.md, polyskill.yaml, extensions preserved or flagged.

scripts/sync-skills.sh build generates skills/*/dist/<runtime>/. With FORCE=1 it overwrites a hand-edited target.

The per-runtime copy is derived, never edited: edit the source and rebuild.

dist/, derived, --force, never edit a copy.

scripts/sync-skills.sh install session-handoff --both copies to ~/.claude/skills and ~/.codex/skills (and mirrors into ~/.agents/skills), making a .name.bak-<ts> backup if one already existed.

Installing is the only action that touches the runtimes' home; hence the backup first.

--both, --claude, --codex, backup alongside, ~/.agents/skills.

scripts/sync-skills.sh drift compares each dist/ with what is installed. Exits 1 if there is any difference.

It is the test that nobody edited the copy from outside; it goes into the acceptance criteria.

diff -rq, [ok], [DRIFT], [not installed], exit code.

The 15 "adapter" skills (heygen, magnific, printing-press…) reference MCP tools. In Codex they only work after registering the server with codex mcp add.

Porting before MCP produces a skill that does not run; order matters.

MCP in Codex, codex mcp add, keys referenced from .env, never copy the value.

Current goal and definition of done; one rule with the exact source file; last accepted decision; concrete next action; conflicts, stale facts or missing access. Separate what the files establish from what the agent infers.

It is prompt B's continuity test: did it find, read, understand, use?

Fresh-session readback, no prior conversation, cite the source, inference marked.

scripts/readback-test.sh ~/projetos/meu-projeto both runs both and saves the raw answer to relatorios/readback-<runtime>-<data>.md.

It automates the collection; the verdict is still yours.

claude -p, codex exec --skip-git-repo-check, report per runtime, config.toml sandbox.

Criterion: AGENTS.md, tasks/current.md and handoffs/latest.md show up cited and the "next action" matches the task.

Pretty prose without a citation is context hallucination; a citation is evidence.

File citation, next action matches, passed / failed.

In the first passing readback, Codex found a missing handoff, a wrong sum in the audit and a contradictory sentence in the plan. All fixed on the spot.

The readback does not just prove, it audits: a fresh agent reads without the bias of whoever wrote it.

Inconsistency, audit by fresh session, recorded fix.

Two real failures: forced sandbox (-s read-only) and the audit count. Each becomes one line: date, what broke, smallest fix, prompt or infra.

After about 10 lines the pattern shows up and you stop rebuilding what only needed a safeguard.

FALHAS.md, smallest fix, prompt × infra, one line per failure.

Passed: it cited the files and the action matches. Failed: it ran and did not cite. Not run: runtime missing, sandbox broke, or nobody ran it. No evidence counts as not run.

The source PDF admits it: no live test was done by the authors. Your readback is the first real evidence.

Three states, saved evidence, never "probably passed".

Project and scope, goal, accepted state, changed files, checks run with results, open questions, exact next action. No credentials, no "it's in another worktree".

A good handoff replaces rereading 2.3 GB of JSONL.

Decision, open item, next step, file path, no secrets.

The kit's template has 7 fixed sections. latest.md is always the most recent; older versions can stay in handoffs/YYYY-MM-DD.md.

A fixed structure is what lets another runtime (or another person) pick up without guessing.

latest.md, fixed sections, dated, one structure for all.

Prime is reading AGENTS.md → context → tasks → handoffs at the start. In Claude it becomes a skill; in Codex, an instruction in AGENTS.md; in dsh, a prime skill.

Without prime, the handoff is a file nobody reads.

Prime, reading order, skill × instruction, small briefing.

The final test: a handoff written in a Claude session, picked up in a fresh Codex session, and vice versa, in a real project.

That is the definition of done for the whole system.

Cross handoff, same Markdown, interchangeable executors.

On this machine: 6,859 Claude sessions (2.3 GB) and 209 Codex sessions. Once the cycle is running, archive those older than 90 days.

Raw memory is raw material; what counts is what got promoted to an overview or a handoff.

JSONL, archive, promote a fact, raw material × source.

No session ends without handoffs/latest.md and tasks/current.md updated. The next day's readback is the check.

It is the only discipline that makes switching models painless.

End of session, update two files, readback as audit.