Getting started

Pack. Move. Work.

Install Desk

Desk supports Linux and macOS on x64 and ARM64, including Linux inside WSL. With Node.js 20 or newer and npm installed, run:

npm i -g @centillex/desk
desk --help

On Windows, run the installation command inside your WSL Linux terminal, using Node.js and npm installed in WSL.

Keep npm’s optional dependencies and install scripts enabled. npm installs a native Go executable built with CGO_ENABLED=0. Desk embeds SQLite and needs no Node.js, SQLite installation, or C toolchain at runtime.

Install the agent you want to use separately: Claude, Codex, Qoder, or Bob.

Save a project

Stop the source agent and other processes writing your project, then run:

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

Desk prints a pack ID and its tar archive path. Your original files remain in place. A pack includes the workspace, supported native settings, and the project’s sessions. Known credential filenames are filtered from native agent state. Packs can contain project secrets and conversation content and are stored in plaintext.

If exactly one source agent can be detected, desk pack is sufficient.

Choose what travels with your workspace

Availability

Compact Git capture is the default in Desk 0.2.6 and later. npm 0.2.5 uses full workspace snapshots and does not have --workspace-format.

For a Git project, desk pack saves the repository URL, exact commit, and local changes. It keeps staged edits, unstaged edits, deletions, and untracked files. The pack excludes Git history and files matched by repository ignore rules, such as dependency directories and build output.

Run from the repository root with a committed HEAD available from an HTTPS or SSH remote. Desk checks saved remote-tracking references without contacting the server. If compact capture is unavailable, the command explains why and stops.

Use a full snapshot for a non-Git directory, ignored files you need to keep, or restoration without repository access:

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

--workspace-format=auto explicitly allows a full snapshot when compact capture is unavailable. See desk pack for the requirements and storage and archives for the saved contents.

Move to another agent

Install and configure the target agent before launching it. From the same project directory, use its latest saved pack:

desk move --to=codex

Desk keeps the current project directory and restores readable conversation text into Codex’s native session storage. Codex uses your existing HOME, configuration and login. Desk prints the working directory and HOME.

To choose a particular pack, or restore it from another directory, supply its ID:

desk move PACK_ID --to=codex

Restoring a compact pack into another directory requires repository access and the exact saved commit. Moving in the original directory uses its current files and does not fetch Git.

Without an ID, Desk matches the source directory recorded in the pack metadata. If none exists, run desk pack first. Pack again to include new changes.

--to accepts claude, codex, qoder, and bob. Source and target must differ. Bob launch currently supports version 2.0.2.

See what Desk saved

desk ls
desk ps
desk ps -A

ls shows saved packs. In Desk 0.2.5 and later, ps shows only verified running agents managed by Desk. Use ps -A to include saved history and supported native harness processes started outside Desk. See desk ps for availability and the managed/unmanaged distinction.

Storage location

Desk stores data in ~/.desk/store by default. Set DESK_HOME=/path/to/desk to use /path/to/desk/store. Use the same setting across Desk commands. Capture individual projects that do not contain the active store.

desk ls uses short IDs, relative creation times and readable archive sizes. Use desk ls --no-trunc for full IDs; move accepts unique ID prefixes. See storage and archives for the directory layout.

Pick up moved work later

Use your agent’s native continue or resume command in the moved workspace with your normal HOME. Follow the examples for Claude, Codex, Qoder, or Bob.

Prepare a cloud machine

Create a Linux host on Vultr or connect an existing SSH host with desk machine. Save the machine once, check its readiness, and open a shell by name.

See the machine guide for setup, release availability, and connection options.

Supply approved credentials

Desk 0.3.0 adds optional Centillex Secrets integration. Connect the document keys your project needs, then approve credentials for an individual task or agent launch. Begin account setup with:

desk secrets onboard

Follow the Secrets setup guide to create a project, connect a capability, and approve your first request. Packing, moving, listing agents, and managing machines work without Secrets.