Firstmate Codexapp

firstmate-codexapp

Overview

Use this playbook when Firstmate work needs a visible Codex Desktop thread. The current supported shape is Desktop host-tool choreography plus an explicit status-file return-channel check, not a codex-app value in FM_BACKEND.

Boundary

Codex Desktop visible threads are companion host-tool workflows, not a selectable Firstmate backend. Read docs/codex-app-backend.md when it exists in this checkout; that document owns the acceptance contract, bridge requirement, status-return requirement, and staged rollout.

If local helper scripts exist for Codex App work, use only helpers explicitly provided by the operator or maintained by Firstmate. For helpers outside bin/, inspect the source or header before running --help.

Preflight

1. Confirm this session is running inside Codex Desktop and that the host tools are exposed. Search exact names when needed: create_thread, list_threads, read_thread, send_message_to_thread, archive, and set_thread_archived.
2. Confirm the target repository is already saved as a Codex Desktop project. No host tool currently creates Codex App projects for an agent, so the human must add the project in Desktop before a created thread can reliably land there.
3. Do not create projectless threads for repo work. If the project is absent, stop and ask for the project to be added or use a normal Firstmate backend instead.
4. Decide whether this is a real Firstmate-managed task or a visible companion thread. A real task needs a task id, an isolated worktree or Desktop-owned cwd, a branch plan, and a writable state/<id>.status path.

Create And Send

When creating a visible thread, use the Desktop host tool, not shell imitation. Target the saved project and ask the worker to start by reporting:

pwd
git rev-parse --show-toplevel
git branch --show-current
git log --oneline --max-count=3

For writable repo work, instruct the worker to use the Codex-created current directory. Do not tell it to cd into the saved project checkout for edits, commits, no-mistakes, pushes, or PR work.

When sending follow-up instructions, use send_message_to_thread. If the user types directly into the visible thread, treat that as authoritative and reconcile from read_thread instead of undoing it.

Status Return Channel

A Desktop-owned Codex thread can append to Firstmate status files only when the prompt gives an absolute path and the Desktop permission context can write that checkout. That makes status writes a verified return-channel requirement, not a fact to assume.

For a Firstmate-managed task, include an explicit status instruction:

Append supervisor-visible status lines to <absolute-firstmate-home>/state/<task-id>.status.
Use only these prefixes for status changes: working:, needs-decision:, blocked:, paused:, done:, failed:.
Follow the task brief's status-reporting rule for declaring and resolving waits; bin/fm-brief.sh owns that rule.
Before doing substantive work, append "working: Codex Desktop thread started".

Verify the return channel before treating the thread as supervised:

• read_thread shows the worker attempted the status write.
• The local state/<task-id>.status file contains the expected line.
• If available, the transcript includes a file-change entry for that status file.

If the thread cannot write the status file, keep it as a visible companion thread only. Do not claim it is a complete Firstmate backend.