Documentation

Getting started

Nomad runs on your own machine. It needs Node.js 22 or newer and reads agents from the folders their platforms already use, such as ~/.openclaw, ~/.claude, ~/.codex and ~/.hermes.

Start

npx thenomad

Nothing to install first. If you use Nomad often, install it once with npm install -g thenomad and type nomad instead. Nomad keeps its library, backups and receipts in ~/.nomad. Set NOMAD_HOME to use another folder.

Open the dashboard

npx thenomad ui

This opens the dashboard in your browser, served from 127.0.0.1 with a one time session token. Only your machine can reach it. Everything the command line does is available there, including the migration wizard.

Your first move

Run nomad with nothing after it. It finds the agents on this computer, asks which one and where it should go, shows a short summary of what will move and asks once. That is the whole flow.

The same thing in one line:

nomad move openclaw claude-code      move, with a summary and one question
nomad move openclaw ./kestrel.nomad  save to a file you can share or keep
nomad move ./kestrel.nomad codex     open that file somewhere else
nomad restore <backup-id>            undo (the command is printed after every move)

Add --dry-run to only see the summary, --details for every file and diff, and --yes in scripts. A backup is always taken before anything is written.

Signed packages

nomad move openclaw ./kestrel.nomad --sign signs the file with a key Nomad creates for you. Anyone opening it sees who signed it: you, someone they trust, or an unknown key. If a single byte changed after signing, Nomad reports a broken signature. nomad keys shows your fingerprint, and nomad trust kestrel.nomad --name Ada trusts the key that signed a file you received.

Sources and destinations

Wherever a command takes a source you can pass:

Destinations for nomad move are a platform (codex), a platform with a folder (claude-code:~/work/app) or a file ending in .nomad. Platforms without a default location, such as Cursor, use the current folder.

Conflict modes

Command reference

nomad scan                      find platforms and agents
nomad adapters [--platform id]  capabilities per platform
nomad list                      agents in your library
nomad inspect <source>          what an agent contains
nomad                           guided move
nomad move <from> <to>          move to a platform or a .nomad file
nomad export <source> [--sign]  write a .nomad file
nomad import <pack> [--to id]   import, optionally into a platform
nomad migrate --from --to       the long form of move, every option
nomad keys | trust | untrust    signing keys
nomad validate <pack>           check a package
nomad versions <agent>          version history
nomad compare <agent> 1 3       compare versions
nomad compare --left --right    compare two locations
nomad backup <agent>            snapshot an agent's files
nomad backups | restore <id>    list and restore backups
nomad duplicate <agent>         copy under a new identity
nomad sync <agent>              push primary to other locations
nomad history | receipt <op>    past operations
nomad mcp [--allow-writes]      MCP server for assistants
nomad ui                        local web app

Global flags: --json, --quiet, --verbose, --home. Exit codes: 0 success, 1 error, 2 usage, 3 approval needed, 4 invalid package, 5 verification failed, 6 rolled back.

Use it from an assistant

nomad mcp exposes listing, inspection, compatibility checks, previews and exports to any MCP client. It is read only unless started with --allow-writes, and even then an assistant can only apply a preview by quoting its token. Replace mode, edited files and broader permissions also need --allow-replace.

Plugins for Claude Code, OpenClaw and Hermes live in the plugins/ folder of the repository. Continue with the agent format or the platform matrix.