# oh-dsh

> A single DSH runtime packaged into Electron desktop, browser Web, and terminal TUI interfaces. All three share sessions, skins, plugin marketplace, and local workspace, without separate environment installations.

## Metadata

- Author: [@hust-open-atom-club](https://github.com/hust-open-atom-club)
- Repo: <https://github.com/hust-open-atom-club/oh-dsh.git>
- GitHub: [hust-open-atom-club/oh-dsh](https://github.com/hust-open-atom-club/oh-dsh)
- Stars: 255
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://dsh.openatom.club/>
- Topics: `ai-agent`, `cordis`, `dsh`, `dsh-plugin`, `dsh-plugins`
- Forks: 22
- Open Issues: 23
- Last push: 2026-08-20T11:53:01.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:hust-open-atom-club/oh-dsh
```

## Wiki

## One-Line Pitch
Packages DeepSeek Harness, Node runtime, and local development tools into three installable distributions: Desktop, Web, and TUI. All three share the same DSH runtime, sessions, skins, and plugin marketplace, while each retains independent Profiles and interfaces.

## Core Features
- Launch Desktop (Electron), Web (browser shell), or TUI (terminal) with the same `ohdsh` command; the three interfaces share sessions, credentials, skin selections, and plugin cache
- All three endpoints use `~/.ohdsh` as the shared data root for sessions, configurations, skins, plugins, and credentials; `OH_DSH_HOME` changes the directory uniformly without needing separate configuration for each endpoint
- Built-in local development workspace: Workspace, PTY terminal, browser panel, file browser, Side chat, and Trajectory are organized into collapsible, dockable, split-view panels
- Provides Git Review: View changes and commit diffs in the workspace, add review comments to code lines, and complete branch, commit, and push operations in the same sidebar
- Shared plugin marketplace: Desktop, Web, and TUI can all search, preview, install, uninstall, and rollback plugins; a unified transaction manager ensures consistent installation flow for both UI and Agent operations
- Cross-endpoint skins `@oh-dsh/skins`: Desktop uses CSS themes, Web uses DSH theme tokens, TUI uses `/theme` to switch palettes; the same skin ID behaves consistently across all three endpoints
- Built-in `view_image` vision tool (`@oh-dsh/vision`): Performs OCR, image understanding, and UI diagnosis on workspace local images, HTTP(S) images, or image data URLs; defaults to Zhipu glm-4.6v-flash, switchable to local Ollama models

## Technical Implementation
- **Language**: TypeScript (strict ESM, TypeScript 6.0+) + Node.js subprocess orchestration
- **Key Dependencies**: `electron` (Desktop wrapper), `electron-updater` (auto-update), `@deepseek-ai/dsh-base` + `@deepseek-ai/dsh-web-app` (pinned DSH runtime), `pnpm` 11 (plugin workspace management)
- **Architecture Pattern**: Cordis plugin patch mechanism (`cordis.patch.yml`) stacks eight host/client plugins (`@oh-dsh/desktop`, `@oh-dsh/skins`, `@oh-dsh/sidebar`, `@oh-dsh/panel-controls`, `@oh-dsh/pinned-summary`, `@oh-dsh/plugin-marketplace`, `@oh-dsh/vision`, `@oh-dsh/better-sidebar-runtime`) on top of DSH; the `ohDshSurface` service (`plugins/shared/surface.ts`) lets each plugin adapt to desktop/web/tui form factors
- **Entry Points**: `src/cli.ts` (unified CLI launcher), `src/main.ts` (Electron main process), `src/web.ts` (Web startup), `src/tui.ts` (TUI startup), `src/plugin.ts` (Desktop Host-side plugin)

## Use Cases
Developers who want to use DSH with the same configuration across desktop, browser, and terminal, especially those who need an IDE-style workspace beyond CLI/IDE editors (with sidebar, bottom panel, split-view) and native desktop interactions (system menus, shortcuts, auto-update). Suitable as a long-term local primary tool: auto-migrates old data, separates distributions by endpoint to avoid Electron weighing down pure terminal/server environments.

## Prerequisites & Compatibility
| Dependency | Minimum Version | Notes |
|---|---|---|
| Node.js | >=24 | Not required separately; distributions include a fixed Node runtime version |
| macOS | 12.0+ (arm64/x64) | Provides DMG and zip with auto-update support; first launch requires unblocking in "Settings → General" |
| Windows | x64 | Provides NSIS installer and portable version; auto-update support |
| Linux | x64 | Provides AppImage and deb; AppImage supports auto-update |
| Native Modules | electron, node-pty, electron-updater | Loaded via Electron on Desktop; non-Desktop endpoints don't depend on these |
| pnpm | 11.20 | Used internally for builds and plugin transactions; included in distributions |

## Installation
```bash
dsh plugin --profile web add github:hust-open-atom-club/oh-dsh
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `OH_DSH_HOME` | Environment Variable | Unified data root directory shared by Desktop/Web/TUI | `~/.ohdsh` |
| `DSH_OH_WEB_HOST` / `--host` | String | Listen address after Web startup | `127.0.0.1` (loopback only) |
| `DSH_OH_WEB_PORT` / `--port` | Integer | Web listen port; `0` for random | `3080` |
| `DSH_OH_WEB_OPEN` / `--open` / `--no-open` | Boolean | Whether to auto-open browser after startup | Opens by default in interactive terminal |
| `--trusted-host` | String (repeatable) | Required when Web listens on non-loopback addresses | Empty |
| `DSH_OH_WEB_HOME` / `DSH_OH_TUI_HOME` / `--data` | Path | Data root specifically for Web or TUI | Inherits from `OH_DSH_HOME` |
| `OH_DSH_SURFACES` | Comma-separated List | Limits available interfaces for current distribution (desktop/web/tui) | All three enabled |
| `DSH_OH_TUI_LANG` / `--lang` | `zh` or `en` | TUI initial interface language | Determined by upstream TUI |
| `DSH_OH_TUI_FULLSCREEN` / `--fullscreen` / `--inline` | Boolean | Whether TUI uses alternate screen | Fullscreen enabled by default |
| `DSH_OH_TUI_PRESET` / `--preset` | String | Agent preset used on TUI startup | `standard` |
| `DSH_OH_TUI_SESSION_ID` / `--resume` | Session ID | TUI to resume an existing session | New session |
| `ZHIPUAI_API_KEY` / `DASHSCOPE_API_KEY` | Environment Variable | Cloud key for vision tool (@oh-dsh/vision) | None (defaults to Zhipu) |
| `oh-dsh-vision` in `~/.ohdsh/settings.yaml` | YAML | Switch vision backend address, model, timeout, max image bytes, max retries | See docs/usage.md |

## FAQ
**Q: Do I need to install Node or DSH runtime separately after installing oh-dsh?**

A: No. Each distribution includes a fixed version of Node and DSH runtime; just extract and run. It won't require users to pre-install any runtime environment.

**Q: Is data shared between Desktop, Web, and TUI?**

A: Yes. All three endpoints share `~/.ohdsh` by default for sessions, credentials, skins, plugin cache, and plugin state; setting `OH_DSH_HOME` changes the unified data root.

**Q: Can I expose oh-dsh Web to others on my LAN?**

A: Yes, but you must explicitly add `--trusted-host`. Web defaults to listening on 127.0.0.1; using 0.0.0.0 without trusted-host will be rejected by `parseLaunchArgs`.

**Q: Can I install plugins in TUI mode?**

A: Installation transactions can be executed on all three endpoints, but only plugins that declare TUI support will actually take effect in TUI. Use `/plugins` command or Ctrl+M for plugin management in TUI.

**Q: Do plugin installation requests by humans and Agents go through the same flow?**

A: Yes. Humans and Agents share the same transaction manager with four phases: preview, risk approval, apply, and rollback. Agents cannot bypass approval to directly modify the current Profile.

**Q: Can I migrate old Oh-DSH-Desktop data to the new shared directory?**

A: On first launch of new Desktop or Web, it automatically migrates sessions, plugins, and skin preferences from the old `Oh-DSH-Desktop` app data directory or `~/.oh-dsh-web/dsh` to `~/.ohdsh`; old directories are not modified for rollback. (See `src/data-root.ts:262-350`)

**Q: Will running two oh-dsh processes simultaneously cause conflicts?**

A: Data won't be corrupted, but only one process can write to `~/.ohdsh`. Write locks are negotiated via `tryAcquireRuntimeLock`; other processes enter read-only mode to view history and cannot write active sessions; write capability auto-restores after lock release.

**Q: How does oh-dsh handle image recognition?**

A: All three endpoints share the built-in `@oh-dsh/vision` plugin, providing the `view_image` tool for OCR, image understanding, and UI diagnosis on workspace images, HTTP(S) images, or image data URLs; defaults to Zhipu glm-4.6v-flash, configurable in `~/.ohdsh/settings.yaml` to switch to local Ollama/LM Studio models.

**Q: Are both macOS arm64 and Windows x64 supported?**

A: Yes. Distributions cover macOS arm64/x64, Linux x64, and Windows x64; packaging scripts `dist:mac`, `dist:linux`, `dist:win`, `dist:web`, `dist:tui` produce different builds.

**Q: Where can I find version numbers and release notes?**

A: All interfaces display the unified version from repository tags (`src/version.ts` parses the latest reachable tag); detailed macOS, Windows, Linux, Web packaging steps and signing requirements are in `docs/usage.md`.

## Learning Curve
Beginner — All three endpoints share the same data. Users already familiar with DSH can directly start with `ohdsh desktop|web|tui`; only scenarios like custom vision backends or exposing Web across origins require modifying `settings.yaml` or environment variables.

## Known Issues & Limitations
- Starting Web on non-loopback addresses requires explicit `--trusted-host` declaration on the command line, otherwise `parseLaunchArgs` rejects it (`src/web.ts:200-208`)
- TUI can only run in truly interactive terminals: if stdin/stdout is not a TTY, `tui.ts:233-236` exits with an error
- Desktop may trigger "Cannot verify developer" on first macOS launch due to unsigned code; unblock in "Settings → General" (see `docs/usage.md`)
- Unsigned Windows installers also trigger SmartScreen; choose "More info → Still run" (see `docs/usage.md:59-61`)
- Web runtime will be force-killed by `DshRuntimeSupervisor` with `SIGTERM` if no `dsh web: <url>` line is printed within 60 seconds (`src/runtime.ts:123-127`)
- Auto-update depends on signed builds; when macOS/Windows signing credentials are missing, CI falls back to ad-hoc/unsigned installers and disables auto-update (see `docs/usage.md:333-347`)
- In Desktop's isolated preview (`OH_DSH_MARKETPLACE_PREVIEW=1`) and read-only view mode (`OH_DSH_READ_ONLY=1`), the plugin marketplace Host is explicitly disabled (`plugins/plugin-marketplace/src/index.ts:46-58`)
- Data migration from old `Oh-DSH-Desktop` and `~/.oh-dsh-web/dsh` is non-destructive; old directories are preserved for rollback, but existing shared entries from the same source are not overwritten (`src/data-root.ts:262-350`)

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [oh-dsh](https://deepseek-plugin.org/plugins/hust-open-atom-club/oh-dsh)
Wiki generated by AI (model: `MiniMax-M2.5`)