david-lzy/codex_session_renamer/codex-session-renamer

Codex Session Emoji

Default Rule

Keep Codex on the two Desktop-only boundaries:

1. Start review: call codex_app.list_threads, save the JSON snapshot, run bootstrap-review, and start the local review server.
2. Apply approved titles: read desktop_apply_request.json, call codex_app.set_thread_title for each submitted item, and write desktop_apply_result.json.

Do not generate titles in Codex on the default path. The web/local service handles local LLM, heuristic proposals, review UI, and approval files.

propose and agent-review skip sessions whose current title already starts with an emoji by default. Use --include-existing-emoji only when the user explicitly wants to re-review already named sessions.

Short User Brief

Use the user's language. In Chinese, keep it short:

我会走低 token 流程：先只用 Codex 导出当前会话列表并打开本地审核页；标题生成和审核在本地网页/服务里完成。你提交后，我再只读取批准结果并调用 Codex 官方改名工具实时刷新侧栏。

Start Review

1. Call codex_app.list_threads with limit: 50.
2. Save the exact tool JSON to:

~/.codex/tmp/session-renamer/current/local_threads.json

1. Prefer the automatic path. It does not start the web server; it reuses the last saved web/CLI vLLM and remote-host config and directly runs maintenance, discover, propose, and render-review:

python <skill-dir>/scripts/session_renamer.py auto-review --local-json ~/.codex/tmp/session-renamer/current/local_threads.json

For the no-browser full path, use:

python <skill-dir>/scripts/session_renamer.py auto-all --local-json ~/.codex/tmp/session-renamer/current/local_threads.json --auto-approve-valid

Then read auto_review_status.json. If state is pending_codex_apply, immediately run the Apply Approved Renames flow below against the generated desktop_apply_request.json.

If it writes auto_review_status.json with state: needs_config, stop and ask the user for:

• OpenAI-compatible/vLLM base URL;
• model name, optional when /v1/models is available;
• remote SSH hosts to include.

When the user provides them, rerun auto-review with --vllm-base-url, optional --model, repeated --ssh-host, and --save-config.

1. If the user only wants to configure the browser page first, run:

python <skill-dir>/scripts/session_renamer.py bootstrap-review --local-json ~/.codex/tmp/session-renamer/current/local_threads.json
powershell -ExecutionPolicy Bypass -File <skill-dir>/scripts/restart_review_server.ps1 -Port 8765

1. Tell the user to open or refresh:

http://127.0.0.1:8765/

Do not open/control Browser unless the user explicitly asks you to operate or inspect the page.

If the web page writes start_review_request.json and asks for a fresh scriptable review, read runbooks/start-review-from-web.md.

Apply Approved Renames

When the user says they submitted approvals:

1. Read:

~/.codex/tmp/session-renamer/current/desktop_apply_request.json

1. For each items[] entry, call:

{"threadId":"<threadId>","title":"<newTitle>"}

using codex_app.set_thread_title.

1. Write:

~/.codex/tmp/session-renamer/current/desktop_apply_result.json

with:

{"created_at":"...","applied":[],"failed":[],"skipped":[]}

If a tool call returns No AppServerManager registered, record that item as skipped and continue. For detailed apply handling, read runbooks/apply-approved.md.

On-Demand Paths

Read these files only when the trigger applies:

• runbooks/codex-subagent.md: user selects Codex subagent, agent_review_status.json says needs_subagent, or a subagent_requests/*.json request is pending.
• runbooks/remote-fallbacks.md: user explicitly requests remote persistence, selects remote hosts for apply, or local set_thread_title cannot address the target host.
• runbooks/troubleshooting.md: local server fails, JSON parsing fails, port 8765 is stuck, review files are missing, or the page reports an internal error.
• runbooks/browser-usage.md: user asks you to click, inspect, screenshot, or verify the review page in the in-app Browser.

Safety

• Never apply titles before approval.
• Never edit transcript files.
• Prefer codex_app.set_thread_title for visible local Desktop updates.
• Remote fallback commands must back up the target state/index first and should only run after explicit user approval.
• Do not send full transcripts or secrets to any model; scripts use redacted short snippets.