| name | agentkit-codex-handoff |
| description | Continue the current local Codex conversation and coding task in an AgentKit Studio cloud Codex Sandbox using a Studio URL and short one-time pairing code. Use when the user asks to hand off, migrate, or continue a local repository in Studio, especially when a prompt contains a Studio address and pairing code. Export the complete user-visible user and assistant message history from every prior turn, including interrupted turns and progress commentary, create a temporary Studio Sandbox, restore tracked and non-ignored working-tree files plus Git metadata, inject that visible history into the cloud Thread, transfer GitHub CLI authentication separately when needed, and send one final continuation message; never copy system or developer prompts, reasoning, tool logs, SQLite state, global configuration, local skills, or SSH private keys. |
Continue a Task in Studio
Transfer the project plus the current task's visible conversation, not the local Codex runtime. Create one temporary Studio Sandbox with the supplied pairing code, restore the project, inject the complete visible history from every prior turn into its fresh cloud Thread, then send exactly one new user message so the cloud Session continues working.
Accept a terse handoff prompt containing only the intent, Studio URL, and pairing code. When invoked immediately after Plugin installation, stay in the current Codex task, load this Skill explicitly if automatic discovery has not refreshed, and continue without asking the user to repeat the repository or task context.
Boundaries
Include only:
- Git tracked files and non-ignored untracked files, including working-tree edits and deletions
- repository-level
AGENTS.md files selected by the same Git rules
- Git branch, HEAD commit, sanitized remote URL, and status metadata
- a generated
HANDOFF.md; append the generated section when the project already has one, and keep the generated metadata out of Git commits
- every user and assistant message visible in the active Codex task before the current handoff turn, including progress commentary and interrupted turns
- local PNG, JPEG, GIF, or WebP images attached to those prior user messages
Never include:
- Codex system or developer prompts, reasoning summaries, tool calls or outputs, rollout JSONL, or SQLite state
$CODEX_HOME, local or global Skills, plugin caches, or global Codex settings- SSH private keys, non-GitHub credentials, or global Git configuration
- ignored files such as
.env unless they are deliberately tracked
Do not place conversation history in the repository, HANDOFF.md, retained project bundle, logs, or command output. Send it only through the authenticated one-time continuation request. Do not claim that the remote environment is an exact copy of local Codex; it is a visible-history and project handoff into a separately configured Studio runtime.
The restore helper hides a newly generated HANDOFF.md through the repository-local Git exclude file. When the repository already tracks HANDOFF.md, it applies skip-worktree in the temporary cloud checkout so the appended transfer metadata is not staged by broad git add commands. Never commit generated transfer metadata. If the cloud task deliberately needs to edit a tracked HANDOFF.md, first remove the temporary flag with git update-index --no-skip-worktree HANDOFF.md, then delete the generated section before committing.
Workflow
-
Resolve the repository from the user's repo value or the current working directory. Confirm it with pwd.
-
Resolve studio_url and pairing_code from the user's prompt. Treat the pairing code as a secret: do not print it, write it to a file, or place it in the bundle.
-
Create a concise Chinese task description for the cloud Agent name. Infer it yourself from the active task; do not ask the user to name it. Use at most 12 Unicode characters, omit punctuation and generic prefixes such as Codex, and describe the work rather than the repository. Examples: 完善端云接力, 修复登录超时, 优化订单检索.
-
Export the active task's complete visible conversation with the Codex app task tools:
-
Call list_threads and select the most recently updated active Codex task whose working directory matches the repository and whose title or summary matches the current objective.
-
Identify the current handoff turn as the turn containing the pairing-code request being executed. Exclude that entire turn only; do not exclude any older turn based on completed, interrupted, failed, or other status.
-
Call read_thread with includeOutputs: false, maxOutputCharsPerItem: 20000, and turnLimit: 10. The response is newest_first: save its page.nextCursor, call read_thread again with that cursor whenever page.hasMore is true, and continue until page.hasMore is false or 100 eligible visible messages have been collected. Never stop after the first page merely because it contains a completed turn.
-
Reassemble pages and turns oldest-to-newest. Within each eligible turn, preserve item order and keep every userMessage and every agentMessage exactly once. Keep all user-visible assistant phases, including progress commentary before a final answer; do not merge, summarize, deduplicate, or replace them with the final answer.
-
Exclude system/developer instructions, reasoning, tool calls and outputs, approvals, environment context, and other item types. Filtering is based on item type, never on turn status or agentMessage.phase.
-
A delegated user message can contain an XML-looking wrapper. When the structured text part contains , use that value as the user-visible text and discard the wrapper. Never upload the wrapper or its .
AGENTKIT_STUDIO_PAIRING_CODE="$pairing_code" \
scripts/upload_current_dir.sh \
--repo "$PWD" \
--studio-url "$studio_url" \
--agent-name "$agent_name" \
--handoff "$handoff_file" \
--history "$history_file" \
--continue-message "$continue_message" \
--yes
Keep the command attached until it returns. Relay each [handoff] progress:
line as concise progress to the user instead of waiting silently. The command
returns after Studio confirms that the cloud Codex completed the continuation and generated a visible reply;
the cloud task then keeps running independently.
- Delete the temporary history and handoff files after the command returns. Confirm that the script created a temporary Studio Sandbox, restored the project, kept generated handoff metadata out of Git status, injected the visible conversation history and images, and sent the final continuation message. Report the Sandbox display name, session ID, remote project directory, restored file count, imported message count, imported image count, Git status, GitHub authentication result, and continuation status. Do not claim success when the continuation stream reports an error or closes before completion.
Script options
--agent-name is required for a live handoff and controls only the cloud Agent name. --history is required and accepts only the versioned visible-message JSON described above. Images are limited to 10 supported files, 4 MiB per image, and 8 MiB total. --continue-message defaults to 继续. --project-name controls the bundle and remote directory and defaults to the repository basename. Use --remote-home only when Studio supports a different home, --handoff to append the task summary, and --output to retain a local copy of the generated project bundle. The script always creates a temporary Studio Sandbox. Use --no-github-credentials only when the user explicitly opts out; otherwise a GitHub remote requires working local gh authentication.
The live command requires --yes. Add --allow-sensitive only after explicit approval for filenames or possible secret assignments identified by the preview. Visible history travels in the one-time Studio request and is injected with thread/inject_items before the final turn/start; old messages must never be replayed as turns. GitHub credentials travel in a separate ephemeral payload, never in the retained --output bundle, and the remote staging payload is deleted after installation. On failure, report the safe error and whether Studio already created a Session; never expose the pairing code, conversation contents, token, or returned private Sandbox endpoint.
Large project bundles are uploaded in bounded parts, reassembled in order, and verified by SHA-256 before restore. If upload or restore fails after Session creation, the script reports the failed stage to Studio and a retry with the same pairing code resumes the existing Session instead of creating another one. Reuse the original pairing code for that retry while it remains valid.
