Skip to content

codex-fork-tasks.md

Latest commit

 

History

History
132 lines (88 loc) · 3.22 KB

codex-fork-tasks.md

File metadata and controls

132 lines (88 loc) · 3.22 KB

Codex Fork Tasks

These Flow tasks automate the personal Codex fork workflow described in:

  • ~/docs/codex/codex-fork-home-branch-workflow.md

They are intentionally narrow:

  • keep ~/repos/openai/codex as the upstream reference checkout
  • keep ~/repos/nikivdev/codex as the fork home checkout
  • create one stable worktree per real fork task under ~/.worktrees/codex
  • attach Codex sessions to that worktree instead of to one drifting checkout

Commands

Run these from ~/code/flow:

cd ~/code/flow
f codex-fork-status
f codex-fork-sync
f codex-fork-task "add workspace ref to the footer"
f codex-fork-last
f codex-fork-promote --push

If you are outside ~/code/flow, use the explicit config form:

flow run --config ~/code/flow/flow.toml codex-fork-task "add workspace ref to the footer"

What Each Task Does

f codex-fork-status

Shows:

  • the upstream reference checkout
  • the personal fork home checkout
  • the current nikiv, upstream/main, and private/nikiv refs
  • existing fork worktrees
  • the last worktree used by the helper

Use this first when the fork state is unclear.

f codex-fork-sync

Fast-forwards nikiv in ~/repos/nikivdev/codex to upstream/main.

Optional push:

f codex-fork-sync --push

Safety rule:

  • it refuses to run if the fork home checkout is dirty

f codex-fork-task "<query>"

This is the main entry point.

It:

  1. derives a branch like codex/<slug>
  2. creates or reuses ~/.worktrees/codex/<branch-name-with-slashes-rewritten>
  3. records that worktree as the "last fork worktree"
  4. resumes the last Codex session in that worktree if one exists
  5. otherwise starts a fresh Codex session there with an initial prompt that points at the fork workflow doc

Examples:

f codex-fork-task "add workspace ref to the footer"
f codex-fork-task "thread name startup" --branch codex/thread-name-startup
f codex-fork-task "statusline workspace ref" --no-launch

f codex-fork-last

Resumes codex resume --last in the last worktree created or used by the helper.

This is the closest current Flow equivalent to binding a key that reattaches to the last active fork session.

You can also target a branch or path explicitly:

f codex-fork-last codex/workspace-awareness
f codex-fork-last ~/.worktrees/codex/codex-workspace-awareness

f codex-fork-promote

Creates or updates a review branch from the current task worktree tip.

Default mapping:

  • codex/workspace-awareness -> review/workspace-awareness

Examples:

f codex-fork-promote
f codex-fork-promote codex/workspace-awareness --push
f codex-fork-promote ~/.worktrees/codex/codex-workspace-awareness --review-branch review/workspace-awareness

State File

The helper records the last used worktree in:

~/.flow/codex-fork/last-worktree.txt

That is what powers f codex-fork-last.

Environment Overrides

If you want the helper to point somewhere else, override these env vars:

  • FLOW_CODEX_UPSTREAM_CHECKOUT
  • FLOW_CODEX_FORK_HOME
  • FLOW_CODEX_WORKTREE_ROOT
  • FLOW_CODEX_WORKFLOW_DOC
  • FLOW_CODEX_FORK_STATE_DIR
  • FLOW_CODEX_FORK_BASE_BRANCH
  • FLOW_CODEX_FORK_PRIVATE_REMOTE
  • FLOW_CODEX_FORK_UPSTREAM_REMOTE
  • FLOW_CODEX_FORK_UPSTREAM_BRANCH