# dsh-command-opt

[![CI](https://github.com/csiroqa/dsh-command-opt/actions/workflows/ci.yml/badge.svg)](https://github.com/csiroqa/dsh-command-opt/actions/workflows/ci.yml)

A **command-optimization** plugin for DeepSeek Harness (DSH): Tab/Enter command completion, argument-format guidance with a persistent hint popup, a patch for tool-opened (subagent) conversations, and blank-conversation command-output repair.

中文版：[README.md](README.md)

## Features

- **Tab/Enter completion**: type `/prefix` in the composer and press Tab (or Enter while a menu candidate is highlighted) to complete from the current session's command catalog — works anywhere in the draft; prefix-first with a menu-aligned fuzzy fallback, recently used commands ranked first; multiple matches extend to the longest common prefix, then cycle on repeated Tab; ↑↓ menu highlight wins — both Tab and Enter complete the selected command
- **Argument-format guidance**: completing a hinted command at line start enters the claim directly, with the parameter format (input hint) shown as ghost text aligned with the input; in the claim phase Tab cycles `|`-separated options (e.g. `/plan off|message`)
- **Persistent hint popup**: registered on `conversation.input.overlay` with the same anchor and style as the built-in menu — while typing arguments it stays visible under the command, highlighting the parameter currently being filled (multi-parameter commands like `/schedule` keep their hints after you start typing); candidates are shown as a fallback whenever the built-in menu is not displayed (name followed by parameters instead of description)
- **Tool-opened (subagent) conversations patch**: the built-in command directory is empty for subagents, so such conversations had "no options" and could not run `/archive` etc. — this plugin reads the host catalog directly, shows command options in the popup, executes full commands on Enter, and adds an "Actions" menu in the conversation header (archive / duplicate session / jump to parent)
- **Blank-conversation output repair**: after running `/command` in a fresh session the output renders normally, header action buttons appear, and the session is no longer reused/merged by the "New Conversation" flow
- **Catalog caching**: prefetch on `/` typing, invalidation on `commands/change` and `agent-preset/selected`, TTL fallback, per-session in-flight coalescing, pruning on session removal

## Configuration

After installation the `command-opt` row in `cordis.patch.yml` supports the following optional config (note: by DSH design the browser half never receives patch config — defaults live in the code, editing config does not change browser behavior):

| Key | Default | Description |
| --- | --- | --- |
| `tabComplete` | `true` | Tab/Enter command completion |
| `hintPopup` | `true` | Hint popup (conversation.input.overlay) |
| `subagentPatch` | `true` | Tool-opened (subagent) conversations patch |
| `blankEngage` | `true` | Blank-conversation output repair |
| `catalogTtlMs` | `15000` | Command catalog TTL (ms) |

## Installation

Prerequisites: Node.js >= 22, pnpm, and a local `deepseek-harness` checkout (dependencies use `link:` into `../deepseek-harness`).

```sh
git clone https://github.com/csiroqa/dsh-command-opt.git
cd dsh-command-opt
pnpm install
pnpm build

# Install into the web profile (link: points at this directory)
dsh plugin --profile web add link:$(pwd)        # POSIX
dsh plugin --profile web add link:D:\path\to\dsh-command-opt   # Windows
```

Restart `dsh web` and hard-refresh the browser (**Ctrl+F5**).

## Usage

1. Type `/` + prefix and press Tab to complete the command name (multiple candidates extend to the common prefix first, then cycle on repeated Tab; ↑↓ selection makes both Tab and Enter complete the selected item)
2. After completing a hinted command at line start (e.g. `/schedule`), the argument position engages directly: the ghost hint shows the parameter format, Tab cycles `|`-separated options, and the popup stays visible while you fill the parameters
3. In tool-opened conversations: Enter runs full commands such as `/archive` directly; the header "Actions" menu offers archive / duplicate session / jump to parent
4. After running a command in a blank session: output renders normally, header buttons appear, and the session is no longer reused by the next "New Conversation"

## Compatibility

- **Platforms**: Windows / macOS / Linux (Node >= 22) — three-platform builds and smoke tests are verified by [GitHub Actions CI](https://github.com/csiroqa/dsh-command-opt/actions)
- Developed against DSH `0.1.1-rc.2` checkouts; uses the public `dsh-client-runtime` surface, with a few internals (session activation via `handleBlank`/`promptAttempted`, list summary `recordMutation`) guarded by runtime feature detection with silent degradation
- **Known limitations**: blank-conversation activation is browser-side only; the host summary still reports blank, so the session disappears from the list after a page reload (until a real turn starts); the browser half never receives patch config — defaults are baked into the code
- Build: `tsdown` (host half `lib/index.js` + browser half `lib/client.js` in the standard `window.__ModuleLoader__.load` closure-factory format)

## Security

- The plugin only affects the local page; no network listening
- Installed with `link:` pointing at this directory; after changing the source, rebuild (`pnpm build`) and hard-refresh to apply

## License

**MIT License** (see [LICENSE](LICENSE)).

Feel free to use, modify, reference, or bundle this project into your own plugin collection — just keep the `LICENSE` file and copyright notice, and credit the source.

## Related

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
- Sibling plugins: [dsh-schedule](https://github.com/csiroqa/dsh-schedule) (scheduled tasks + status monitoring), [dsh-hotkeys](https://github.com/csiroqa/dsh-hotkeys) (global hotkeys), [dsh-plugin-usage-report](https://github.com/csiroqa/dsh-plugin-usage-report) (usage stats)