Metadata-Version: 2.4
Name: huashen
Version: 0.1.0
Summary: HuaShen (化身) — export and import opencode config, sessions, agents, skills, commands, plugins and MCP servers as portable bundles.
Project-URL: Homepage, https://github.com/cycleuser/HuaShen
Project-URL: Repository, https://github.com/cycleuser/HuaShen
Project-URL: Issues, https://github.com/cycleuser/HuaShen/issues
Author-email: cycleuser <cycleuser@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: backup,config,export,import,opencode,portable,session
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# HuaShen (化身)

> Export and import [opencode](https://opencode.ai) 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

```bash
pip install huashen
```

Or with pipx (recommended):

```bash
pipx install huashen
```

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

## Quick start

```bash
# 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

| Component     | Default | Flag to skip           | Notes                                                                 |
| ------------- | ------- | ---------------------- | --------------------------------------------------------------------- |
| Global config | ✓       | `--no-config`          | `~/.config/opencode/opencode.json(.jsonc)` + `.gitignore`             |
| Project cfg   | ✓       | `--no-project-config`  | `./opencode.json(.jsonc)` and `.opencode/opencode.json` if present    |
| Agents        | ✓       | `--no-agents`          | `~/.config/opencode/agent(s)/` + `.opencode/agent(s)/`                |
| Commands      | ✓       | `--no-commands`        | `~/.config/opencode/command(s)/` + `.opencode/command(s)/`            |
| Skills        | ✓       | `--no-skills`          | `~/.config/opencode/skill(s)/` + `.opencode/skill(s)/`                |
| Plugins       | ✓       | `--no-plugins`         | `*.ts/*.js` in `.opencode/plugin(s)/`                                 |
| MCP / auth    | ✗       | n/a (opt-in)           | `auth.json` and provider `apiKey` fields — off by default             |
| Sessions      | ✓       | `--no-sessions`        | SQLite rows for session/message/part/todo + event log                 |
| Logs          | ✗       | n/a (opt-in)           | `--include-logs` to also bundle `opencode.log`                        |
| Cache / repos | ✗       | n/a                    | Never exported (regenerable)                                          |

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](LICENSE).