Storage and archives

Store location

Desk uses ~/.desk/store by default. Set DESK_HOME to override the ~/.desk base directory; Desk stores its data in $DESK_HOME/store. An unset or empty DESK_HOME uses the default. There is no store command flag.

export DESK_HOME=/path/to/desk
desk ls                         # Reads /path/to/desk/store

Use the same setting for pack, ls, ps, and move. Changing it selects a different store; it does not migrate existing packs or working directories. Use an absolute path so the setting remains consistent when you change directories. The default HOME is the HOME of the process running Desk.

Capture individual project directories. Desk rejects a captured tree that contains the active store, including the store itself.

Default layout (under $DESK_HOME/store when configured):

~/.desk/store/
  packs/<PACK_ID>.tar
  agents/<AGENT_ID>.json
  work/<AGENT_ID>/
    workspace/
    home/.<target>/.desk-handoff/
      README.md
      report.json
      transcript.json
      settings/
      sessions/

transcript.json is written when a selected session exists and transcript extraction succeeds. Otherwise, report.json records its absence or extraction error. The working HOME holds staging files only. New moves install the authored session into your local agent directory and inherit your normal environment. Bob adds a task to ~/.bob/db/bob.db transactionally, preserving existing tasks. CODEX_HOME and CLAUDE_CONFIG_DIR are respected when set.

Tar format

All packs are ordinary uncompressed tar files. Full snapshots use schema 1. Compact Git snapshots use schema 2 and are available in Desk 0.2.6 and later. Compact capture is the default; --workspace-format=full selects a full snapshot explicitly. Existing schema-1 packs remain readable.

Each tar contains:

Entry	Contents
desk.json	Schema version, pack ID, UTC capture-start time, source project path, source agent and adapter; selected session ID when available.
workspace/	Full format: entire project tree. Git format: changed and untracked working files only.
workspace-meta/	Git format only: state.json records index and working-tree changes; index/HASH holds changed staged file content.
settings/	Supported native settings and prior Desk handoff context.
sessions/	Project-scoped native session files or Bob’s project-only SQLite snapshot; empty when no conversation exists.

Inspect and extract with ordinary tar tools. Use the full pack ID from desk ls --no-trunc for the archive filename:

desk_store="${DESK_HOME:-$HOME/.desk}/store"
tar -tf "$desk_store/packs/PACK_ID.tar"
mkdir /path/to/empty-inspection-directory
tar -xf "$desk_store/packs/PACK_ID.tar" -C /path/to/empty-inspection-directory

Manual extraction lets you inspect the snapshot. For compact packs, this extracts only the saved changes; it does not fetch or reconstruct the Git baseline. Use desk move PACK_ID --to=TARGET to create a managed target with the appropriate handoff context. Ordinary tar does not apply Desk’s extraction checks or permission rules; its own options and your environment determine extraction behavior.

Git restoration

A compact pack records workspace_format: "git-v1" in desk.json, alongside the repository URL, exact commit hash, source branch and remote branch used to locate the commit. URLs omit embedded passwords, HTTPS user information, query strings and fragments. Agent settings and sessions use the same capture rules as full packs.

When restoring into a new directory, Desk fetches the repository with its built-in Go Git client, checks out the exact saved commit, and applies the saved index and working files. A branch advancing after packing does not change the restored base. If the commit is unavailable or authentication fails, the move fails and Desk cleans up the new preparation directory. Packing relies on local remote-tracking references; it cannot guarantee that the server will retain the commit later.

Public HTTPS repositories need no Git credentials. For private HTTPS repositories, set DESK_GIT_TOKEN in the destination environment. SSH remotes use the destination’s SSH agent and known-hosts verification. Desk does not copy source credentials, invoke Git credential helpers, or require a Git executable. The token is not saved in the pack or restored repository configuration.

Compact packs retain file contents, staged versus unstaged edits, deletions, untracked files, executable bits and supported relative symlinks. Ignore filtering uses repository .gitignore files and .git/info/exclude; global ignore settings are not consulted. Tracked files are retained even when an ignore rule matches. Changed files are stored whole, so editing a large binary still stores that file.

Repository history, local configuration, hooks, other local branches, stashes and empty directories are not captured. Git filters and Git LFS are not run; source working-file bytes are preserved as captured. Use --workspace-format=full when you need the original repository state or ignored files, or must restore offline. Full packs may still depend on external submodule or linked-worktree repositories.

Moving in the original project directory uses its current files and Git state. It does not fetch a repository or apply the saved workspace changes.

File handling

Packs publish only after capture completes. Desk refuses to overwrite a pack and restores into a new private directory. On extraction or preparation failure, Desk attempts to remove that new directory. Cleanup can fail if the filesystem refuses removal. A failed agent launch retains the prepared workspace and HOME.

Full snapshots copy the workspace without Git ignore filtering, including hidden and untracked files. Compact snapshots follow the Git rules above. Supported native settings and session paths use filters that exclude known credential filenames. Prior .desk-handoff contents are carried forward as-is, without another credential-filter pass. Desk does not scan file contents for secrets. Packs are plaintext and may contain project secrets and conversation content.

Only relative symlinks whose paths stay within their captured tree are accepted. Absolute symlinks are rejected even when they point inside that tree. Unsupported special files, such as sockets and FIFOs, block packing when included in capture.

Desk restores directories with mode 0700 and regular files with mode 0600, retaining the owner executable bit (0700 for executable files), subject to the process umask. It does not preserve original ownership or full file permissions. Desk’s extraction confines filesystem access to the new destination and rejects unsafe archive paths and link targets.

Source writers must remain stopped throughout capture. Ordinary filesystem packing cannot provide a consistent live snapshot while arbitrary writers change files.

Source directory and pack selection

The project field in desk.json records the canonical absolute source directory. desk move --to=TARGET selects the newest capture with that exact directory path. Directories with the same name remain distinct; symlinks resolve to the same path. An explicit pack ID lets you restore a pack from any directory. The match is exact, not a search through parent directories. --project selects another directory for this lookup. If no pack matches, Desk asks you to pack first.

Bob state

When the source has Bob conversations, Desk builds a database snapshot containing all tasks for the chosen project, their messages and attribution history, and migration records. Selecting --session identifies the handoff conversation; it does not limit the snapshot to that one task. Unrelated project tasks and global key/value state are excluded from this database snapshot. A project with no conversation gets an empty sessions directory instead.

For a database snapshot, unsupported schemas, active project tasks, pending approvals, and parent/child task relationships crossing project boundaries block capture. Expired task locks are cleared in the snapshot.

These exclusions apply to the derived Bob session database. Files you keep in the workspace follow the selected workspace format.

Local moves use the existing project directory when it matches the selected pack’s source path. The target works on the existing project files. work/AGENT_ID/home holds preparation and handoff files.

Claude text history is installed in the local Claude projects directory. Bob text history is installed as native messages in the local ~/.bob/db/bob.db. These records contain extracted user and assistant text, not replayable tool history.