# dsh-everything-search

Instant filename search for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) agents, backed by [voidtools Everything](https://www.voidtools.com/). Registers two host-side agent tools:

- **`everything_search`** — whole-index filename queries in **milliseconds** (reads the NTFS MFT index, never a slow recursive directory walk), with optional path scoping, `node_modules`/`.git` noise filtering, and exact/prefix/substring ranking.
- **`everything_status`** — reports whether the Everything backend is usable, where `es.exe` was found, and what to do if it is not.

> ⚠️ **Windows-only.** Everything indexes NTFS volumes on Windows; on other platforms the tools return a clear error telling the agent to fall back to the regular `glob`/`grep` tools.

## Install

Requires [pnpm](https://pnpm.io/) and a [DSH profile](https://github.com/deepseek-ai/deepseek-harness).

```bash
# into the web profile (the default GUI profile)
dsh plugin --profile web add github:Argonaut790/dsh-everything-search

# or into the desktop profile
dsh plugin --profile desktop add github:Argonaut790/dsh-everything-search
```

If `pnpm add` is blocked from running the package's build scripts, add the exact key pnpm printed under `allowBuilds` in `<profile>/pnpm-workspace.yaml`, then re-run.

### Backend requirements

The tools shell out to `es.exe` (the Everything command-line interface). It is discovered from, in order:

1. the `EVERYTHING_ES` environment variable,
2. `~/.dsh/bin/everything/es.exe` (the portable Everything layout used by DSH Desktop),
3. `Program Files` / `Program Files (x86)` / `%LOCALAPPDATA%` Everything installs,
4. `es.exe` on `PATH`.

Install Everything from <https://www.voidtools.com/> (or run the portable copy under `~/.dsh/bin/everything`). Everything must be running (it stays in the tray); if it is installed but not running, the plugin attempts to start it once with `Everything.exe -startup` and retries.

## Tools

### `everything_search`

| Parameter      | Type    | Default | Description |
| -------------- | ------- | ------- | ----------- |
| `query`        | string  | —       | Filename substring (case-insensitive). `*`/`?` pass through as Everything search syntax. |
| `root`         | string  | —       | Absolute Windows folder to scope the search to (e.g. `Z:\Programming\SmartQuestApp`). Omit for the whole machine. |
| `limit`        | integer | 50      | Max results (cap 200). |
| `skipNoise`    | boolean | `true`  | Drop `node_modules`/`.git` paths from results. |
| `content`      | boolean | `false` | Search file contents instead of names (requires Everything content indexing). |
| `caseSensitive`| boolean | `false` | Match case exactly. |

Results are ranked like the GUI file tree: exact name match, then prefix, then substring; shorter paths first; alphabetical tie-break. Each hit is `{ path, name, isDir }` (folders are excluded — they are found via path prefixes anyway).

### `everything_status`

No parameters. Returns `backend`, `esPath`, `reachable`, optional `error`/`detail`, and a human-readable `hint`.

## Design rules

- **Never falls back to a slow recursive directory walk.** If Everything is missing or not running, the tool returns a structured error telling the agent to use `glob`/`grep` instead.
- Queries are literal substrings by default; Everything's own search syntax is passed through when the query contains `*` or `?`.
- Output is lossless JSON (no `undefined` values), so results pass dsh-tools validation.

## Development

```bash
git clone https://github.com/Argonaut790/dsh-everything-search.git
cd dsh-everything-search
pnpm install            # pulls @deepseek-ai/dsh-tools for type-checking/imports
node .test-tmp/run-test.mjs   # standalone smoke test against the real es.exe
```

To use a local checkout instead of the published repo:

```bash
dsh plugin --profile web add link:/absolute/path/to/dsh-everything-search
```

## License

[Apache-2.0](./LICENSE)