Claude Code
~/.claude
( Agentic operating system )
One harness, provider-aware execution.
Codex is my current primary production environment inside a provider-aware operating system. Claude Code and OpenCode remain compatible runtimes, while shared instruction contracts, skills, state, phase gates, and feedback loops keep the engineering method portable. The linker parses locally in your browser; nothing leaves the tab.
Three runtimes, one contract.
( Runtimes )
Claude Code
~/.claude
A compatible runtime used selectively for implementation, review, and existing workflow support.
- agents/
- Subagent definitions — markdown with frontmatter: name, description, model tier.
- skills/
- Packaged procedures, one SKILL.md per skill — the installable unit of capability.
- commands/
- Slash commands as plain markdown; the filename is the command name.
- settings.json
- Hooks, permission rules, env — mechanical enforcement. Rendered as counts, never contents.
- plugins/
- The installed-plugin registry — exactly one file read: installed_plugins.json.
- projects/
- Per-project session transcripts and plans. Counted by entry, never opened.
Codex
~/.codex
The current primary production environment for planning, implementation, orchestration, and verification.
- config.toml
- The single config surface — model, reasoning effort, MCP servers, trusted projects, plugin toggles.
- skills/
- The same SKILL.md convention as Claude Code — skills port across runtimes.
- prompts/
- Reusable prompt files in markdown — optional; present once custom prompts are saved.
- rules/
- Standing rule files applied across every session.
- hooks.json
- Hook definitions — rendered as a count, never the command strings.
- sessions/
- Session transcripts. Counted by entry, never opened.
OpenCode
~/.config/opencode
The lightweight third runtime — quick tasks on a lean plan, same harness underneath.
- opencode.jsonc
- One JSONC config: plugins, MCP servers, model selection. Comments and trailing commas are part of the format.
- skills/
- The shared SKILL.md packaging a third time — three runtimes, one convention.
- agent/ + command/
- Optional markdown directories for custom agents and commands, mirroring Claude Code's layout.
- package.json
- Plugins are npm dependencies — dependency names only are read.
The OS, mapped.
( Architecture )
- Kernel
- Instruction contracts — AGENTS.md / CLAUDE.md
- The Instructions subsystem: rules, constraints, definitions of done, and the reading order every fresh session boots from. When the kernel and anything else disagree, the kernel wins.
- Processes
- Agents and subagents
- Focused workers dispatched with a narrow scope and a fresh context window, each in its own worktree — the Environment subsystem is the process's address space. The scheduling law: writes stay single-threaded, reads fan out.
- Syscalls
- Tools
- The Tools subsystem — commands, scripts, and MCP tools are the only interface an agent has to the world. Tool descriptions are public API contracts; a bad one degrades the agent in ways that look like model failure.
- Daemons
- Hooks
- Background enforcement outside the context window. A hook that blocks an operation is a guarantee; an instruction in a context file is advice that competes with everything else and loses under pressure.
- Packages
- Skills and plugins
- Versioned, installable capability — one SKILL.md per skill, the identical packaging convention across all three runtimes. Plugins extend the runtime itself.
- IPC
- MCP servers
- How processes talk to external systems — READ tools run free, WRITE tools sit behind human confirmation. I've built real ones — ~37 protocol MCP servers integrated into an LLM platform.
- Scheduler
- Orchestration modes
- Single agent, subagent, agent team, or dynamic workflow — selected intentionally before implementation, never by default. Hard limits cap the blast radius: 3 subagents, 4 per team, 8 workflow workers, 6 feedback iterations.
- State
- Memory, sessions, logs
- The State subsystem — progress logs, decision records, handovers, the feature list. Externalized so any session resumes from documented state instead of someone's memory.
- Feedback
- Review loops and verdicts
- The Feedback subsystem — evaluator rubric, verification evidence, retrospectives. Every loop ends in a verdict: PASS, REVISE, or BLOCK — and PASS demands evidence, not assertion.
Link your system.
( System Linker )
Three link cards, one parser pipeline. Point the linker at ~/.claude, ~/.codex, or ~/.config/opencode and it renders a system report of your installation — agents, skills, commands, hooks, MCP servers, settings highlights, session counts. Or load the demo: a sanitized snapshot of my rig, run through the exact same parsers.
Your linked files are read and parsed entirely in this browser tab. Their contents are never sent anywhere — no upload, and no analytics event includes a file name, path, or anything derived from them. Credential files are never opened.
Codex
~/.codex
OpenCode
~/.config/opencode
( known limitations )
The operating loop.
( Feedback )
Whichever runtime executes, the work runs one closed loop: explicit phase gates, model-tier routing, persistent handoffs, independent review, and evidence-backed completion.
Plan
A sprint contract before any non-trivial change: goal, scope, non-goals, acceptance criteria, verification plan, and an intentionally selected orchestration mode.
Implement
Single-threaded writes — one scoped builder executes against the contract, with reads fanned out to parallel subagents when discovery demands it.
Verify
A runnable check in the same pass: lint, typecheck, build, e2e. Evidence is captured, not asserted — 'looks done' is not a signal.
Review
A fresh-context reviewer — ideally a different model lineage — scores the work 1–10 against the rubric and issues a verdict.
Handover
Compact written state so the next session resumes from documents, not memory: what happened, what's in flight, what to do next.
( hard limits )
| Limit | Value |
|---|---|
| Max subagents | 3 |
| Max team size (incl. lead) | 4 |
| Max workflow workers | 8 |
| Max feedback iterations | 6 |
( verdicts )
PASS requires exactly 10/10 — zero critical or major issues, verification evidence present; in an autonomous loop there is no partial pass. REVISE sends the work back through the loop with findings attached; BLOCK stops it for human review.