6.1 Two agents, one project

🎯What you get here

A real, tested workflow from someone who works with both agents. You’ll learn how to configure a VS Code setup, pass context between them in 30 seconds, divide work without getting in each other’s way, and prepare for new runtimes to arrive.

Detailed content

📋 Session handoff — the standardized summary

A short, structured summary you ask the current agent for BEFORE handing things off to the other one. This is the feature that unlocks a dual workflow. Without it, you keep re-explaining context. With it, you have a cheat sheet and can move on.

Handoff template (5 sections)

# Session handoff — 2026-05-24 16:30

## 🎯 Foco atual
Implementar autenticação OAuth no /api/auth com Google.

## 📂 Arquivos tocados (com estado)
- src/api/auth.ts          ← parcial, falta validação JWT
- src/api/auth.test.ts     ← testes do happy path passando
- prisma/schema.prisma     ← adicionou model OAuthAccount

## ✅ Decisões tomadas
- Usar passport.js (não auth0)
- JWT em cookie httpOnly (não localStorage)
- Refresh token rotacionando a cada 1h

## 🚧 Problema aberto
JWT verification falhando com "jwt malformed" no payload de teste.
Tentei 3 abordagens (recriar token, mudar secret, verificar
cookie parse) sem sucesso. Provável bug na lib ou no setup do test.

## ⏭ Próximos passos
1. Investigar setup do test (jest mock do passport?)
2. Se persistir, trocar passport por jose lib
3. Implementar refresh endpoint
4. Cobertura de erro paths

✓ Good handoff

• Short (fits on one page)
• Fixed structure (5 sections)
• List of files WITH status
• Explicit decisions (not obvious from the code)
• Current problem with previous attempts

✗ Useless handoff

• "I'm working on feature X" (vague)
• 20 pages of context (no one reads them)
• No current problem (doesn't know what to do)
• Decisions you can read from the code (redundant)
• No next step

💡Becomes a skill

Perfect candidate for a skill session-handoff in both runtimes (written once via polyskill). You run /session-handoff or $session-handoff, gets the completed template ready to paste into the other agent.

Key concepts

5 fixed sections
Focus, files, etc.

Candidate skill
Standardizes

Short > complete
Single page

Current problem
+ attempts

🖥️ Two terminals, one project — VS Code setup

Practical setup that works: VS Code open in the project, two terminal panes — one running claude, another running codex. Same filesystem, same git, same docs. You switch panels with a shortcut.

VS Code ASCII layout

┌──────────────────────────────────────────────────────────────────┐
│ Explorer │  src/api/auth.ts                                       │
│          │  ──────────────────────────────────────                │
│ ▾ src    │  export async function login(req, res) {               │
│   api    │    // implementação aqui                               │
│   ui     │    ...                                                 │
│ ▸ tests  │  }                                                     │
│          │                                                        │
│          ├────────────────────────────┬───────────────────────────┤
│          │ TERMINAL 1: claude         │ TERMINAL 2: codex         │
│          │ > refatorando auth.ts      │ > escrevendo testes       │
│          │ [Claude pensa…]            │ [Codex pensa…]            │
│          │                            │                           │
└──────────┴────────────────────────────┴───────────────────────────┘

⌨️

Terminal split

Ctrl+Shift+5 (VS Code) splits the panel. Each half runs an agent.

🎨

Profile per agent

Create 2 terminal profiles in VS Code: "Claude" and "Codex". Different colors, agent auto-start.

⚡

focus shortcut

Ctrl+Shift+` focuses the terminal. Use the arrow keys to navigate between panels without a mouse.

Ideal workspace settings

// .vscode/settings.json
{
  "terminal.integrated.profiles.osx": {
    "Claude Code": {
      "path": "/bin/zsh",
      "args": ["-c", "claude"],
      "color": "terminal.ansiBlue"
    },
    "OpenAI Codex": {
      "path": "/bin/zsh",
      "args": ["-c", "codex"],
      "color": "terminal.ansiMagenta"
    }
  },
  "files.watcherExclude": {
    "**/.claude/**": false,
    "**/.codex/**": false,
    "**/.agents/**": false
  }
}

Key concepts

Terminal split
Side-by-side panels

Colorful profile
Visual distinction

focus shortcuts
No mouse

Repo settings
.vscode/ in git

⚠️ Avoiding conflicts — when both edit

If both agents edit the same file at the same time, one overrides the other. It’s the #1 way to lose work with a dual workflow. The solution is simple discipline: split by area or phase.

📂 Division by area

Each agent works in different folders:

Claude   → src/api/    (backend)
Codex    → src/ui/     (frontend)

No overlap, no conflicts. Simpler.

⚙️ Division by phase

Same area, different phases:

Claude   → implementa src/x.ts
Codex    → escreve testes/x.test.ts

Coordinates: implementation done? Tell Codex to run a test.

Advanced strategies

Git branch per agent: claude works in feat/x-impl, codex in feat/x-test. Merge later.

Manual lock via comment: whoever gets there first adds it // LOCKED by claude — 16:30 at the top. Someone else sees it and respects it.

git stash between switches: before switching agents, stash any partial work. The other agent works in a clean state.

⚠️The scenario to avoid

Two agents editing src/api/auth.ts in parallel. Claude finishes and writes. Codex finishes 30s later and writes over it—Claude’s work is lost. You discover at the next commit that half the changes are missing. 1–2 hours of drama to reconstruct it.

Key concepts

Division by area
Simpler

Division by phase
Implementation vs. test

Branch per agent
Advanced

Last-write-wins
Loses work

🔌 Shared MCP servers

MCP servers run as independent processes. Configured once, both agents connect to the same. The server isn’t duplicated—only the declaration on the client (JSON for Claude, TOML for Codex).

Mirrored configuration

# Claude: .mcp.json (no projeto)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@mcp/github"],
      "env": { "TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

# Codex: .codex/config.toml (no projeto)
[mcp_servers.github]
command = "npx"
args = ["-y", "@mcp/github"]

[mcp_servers.github.env]
TOKEN = "${GITHUB_TOKEN}"

# Resultado:
# Os dois agentes apontam pro MESMO server (mesmo binário,
# mesmas credenciais, mesmas ferramentas expostas).

🔧

Independent server

MCP server is a process. It starts when called and stays available. It doesn't matter who called it.

🔑

Centralized env

Use .env shared. The GitHub token is in one place — both clients read it.

🛡️

Allowlist by runtime

Each client can have a different allowlist. Codex allows everything, Claude allows read-only access. OK.

💡Maintenance

A skill that needs a specific MCP? Declare it in openai.yaml sidecar for Codex AND in the frontmatter or doc for Claude. Polyskill handles this automatically when building.

Key concepts

Single server
Doesn't duplicate

central .env
Credentials once

2x declaration
JSON + TOML

Independent allowlist
By client

🪝 Hooks shared via script

Hooks are shell commands. Put the logic in scripts/check.sh in the project, both runtimes point to this script. Maintenance in one place—edit the script, and both agents follow it.

Recommended standard

# scripts/lint-on-edit.sh — lógica central
#!/bin/bash
set -e

CHANGED_FILE="$1"  # passado pelo hook

if [[ "$CHANGED_FILE" == *.ts ]]; then
  npx tsc --noEmit "$CHANGED_FILE"
  npx eslint "$CHANGED_FILE"
fi

if [[ "$CHANGED_FILE" == *.py ]]; then
  ruff check "$CHANGED_FILE"
fi

# .claude/settings.json — declara o hook
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "./scripts/lint-on-edit.sh ${file}"
      }]
    }]
  }
}

# .codex/config.toml — mesma coisa
[[hooks]]
event = "post_tool_use"
matcher = "edit"
command = "./scripts/lint-on-edit.sh ${file}"

✓ Logic in the script

• Update the script → applies to both
• Script can be tested outside the agent
• Versioned alongside the code
• Can also be used in CI/pre-commit

✗ Inline logic in hooks

• Duplicates regex/commands across both runtimes
• Forgets to update one side
• Hard to test in isolation
• Can't be reused outside hooks

💡Git pre-commit hook too

Put scripts/lint-on-edit.sh no .git/hooks/pre-commit (or via husky). The same logic applies to both agents and manual commits. Triple guarantee.

Key concepts

Shared script
Core logic

Hook = wrapper
Only calls a script

Exit 0/1
Pass/block

Reuse in CI
Same script

📊 Governance — when to use which

Set of rules for choosing an agent by task type. Without a written rule, choices come down to unstable intuition. With a rule, new team members have a standard to follow.

Rule of thumb (real example)

Write in CLAUDE.md/AGENTS.md

Put the rule in the project manual. Everyone on the team sees it.

🔬

Periodic A/B testing

Every 2–3 months, redo a task in both. Calibrate the rule.

🎲

"Grab the idle one"

When it's a tie, use whichever has less context loaded.

💡Quarterly review

Models are updated all the time. What was one model’s strength may be another model’s strength 3 months later. Schedule a review of the rule of thumb every quarter. Without a review, the rule becomes a myth.

Key concepts

Written rule
Time consultation

A/B test
Calibrates

Default + backup
Always an alternative

Quarterly
Fixed review

🚀 Next runtimes — preparing for the future

The ecosystem doesn't stop at Claude+Codex. Gemini CLI, Cursor, Copilot, JetBrains AI Assistant are on the polyskill roadmap. Your cross-runtime skills are already ready—all that’s missing is the adapter.

Polyskill roadmap

✓

Claude Code — complete adapter, production-ready

✓

OpenAI Codex — complete adapter, production-ready

✓

Portable — canonical source

🔜

Gemini CLI — under discussion, waiting for a stable spec

🔜

Cursor — under discussion

🔜

GitHub Copilot — under discussion

🔜

JetBrains AI Assistant — under discussion

How to contribute a new adapter

Repo fork inematds/pollyskill
Create a new file in src/adapters/<nome>.ts implementing an interface Adapter (parse, emit, validate)
Register in src/adapters/index.ts: register(new SeuAdapter());
Add an example in examples/<nome>-example/ with round-trip
Open a PR with a tag new-adapter

Community — Early AI Dopters

The patterns behind polyskill, updates as new runtimes gain adapters, and a working group of builders shipping cross-runtime tools — all of this lives at:

skool.com/earlyaidopters/about

🦜The investment that lasts

Every skill you write in the portable format is future-proof. When Gemini gets an adapter, your skill works there on day 1. When Cursor does? Same thing. When “Claude 5 Code” comes along? Same thing. You don't rewrite it.

Key concepts

Via PR adapter
Standard contribution

Future-proof skill
Investment lasts

Community
Early AI Dopters

parse+emit+validate
Single slash

🎯Module summary

✓

Session handoff in 5 sections — becomes a skill, standardizes the transition.

✓

Two terminals in VS Code with colored profiles — focus shortcut, committed settings.

✓

Avoid overlap: by area OR by phase — simple discipline, zero lost work.

✓

Shared MCP server, declaration 2× — central credentials (.env).

✓

Hooks call a central script — reusable in CI/pre-commit too.

✓

Governance = written rule of thumb + quarterly review — no myths.

✓

Gemini/Cursor/Copilot are coming — portable skills are ready.

🏁 Course complete!

You completed all 6 paths. Now you know the anatomy of both runtimes, how to migrate, how to write cross-runtime skills with polyskill, and how to work with both day to day.

← Back to Track 6 🏁 Course landing page