Personal AI coding assistant configuration for Python/ML OSS development. Version-controlled, opinionated, continuously improved.

borda.local/
├── .claude/                # Claude Code (Claude by Anthropic)
│   ├── CLAUDE.md           # workflow rules and core principles
│   ├── settings.json       # permissions and model preferences
│   ├── agents/             # specialist agents
│   ├── skills/             # workflow skills (slash commands)
│   └── hooks/              # UI extensions
├── .codex/                 # OpenAI Codex CLI
│   ├── AGENTS.md           # global instructions and subagent spawn rules
│   ├── config.toml         # multi-agent config (gpt-5.3-codex baseline)
│   └── agents/             # per-agent model and instruction overrides
├── .pre-commit-config.yaml
├── .gitignore
└── README.md

Agents and skills for Claude Code (Anthropic's AI coding CLI).

Specialist roles with deep domain knowledge. You can request a specific agent by name in your prompt (e.g., "use the qa-specialist to write tests for this module"). Claude Code also selects agents automatically when spawning subagents via the Task tool.

Skills are orchestrations of agents — invoked via slash commands (/review, /develop fix, etc.). A single skill typically composes multiple agents in parallel and consolidates their output. Think of agents as specialists you can talk to, and skills as predefined workflows that coordinate them.

Skills chain naturally — the output of one becomes the input for the next.

/analyse 42            # understand the issue, extract root cause hypotheses
/develop fix 42        # reproduce with test, apply targeted fix
/review                # validate the fix meets quality standards

/optimize src/mypackage/dataloader.py   # profile and fix top bottleneck
/develop refactor src/mypackage/dataloader.py "extract caching layer"  # structural improvement
/review                                 # full quality pass on changes

/review 55             # 7 agent dimensions + Codex co-review
/develop fix "race condition in cache invalidation"  # fix blocking issue from review
/review 55             # re-review after fix

/analyse 87            # understand the issue, clarify acceptance criteria
/develop feature 87    # codebase analysis, demo test, TDD, docs, review
/release               # generate CHANGELOG entry and release notes

/survey "efficient attention for long sequences"  # find SOTA methods
/develop feature "implement FlashAttention in encoder"    # TDD-first implementation
/review                                           # validate implementation

/research plan "increase test coverage to 90%"   # interactive config wizard
/research "increase test coverage to 90%"        # run 20-iteration loop; auto-rollback on regression
/research resume                                  # resume after crash or manual stop
/review                                           # validate kept commits

/survey "knowledge distillation for small models"   # find best approach
/research plan "improve F1 from 0.82 to 0.87"       # configure metric + guard + agent
/research "improve F1 from 0.82 to 0.87" --team     # parallel exploration across axes
/review                                              # quality pass on kept changes

/observe               # analyze work patterns, suggest new agents/skills
/manage create agent security-auditor "..."  # scaffold suggested agent
/audit                 # verify config integrity — catch broken refs, dead loops
/calibrate routing     # confirm new agent description doesn't confuse routing
/sync apply            # propagate clean config to ~/.claude/

/codex "add Google-style docstrings to all undocumented public functions" "src/mypackage/"
# Codex executes; Claude validates with lint + tests
/review                                   # full quality pass on Codex output

/resolve 42   # auto-detect conflicts → resolve semantically → apply review comments via Codex
/review       # full quality pass on all applied changes

/analyse 42 --reply      # assess PR readiness + draft contributor reply in one step
                          # reuses today's analysis if no new activity since last run

# or if you need the full deep review first:
/review 42 --reply        # 7-agent + Codex co-review + draft overall comment + inline comments table
                          # output: tasks/output-reply-pr-42-<date>.md

# post when ready:
gh pr comment 42 --body "$(cat tasks/output-reply-pr-42-<date>.md)"

/observe                        # analyze work patterns, surface what agents are missing or miscalibrated
/calibrate all fast ab apply    # benchmark all agents vs general-purpose baseline, apply improvement proposals
/audit fix                      # structural sweep after calibrate changed instruction files
/sync apply                     # propagate improved config to ~/.claude/

/audit                      # Check 12 flags description overlap pairs (static, fast)
/calibrate routing fast     # behavioral test: generates task prompts, measures routing accuracy includes confusion matrix + description improvement proposals

/audit                 # inspect findings + docs-sourced upgrade proposals — report only, no changes
/audit upgrade         # apply upgrade proposals: config changes verified, capability changes A/B tested
/audit fix             # full sweep + auto-fix critical and high findings
/sync apply            # propagate verified config to ~/.claude/

/audit                 # fetches latest Claude Code docs, surfaces applicable improvements as upgrade proposals
/audit upgrade         # applies config proposals (correctness check) and capability proposals (calibrate A/B)
/calibrate all fast    # re-benchmark all agents to confirm no regression from applied changes
/sync apply            # propagate clean, calibrated config to ~/.claude/

/release v1.2.0..HEAD  # generate release notes from git history

Claude Code's experimental Agent Teams feature is enabled. Teams are always user-invoked — nothing auto-spawns. You use /develop fix --team, /develop feature --team, etc. explicitly.

Enable: Already active via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json.

Model tiering: Lead uses opusplan/opus. Deep reasoning teammates (sw-engineer, qa-specialist, ai-researcher, perf-optimizer) use opus. Execution teammates (doc-scribe, linting-expert, ci-guardian) use sonnet. Keep teams to 3–5 teammates (~7× token cost vs single session).

Communication protocol: Inter-agent messages use the AgentSpeak v2 compressed syntax defined in .claude/TEAM_PROTOCOL.md (~60% token savings vs natural language). Lead-to-human communication uses normal English.

Security in teams: No standalone security agent. qa-specialist automatically embeds OWASP Top 10 security checks when operating as a teammate on code touching auth, payment flows, or user data.

Quality hooks: hooks/teammate-quality.js handles TeammateIdle (redirects to pending tasks if any exist) and TaskCompleted (reserved for future quality gates).

A lightweight hook (hooks/statusline.js) adds a persistent multi-row status bar to every Claude Code session:

Row 1:  claude-sonnet-4-6 │ Borda.local │ Pro ~$1.20 │ ████░░░░░░ 38%
Row 2:  🕵 5 agents (self-mentor ×3, opus, sw-engineer) │ 🤖 codex ×2 │ 🔧 Bash ×3 · Edit · Read ×12

Row 1 shows the active model name, current project directory, billing indicator, and a 10-segment context usage bar (green → yellow → red). Row 2 combines agent count, Codex sessions, and active tools — always visible (shows none when idle).

Agent row — groups running agents by display name, then appends active Codex sessions:

• Specialized agents (have a .claude/agents/ file) → shown by type name in their declared color: from frontmatter (e.g. sw-engineer in blue, self-mentor in pink)
• General-purpose agents or agents without a pinned model → shown by model name in gray (e.g. opus, sonnet)
• Agents of the same type are grouped with a ×N count
• Codex sessions — appended after agents as codex ×N in yellow when /codex is running (tracked via PreToolUse/PostToolUse hooks on both Skill and Bash paths; covers /codex, /resolve, and any direct codex exec or timeout N codex … Bash call)

Tool row — shows tools called in the last 30 seconds, each in a unique fixed color: Read (blue) · Write (bright green) · Edit (green) · Bash (yellow) · Grep (cyan) · Glob (bright cyan) · WebFetch (magenta) · WebSearch (bright magenta) · Task/Agent (bright blue) · Skill (bright yellow)

The agent row is powered by hooks/task-log.js, which handles: SubagentStart/SubagentStop (one file per active agent in .claude/state/agents/<id>.json), PreToolUse/PostToolUse (audit log + tool activity state in .claude/state/tools/<tool>.json; Codex session lifecycle in .claude/state/codex/<id>.json), PreCompact (context snapshot in .claude/state/session-context.md), and Stop/SessionEnd (clear all state so the status line resets cleanly). A 10-minute safety-net age-out handles crashed or hung agents; a 30-minute cutoff handles stalled Codex sessions.

Configured via statusLine in settings.json. Zero external dependencies — stdlib path and fs only.

This repo is the source of truth for all .claude/ configuration. Home (~/.claude/) is a downstream copy kept in sync via the /sync skill.

Borda.local/.claude/   →   ~/.claude/
  agents/                    agents/
  skills/                    skills/
  hooks/statusline.js        hooks/statusline.js
  settings.json              settings.json  (statusLine path rewritten to absolute)

One file is intentionally not synced: settings.local.json (machine-local overrides). CLAUDE.md is synced as part of the standard propagation.

Workflow:

/sync          # dry-run: show drift report (MISSING / DIFFERS / IDENTICAL per file)
/sync apply    # apply: copy all differing files and verify outcome

Run /sync after editing any agent, skill, hook, or settings.json in this repo to propagate the change to the home config.

Claude and Codex complement each other — Claude handles long-horizon reasoning, orchestration, and judgment calls; Codex handles focused, mechanical in-repo coding tasks with direct shell access.

Every skill that reviews or validates code uses a three-tier pipeline, where cheaper tiers gate the expensive ones:

† For /review, Codex runs as a full co-reviewer alongside Tier 2 agents (not as a gate before them) — its findings are independently consolidated rather than seeding the agent prompts.

Why unbiased review matters / Real example: Claude makes targeted changes with intentionality — it has a mental model of which files are "in scope" for a task. Codex has no such context: it reads the diff and the codebase independently. During one session, Claude applied a docstring-style mandate across 6 files, reported the work done, and scored its own confidence at 0.88. The Codex pre-pass then found skills/develop/modes/feature.md still referencing the old style — a direct miss from the batch fix. That file simply wasn't on Claude's mental scope list, so it was never checked. The union of both passes is more complete than either alone.

1. Offloading mechanical tasks from Claude to Codex

   Claude identifies what needs to change (rename a symbol, fill in docstrings, add type annotations across a module) and delegates execution to Codex. Claude keeps its context clean and validates the output.

   # Claude orchestrates, Codex executes
   /codex "add Google-style docstrings to all undocumented public functions" "src/mypackage/"
   /codex "rename BatchLoader to DataBatcher throughout the package" "src/mypackage/"
   /codex "add return type annotations to all functions missing them" "src/mypackage/utils.py"
   # Claude then reviews with lint + tests
   /review

2. Codex reviewing staged work

   After Claude (or you) stages changes, Codex can serve as a second pass — examining the diff, applying review comments, or resolving PR conflicts. The /resolve skill automates this: it resolves conflicts semantically (Claude) then applies review comments (Codex).

   # Stage changes, then let Codex process review feedback
   /resolve 42   # Claude resolves conflicts → Codex applies review comments
   /resolve "rename the `fit` method to `train` throughout the module"  # single-comment fast path

# Install Claude Code (if not already)
npm install -g @anthropic-ai/claude-code

# Install Codex CLI
npm install -g @openai/codex    # npm show @openai/codex version for latest

# Verify
which claude && which codex

Multi-agent configuration for OpenAI Codex CLI (Rust implementation). Where Claude Code excels at long-horizon planning and research, Codex CLI is optimized for focused, in-repo agentic coding — running shell commands, editing files, and spawning parallel sub-agents directly in your terminal.

Nine specialist roles wired into the multi-agent system. Codex can spawn them autonomously based on task type (see AGENTS.md for the full spawn-rule matrix) or you can address them by name in your prompt.

All agents in this repo are configured to use gpt-5.3-codex. Differentiation is via reasoning effort:

• xhigh — adversarial roles (qa-specialist, security-auditor): exhaustive search for what could go wrong
• high — analytical roles (sw-engineer, squeezer, data-steward, oss-maintainer): depth without unbounded budget
• medium — writing/config roles (doc-scribe, ci-guardian, linting-expert): quality over deductive intensity

# Interactive session — Codex selects agents automatically
codex

# Address a specific agent by name in your prompt
codex "use the security-auditor to review src/api/auth.py"
codex "spawn data-steward to validate the train/val split in data/splits/"

# Parallel fan-out (Codex orchestrates automatically per AGENTS.md rules)
# e.g. after sw-engineer finishes → qa-specialist + doc-scribe run concurrently

This repo is the authoring location. To activate globally, copy the entire .codex/ directory to ~/.codex/:

cp -r .codex/ ~/.codex/

config_file paths in config.toml are relative to that file — no substitution needed. The AGENTS.md at ~/.codex/AGENTS.md is read by Codex for every project; a project-local AGENTS.md at the repo root extends it.

• Agents are roles, skills are workflows — agents carry domain expertise, skills orchestrate multi-step processes
• No duplication — agents reference each other instead of repeating content (e.g., sw-engineer references linting-expert for config)
• Profile-first, measure-last — performance skills always bracket changes with measurements
• Link integrity — never cite a URL without fetching it first (enforced in all research agents)
• Python 3.10+ baseline — all configs target py310 minimum (3.9 EOL was Oct 2025)
• Modern toolchain — uv, ruff, mypy, pytest, GitHub Actions with trusted publishing

This setup is optimized for maintaining Python/ML OSS projects in the PyTorch ecosystem:

• Libraries with public APIs requiring SemVer discipline and deprecation cycles
• ML training and inference codebases needing GPU profiling and data pipeline validation
• Multi-contributor projects with CI/CD, pre-commit hooks, and automated releases