hiShare

中文文档

hiShare creates portable handoff packets and resumable native sessions between Claude Code and Codex. Source agent stores remain read-only: hiShare indexes metadata, loads only a selected transcript, and creates a new target session without editing the original JSONL file.

Install

Building or installing from source requires Rust 1.95 or newer:

cargo install --path crates/hishare-cli
hishare --version

Prebuilt binaries for v0.1.0 are available on GitHub Releases. The release includes:

• hishare-aarch64-apple-darwin.tar.xz
• hishare-x86_64-apple-darwin.tar.xz
• hishare-aarch64-unknown-linux-gnu.tar.xz
• hishare-x86_64-unknown-linux-gnu.tar.xz
• hishare-x86_64-pc-windows-gnu.zip
• source.tar.gz
• hishare-installer.sh, hishare-installer.ps1, checksums, and hishare.rb

Install the latest release with the shell installer:

VERSION=v0.1.0
curl --proto '=https' --tlsv1.2 -LsSf \
  "https://github.com/harrychih/hiShare/releases/download/${VERSION}/hishare-installer.sh" | sh

$Version = "v0.1.0"
irm "https://github.com/harrychih/hiShare/releases/download/$Version/hishare-installer.ps1" | iex

Each release plan also creates a Homebrew formula artifact named hishare.rb. After downloading that formula from a published release, install it directly with brew install --formula ./hishare.rb. Stable tap installation and automatic formula publication require a separate writable external Homebrew tap and release credential; this repository does not create or publish that tap automatically yet.

From an uninstalled source checkout, commands can instead use this prefix:

CARGO_INCREMENTAL=0 cargo run --locked -p hishare -- sessions refresh --home "$HOME"

The remaining examples use the installed hishare binary.

Select A Session

Refresh creates the rebuildable metadata index at $HOME/.hishare/index.sqlite. The index contains catalog metadata and diagnostics, not transcript bodies. If an incompatible pre-release index exists, move the index and its SQLite sidecars aside and refresh again; never delete or move native sessions.

hishare sessions refresh --home "$HOME"
hishare sessions list --home "$HOME"
hishare sessions list --home "$HOME" --agent claude --project hishare --since 2026-07-01
hishare sessions tree --home "$HOME" --agent codex --project hishare --since 2026-07-01

The second list column is the short hiShare ID, such as claude:<hash>. The final column is the native software session ID for reference. show and export accept the complete short ID or an unambiguous prefix; ambiguous prefixes fail and print candidates.

hishare sessions show --home "$HOME" --id 'claude:<unique-prefix>'
hishare sessions show --home "$HOME" --id 'claude:<unique-prefix>' --full-tools

show prints private transcript content. By default it bounds large tool output; use --full-tools only in an appropriate local terminal.

Import A Resumable Session

Create a new target-agent session in the same project with the redacted translated transcript, tool history, attachments, and continuation brief:

hishare sessions import \
  --home "$HOME" \
  --id 'claude:<unique-prefix>' \
  --to codex

# Override the source project when needed:
hishare sessions import \
  --home "$HOME" \
  --id 'codex:<unique-prefix>' \
  --to claude \
  --project /path/to/project

The command prints the new native session ID and an exact resume command such as codex resume <id> or claude --resume <id>. It creates the target session but does not start an agent or make a model call. Native import is deliberately version-gated because it writes vendor-owned formats: this revision supports Codex 0.144.4 and Claude Code 2.1.210 exactly, and rejects untested versions before writing.

Export A Handoff

An export atomically publishes three sibling artifacts. On Unix, hiShare normalizes generated files to mode 0600 and managed directories to 0700. On Windows, hiShare does not configure or verify local-user-only ACLs; outputs inherit the machine's local ACL policy, so owner-only access is not claimed there.

• handoff.json: the complete redacted audit packet.
• handoff.md: the continuation brief delivered to the target agent.
• handoff.redaction.json: rule IDs, JSON pointers, and replacement counts without original secret values.

hishare sessions export \
  --home "$HOME" \
  --id 'claude:<unique-prefix>' \
  --to codex \
  --output /tmp/handoff.json

hishare validate /tmp/handoff.json

For a known source path, use the direct form:

hishare export --from claude --to codex \
  --home "$HOME" \
  --input tests/fixtures/claude_basic.jsonl \
  --output /tmp/handoff.json

--home is optional for direct export. When supplied, that home controls imported MCP, skill, and plugin context instead of the operator's default home.

The deterministic brief is the default and requires no model call. Its default maximum is 32,000 estimated tokens; the accepted minimum is 16. Set another valid limit with --max-brief-tokens. Optional --summarize claude and --summarize codex polish only the already-redacted deterministic draft with an ephemeral local agent process, fall back to deterministic output on failure, and still pass the final budget and secret gates.

--archive keep is the default. --archive copy writes a validated copy to the managed archive, normally $HOME/.hishare/archive, or to --archive-dir; the native source remains byte-for-byte unchanged.

Validate And Launch

The committed packet schema is schemas/hishare.packet.v1.json, for schema version hishare.packet.v1. Generate the exact current schema and validate a packet plus its sibling brief with:

hishare schema --output /tmp/hishare.packet.v1.json
hishare validate /tmp/handoff.json

Validation applies JSON Schema, semantic checks, sibling digest agreement, and final raw-packet/Markdown secret scans. Supported degradation warnings are printed by stable code without making an otherwise valid packet fail.

Launch defaults to dry-run; --dry-run and --execute are mutually exclusive. It verifies the packet target and sibling brief, writes a private prompt (0600 on Unix; inherited, unverified local ACLs on Windows), and sends brief content through stdin, never a prompt-file path: claude -p for Claude and codex exec - for Codex.

hishare launch --target codex --packet /tmp/handoff.json --dry-run
hishare launch --target codex --packet /tmp/handoff.json --execute

--execute is the only form that starts a target agent. A usable source working directory is inherited; otherwise launch stays in the current directory and reports a warning.

Diagnose Safely

doctor refreshes the index and reports aggregate format coverage without message text. Redacted JSON hashes source paths and untrusted diagnostic labels while preserving aggregate counts, and is the preferred support artifact:

hishare doctor --home "$HOME" --json --redact-paths

Malformed and truncated records become warning codes or isolated scan issues. One unusable file does not abort discovery, listing, browsing, or export of another session.

Browse Locally

Start the private browser, navigate by agent and project, inspect the scrollable transcript, and create a resumable target session from the import controls:

hishare sessions serve --home "$HOME" --port 0 --open

Port 0 selects an available port. The server binds only to 127.0.0.1, validates the loopback Host, creates an unguessable per-process URL token, sends no permissive CORS header, and stops with the command. Keep the URL private; browser exports also require the token in X-hiShare-Token.

Bootstrap and catalog responses contain UI assets, metadata, counts, and diagnostics only. Transcript pages load only after selection. Every text, reasoning, tool, result, and attachment preview is capped at 8 KiB on a UTF-8 boundary; explicit Load more requests fetch byte ranges capped at 8 KiB, return a continuation offset, and stay below a 64 KiB serialized response ceiling. sessions browse is the compatibility alias and may write a small URL-only .html shell with --output; it never writes a standalone transcript page.

Verification And Evaluation

The required local quality gates are:

CARGO_INCREMENTAL=0 cargo fmt --all -- --check
CARGO_INCREMENTAL=0 cargo clippy --workspace --all-targets --locked -- -D warnings
CARGO_INCREMENTAL=0 cargo test --workspace --locked
CARGO_INCREMENTAL=0 cargo test -p hishare-core committed_packet_schema_is_fresh --locked

Parser and redaction fuzz targets use nightly Rust and cargo-fuzz:

cd fuzz
cargo +nightly fuzz build parse_claude
cargo +nightly fuzz build parse_codex
cargo +nightly fuzz build redact_value

.github/workflows/fuzz.yml runs bounded scheduled/manual fuzzing. .github/workflows/live-eval.yml is manual and optional: it deliberately requires the selected vendor credential, makes live model calls, and uploads only eval-report.json with agent/version, numeric case indexes, and per-fact scores. It is not a pull-request gate. The equivalent local evaluator is explicit and also makes a live agent call:

hishare eval --agent codex \
  --cases tests/eval/cases.json \
  --output /tmp/eval-report.json \
  --require-pass

CI checks the locked MSRV 1.95 workspace and tests Linux, macOS, and Windows. Local verification covers only the current host; configured cross-platform release archives are built by tag-gated GitHub jobs.

Current Limits

• Native import is limited to the exact tested Claude Code and Codex versions documented above; newer vendor formats require an explicit compatibility update.
• MCP servers, skills, and plugins are descriptive metadata, not executable definitions or credentials.
• The browser is loopback-only, not a shared web service.
• No external Homebrew tap is published; install the formula artifact (hishare.rb) from the GitHub Release manually.