How-to

Use Codex with Buffaly

Use Codex as Buffaly's source-editing engine while Buffaly owns planning, evidence, validation, commit scope, and user-facing judgment.

Quick answer

Codex is Buffaly's editing engine for code and file changes. Buffaly should still inspect evidence, decide whether Codex is the right tool, constrain the edit, validate the result, and commit only intended files.

Use Codex for

Coherent source edits, refactors, and multi-file documentation or code changes where validation can prove the result.

Prefer typed paths for

Inspection, validation, provider configuration, secrets, session management, services, and domain-native work when available.

What Codex does inside Buffaly

The checked-in Codex skill exposes edit and subagent actions backed by Buffaly.Agent.Tools.Codex.CodexTools. The simple edit action runs one Codex edit turn with an absolute working directory, instruction, and optional trusted prompt path.

Action family	Use
`ToCodexEditTool`	Run one bounded edit turn for a working directory and instruction.
Codex subagent actions	Open, send, steer, cancel, list, or close longer Codex-backed editing sessions.

Codex backend, OpenAI API, and normal tools are different

Concept	User meaning
Codex edit tool	Buffaly action used to delegate source/file edits to Codex.
Codex backend	OpenAI/ChatGPT-backed completion transport used by Buffaly when configured as the provider route.
OpenAI API provider	Conventional OpenAI API-key route, separate from Codex backend/profile auth.
Typed tools and services	Buffaly-native capabilities for files, processes, secrets, SQL, HTTP, sessions, services, and provider-specific operations.

Use Codex for editing. Use typed tools for inspection, validation, provider configuration, secrets, session management, and other domain-native work when available.

When to use Codex

Good Codex work

Code or documentation edits across multiple nearby sections or files.
Refactors that need coherent source changes.
Edits where a SmartPatch would be too brittle.
Non-ProtoScript source or file editing.

Prefer another path

Read or search files with file/search tools first.
Use SmartPatch for tiny deterministic text replacements.
Use typed ProtoScript authoring tools for .pts behavior.
Use secrets/settings tools for credentials.

Configuration and credentials

Codex use can involve two separate areas: the Codex tool/runtime path for edit actions, and the Codex backend/provider path for provider catalog selection and ChatGPT/OpenAI credentials when that transport is selected.

Codex auth/profile settings are distinct from OpenAI Feature.ApiKey.
Start credential questions with Providers and authentication and Secrets handling.
Do not paste API keys, OAuth tokens, browser cookies, or account passwords into a Codex instruction, prompt file, code file, or wiki page.

How to ask Buffaly to use Codex

Good requests give Buffaly the goal, target path, constraints, validation expectation, and commit expectation.

Inspect the code first, then use Codex to update only the login settings UI. Validate the changed JavaScript/HTML paths, do not touch unrelated files, and commit the result with a clear message.

Use Codex for the implementation step only. First identify the failing provider validation path from source, then ask Codex for a minimal fix, run focused validation, and commit only intended files.

Create a documentation how-to in the wiki. Use source as truth, use the absolute wiki path, do not edit unrelated files, validate the markdown, and commit only the new article.

Refactor this C# helper with Codex, but keep the existing typed contract shape exactly. Do not add compatibility parsing or alternate casing. Build if source changes require it.

A safe Codex workflow

Clarify the desired outcome, repository root, target files, and risks.
Inspect source first with file, search, log, or session tools.
Choose Codex intentionally only when the edit is source/file editing.
Constrain the instruction with target paths, files not to touch, source-of-truth rules, validation requirements, and commit scope.
Run Codex in the correct absolute working directory.
Review diffs and ensure unrelated files were not changed.
Validate with the smallest relevant markdown, build, compile, focused test, smoke, or runtime check.
Stage only files changed for the assignment and commit with a clear message.
Report changed files, validation result, and commit hash.

Validation and commits after Codex edits

A Codex edit is not complete just because files changed. Buffaly should validate after the edit and leave unrelated dirty files unstaged.

Show the git diff for only the files Codex changed.
Run a focused non-parallel build when source changes require it.
Verify documentation paths exist and contain expected headings.
Check git status --short, stage only intended files, and commit with a message that explains what changed.

Common failures and recovery

Wrong path or unrelated files

Stop and inspect cwd, target paths, and git diff. Do not stage unrelated files; keep only the assignment files.

Codex auth/backend failure

Check Codex auth/profile status, Codex Auth Feature, Codex Backend Feature, provider selection, and logs. Do not add an OpenAI API key unless that route is actually selected.

Codex turn already running

List subagents, wait for completion, steer if supported, or cancel the active turn.

Validation fails

Treat validation output as the next source of truth. Fix the root cause rather than hiding, normalizing, or bypassing the failure.

Codex editing workflows SmartPatch Troubleshooting