Quick start

Requirements: Node.js 22.19 or later in the 22.x line, or Node.js 24 or newer, plus a DeepSeek API key for live model turns.

npm install --global @agi-fans/oh-my-dsh
omdsh

Run /login once inside omdsh to validate and save your DeepSeek API key, then start a conversation. To try it without a global installation, run npx @agi-fans/oh-my-dsh.

Highlights

• Durable conversations: resume sessions, rewind to a human turn, retry, compact, and export complete transcripts as Markdown.
• Harness-native workflows: use plugin-owned commands, permissions, models, reasoning effort, plans, goals, todos, Skills, MCP servers, approvals, and user questions.
• Rich terminal input: search project files with @, paste clipboard images, reuse persistent prompt history, edit multiline prompts externally, and retrieve queued follow-ups.
• Readable tool activity: follow streaming calls, inspect distinct Input and Output sections, expand long results, and keep domain-specific presentation owned by tool plugins.
• Live operational context: see model, reasoning effort, workspace, Git state, context pressure, tokens, TTFT, throughput, cache, timings, turns, and steps without leaving the composer.
• Responsive by design: retain settled transcript layout, coalesce scroll updates, emit row-level terminal diffs, and preserve correct display-cell alignment for CJK text and emoji.

Learn

• Tutorials — complete a first task, add precise context, guide queued work, recover long sessions, and customize the environment.
• Skills and MCP — extend a project with reusable instructions and external tools.
• Architecture — understand the plugin boundaries and runtime data flow.
• Performance — inspect the benchmarks, methodology, and rendering optimizations.

Why oh-my-dsh

DeepSeek Harness provides a capable agent runtime and a strong architectural idea: everything is a plugin. oh-my-dsh brings that runtime into a calm, keyboard-driven terminal experience without creating a second agent core or hiding Harness behind a parallel abstraction.

The TUI remains a presentation and interaction layer. Sessions, tools, permissions, models, Skills, MCP servers, commands, and telemetry come from Harness services and plugins; omdsh composes them into a terminal application and adds the interface behavior needed to use them comfortably.

The project follows four principles:

• Harness-native: use published DeepSeek Harness packages as the source of truth for agent behavior, state, and lifecycle.
• Real plugin boundaries: create plugins for independently owned lifecycles and contribution points, not for every source file.
• One terminal owner: keep raw input, cursor state, viewport management, and atomic rendering inside the local TUI Provider.
• Progressive disclosure: keep the default view concise while making tools, telemetry, settings, and session detail discoverable on demand.

Reference checkouts under refs/ remain read-only research material. Runtime code depends only on published packages and oh-my-dsh workspace packages.

Architecture

DeepSeek Harness plugins and services
                │
                ▼
  @agi-fans/dsh-tui — terminal capability seam
                │
                ▼
  @agi-fans/oh-my-dsh — boot and plugin composition

The TUI package is split into a service definition, local terminal Provider, session and interaction adapters, tool-presentation bridge, command contributions, and interactive Runner. This isolates terminal ownership from Harness domain state and exposes plugin seams only where a capability has an independent lifecycle or owner. See the architecture overview for the current boundaries and data flow.

Performance

Performance is part of the TUI architecture: durable sessions replay in linear time, Harness Projections avoid repeated history scans, settled transcript blocks retain formatted layout, and the terminal writer emits row-level diffs. On the documented Apple M5 Pro environment, restoring 10,000 conversation turns takes a median 2.15 ms, 10,000 tool calls take 21.21 ms, and cached updates over a 5,000-turn surface average 0.24 ms per frame.

See the reproducible TUI performance report or run pnpm benchmark:tui locally.

Configuration

Run /login to open the DeepSeek API Key dashboard, enter a key in a masked prompt, validate it, and save it through the Harness credential store. An interactively selected key takes priority over an inherited DEEPSEEK_API_KEY on subsequent requests and across restarts. /logout removes the omdsh-managed choice and falls back to the environment when available.

Model settings can also come from $DSH_HOME/settings.yaml. Skills and MCP configuration are documented in Skills and MCP.

After an upgrade, omdsh can show release notes once at startup. Use /changelog for recent entries or /changelog full for the complete packaged history. A cached daily npm check reports newer versions without installing anything automatically; both behaviors can be customized in /settings.

Development

pnpm install
pnpm omdsh "list files"  # run from source
pnpm typecheck           # check TypeScript
pnpm test                # unit and pipe-mode tests
pnpm build               # build all workspace packages
pnpm smoke               # interactive PTY smoke test
pnpm smoke:happy         # mock-LLM happy path

The checkouts in refs/deepseek-harness and refs/oh-my-pi are read-only references. Do not use them as runtime dependencies or modify them while developing omdsh.

Changelog

User-visible changes and release history are tracked in CHANGELOG.md.

Acknowledgements

oh-my-dsh exists because of two projects:

• DeepSeek Harness provides the runtime foundation, plugin architecture, and the conviction that agent capabilities should be composable rather than embedded in one application.
• oh-my-pi demonstrates how thoughtful terminal interaction, compact information design, and careful keyboard workflows can make an agent feel fast and approachable.

Thank you to both projects and their contributors. omdsh is an independent community project: it is built on DeepSeek Harness and learns from OMP, but is not an official distribution of either project.

License

oh-my-dsh is available under the MIT License.