Troubleshooting

Desk cannot identify one source agent

Several agents may have sessions or instruction markers in a project, or none may be present. Specify the source:

desk pack --from=claude
desk move --to=codex

Use --project and --source-home when the defaults do not point to the intended project or native state. --session selects a specific existing conversation.

The source agent is still running

Desk 0.2.7 and later identifies the source agent and process in the packing error:

Error: codex is still running for this project (PID 12345); stop it manually before packing

Stop it manually, along with other project writers, and retry. Desk never stops a source process on your behalf. For Bob, running or compacting tasks, live leases, and pending approvals also block capture.

The store is inside the captured tree

Desk uses ${DESK_HOME:-$HOME/.desk}/store. Run pack from an individual project that does not contain the store, or select the project explicitly:

desk pack --from=claude --project=/path/to/project

Do not pack your entire HOME or a parent directory containing the store.

Compact packing is unavailable

In Desk 0.2.6 and later, desk pack requires compact Git capture by default. Run from the repository root and check that it has a committed HEAD and an HTTPS or SSH remote. Desk uses origin, or the only remote when origin is absent. The commit must be reachable from a saved remote-tracking branch.

If your latest commits have not been pushed, publish them to your repository when appropriate and update its remote-tracking references before retrying. Desk does not push or fetch during packing. An unfinished merge or rebase, conflicted or sparse index, submodules, or a linked worktree also prevents compact capture.

For a non-Git directory or a project that needs a full snapshot, select it explicitly:

desk pack --from=claude --workspace-format=full

To allow full capture automatically when compact capture is unavailable, use --workspace-format=auto. These flags are not available in npm 0.2.5.

Ignored files are absent from a restored workspace

Compact capture excludes untracked files matched by repository .gitignore files and .git/info/exclude. Reinstall dependencies or regenerate build output in the restored workspace. To carry ignored files with the project, create a new pack with --workspace-format=full. A file already tracked by Git is retained even when an ignore rule matches it.

Ordinary tar extraction of a compact pack reveals only its saved changes. Use desk move PACK_ID --to=TARGET from another directory to fetch the baseline and reconstruct the workspace. See Git restoration.

Git restoration cannot fetch the saved commit

A compact pack needs destination access to its remote repository when it is restored into a new directory. Public HTTPS repositories require no credentials. For private HTTPS repositories, provide DESK_GIT_TOKEN in the destination environment. For SSH, check the destination’s SSH agent and known-hosts entry. Git authentication and the target agent’s login are separate.

If access works but the saved commit is unavailable, restore remote access to that commit or create a new pack from the source workspace. Desk does not replace the saved commit with the latest branch. A full snapshot can restore its captured files without fetching the repository.

A move in the original project directory keeps its current files and skips Git fetching. It does not roll that directory back to the saved pack.

The target executable cannot be found

Install the target and put it on PATH, or pass its absolute executable path:

desk move PACK_ID --to=codex --binary=/path/to/codex

desk pack needs no installed target. Bob launch supports version 2.0.2.

New moves use your normal HOME and existing local login. Check that Desk runs from the same shell and account as the agent. CODEX_HOME and CLAUDE_CONFIG_DIR are inherited. Older isolated sessions retain their original HOME; move the pack again with the current binary to create a native local session.

The readable transcript is missing

Inspect work/AGENT_ID/home/.TARGET/.desk-handoff/report.json under the Desk store. An empty source has no conversation; unsupported or malformed native data may prevent text extraction. Original native state remains in the archived sessions/ tree for review.

A target exited or a launch was interrupted

Check desk ps -A and the retained workspace. Only a prepared entry can be started with desk move --to=TARGET --resume=AGENT_ID.

A launch that has already been attempted cannot be replayed in the same target. Move the source pack again for an independent attempt. To keep new work, stop writers and pack the target workspace before moving it instead.

Secrets setup and approval

Secrets is optional in Desk 0.3.0. A missing account, broken configuration, or unavailable Secrets service does not block ordinary Desk commands. A task or move that explicitly requests credentials stops if they cannot be retrieved.

Symptom	What to do
Setup requires an interactive terminal	Run `desk secrets onboard` in your own terminal and desktop session.
The browser does not open	Check that HTML files open in your browser. On WSL, enable Windows interoperability and localhost forwarding. Run onboarding again.
No capability is configured for this project	Run from the directory where you connected it, or run `desk secrets connect` from the destination project. `desk secrets ls` lists local capabilities for the current directory.
A task waits for approval	Open the printed approval link, or use `desk secrets requests` and `desk secrets approve --request REQUEST_ID` in another terminal.
The owner session has locked	Run the owner command again and enter a fresh authenticator code. Sign in with Google again if that session has also expired.
Activation was interrupted	Keep the device and recovery files and run `desk secrets onboard` again. Desk checks the signed activation status.

See the Secrets guide for account recovery, project setup, and the difference between local discovery and service access.