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