codex-telegram-bot/.codex/skills/codex-thread-cwd/SKILL.md

name, description

name	description
codex-thread-cwd	Change a Codex thread working directory/cwd on the Codex side, not in downstream tool databases. Use when asked to change, move, fix, align, or sync a Codex thread workspace/cwd, especially for app-server threads or client integrations where dependent tools should sync from Codex afterward.

Codex Thread CWD

Use this skill to change a Codex thread's stored working directory (cwd) in Codex state, then let clients such as a Telegram bot sync from Codex. Do not edit downstream client databases as the source of truth.

Required Inputs

• Target thread_id, usually a Codex UUID. If the user refers to a client-specific current thread, inspect that client's state only to discover the Codex thread_id; do not edit that client state unless explicitly asked.
• Target absolute cwd. Do not assume a machine-specific path; derive it from the user's request, the current repo, or an explicit argument.

Preferred Workflow

1. Resolve the target thread ID.
   • For this repo's Telegram bot, read its configured SQLite DB only to discover sessions.active_thread_id -> threads.codex_thread_id for the relevant Telegram user.
   • If ambiguous, list candidates and ask the user to choose.
2. Confirm the target cwd is absolute and exists, unless the user intentionally wants a path that does not exist yet.
3. Run the bundled script from the skill directory:

python3 path/to/codex-thread-cwd/scripts/set_thread_cwd.py THREAD_ID /absolute/new/cwd

Use --codex-home, --state-db, or CODEX_HOME when the Codex state is not under the current user's default Codex home.

4. Verify Codex-side state, preferably with app-server thread/read if a socket is available. DB-level verification from the script is acceptable when app-server is unavailable.
5. Trigger the dependent tool's normal sync path, such as asking a bot for /workspace or /threads. Do not manually insert or update downstream workspace rows unless the user explicitly asks for emergency repair.

Notes

• The app-server schema exposes cwd on thread/resume, thread/fork, and turn/start; thread/metadata/update does not patch cwd.
• In observed behavior, thread/resume with cwd may return the original cwd and not mutate existing stored thread cwd.
• turn/start.cwd is schema-supported as an override for that turn and subsequent turns, but it starts a new turn.
• The proven no-turn approach is to update Codex's own state_*.sqlite threads.cwd row and the first session_meta.payload.cwd line in the rollout JSONL. This is Codex-side state, not downstream client state.
• The script preserves a rollout backup by default; it writes <rollout>.bak.<timestamp> unless --no-backup is passed.

Verification Examples

Inspect Codex state directly:

python3 path/to/codex-thread-cwd/scripts/set_thread_cwd.py THREAD_ID /absolute/new/cwd --verify-only

Read through app-server and check result.thread.cwd equals the requested path.