acpx-codex-playbook

Use acpx as a structured control plane for Codex. Prefer persistent sessions, prompt files, and shell-based file generation over fragile one-shot prompts and tool-native file writes.

Quick start

Run this default flow for any non-trivial task:

acpx codex sessions new --name task
acpx codex set-mode -s task full-access
acpx codex -s task -f prompt.txt

Prefer this over acpx codex exec ... when the task needs iteration, file output, validation, or retries.

Workflow

1. Choose session type

Use exec only for small one-shot tasks.

Use a persistent session when the task involves any of the following:

• generating files
• multiple retries
• long prompts
• validation steps
• local installs or virtual environments
• deliverables such as .pptx, .docx, reports, videos, or scripts

2. Set mode explicitly

For practical work, set mode before prompting:

acpx codex set-mode -s task full-access

Interpretation:

• read-only: inspect only
• auto: moderate default behavior
• full-access: broader session capability, including easier file edits and broader path/network freedom

Do not assume full-access means sudo or root. It relaxes the ACP session; it does not guarantee system-level privilege escalation.

3. Use prompt files, not huge shell strings

For long or delicate instructions, always write a prompt file and pass -f:

cat > prompt.txt <<'TXT'
Task: ...
Constraints: ...
Outputs: ...
Validation: ...
TXT

acpx codex -s task -f prompt.txt

This avoids shell quoting failures and makes retries reproducible.

4. Prefer shell/Python file writes over ACP fs writes

If the task must create or rewrite files, instruct Codex to prefer:

• shell heredocs
• python - <<'PY' ... PY
• direct command-line generation

Prefer these over tool-native fs/write_text_file style edits when prior attempts showed permission failures.

Recommended instruction snippet:

If built-in file-editing tools fail, write files via shell heredoc or Python scripts instead of ACP fs write calls.

5. Use writable output paths first

For fragile generation tasks, write outputs under /tmp first, validate them, then move/copy them into the target workspace.

Recommended pattern:

• generate under /tmp/...
• validate structure and existence
• copy to final destination only after success

This is especially useful for generated binaries like .pptx.

6. Validate before declaring success

Always ask Codex to verify outputs.

Examples:

• file exists
• zip/XML structure parses for .pptx
• image dimensions or PDF page count
• report file with output path, validation result, and model if visible

Practical patterns

Pattern: generated deliverables

For PPT/report/document generation, require all of the following in the prompt:

• exact output path
• exact report path
• validation steps
• final two-line summary with model/path if possible

See references/ppt-playbook.md for a concrete template.

Pattern: local dependency installs

If non-stdlib packages are needed, prefer project-local installs:

python3 -m venv .venv
. .venv/bin/activate
pip install <package>

Avoid assuming global install rights. Use system-level installs only when explicitly intended and actually permitted by the host.

Pattern: troubleshooting failed writes

If touch or shell writes work but ACP file edits fail, treat it as an ACP handler or sandbox-path issue, not proof that Codex itself lacks capability. Switch the generation strategy to shell/Python writes.

Decision rules

• If the task is small and read-heavy: exec is acceptable.
• If the task must create deliverables: use a persistent session.
• If the prompt is long: use -f prompt.txt.
• If file editing fails once: switch to shell/Python write strategy.
• If dependencies are missing: try local .venv install before changing system state.
• If a binary artifact is required: generate in /tmp, validate, then move.

Anti-patterns

Avoid these common failure modes:

• stuffing long multilingual prompts directly into one shell string
• assuming full-access equals sudo/root
• relying only on ACP fs writes for large generated files
• declaring success before validating output structure
• writing the final artifact directly into a path that may be sandbox-restricted

References

• Read references/ppt-playbook.md when the task is to generate a PPT or similar structured binary deliverable via acpx/Codex.
• Read references/troubleshooting.md when acpx sessions start but file creation, mode behavior, or sandbox boundaries are unclear.