Metadata-Version: 2.2
Name: swll
Version: 1.2.0
Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
Author: John Harrington
License: Proprietary
Project-URL: Homepage, https://swll.app/
Project-URL: Product, https://swll.app/product/
Project-URL: Changelog, https://swll.app/now/tag/changelog/
Keywords: indexer,mcp,metadata,model-context-protocol,file-indexing,sqlite,context-engineering,personal-information-management
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml<7.0,>=6.0.1
Requires-Dist: rich<14.0,>=13.7.0
Requires-Dist: click<9.0,>=8.2.0
Requires-Dist: rich-click<2.0,>=1.9.0
Requires-Dist: mcp<2.0,>=1.0.0
Requires-Dist: fastapi<1.0,>=0.115.0
Requires-Dist: uvicorn<1.0,>=0.30.0
Requires-Dist: cryptography<46.0,>=42.0.0
Provides-Extra: semantic
Requires-Dist: chromadb<2.0,>=1.4; extra == "semantic"
Requires-Dist: onnxruntime<2.0,>=1.16.0; extra == "semantic"
Provides-Extra: parse
Requires-Dist: pypdf<6.0,>=3.0.0; extra == "parse"
Requires-Dist: python-docx<2.0,>=1.1.0; extra == "parse"
Requires-Dist: openpyxl<4.0,>=3.1.0; extra == "parse"
Requires-Dist: python-pptx<2.0,>=0.6.21; extra == "parse"
Provides-Extra: full
Requires-Dist: swll[semantic]; extra == "full"
Requires-Dist: swll[parse]; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=4.1.0; extra == "dev"
Requires-Dist: ruff<1.0,>=0.1.0; extra == "dev"
Requires-Dist: httpx<1.0,>=0.27.0; extra == "dev"

# SWLL

[![PyPI](https://img.shields.io/pypi/v/swll)](https://pypi.org/project/swll/)

**A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**

> **Version note.** SWLL 1.0.0 is the first release of SWLL, continuing the codebase formerly published as `footprinter-cli` (last public release 1.1.1). The version resets to 1.0.0 because SWLL is a distinct, proprietary product — the reset is intentional, not a regression.

> **swll is a command-line tool** — you run the `swll` command; it's not a library you import. So install it with **pipx**, the standard way to install a Python CLI app: pipx gives swll its own isolated environment and puts the `swll` command on your PATH.

```bash
pipx install swll
```

Your work lives across filesystems, browsers, inboxes, chat histories, and other tools. SWLL indexes those sources into a single local database, organizes them into the projects and groupings you define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.

## Install

**Recommended — install with pipx** (macOS 13+ or Linux, Python 3.11+):

```bash
pipx install swll     # install the CLI
swll setup            # configure sources + optional features (interactive)
```

That's the whole path. `pipx install swll` puts three commands on your PATH:

| Command | What it is |
|---------|-----------|
| `swll` | The CLI and indexing pipeline |
| `swll-mcp` | The MCP server for AI agents |
| `swll-api` | The HTTP API |

`swll setup` then configures your sources and offers to install optional features:

| Feature | What it adds |
|---------|-------------|
| Semantic search | Finds files and chats by meaning, via ChromaDB + ONNX embeddings |
| Document parsing | PDF, Word, Excel, PowerPoint content extraction |

pipx installs swll in its own isolated environment, and `swll setup` asks about each feature and installs the ones you choose into that same environment — there is no command to type. Semantic search brings document parsing with it; document parsing can also be added on its own. To add a feature later, run `swll setup` again.

If you don't have Python 3.11+ yet, install it from [python.org](https://www.python.org/downloads/) first, then run the `pipx` command above.

<details>
<summary>Advanced, developer install, and troubleshooting</summary>

### Advanced / for developers

**pip install into a venv (embedding or hacking on swll).** If you're embedding swll in your own project or working on swll itself, install it with `pip` inside a virtual environment you manage:

```bash
python3 -m venv venv
./venv/bin/pip install swll
```

Use the pipx path above for a normal command-line install — bare `pip install swll` into your *system* Python is commonly blocked on modern macOS/Homebrew/Debian, which is exactly why pipx exists.

**Adding extras by hand (pipx).** `swll setup` is the recommended way to add optional features, and you rarely need to do this yourself. The extras are `[semantic]` (semantic search), `[parse]` (document parsing) and `[full]` (both). If you do want to add extras through pipx directly, they must be on the *first* install:

```bash
pipx install 'swll[full]'      # semantic + parse, on a fresh install
```

A plain re-run of `pipx install swll` on an existing install is a **no-op** — it won't add extras. To add them to an install you already have, force a reinstall or inject the dependency:

```bash
pipx install 'swll[full]' --force    # reinstall the same version, now with extras
pipx inject swll chromadb            # or inject a single dependency into swll's env
```

> **zsh note:** zsh treats `[...]` as a glob, so quote the specifier — `'swll[full]'`, not `swll[full]`.
>
> **Footnote — why bare `pip install` is blocked:** Homebrew/Debian/Fedora mark their Python as "externally managed" (PEP 668), so a global `pip install` is refused to protect the system package manager. pipx and venvs both sidestep it; you don't need to know any of this to install swll.

### Troubleshooting

**Python version:** Stock macOS ships Python 3.9. Install 3.11+ from [python.org](https://www.python.org/downloads/) or `brew install python@3.11`.

**Full Disk Access:** Required for browser history indexing on macOS. `swll setup` will prompt you when needed.

**ChromaDB telemetry:** SWLL sets `anonymized_telemetry=False`. ChromaDB also removed product telemetry in v1.5.4. See [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss).

**Apple Silicon (Rosetta):** If `swll doctor` warns about x86_64 Python on arm64 hardware, move SWLL onto a native arm64 Python; the warning gives the remedy for the way you installed it. On a pipx install, run `pipx reinstall swll --python /opt/homebrew/bin/python3`. On a venv, recreate the venv with a native Python such as `/opt/homebrew/bin/python3` and install SWLL into it again. This avoids compatibility issues with native-extension dependencies.

</details>

### Upgrading

On SWLL 1.1.0 or later, `swll upgrade` works out how SWLL was installed and either upgrades it or shows you the matching upgrade command. From 1.2.0, a pipx upgrade run by `swll upgrade` finishes by bringing your local index up to the new version. If you upgrade by hand instead (`pipx upgrade swll` or `pip install -U swll`), or you are upgrading *to* 1.2.0 from an earlier version — whose `swll upgrade` does not have that last step — run `swll upgrade --finish` afterwards. Until it has run, an AI agent connected over MCP is told the index is outdated rather than being served from it, and the CLI commands that open the index — `swll status`, `search`, `view`, `policies`, `add` (other than `add chats`), `update`, `delete`, `config unlist add` and `remove`, and the `swll setup` wizard — stop with a line naming `swll upgrade --finish`. An unlist rule added or removed while the index is refused is still saved to your config, and the next `swll ingest` applies it. `swll ingest` does not stop: it migrates the index itself before it indexes, and so does a chat import with `swll add chats`.

On 1.0.0 and 1.0.1, `swll upgrade` does not exist — the CLI answers `invalid choice: 'upgrade'`. You don't need it; upgrade with the command for how you installed:

```bash
pipx upgrade swll               # pipx install (the recommended path above)
./venv/bin/pip install -U swll  # pip inside a venv you manage
```

Your database and MCP configuration carry over. Run `swll doctor` afterwards to confirm the install is healthy.

### Uninstall

```bash
swll uninstall                        # remove MCP entry + user data
pipx uninstall swll      # remove the package
```

## Quick Start

```bash
swll setup     # Configure sources (interactive wizard)
swll ingest    # Index your files
swll status    # See what's indexed
swll search "meeting notes"   # Find things
```

A few first-run notes:

- The first ingest is implicitly full; subsequent runs are incremental. If you change exclusions or add directories after the first run, re-run with `swll ingest --full` so previously skipped files get picked up.
- With `[semantic]` or `[full]`, the **first ingest downloads ~80MB** of ONNX embedding model weights. It's a one-time cost — subsequent ingests are fast.
- Keep the directories you want indexed **outside `~/Downloads`** — the default exclusion list skips it.

## Connect to Claude Desktop

SWLL includes an MCP server that gives Claude Desktop (or any MCP client) structured access to your indexed data:

```bash
swll setup mcp --claude    # Configure MCP for Claude Desktop
```

After running this, **fully quit Claude Desktop (Cmd+Q) and relaunch** before the SWLL tools appear in the conversation tools list. A simple window close isn't enough — the app keeps running in the menu bar.

Once configured, Claude can search your files, browse projects, and find related conversations — through natural language.

## What It Indexes

| Source | What's captured |
|--------|----------------|
| **Local files** | Path, type, size, timestamps, content hash |
| **Browser history** | Safari and Chrome — URLs, titles, visit times |
| **Chat exports** | Claude and ChatGPT conversation exports |
| **Email** | Subject, sender, recipients, body, timestamps |
| **Documents** | PDF, Word, Excel, PowerPoint content (with `[parse]` extra) |
| **Semantic embeddings** | Conceptual similarity across local files and chat exports (with `[semantic]` extra); email and browser history are keyword-searchable only |

What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, SWLL only indexes metadata; it does not read your file content until you explicitly enable it. `swll setup` walks you through the tiers and states what each one reads.

## CLI Commands

All commands use the `swll` entry point.

| Command | Purpose |
|---------|---------|
| `swll setup` | Configure sources and integrations |
| `swll config` | Add, remove, and list scan directories and unlist rules without the wizard |
| `swll ingest` | Run the indexing pipeline |
| `swll status` | System health and data counts |
| `swll search` | Search across all indexed sources |
| `swll connect` | Manage optional integrations |
| `swll policies` | Manage access policies (visibility, permissions) |
| `swll view` | Browse indexed data (files, folders, projects, clients, chats, emails, visits) |
| `swll add` | Create new entity records or import from CSV |
| `swll update` | Update existing records by ID — assignments, metadata |
| `swll delete` | Hard-delete a super entity (irreversible) |
| `swll doctor` | Post-install health check (Python version, platform, FDA, MCP wiring) |
| `swll upgrade` | Upgrade SWLL — runs `pipx upgrade swll` for pipx installs (after a confirm) and then brings the local index up to the new version; prints the command for any other install. `--finish` does that last step on its own, after a manual upgrade |
| `swll version` | Show the installed SWLL version (also `swll --version`) |
| `swll uninstall` | Remove SWLL — MCP entry, user data, package |

Run `swll <command> --help` for full usage.

## Architecture

Single-process CLI with optional MCP server. SQLite database. No containers, no cloud, no accounts.

Sources are scanned into SQLite with bidirectional links connecting local files to remote backups via content hash matching. Embeddings are generated at ingest time for semantic search. The MCP server serves indexed data through three layers, two of them access controls: the listing-status filter (Layer 0), which the system derives and which is not an access control, then visibility policy (Layer 1) and permission policy (Layer 2). You decide what agents can see.

## Documentation

`swll --help` documents every command, and `swll <command> --help` covers each one in detail. `swll setup` explains the choices it asks you to make as it makes them.

The full documentation is at [swll.app/docs](https://swll.app/docs/).

## Contributing

SWLL is a proprietary product developed by SwellCity Group. The source is published to PyPI so you can read exactly what you run — but the repository is private, and unsolicited contributions are not accepted.

**Found a bug, or something that doesn't match this README?** Email [hello@swellcity.ai](mailto:hello@swellcity.ai). **Security vulnerabilities go to the same address** — please report them privately, and include enough detail to reproduce.

No Contributor License Agreement required. By submitting a contribution, you agree it may be incorporated into SWLL under the project's proprietary LICENSE (Copyright © 2026 SwellCity Group, All Rights Reserved).

## License

This package is free — the CLI, MCP server and HTTP API are the full tool, with no feature gates and nothing held back for a paid tier — while the paid side sits alongside it: separately distributed connectors, the desktop app, and advisory work.

Proprietary — Copyright © 2026 SwellCity Group, All Rights Reserved. See the `LICENSE` file included with this package, which grants you the right to install and run it at no charge, for personal or commercial work.
