Run from source

git clone https://github.com/pikselkroken/pixlstash-lmstudio
cd pixlstash-lmstudio
npm install
lms dev   # hot-reload; the plugin appears in LM Studio's plugin list

Edit anything under src/ and save — lms dev rebuilds via esbuild and re-registers the plugin automatically. Open LM Studio, set the gear-icon config to point at your PixlStash, and start a chat.

Source layout

src/
├── index.ts            # plugin entry — registers config + the prediction loop
├── config.ts           # global + per-chat config schemas
├── predictionLoop.ts   # the act() loop + the show_pixlstash_image tool
└── pixlstash.ts        # PixlStash API client + image pipeline + scope resolution

The plugin is a prediction-loop handler (not a Tools Provider or Generator). It drives the user-selected model via model.act() with one tool (show_pixlstash_image); the tool's implementation runs the PixlStash search and renders the picture itself in an assistant content block — so the model doesn't have to echo any markdown. See CLAUDE.md for the full rationale (and the dead-ends we tried before landing here).

Commands

npm run typecheck   # tsc --noEmit, covers src/ and test/
npm test            # node --import tsx --test test/*.test.ts
npm run build       # tsc -p tsconfig.build.json → dist/
lms dev             # hot-reload dev server

Tests

The pure helpers (describeError, downscale, collectUsedIds, makeLeadingNoiseStripper) have unit tests under test/ using Node's built-in test runner (node:test + node:assert/strict), with tsx as a loader so the suite runs .ts directly with no build step:

npm test

The wider PixlStash HTTP path (fetchImageMarkdown, resolveScopeId) isn't unit-tested — it needs lms dev against a real PixlStash to exercise the network/file/jimp pipeline end-to-end. If you add a non-trivial branch to those functions, smoke-test it manually with lms dev before opening a PR.

Releasing a new version

The plugin is distributed through the LM Studio Hub under pikselkroken/pixlstash-lmstudio (set in manifest.json). End users install it from the Hub (either from inside LM Studio's plugin browser, or with lms clone pikselkroken/pixlstash-lmstudio on the CLI).

Pre-flight checks

npm run typecheck   # tsc --noEmit
npm run build       # tsc → dist/
lms dev             # smoke-test in LM Studio: load a model, run one turn

If anything in src/ changed, bump version in package.json per semver — patch for fixes, minor for features, major for breaking config/behaviour changes.

Publish

lms push uploads the current folder to the Hub as a new revision (the first push creates the artifact; later pushes add revisions). To keep the upload tidy, scrub dev artifacts first:

npm run clean       # removes dist/ and .lmstudio/ (keeps node_modules)
lms login           # one-time (or after the session expires)
lms push            # uploads as pikselkroken/pixlstash-lmstudio

node_modules/ is left alone so you can keep working; the LM Studio Hub bundles your plugin from src/ on install, so users don't need our node_modules/.

Optional flags worth knowing:

• lms push --private — first publish only; marks the artifact private.
• lms push --write-revision — writes the new revision number back into manifest.json so it lands in git.
• lms push --description "…" — overrides the manifest description for the Hub listing.

After publishing

Verify the published version actually works for a fresh install:

cd /tmp && lms clone pikselkroken/pixlstash-lmstudio

…then open LM Studio and confirm the plugin loads and runs a turn end-to-end. If something is missing (e.g. dependencies didn't bundle), fix it locally, bump the patch version, and re-publish.

Reporting issues

Please file bugs and feature requests at the issue tracker. Useful info to include:

• LM Studio version and the model you had loaded.
• Whether your PixlStash server is on http:// or self-signed https://.
• The relevant lms dev console output (logs lines starting with PixlStash: cover most of the runtime path — search returned …, injected picture #…, scope … not found, etc.).

Pull requests

• Run npm run typecheck and npm run build locally before opening a PR.
• Keep changes focused; if a PR touches both the search pipeline and the prediction-loop wiring, split it.
• For non-trivial behavior changes, update CLAUDE.md so the architecture notes stay in sync.