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

Each uncompressed 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/	Entire project tree.
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. 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.

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.

The workspace is copied without Git ignore filtering, including hidden and untracked files. 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 are still subject to the full workspace-copy behavior above.

Local moves use the existing project directory when it matches the selected pack’s source path. The extracted workspace remains a snapshot; the target works on the existing project files. Its HOME and native task database stay under work/AGENT_ID/home.

Claude text history is installed at home/.claude/projects/PROJECT_KEY/SESSION_ID.jsonl. Bob text history is installed as native messages in home/.bob/db/bob.db. These records contain extracted user and assistant text, not replayable tool history.