Agent Adapters (Codex, OpenCode, Pi)
Relevant source files
The following files were used as context for generating this wiki page:
Delano is an agent-agnostic delivery runtime that facilitates collaboration between various coding agents and human operators using file-backed delivery contracts. While the core logic and workflow are shared, Delano uses Agent Adapters to provide runtime-specific instructions and entry points for different AI agents, specifically Codex, OpenCode, and Pi.
The architecture relies on a "thin" entry point strategy where agent-specific nuances are isolated in adapters, while the heavy lifting of process management and contract validation remains in the shared .agents/ runtime and .project/ directory.
Sources: README.md:14-17, AGENTS.md:3-5, CODEX.md:1-12
Adapter Architecture
The adapter system is structured to minimize duplication. Every agent interaction begins with a standardized "First-turn workflow" defined in the shared AGENTS.md. Each specific agent then follows its own adapter entry point (e.g., CODEX.md) which points to more detailed, agent-specific notes stored within .agents/adapters/<agent>/.
Core Components
- Entry Points: Top-level Markdown files (
CODEX.md,OPENCODE.md,PI.md) that serve as the initial contact for the agent. - Adapter Notes: Located in
.agents/adapters/<agent>/README.md, containing specific technical instructions for that model's capabilities or limitations. - Shared Workflow: Defined in
AGENTS.md, this is the primary operational handoff for all agents. - Common Runtime: Scripts, hooks, rules, and skills stored in
.agents/used by all adapters.
Sources: AGENTS.md:8-16, CODEX.md:1-12, OPENCODE.md:1-12, PI.md:1-12
Workflow Diagram
The following diagram illustrates how an agent navigates the Delano file structure upon activation.
The diagram shows the hierarchy of instructions, starting from agent-specific entry points and funneling into shared rules before accessing granular adapter notes and project state.
Sources: AGENTS.md:8-16, CODEX.md:5-12
Supported Adapters
Delano provides specific support for three primary adapters in addition to the standard Claude compatibility layer.
| Adapter | Entry Point | Specific Notes Path | Key Features |
|---|---|---|---|
| Codex | CODEX.md | .agents/adapters/codex/README.md | SessionStart hooks, .codex/hooks.json integration. |
| OpenCode | OPENCODE.md | .agents/adapters/opencode/README.md | Standardized tool-use and contract-first workflow. |
| Pi | PI.md | .agents/adapters/pi/README.md | Minimalist interaction model focused on core tasks. |
Sources: CODEX.md, OPENCODE.md, PI.md, src/cli/lib/install.js:18-19
Codex Specific Integration
The Codex adapter includes deeper integration with the Codex CLI through specialized hooks. Delano provides a .codex/hooks.json file that configures a SessionStart hook. This hook triggers the .agents/hooks/codex-session-status.js script to inject project context directly into the Codex session.
Codex Hook Logic
When running delano install, the system attempts to merge Codex hooks rather than overwriting them to preserve user configurations.
This sequence ensures that Codex starts every session with an up-to-date understanding of the local delivery state.
Sources: README.md:139-158, src/cli/lib/install.js:16-17, 396-420
Shared Operational Workflow
All adapters are bound by the "First-turn workflow" and "Safety Boundaries" defined in AGENTS.md. This ensures consistent behavior regardless of the underlying LLM.
First-Turn Requirements
- Read Shared Rules: Consult
AGENTS.mdfor the source-of-truth map. - Inspect State: Run
git status --short --branchand check.project/projects/contracts. - Task Selection: Choose the smallest task-safe change.
- Validation: Run
bash .agents/scripts/pm/validate.shornpm testbefore claiming completion. - Evidence: Record logs and validation results in the task artifact.
Sources: AGENTS.md:8-16, 28-35
Installation and Distribution
The adapters and their corresponding runtime files are distributed via the @bvdm/delano npm package. The install-manifest.json defines which adapter-specific files are deployed during the delano install process.
File Distribution Table
| Target Path | Category | Purpose |
|---|---|---|
.agents/adapters/codex/README.md | agent-runtime | Codex-specific operating instructions. |
.agents/adapters/opencode/README.md | agent-runtime | OpenCode-specific operating instructions. |
.agents/adapters/pi/README.md | agent-runtime | Pi-specific operating instructions. |
.codex/hooks.json | codex-hooks | Codex session hook configuration. |
.agents/hooks/codex-session-status.js | codex-hooks | Script executed by Codex on session start. |
Sources: assets/install-manifest.json:4-8, 16, 212, src/cli/lib/install.js:20-25
Conclusion
The Agent Adapter system in Delano provides a scalable way to support diverse AI models while maintaining a unified delivery process. By separating agent-specific entry points from shared runtime logic, Delano ensures that whether an operator is using Codex, OpenCode, or Pi, the resulting work remains grounded in the local project contracts and subject to the same validation rigors.