HuaShen (化身)

Export and import opencode config, sessions, agents, skills, commands, plugins and MCP servers as portable bundles.

化身 (HuaShen) means "avatar / incarnation" — this tool lets your opencode identity travel between machines. Pack everything into a single .hsb (HuaShen Bundle, a tar.gz archive) and restore it elsewhere. Pick exactly what to carry: just config, just one session, or the whole shebang.

Install

pip install huashen

Or with pipx (recommended):

pipx install huashen

Provides two console commands: huashen and the short alias hs.

Quick start

# Export everything (config + all sessions + agents + skills + commands + auth)
huashen export -o my-avatar.hsb

# Export only config and skills, no secrets
huashen export -o lite.hsb --no-sessions --no-auth

# Export a single session by id (or by fuzzy title match)
huashen export -o one.hsb --session ses_08578bbd5ffeohc37zQcMhYNCP
huashen export -o one.hsb --session "prevent system sleep"

# List what is in a bundle without importing
huashen info my-avatar.hsb

# Import everything from a bundle (use --dry-run first to preview)
huashen import my-avatar.hsb --dry-run
huashen import my-avatar.hsb
huashen import my-avatar.hsb --only config,sessions --merge-sessions

What it can carry

Secrets (auth.json + inline apiKeys inside provider.*.options.apiKey) are off by default. Pass --with-auth to include them; the bundle is then printed with a red warning. Treat .hsb files containing auth like plaintext passwords.

Bundle layout

A .hsb is a tar.gz with this structure:

manifest.json            # what's inside, versions, timestamps, checksums
config/
  global/opencode.json
  global/opencode.jsonc
  global/.gitignore
  project/opencode.json  # only if a project config was found
agents/...
commands/...
skills/...
plugins/...
auth.json                 # only when --with-auth
sessions/
  opencode.db.dump.sql    # filtered SQL dump of session/message/part/todo/event
  index.json              # per-session metadata + which rows belong to it
logs/
  opencode.log            # only when --include-logs

Import modes

• Overwrite (default): replaces matching files/rows with the bundle's version.
• Merge sessions: --merge-sessions keeps existing sessions and only inserts ones whose id is missing. Useful when importing a single session into an existing database.
• Selective: --only config,skills,agents imports just those components from the bundle.

Exit codes

• 0 success
• 1 generic error (bad bundle, IO failure)
• 2 nothing to do (e.g. export with everything disabled)
• 3 dry-run abort (intentional)

License

GPL-3.0-or-later. See LICENSE.