One-Line Positioning

This plugin is a DeepSeek Harness adapter for the Petdex desktop floating window: it normalizes DSH Web's session lifecycle events into 5 states, POSTs them to Petdex desktop's built-in local hook server (127.0.0.1:7777), and makes that pixel pet switch animations based on the task you're running in DSH — jumping when started, running when busy, raising its hand waiting for your approval, waving when done.

Core Features

• Listens to three types of session lifecycle events from DSH Web: session/created, session/disposed, session/event
• Normalizes events like turn, step, tool, workflow, goal, compaction into five Petdex states: jumping / running / waiting / waving / failed
• Subagent events are folded into the top-level session's same card — no new cards are opened for subagents
• Approval requests (approval/asked, approval/decided) only reflect as "raising hand to get your attention" state, never approving or rejecting any operations on your behalf
• Uses token authentication to POST normalized results to local 127.0.0.1:7777's /state and /bubble endpoints, never carrying prompts, tool parameters, or model outputs
• When Petdex desktop is not running, the entire delivery chain fail-opens, never affecting DSH's normal operation

Technical Implementation

• Language: JavaScript (ESM, source is .js; Cordis bundle is not TS)
• Key Dependencies: No third-party dependencies; only uses Node built-ins node:fs/promises, node:os, node:path, no npm packages
• Architecture Pattern: Cordis plugin (cordis.patch.yml registers id: petdex-dsh-bridge, inject: ["sessions"]); after listening to official lifecycle events, normalizes, deduplicates, rate-limits (queue limit 64, 300ms timeout per request), delivers "event projection" to Petdex desktop's built-in hook server via loopback HTTP
• Entry File: src/index.js (exports apply, createBridge, projectionToRequests, name, inject), normalization logic in src/normalize.js

Use Cases

You're running tasks with DSH Web on macOS while the Petdex desktop floating window is open: after installing this plugin, the pet will animate based on your current work status in DSH — jumping when starting a task, becoming busy when running tools, raising its hand when needing your approval, waving when done. It's suitable for people who "一边跟 DSH 对话，一边用浮窗上的小动物确认任务在不在跑" (use DSH for dialogue while confirming tasks are running via the floating window's little animal).

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:crafter-station/petdex/packages/petdex-desktop-native/integrations/dsh

The actual installation flow is triggered by Petdex desktop App's Settings → Agents → DeepSeek Harness → Install: the desktop attempts to write the embedded petdex-dsh-plugin-0.1.0.tgz (SHA256固化) to ~/.petdex/integrations/dsh/0.1.0/, then runs npx ... dsh plugin --profile web add --ignore-scripts <tarball> via macOS login shell. After installation completes, you must manually restart DSH Web.

Configuration

This plugin requires no additional configuration. The apply(ctx, config = {}) receives config defaulting to empty object, and the plugin only reads options.deliver (used for test-injected mock delivery function), never reads any user configuration at runtime.

The only implicit constraint comes from Petdex desktop's install command: DSH version is hardcoded to 0.1.0-rc.6, pnpm is hardcoded to 11.19.0, cannot be changed via plugin configuration.

FAQ

Q: After installation, why does Petdex still show "Restart DSH Web"?

A: This plugin is a Cordis bundle and won't be hot-loaded by DSH. After successful installation, you must manually restart npx @deepseek-ai/dsh web once, then start or continue a real task — only then will Petdex read handshake info from ~/.petdex/runtime/dsh-handshake.json and show Connected. Simply opening DSH doesn't trigger any events, handshake won't complete.

Q: Will the plugin send my prompts, tool parameters, or model outputs to Petdex?

A: No. The plugin only listens to official session lifecycle events, and after normalization only projects states (jumping/running/waiting/waving/failed), display text, session ID, sequence number, and event type; prompts, tool parameters, model outputs, and approval content are all discarded. POST only goes to local 127.0.0.1:7777 and requires token authentication from ~/.petdex/runtime/update-token.

Q: Clicking the pet should jump to DSH's current session, why does it only open the default browser?

A: V1 doesn't have precise browser tab positioning capability. Clicking the pet only activates the current macOS default browser, won't jump to any URL, won't open new tabs, and won't distinguish which tab DSH occupies. This is the current intentionally preserved fallback behavior, not a bug.

Q: I installed DSH in a custom directory (DSH_HOME points to non-~/.dsh), how to configure?

A: Set the same-named DSH_HOME in Petdex process's runtime environment. Petdex started from Finder won't inherit variables only exported in interactive shell; if DSH uses a custom home, you need to inject DSH_HOME into Petdex process's visible environment before installation, otherwise Petdex won't find the profile.

Q: After uninstall, I can still see this plugin in DSH Web, what to do?

A: The uninstall command only calls dsh plugin --profile web remove @petdex/dsh-plugin, won't clean DSH profiles, sessions, models, or other plugins. After uninstall completes, you also need to manually restart DSH Web once to let the running process unload the plugin bundle.

Q: Installation command reports "Plugin command failed - check npx and network", how to troubleshoot?

A: Desktop runs npx --package=@deepseek-ai/[email protected] [email protected] dsh plugin --profile web add, requires npx and access to npm registry. Installing global pnpm is not required (command carries embedded version). Errors usually mean shell started from Finder didn't inherit PATH, registry unreachable, or desktop package's tarball hash check failed (desktop will clear handshake and report error).

Q: Can this plugin be used on Linux or Windows?

A: No. Petdex desktop itself is cross-platform, but DSH integration is macOS-first first integration slice (agent_hooks.zig comment explicitly states "DSH Web is macOS-only in the first integration slice"). On Linux/Windows, DeepSeek Harness line in Petdex Settings will only show Not detected.

Ease of Use

Beginner — one-click install via desktop App, restart DSH Web and use immediately, no code or configuration changes needed; but understanding "why restart is needed after installation" requires glancing at Petdex's handshake file.

Known Issues & Limitations

• macOS only: Plugin doesn't restrict platform at runtime (any system that can run DSH Web can load it), but Petdex desktop's installation and status detection paths are explicitly short-circuited on non-macOS, Linux/Windows users won't see installation entry
• No precise browser tab positioning: Clicking the pet only activates default browser, won't jump to DSH's current session
• Both install/uninstall require manual DSH Web restart: Cordis bundle doesn't hot-load, state machine goes from restart_required to connected only after user restart + real events
• DSH version hardcoded to 0.1.0-rc.6 on desktop side: Plugin's package.json doesn't declare DSH compatibility; if DSH upgrades to incompatible version, desktop needs to sync update version string in dsh_integration.zig
• Delivery queue limit 64, 300ms timeout per request: Under extreme high-frequency events, non-critical progress events get merged and dropped, but all intervention (approval) and terminal (turn.completed/failed/blocked) events retain priority
• Petdex started from Finder won't inherit interactive shell environment variables: Custom DSH_HOME must be explicitly injected into desktop process's visible environment

---

What is Petdex

Petdex is three things working together:

1. A web gallery at petdex.dev where the community submits, reviews, and showcases animated pets in the Codex sprite format.
2. A CLI that installs any pet on your machine with one command and ships them straight into Codex.
3. A desktop app that floats a pet on your screen and reacts to your coding agent's activity in real time.

Every pet is a folder. Every folder is a Pokédex entry. Every entry is one npx petdex install away.

Quick start

Follow this checklist to get a pet installed, visible in Codex, and connected to the desktop app.

1. Install a known pet:

npx petdex install boba

You should see ~/.petdex/pets/boba/ with pet.json and a spritesheet.

2. Get the desktop app from petdex.dev/download. It runs on macOS, Linux and Windows.

3. Open it, then hit Cmd+, over the pet to open Settings. Pick your pet under Pets, and connect your coding agents under Agents with one click each. No terminal involved.

The pet floats above your workspace and animates on every tool call your agent makes.

For users

Full CLI reference: packages/petdex-cli/README.md.

For builders

If you want to build on top of Petdex (a desktop client, a wearable, an SDK, a Discord bot, anything), you have two stable surfaces:

• The HTTP API. petdex.dev/api/manifest returns every approved pet with its slug, spritesheet URL, animation states, and metadata.
• The pet package format. Every pet is a pet.json plus a spritesheet.{webp,png} rendered as an 8x9 grid of 192x208 frames, or the v2 8x11 grid.

21 open-source and source-available projects already build on these. See petdex.dev/built-with for the catalog, then submit yours via the issue template.

Architecture

crafter-station/petdex
├── src/
│   ├── app/[locale]/          Public site: gallery, /pets/<slug>, /collections, /built-with, /community, /create, /download, /submit, /u/<handle>, ...
│   ├── app/api/cli/           CLI endpoints: OAuth config, submit (zip → presigned R2), dedup check, register
│   ├── app/api/manifest/      Public manifest: every approved pet with its spritesheet URL
│   ├── app/api/admin/         Admin review surface for submissions, edits, collection requests
│   └── lib/db/schema.ts       Drizzle schema (Postgres)
├── packages/
│   ├── petdex-cli/            npm `petdex` catalog client (auth, list, install, submit)
│   ├── petdex-desktop-native/ Native SDK floating mascot for macOS, Linux and Windows
│   ├── petdex-desktop-windows/ Legacy Tauri Windows implementation (not the release path)
│   └── discord-bot/           Discord.js bot for the Petdex server
├── public/built-with/         Screenshots for the community page
├── public/brand/              Logos, OS icons, Discord icon
└── drizzle/                   SQL migrations (Postgres schema history)

Web stack: Next.js 16, React 19, Tailwind, Drizzle, Postgres, Redis, Clerk, R2.
CLI: Bun + TypeScript, ships as a single npm binary. Auth via Clerk OAuth + PKCE.
Desktop: Native SDK app with an in-process Zig hook server on 127.0.0.1:7777. The current release path has no WebView or Node sidecar.

Develop locally

Two paths are supported.

git clone https://github.com/crafter-station/petdex.git
cd petdex
bun install
bun run dev:docker

Open localhost:3000. Full guide in CONTRIBUTING.md.

Pet package format

Every pet is two files:

my-pet/
├── pet.json                Metadata: name, slug, tags, vibes, kind, frame size, animation states
└── spritesheet.webp        8x9 or v2 8x11 frame grid of 192x208 px each (or .png)

The native renderer supports nine state rows: idle, running-right, running-left, waving, jumping, failed, waiting, running, and review. Codex and the supported coding agents map their activity hooks to these states. The v2 8x11 atlas leaves two additional rows available to the consuming client.

Contribute

• Submit a pet: petdex.dev/submit or npx petdex submit <path>.
• List your project: open a Built with Petdex issue.
• Fix a bug or add a feature: read CONTRIBUTING.md, then open a PR.
• Hang out: Discord has channels for shipping (#wip, #ship-or-sink), feedback (#cli-feedback), and showcases (#showcase).

Pet IP and takedowns

Pets are user-submitted fan art. Petdex does not claim rights to any underlying IP. If you hold rights to a character and want a pet removed, file a takedown request and we review within 48 hours.

License

The source code is MIT. Pet assets are owned by their submitters under whatever license they choose to declare.

---