desk pack

Save a source workspace, supported native settings and project sessions as a tar snapshot. The command prints the pack ID and archive path and records the source as packed in desk ps -A.

desk pack [flags]

Compact Git workspaces and --workspace-format are available in Desk 0.2.6 and later. npm 0.2.5 uses full workspace snapshots.

Examples

# Detect the source agent in the current directory.
desk pack

# Choose a source and conversation.
desk pack --from=claude
desk pack --from=claude --session=SESSION_ID

# Require a compact Git pack, or include the full project explicitly.
desk pack --workspace-format=git
desk pack --workspace-format=full

# Capture a specific project and source HOME.
desk pack --from=bob --project=/path/to/project --source-home=/path/to/home

Stop the source agent and other project writers first. Packing creates no target workspace, HOME, or handoff task and requires no installed agent executable.

Flags

Flag	Meaning
--from	Source: claude, codex, qoder, or bob. Auto-detected when unambiguous.
--project	Source workspace. Defaults to the current directory.
--source-home	Source agent HOME. Defaults to the user HOME, or the managed workspace’s HOME.
--session	Selected conversation. Defaults to the newest parent session.
--workspace-format	git (default), full, or auto. See workspace contents below.

For ordinary Codex capture, Desk honors CODEX_HOME when --source-home is not provided. Source detection also recognizes an existing Desk working workspace, including when the current directory is nested inside it.

Packs are stored in ~/.desk/store/packs/ by default, or $DESK_HOME/store/packs/ when DESK_HOME is set.

--workspace-format controls how project files are stored. Every format uses a tar archive; the flag does not select an archive encoding or output style.

Workspace contents

By default, Desk saves eligible Git projects as a repository URL, exact commit, and local changes. Unchanged tracked files come from the repository when the pack is restored elsewhere. Changed files, staged content, deletions and untracked files travel in the pack. Staged and unstaged edits remain separate.

Repository ignore rules exclude files such as node_modules and build output. Git history, local configuration, hooks, other branches and stashes are not included. Native agent settings and sessions are still captured as usual.

Compact capture requires a repository root with a .git directory, an HTTPS or SSH remote, and a committed HEAD reachable from a saved remote branch reference. Push and fetch your latest commits first. Desk does not push commits or contact the remote during packing. Unpublished HEAD commits, submodules, conflicted or sparse indexes, and in-progress Git operations require a full snapshot.

• git (default) requires compact capture and fails if its requirements are not met. For non-Git directories or unsupported repositories, choose full explicitly.
• auto opts into fallback: it uses compact capture when supported, otherwise prints the reason and saves a full snapshot. Non-Git directories use full snapshots.
• full includes the entire project tree, including .git and ignored files. Use it for a workspace snapshot that can be restored without repository access.

Restoring a compact pack into a new directory needs access to the remote and saved commit. A local move in the original project directory keeps your current files and does not fetch Git. See Git restoration for authentication and format details.

Use the saved pack

desk ls
desk move PACK_ID --to=codex

Every pack gets a new ID. Moving from another directory restores a separate writable copy; moving within the original project uses its current files. See storage and archives for contents and file handling.