Metadata-Version: 2.4
Name: everyfile
Version: 2026.4.21
Summary: Zero-dependency Python CLI for Voidtools Everything search. Pure Python IPC via ctypes — no DLL required.
Author: LouisGameDev
License-Expression: MIT
Project-URL: Homepage, https://github.com/LouisGameDev/everyfile
Project-URL: Repository, https://github.com/LouisGameDev/everyfile
Project-URL: Issues, https://github.com/LouisGameDev/everyfile/issues
Keywords: everything,search,voidtools,cli,ctypes,ipc,file-search
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# everyfile

[![CI](https://github.com/LouisGameDev/everyfile/actions/workflows/ci.yml/badge.svg)](https://github.com/LouisGameDev/everyfile/actions/workflows/ci.yml)

## Table of Contents

| | Section | What's inside |
|---|---------|---------------|
| **Intro** | [What is Everything?](#what-is-everything) | Why Everything beats Windows Search, benchmark comparison |
| | [Features](#features) | Capabilities at a glance |
| **Setup** | [Install](#install) | |
| | [Prerequisites](#prerequisites) | Windows, Python ≥ 3.11, Everything running |
| | [CLI](#cli--search-files-from-the-terminal) | `pip install everyfile` — `ev` command |
| | [Python API](#python-api--search-files-from-code) | `from everyfile import search` |
| | [MCP Server](#mcp-server--give-ai-assistants-file-search) | `pip install everyfile[mcp]` + client config |
| | [Agent Skill](#agent-skill--teach-any-ai-agent-to-use-everything) | `npx skills add LouisGameDev/everyfile` |
| | [OpenClaw](#openclaw--use-everything-from-openclaw-agents) | Skill + MCP for OpenClaw gateway agents |
| | [Install from source](#install-from-source) | Editable dev install |
| | [Command aliases](#command-aliases) | `ev`, `every`, `everyfile` |
| **CLI** | [Quick Start](#quick-start) | First commands to try |
| | [Using Results](#using-results-with-other-commands) | VS Code, delete, copy, grep, jq, pagination |
| | [Examples](#examples) | Sort, filter, regex, count, pipes, `ev filter`, `ev pick`, output modes |
| **CLI Reference** | [Fields](#fields) | `-f` / `--fields` options and groups |
| | [Sorting](#sorting) | `--sort` options, default order |
| | [`ev filter` flags](#ev-filter-flags) | Structured NDJSON filtering flags |
| | [Search Syntax](#everything-search-syntax) | Operators, wildcards, functions, macros, size/date filters |
| | [Instance Management](#instance-management) | Multi-version Everything, `--instance`, env var |
| | [Service Info](#service-info) | `--version`, `--info`, `--instances` |
| **Python API** | [Python API](#python-api) | `search()`, `count()`, `Cursor`, `Row`, `Everything` class, error handling |
| **Internals** | [Versioning](#versioning) | CalVer scheme, release workflow |
| | [Architecture](#architecture) | Module layout, IPC approach |
| | [MCP Server](#mcp-server) | `search_files`, `count_files`, `aggregate_files`, `get_everything_info` tools |
| | [Development](#development) | Clone, install, type-check, test |
| | [See Also](#see-also) | External links |
| | [License](#license) | MIT |

A zero-dependency Python CLI for [Voidtools Everything](https://www.voidtools.com/) search.

```powershell
ev ext:py path:fixtures -n 5
```

<!-- example:hero -->
```
views.py  2026-04-17 00:00  webapp\src\api  652 B
models.py  2026-04-16 23:00  webapp\src\db  608 B
serializers.py  2026-04-16 22:00  webapp\src\api  783 B
middleware.py  2026-04-16 21:00  webapp\src  1011 B
admin.py  2026-04-16 20:00  webapp\src  523 B

  5 of 18 results for "ext:py path:fixtures"

  ├ size      3.5 KB
  └ names     admin.py  middleware.py  models.py  serializers.py  views.py
```
<!-- /example:hero -->

## What is Everything?

[Everything](https://www.voidtools.com/) by Voidtools is a **free, lightweight file search engine** for Windows. When you install it, Everything reads the Master File Table (MFT) of every NTFS volume on your system and builds a complete filename index — typically in **under a second**, even for drives with millions of files. It then monitors the USN Change Journal to keep that index current in real time. The result: **every file and folder on your machine is searchable instantly**.

Everything runs as a small background process (~15 MB of RAM for 1 million files) and provides a rich search syntax for filtering by extension, size, date, path, content, duplicates, and more.

### Why not just use Windows Search?

| | **Everything** | **Windows Search** | **`Get-ChildItem -Recurse`** |
|---|---|---|---|
| **Speed** | **~10 ms** for any query | Seconds to minutes; often misses files | Traverses the entire filesystem every time |
| **Completeness** | Every file and folder on all NTFS volumes | Only indexes "included locations"; skips system dirs, app data, etc. | Complete, but slow |
| **Index size** | ~75 MB for 1 M files | Hundreds of MB to GB, with CPU spikes during re-indexing | No index (brute-force walk) |
| **Startup** | Indexes a fresh 1 M-file drive in ~1 s | Initial indexing can take **hours** | N/A |
| **Advanced filters** | `ext:`, `size:`, `dm:`, `dupe:`, `regex:`, `content:`, `parent:`, macros | Basic filters, inconsistent behaviour | `-Filter`, `-Include` flags |
| **Real-time updates** | Via NTFS USN journal — instant | Periodic, often delayed minutes | N/A |
| **Resource usage** | ~15 MB RAM | Heavy (SearchIndexer.exe) | Spikes CPU/disk during scan |

### See the difference yourself

Run this in PowerShell to compare a full-drive extension search:

```powershell
# Built-in: traverses every directory on C:\ (slow)
Measure-Command { Get-ChildItem C:\ -Recurse -Filter *.py -ErrorAction SilentlyContinue } | Select-Object TotalSeconds

# Everything via ev: queries the pre-built index (instant)
Measure-Command { ev ext:py -l } | Select-Object TotalSeconds
```

Typical results on a drive with ~1 M files:

| Method | Time |
|---|---|
| `Get-ChildItem -Recurse` | **30 – 120 s** |
| `ev ext:py -l` | **0.02 – 0.1 s** |

The difference grows with drive size. On multi-drive systems with millions of files, Everything stays under 100 ms while filesystem traversals can take **minutes**.

## Features

- **Instant search** — queries Everything's indexed database, returns results in milliseconds
- **Pipe-friendly** — human-readable output on stderr, NDJSON on stdout when piped
- **Pipe composition** — chain `ev` commands to filter results without re-querying
- **Zero dependencies** — stdlib + ctypes only, no DLL needed
- **Everything search syntax** — full pass-through (`ext:`, `dm:`, `size:`, `content:`, `dupe:`, regex, wildcards, macros)
- **Importable Python API** — use as a library with typed `Cursor`/`Row` objects, DB-API 2.0 semantics
- **MCP server** — expose Everything search to AI assistants (Copilot, Claude, etc.) via Model Context Protocol
- **Multi-instance support** — works with Everything 1.4, 1.5, and 1.5a side by side
- **Pure Python IPC** — communicates via ctypes `SendMessageW` / `WM_COPYDATA`, no DLL required

# Install

## Prerequisites

1. **Windows** — Everything uses NTFS and Windows IPC
2. **Python ≥ 3.11**
3. **[Voidtools Everything](https://www.voidtools.com/downloads/)** running in the background

> **New to Everything?** Download [Everything 1.5a](https://www.voidtools.com/downloads/#alpha) (recommended). It's the latest alpha with the most features, runs alongside stable versions, and is what most power users run. Install it, let it index your drives (takes ~1 second), and leave it running in the system tray.

Pick what you need — each layer builds on the one before it.

## CLI — search files from the terminal

```powershell
pip install everyfile
```

This gives you the `ev` command (plus `every` and `everyfile` as aliases):

```powershell
ev ext:py                          # find all Python files instantly
ev ext:log size:>1mb dm:today      # large log files modified today
ev server.py -n 1 -l | code -     # open first match in VS Code
```

## Python API — search files from code

Same package, just import it:

```python
from everyfile import search, count

for row in search("ext:py dm:today", limit=10):
    print(row.name, row.full_path)

print(f"Total Python files: {count('ext:py')}")
```

## MCP Server — give AI assistants file search

```powershell
pip install everyfile[mcp]
```

Add to your MCP client config (VS Code `settings.json`, Claude Desktop, etc.):

```jsonc
{
  "mcpServers": {
    "everything": {
      "command": "everyfile-mcp"
    }
  }
}
```

Your AI assistant can now call `search_files`, `count_files`, `aggregate_files`, and `get_everything_info` directly.

## Agent Skill — teach any AI agent to use Everything

Install to any [Agent Skills](https://agentskills.io/)-compatible agent (Copilot, Claude Code, Cursor, Codex, and [40+ more](https://agentskills.io/clients)):

```powershell
npx skills add LouisGameDev/everyfile -g
```

Or install from a local clone:

```powershell
npx skills add ./path/to/everyfile -g
```

The skill teaches agents *when* and *how* to use `ev`, the Python API, and the MCP tools — with search syntax, safety guidelines, and decision logic included.

## OpenClaw — use Everything from OpenClaw agents

If you run [OpenClaw](https://openclaw.ai/), you can give your agents instant file search on Windows.

**Install the skill** (via [ClawHub](https://clawhub.ai/) or manually):

```bash
openclaw skills install everyfile
```

Or copy the skill folder manually into your workspace:

```bash
cp -r .agents/skills/everyfile <workspace>/skills/everyfile
```

**Install the Python package** (the skill gates on the `ev` binary):

```powershell
pip install everyfile
```

**Optional: add the MCP server** for tool-level access from any agent:

```powershell
pip install everyfile[mcp]
```

Then add to your agent's MCP config or `openclaw.json`:

```jsonc
// In openclaw.json → tools or agent-level MCP config
{
  "mcpServers": {
    "everything": {
      "command": "everyfile-mcp"
    }
  }
}
```

The skill auto-gates on `win32` and requires `ev` on PATH. Once installed, your OpenClaw agents will use Everything for all file discovery instead of slow filesystem traversals.

## Install from source

```powershell
git clone https://github.com/LouisGameDev/everyfile.git
cd everyfile
pip install -e ".[dev]"           # editable install with dev tools
pip install -e ".[dev,mcp]"       # + MCP server
```

## Command aliases

All three run the same binary. Examples in this README use `ev`.

```powershell
everyfile ext:py           # full name
every ext:py               # short form
ev ext:py                  # shortest — recommended for daily use
```

## Quick Start

```powershell
ev ext:py                          # all Python files
ev ext:py dm:today                 # Python files modified today
ev ext:py -n 5                     # 5 most recently modified
ev ext:py --sort size -d           # largest first
ev --count ext:py                  # just the total count
```

## Using Results With Other Commands

The `-l` flag outputs one full path per line — perfect for feeding into other tools.

### Open a file in VS Code

Find a file by name and open it instantly:

```powershell
code $(ev server.py -n 1 -l)
# opens C:\Projects\webapp\src\server.py in VS Code
```

### Open multiple files

```powershell
# Open all recently modified Python files in VS Code
ev ext:py dm:today -l | ForEach-Object { code $_ }
```

### Delete files

```powershell
# Clean up temp files
ev ext:tmp -l | ForEach-Object { Remove-Item $_ }

# With confirmation prompt
ev ext:tmp -l | ForEach-Object { Remove-Item $_ -Confirm }
```

### Copy or move files

```powershell
# Copy all project configs to a backup folder
ev "ext:toml|ext:cfg path:Projects" -l | ForEach-Object { Copy-Item $_ D:\Backup\ }

# Move all .log files to archive
ev ext:log -l | ForEach-Object { Move-Item $_ D:\Archive\Logs\ }
```

### Count lines of code

```powershell
# Total line count across all Python files in a project
ev "ext:py path:webapp\src" -l | ForEach-Object { Get-Content $_ } | Measure-Object -Line

Lines Words Characters Property
----- ----- ---------- --------
  331
```

### Find TODOs across search results

```powershell
# Find TODO comments in recently changed Python files
ev "ext:py dm:thisweek" -l | ForEach-Object { Select-String -Path $_ -Pattern "TODO" }
C:\Projects\webapp\src\api\views.py:42:    # TODO: add pagination
C:\Projects\webapp\src\db\models.py:17:    # TODO: add index
```

### Paginate results

```powershell
# Skip first 10, show next 5
ev ext:py -l | Select-Object -Skip 10 -First 5

# Or use --offset and -n directly
ev ext:py --offset 10 -n 5
```

### Combine with jq

```powershell
# Get names of large files as a JSON array
ev "ext:py size:>100kb" -j | jq -s '[.[].name]'
["generate_parser.py", "codegen.py", "transformer.py"]
```

## Examples

### Sort by size

Find the 5 largest Python files:

```powershell
ev ext:py path:fixtures -n 5 --sort size -d -f name,size
```

<!-- example:sort-size -->
```
middleware.py  1011 B
utils.py  824 B
serializers.py  783 B
test_views.py  718 B
views.py  652 B

  5 of 18 results for "ext:py path:fixtures"  │  sorted by size ↓

  ├ size      3.9 KB
  └ names     middleware.py  serializers.py  test_views.py  utils.py  views.py
```
<!-- /example:sort-size -->

### Combined functions — extension + size

Search functions compose with AND. Find Python files over 500 bytes:

```powershell
ev "ext:py size:>500" path:fixtures -n 5 -f name,size,path
```

<!-- example:size-filter -->
```
views.py  652 B  webapp\src\api
models.py  608 B  webapp\src\db
serializers.py  783 B  webapp\src\api
middleware.py  1011 B  webapp\src
admin.py  523 B  webapp\src

  5 of 10 results for "ext:py size:>500 path:fixtures"

  ├ size      3.5 KB
  └ names     admin.py  middleware.py  models.py  serializers.py  views.py
```
<!-- /example:size-filter -->

### Custom field order

Show name, path, size, and date in any order you want:

```powershell
ev "ext:py path:fixtures" -n 5 -f name,path,size,date_modified
```

<!-- example:date-scope -->
```
views.py  webapp\src\api  652 B  2026-04-17 00:00
models.py  webapp\src\db  608 B  2026-04-16 23:00
serializers.py  webapp\src\api  783 B  2026-04-16 22:00
middleware.py  webapp\src  1011 B  2026-04-16 21:00
admin.py  webapp\src  523 B  2026-04-16 20:00

  5 of 18 results for "ext:py path:fixtures"

  ├ size      3.5 KB
  └ names     admin.py  middleware.py  models.py  serializers.py  views.py
```
<!-- /example:date-scope -->

### OR operator

Use `|` to combine extensions. Quote the pipe so the shell doesn't intercept it:

```powershell
ev 'ext:log|ext:tmp path:fixtures' -n 5 -f name,size,path
```

<!-- example:or-operator -->
```
cache.tmp  195.3 KB  webapp
app-2026-04-14.log  258.8 KB  webapp\logs
debug.log  12.6 KB  webapp\logs

  3 of 3 results for "ext:log|ext:tmp path:fixtures"

  ├ size      466.7 KB
  └ names     app-2026-04-14.log  cache.tmp  debug.log
```
<!-- /example:or-operator -->

### Regex search

Find test files using Everything's `regex:` function:

```powershell
ev 'regex:^test_.*\.py$ path:fixtures' -n 5 -f name,path
```

<!-- example:regex -->
```
test_views.py  webapp\tests
test_serializers.py  webapp\tests
test_auth.py  webapp\tests
test_utils.py  toolkit\tests

  4 of 4 results for "regex:^test_.*\.py$ path:fixtures"

  └ names     test_auth.py  test_serializers.py  test_utils.py  test_views.py
```
<!-- /example:regex -->

### Finding empty files

`size:empty` locates zero-byte placeholder files:

```powershell
ev 'size:empty ext:py path:fixtures' -f name,size,path
```

<!-- example:empty-files -->
```
__init__.py  0 B  webapp\tests
__init__.py  0 B  webapp\src\db
__init__.py  0 B  webapp\src\api
__init__.py  0 B  webapp\src

  4 of 4 results for "size:empty ext:py path:fixtures"

  ├ size      0 B
  └ names     __init__.py×4
```
<!-- /example:empty-files -->

### Count mode

Just the number — no results, no table:

```powershell
ev --count 'ext:py path:fixtures'
```

<!-- example:count -->
```
everything: 18 results for "ext:py path:fixtures"
```
<!-- /example:count -->

### Pipe composition — chaining filters

When you pipe `ev` into `ev`, the second invocation filters locally (no re-query).
Start broad, then narrow to API:

```powershell
ev 'ext:py path:webapp\src' -n 20 -j | ev '!__init__' | ev 'path:api' -f name,path
```

```
views.py        C:\Projects\webapp\src\api
serializers.py  C:\Projects\webapp\src\api
urls.py         C:\Projects\webapp\src\api
permissions.py  C:\Projects\webapp\src\api
```

### `ev filter` — structured NDJSON filtering

`ev filter` applies typed conditions to NDJSON fields — like `jq` but zero-dep.
Find project source files > 5 KB:

```powershell
ev 'ext:py path:webapp\src' -f all -j | ev filter --size-gt 5000 --is-file | ev pick name size
```

```
{"name":"views.py","size":8412}
{"name":"models.py","size":6553}
{"name":"serializers.py","size":7201}
{"name":"admin.py","size":5890}
{"name":"middleware.py","size":6104}
```

### `ev pick` — field extraction

Extract only the fields you need from NDJSON:

```powershell
ev 'ext:py path:webapp\src' -n 5 -f all -j | ev pick name size
```

```
{"name":"views.py","size":8412}
{"name":"models.py","size":6553}
{"name":"urls.py","size":345}
{"name":"__init__.py","size":0}
{"name":"admin.py","size":5890}
```

### Output modes

| Flag | Description | Use case |
|------|-------------|----------|
| *(default)* | Human table on stderr, NDJSON on stdout when piped | Interactive browsing |
| `-l` / `--list` | One full path per line | `ForEach-Object`, `$(...)` |
| `-0` / `--null` | Null-separated full paths | Paths with special characters |
| `-j` / `--json` | Force NDJSON to stdout | Processing with `ev filter`/`ev pick`/`jq` |

```powershell
ev ext:py path:fixtures -n 3 -l
```

<!-- example:list-mode -->
```
webapp\src\api\views.py
webapp\src\db\models.py
webapp\src\api\serializers.py
```
<!-- /example:list-mode -->

## Fields

`-f` / `--fields` controls both the human-readable stderr display and NDJSON output fields.

```powershell
ev ext:py -f name,size             # display and NDJSON: name + size
ev ext:py -f all                   # all fields
ev ext:py -f dates,meta            # default + date + metadata groups
```

Run `ev --help-fields` for the full list:

```
available fields (use with -f/--fields):

  * name                      file or folder name
  * path                      parent directory path
    full_path                 complete path including filename
    ext                       file extension (without dot)
  * size                      file size in bytes
    date_created              creation timestamp
  * date_modified             last modified timestamp
    date_accessed             last accessed timestamp
    date_run                  last run timestamp
    date_recently_changed     recently changed timestamp
    run_count                 number of times file was executed
    attributes                file system attributes string
    is_file                   true if result is a file (derived)
    is_folder                 true if result is a folder (derived)
    hl_name                   highlighted matching name
    hl_path                   highlighted matching path
    hl_full_path              highlighted matching full path

  * = included in default display

groups:
    default      name, path
    all          every available column
    dates        date_created, date_modified, date_accessed
    meta         size, ext, attributes, is_file, is_folder
    hl           hl_name, hl_path, hl_full_path
```

## Sorting

Default sort is **date modified descending** (newest first), so `-n 5` gives the 5 most recently modified matches.

```powershell
ev ext:py                          # newest first (default)
ev ext:py --sort name              # alphabetical
ev ext:py --sort size -d           # largest first
ev ext:py --sort created           # oldest created first
```

Sort fields: `name`, `path`, `size`, `ext`, `created`, `modified`, `accessed`, `run-count`, `date-run`, `recently-changed`, `attributes`.

## `ev filter` flags

| Flag | Description |
|------|-------------|
| `--name GLOB` | Glob match on name |
| `--path GLOB` | Glob match on path |
| `--ext .EXT` | Exact extension match |
| `--size-gt N` | Size > N bytes |
| `--size-lt N` | Size < N bytes |
| `--modified-after DATE` | Modified after ISO date |
| `--modified-before DATE` | Modified before ISO date |
| `--created-after DATE` | Created after ISO date |
| `--created-before DATE` | Created before ISO date |
| `--is-file` | Only files |
| `--is-folder` | Only folders |
| `--attr CHARS` | Require attribute chars (e.g. `RHA`) |

## Everything Search Syntax

The query is passed verbatim to Everything. Full syntax reference:

```
Operators:    space=AND  |=OR  !=NOT  < >=group  " "=exact phrase
Wildcards:    *=any chars  ?=one char
Functions:    ext:py  size:>1mb  dm:today  parent:C:\Dev  content:TODO
              dc: da: dr: rc: depth: len: dupe: child: childcount:
Modifiers:    case: nocase: regex: path: ww: file: folder:
Macros:       audio: video: doc: pic: zip: exe:
Size:         size:1kb..10mb  size:>1gb  size:empty  size:tiny..huge
Dates:        dm:today  dm:thisweek  dc:yesterday  da:last2weeks
```

Shell metacharacters need quoting:

```powershell
ev 'foo|bar'              # OR (quote the pipe)
ev '!secret'              # NOT (quote the bang)
ev 'size:>1mb'            # function (quote the >)
ev ext:py dm:today        # no special chars — no quoting needed
```

## Instance Management

Multiple Everything versions can run side-by-side. The CLI auto-detects instances in priority order: `1.5a → 1.5 → 1.4 → default`.

```powershell
ev --instances                              # list running instances
ev --instance 1.4 ext:py                    # query via Everything 1.4

# Persist your choice
$env:EVERYTHING_INSTANCE = "1.5a"           # session
[System.Environment]::SetEnvironmentVariable('EVERYTHING_INSTANCE', '1.5a', 'User')  # permanent
```

Priority: `--instance` flag > `$EVERYTHING_INSTANCE` env var > auto-detect.

## Service Info

```
$ ev --version
everyfile 2026.04.15 (Python 3.13.5) / Everything 1.5.0.1404
Instance: 1.5a  (via auto-detect)

$ ev --info
Everything v1.5.0.1404
Admin: no
AppData: no
Instance: 1.5a

$ ev --instances
Running Everything instances:

  1.5a         class: EVERYTHING_TASKBAR_NOTIFICATION_(1.5a)  ←  active

Active instance: 1.5a
  Selected via: auto-detect
```

## Python API

`everyfile` is also a fully importable Python library — no CLI needed. The API uses DB-API 2.0 cursor/row semantics, is fully type-annotated, and has zero dependencies.

### Quick Start

```python
from everyfile import search, count

# Iterate results
for row in search("ext:py"):
    print(row.name, row.full_path)

# Count matches without fetching
print(f"Python files: {count('ext:py')}")
```

### Search with Options

```python
from everyfile import search

# Find the 10 largest log files
cursor = search(
    "ext:log",
    fields="size",
    sort="size",
    descending=True,
    limit=10,
)

print(f"Showing {cursor.count} of {cursor.total} total matches")
for row in cursor:
    print(f"  {row.size:>12,} bytes  {row.full_path}")
```

Parameters: `query`, `fields`, `sort`, `descending`, `limit`, `offset`, `match_case`, `match_path`, `match_whole_word`, `regex`, `instance`.

### Cursor — Fetch Patterns

`search()` returns a `Cursor` — a forward-only iterator with DB-API 2.0 fetch methods.

```python
from everyfile import search

cursor = search("ext:py", limit=100)

# Metadata is available immediately (before iterating)
print(f"Total matches: {cursor.total}")
print(f"Results in cursor: {cursor.count}")

# Fetch one at a time
first = cursor.fetchone()       # Row | None

# Fetch in batches
batch = cursor.fetchmany(20)    # list[Row] (up to 20)

# Fetch all remaining
rest = cursor.fetchall()        # list[Row]
```

Batch processing large result sets:

```python
cursor = search("ext:log", limit=10_000, fields="size")

while batch := cursor.fetchmany(500):
    for row in batch:
        process(row)
```

### Row — Typed Property Access

Each result is a `Row` with typed properties and dict-style access.

```python
from everyfile import search

for row in search("ext:py dm:today", fields="size,dates"):
    # Typed properties (IDE autocomplete works)
    row.name            # str    — always present
    row.path            # str    — always present
    row.full_path       # str    — always present
    row.size            # int | None
    row.date_modified   # str | None (ISO 8601)
    row.date_created    # str | None (ISO 8601)
    row.is_file         # bool | None

    # Dict-style access
    row["name"]
    row.get("size", 0)
    "size" in row       # True

    # Serialize to dict
    row.to_dict()       # {"name": ..., "path": ..., ...}
```

### Everything Class — Reusable Connection

For repeated queries or service introspection, create an `Everything` instance.

```python
from everyfile import Everything

ev = Everything()               # auto-detect running instance
# ev = Everything("1.5a")      # target a specific instance

# Reuse connection for multiple queries
py_files = ev.search("ext:py", limit=5)
log_files = ev.search("ext:log", sort="size", descending=True, limit=5)
total_py = ev.count("ext:py")

# Service introspection
print(ev.version)               # {"major": 1, "minor": 5, "revision": 0, ...}
print(ev.info)                  # indexed file/folder counts
print(ev.instance_name)         # "1.5a"

# List all running instances
for inst in Everything.instances():
    print(inst["name"], inst["hwnd"])
```

### Error Handling

```python
from everyfile import search, EverythingError

try:
    results = search("ext:py").fetchall()
except EverythingError as e:
    if e.is_not_running:
        print("Everything is not running")
    else:
        print(f"IPC error: {e}")
```

### Fields and Sorting

```python
from everyfile import search

# Field groups: "default", "all", "dates", "meta", "hl"
search("*.py", fields="all")            # every available field
search("*.py", fields="meta")           # size, ext, attributes, is_file, is_folder
search("*.py", fields="size,ext")       # individual fields

# Sort options: name, path, size, ext, created, modified, accessed, ...
search("*.py", sort="size", descending=True)
search("*.py", sort="modified")         # oldest first
search("*.py", sort="modified", descending=True)  # newest first
```

For the full API reference, see [docs/PYTHON_API_SPEC.md](docs/PYTHON_API_SPEC.md).

## Architecture

```
src/everyfile/
  __main__.py        CLI entry point, argparse, dispatch
  search.py          Search orchestration, pipe filter, count, info, version
  filter.py          Structured NDJSON filter (ev filter)
  pick.py            NDJSON field extraction (ev pick)
  mcp.py             MCP server (search_files, count_files, aggregate_files, get_everything_info)
  querymatch.py      Local query matching for pipe composition
  sdk/
    ipc.py           Pure Python IPC via ctypes (WM_COPYDATA, WM_USER)
    api.py           High-level API wrapper, instance resolution
    constants.py     Everything IPC constants, request flags, sort types
    types.py         Field-to-flag mapping, field groups, resolution
  output/
    ndjson.py        NDJSON serializer (stdout)
    human.py         Human-readable formatter (stderr)
  util/
    glob.py          Glob matching for filter command
    dates.py         FILETIME ↔ ISO 8601 conversion
    attrs.py         FILE_ATTRIBUTE_* ↔ compact string
```

**IPC approach**: Pure Python ctypes — `FindWindowW` to locate Everything's hidden IPC window, `SendMessageW` with `WM_COPYDATA` for search queries, `WM_USER` for version/info. No DLL dependency.

## MCP Server

`everyfile` includes an [MCP](https://modelcontextprotocol.io/) server that exposes Everything search to AI assistants like GitHub Copilot, Claude, and any MCP-compatible client. See [Getting Started](#install) for setup.

### Tools

| Tool | Description |
|------|-------------|
| `search_files` | Search files/folders with full Everything syntax, field selection, sorting, pagination |
| `count_files` | Count matches without transferring results — check scale before fetching |
| `aggregate_files` | Server-side analytics — total size, group by extension/folder/drive, no result cap |
| `get_everything_info` | Service diagnostics: version, instance, admin status |

### Example

Once configured, your AI assistant can call these tools directly:

```
> Find the 5 largest Python files modified this week

search_files(query="ext:py size:>50kb dm:thisweek", sort="size", descending=true, max_results=5)

> How much space do my images use, broken down by format?

aggregate_files(query="ext:jpg;png;gif;webp;heic;svg", group_by="ext", sort_by="total_size")
```

## Versioning

everyfile uses **CalVer** — `YYYY.M.D` (no leading zeros).

| Where | Example | Notes |
|-------|---------|-------|
| PyPI | `2026.4.18` | `pip install everyfile==2026.4.18` |
| Git tag | `v2026.4.18` | `git checkout v2026.4.18` |
| ClawHub | `2026.4.18` | `openclaw skills install everyfile@2026.4.18` |

Same-day patch releases append a pre-release suffix: `2026.4.18-2`, `2026.4.18-3`, etc.

### Release workflow

```powershell
# 1. Bump version in pyproject.toml
#    version = "2026.4.18"   (or "2026.4.18-2" for same-day patches)

# 2. Commit, tag, push
git add pyproject.toml
git commit -m "release: v2026.4.18"
git tag v2026.4.18
git push && git push --tags

# 3. Publish to PyPI
python -m build && twine upload dist/*

# 4. Publish to ClawHub
clawhub publish .agents/skills/everyfile --slug everyfile --version 2026.4.18
```

## Development

```powershell
git clone https://github.com/LouisGameDev/everyfile.git
cd everyfile
pip install -e ".[dev,mcp]"

# Type check
mypy src/

# Test (requires Everything running for integration tests)
pytest
```

## See Also

- [Everything SDK Python documentation](https://www.voidtools.com/support/everything/sdk/python/)
- [Everything search syntax](https://www.voidtools.com/support/everything/searching/)
- [Everything downloads](https://www.voidtools.com/downloads/)

## License

MIT
