dsh-serenity-plugin

In one line: this plugin turns an ordinary directory into an AI workspace. Inside it, the agent gets memory, discipline, tools and boundaries — swap the model, reboot the machine, come back tomorrow, and it picks up where it stopped.

🔵 This file is a short English orientation, not a second manual. The authoritative README — tool inventory, mechanical constraints, entry points, FAQ — is the Chinese one: README.md. Keeping two full translations is a second source of truth that silently drifts (this file had already fallen several releases behind), so it deliberately stays short.

What it is / is not

Supported host bands = peerDependencies in the package package.json. Current version = CHANGELOG.md. Runtime state = the dashboard health tool. None of these are written into prose.

Quick start (2 minutes)

Needs Node ≥ 20 (or bun) and a supported DSH release line.

# 1 install (joins the DSH web profile automatically)
dsh plugin --profile web add @shgroup/dsh-serenity-hooks

# 2 restart dsh web (plugin and web UI take effect together)
dsh web

# 3 verify: open a session inside a directory that has a .serenity marker
#   · the session starts with the container identity and the skill catalog
#   · a status capsule appears next to the session title (green dot + SAFE slider)
#   · run `dashboard health` — the three self-checks should all pass

Uninstall: dsh plugin --profile web remove @shgroup/dsh-serenity-hooks

From source (when you change the code):

git clone https://github.com/tellmewhattodo/dsh-serenity-plugin.git
cd dsh-serenity-plugin
dsh plugin --profile web add link:$(pwd)/hooks/dsh-serenity-hooks

⚠️ Do not use dsh plugin add github:… — that URL points at the repository root, not at the plugin package, so nothing loads.

A workspace is a directory plus one marker file:

my-workspace/
├── .serenity            ← marker: this directory is a workspace (without it the plugin does nothing)
├── .opencode/skills/    ← domain skills: one body of knowledge per domain, may carry small tools
├── AGENT_SESSIONS/      ← the vault: one directory per cognitive trajectory; SESSION.md is its body
└── _tmp/                ← images and files pasted into the conversation land here

Safe mode: flip the SAFE slider in the capsule and bash is removed from the agent's tool list — it cannot see it and cannot call it. The switch belongs to the human side only.

Where to go next

Development

pnpm typecheck   # types (node + web client)
pnpm test        # full test suite (vitest)
pnpm build       # bundle (lib/index.js + client.js)

• One-stop dev script: scripts/dsh-develop.ts (typecheck / test / build / commit / push / version / bump / deploy / lockfile / host-upgrade / restart-web / publish / pack-check / github-push).
• 🔴 After touching dependencies in package.json, run lockfile and commit the lockfile.
• Host type baseline = devDependencies (paths in both tsconfigs point inside the repo).
• The package README is generated from the repo-root README (dsh-develop readme-sync).

License

MIT (see LICENSE)