dsh-shell-command: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A DeepSeek Harness (DSH) plugin. It adds:

1. A /! command (run one shell command, analyze output, inspired by Claude Code's ! gesture)
2. A /terminal command (interactive PTY popup; transcripts persist automatically when the session received input, and are referenced into the model on demand from a history tab — closing never itself sends anything to the model)

Note: DSH's input trigger system only supports / and @ as trigger characters (hardcoded in dsh-client-ui-input-trigger/lib/types/types.d.ts). We cannot use a bare ! prefix like Claude Code does, so we use /! instead.

Not a git repository (no .git) — this is a working checkout, not something to run git log/git diff against for history.

Commands

node test/unit.mjs           # pure parse/format tests, no dependencies
node test/smoke.mjs          # full apply() + handler against a mock context
node test/smoke-terminal.mjs # terminal registry + hasInput tracking + history-reference RPC (mock)

There is no build step (lib/client.js is hand-authored, no bundler) and no lint script configured in package.json.

The smoke tests import the real @deepseek-ai/* peer packages. Outside of a DSH profile install, link them once:

mkdir -p node_modules/@deepseek-ai
ln -s "$HOME/.dsh/profiles/node_modules/@deepseek-ai/"* node_modules/@deepseek-ai/

To exercise the plugin live, install it into a profile (dsh plugin --profile web add "link:/path/to/dsh-shell-command") and restart dsh web.

Architecture

Two independent execution paths

1. Single-command (/!) — Client-side input trigger (lib/client.js) registers under trigger: "/", name-matched to ! (candidates/matchSpace/matchEnter all key off the literal /! token). Handler flow: user types /! ls → client calls RPC /shell-bang-rpc → host (lib/index.js) does parse.js → exec.js → format.js → message.js → agent.followup. This path requires connection and agents services. It checks agent.session.requestHeader() — if the session has no model request context yet, it refuses with an error message (mirroring dsh-btw behavior).