dsh-session-import-codex

English | 中文

An out-of-tree DeepSeek Harness plugin and PowerShell-friendly CLI for importing Codex conversation history. It reads the official Codex App Server stable history methods, converts completed turns into validated Harness session events, persists them through the selected profile's public services, and creates or reuses workspaces from historical working directories.

The primary workflow is a one-shot CLI. The /import-codex chat command remains available for development and targeted fallback use.

What the CLI imports

• all non-archived interactive Codex conversations returned by thread/list with archived: false;
• completed, interrupted, and failed turns that can be represented by the current converter;
• only reasoning summaries by default; raw reasoning content is never imported;
• sessions under deterministic ids such as codex-<thread-id>.

Active conversations are skipped. Existing destination ids never rewrite session logs; a durable rerun refreshes their cold projections and repeats idempotent workspace attachment. A malformed source is reported and does not stop the remaining batch.

The importer never reads Codex rollout files, desktop state, SQLite databases, or private JSONL files. It never writes Harness persistence files directly.

Install from npm

Requirements:

• Node.js ^22.19 or >=24;
• pnpm 10;
• a working codex command on PATH;
• the DeepSeek Harness CLI, either installed or run from its source checkout.

Install the npm package through Harness so the target profile dependency and bundle layer are updated together:

dsh plugin --profile web add dsh-session-import-codex

When running Harness from source:

$harnessPath = Read-Host 'Path to your DeepSeek Harness checkout'
Set-Location $harnessPath
pnpm dsh plugin --profile web add dsh-session-import-codex

No plugin checkout or consumer-side build is required. The npm tarball contains the compiled lib/ files.

Pair with dsh-llm-codex for a complete Codex migration

This importer moves your Codex conversation history into DSH. To also carry over your Codex login and subscription, pair it with dsh-llm-codex (npm package dsh-llm-codex): a DSH LLM adapter plugin that reuses your local Codex CLI login (~/.codex/auth.json) and lets DSH keep using ChatGPT subscription models (such as gpt-5.6-sol) without an API key.

Install it the same way:

dsh plugin --profile web add dsh-llm-codex

Both plugins build on the same codex login credential: this importer starts the Codex App Server to read history, while the adapter serves ChatGPT subscription models in DSH. Together they migrate your full Codex usage habit into DSH:

• conversation history and workspaces → this plugin;
• login credential, subscription models, and quota → dsh-llm-codex.

Develop from source

Clone and build the plugin. The lockfile resolves development dependencies from the public npm registry; the Harness checkout does not need to be a sibling directory.

git clone git@github.com:xing01l/session-import-codex.git
Set-Location session-import-codex
pnpm install --frozen-lockfile
pnpm build
$pluginPath = (Get-Location).Path
Set-Location $harnessPath
pnpm dsh plugin --profile web add $pluginPath

Recommended PowerShell migration

The supported write workflow is offline because the profile stores do not expose a profile-wide writer lock:

1. Stop the target dsh --profile web process with Ctrl+C.
2. Run a dry run.
3. Run the real migration.
4. Restart the Web profile.

Run the profile-installed npm binary to validate every eligible conversation without writes:

pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" exec dsh-import-codex --profile web --dry-run

Perform the migration:

pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" exec dsh-import-codex --profile web

Restart Harness afterwards with dsh --profile web, or from its source checkout:

Set-Location $harnessPath
pnpm dsh --profile web

The CLI prints complete counts and per-thread failure diagnostics in the terminal. A durable run creates or reuses one Harness workspace for each imported session whose historical cwd still exists, then attaches the session. It never creates missing directories.

Run from a source checkout

Set-Location $pluginPath
pnpm import:codex -- --profile web --dry-run
pnpm import:codex -- --profile web

For a short global development command, link the source checkout:

pnpm --dir $pluginPath link --global
dsh-import-codex --profile web --dry-run

CLI reference

dsh-import-codex [--profile <name>] [--dry-run] [--json]

• --profile <name> selects the Harness profile; default: web.
• --dry-run validates source histories and destination collisions without session or workspace writes.
• --json suppresses human progress and emits one JSON document.
• --help prints usage.

Machine-readable validation example:

pnpm import:codex -- --profile web --dry-run --json

Exit codes:

Code	Meaning
0	Batch completed without import or workspace failures. Existing destinations and active skips are expected outcomes.
1	Fatal composition, startup, App Server, or whole-batch failure.
2	Batch completed, but one or more conversations or workspace attachments failed.
130	Interrupted by the user with Ctrl+C.

Rerunning the command is safe: deterministic destination ids prevent duplicate session creation, existing title projections are refreshed from their stored logs, and workspace attachment is idempotent.

Chat-command fallback

These are Harness chat commands, not PowerShell commands:

/import-codex <thread-id> --dry-run
/import-codex <thread-id>
/import-codex --all --dry-run
/import-codex --all

The command result appears as a compact row in the current chat. It persists imported sessions but does not switch the current chat to an imported session. Refresh the Web sidebar after a chat-command import.

Architecture

The package remains an ordinary Harness bundle:

• cordis.patch.yml inserts the shared importer and chat-command plugin;
• the standalone launcher boots the selected profile's non-surface bundle layers;
• cli.patch.yml adds the startup and one-shot runner plugins;
• durable runs add cli.workspace.patch.yml, which composes the same public storage-domain, workspace, and session-projection-cache plugins used by the Web bundle;
• both adapters consume ctx.codexSessionImport;
• App Server processes use ctx.subprocess, sessions use ctx.sessionPersistence, and workspace changes use ctx.workspaceRegistry.

The launcher excludes the known Web and headless surface bundles, so the migration process does not start an HTTP server or an agent task.

Configuration

The bundle row exposes these Cordis configuration fields:

Field	Default	Purpose
codexCommand	codex	Codex executable name or path.
requestTimeoutMs	30000	App Server request deadline.
shutdownGraceMs	3000	Graceful App Server termination window.
maxDiagnosticBytes	65536	Maximum captured process diagnostic bytes.
listPageSize	100	thread/list page size.
reasoningPolicy	summary	Import validated summaries or omit reasoning entirely.

Override the session-import-codex row through the target profile's cordis.patch.yml; both the CLI and chat command consume the same resolved configuration.

Troubleshooting

profile "web" does not include dsh-session-import-codex means the bundle is not installed in that profile. Run the dsh plugin ... add command above.

codex resolution or initialize failures mean the CLI cannot start a compatible Codex App Server. Confirm codex --version and codex app-server --help work in the same PowerShell session.

Exit code 2 is a completed partial migration. Read the [import] and [workspace] lines: import failures usually indicate unsupported history/schema data; workspace failures usually mean a historical cwd no longer exists.

If sessions imported with version 0.1.0 show the workspace basename instead of their Codex titles, update this plugin to 0.1.1 or newer, stop the Web profile, rerun the durable import command once, and restart Web. The rerun rebuilds title projections without rewriting conversation logs.

Do not run a write migration while the target Web/headless profile is still running. Stop it, rerun the CLI, then restart it.

Development checks

pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm pack --dry-run
git diff --check

Maintainer npm release

The package is published to the official npm registry even when the local install registry is a mirror. Confirm that the version is not already published, authenticate to npmjs, then publish; prepublishOnly runs tests, typecheck, and lint, while prepack rebuilds lib/.

npm view dsh-session-import-codex versions --registry=https://registry.npmjs.org/
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
pnpm publish --access public --registry=https://registry.npmjs.org/

Do not publish until the matching Git commit is pushed to https://github.com/xing01l/session-import-codex.

Contributing and security

See CONTRIBUTING.md for the development workflow. Report vulnerabilities privately as described in SECURITY.md; do not attach conversation history or credentials to public issues.

License

Released under the MIT License.