Metadata-Version: 2.2
Name: swll
Version: 1.1.0
Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
Author: John Harrington
License: Proprietary
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: 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 store, 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:

| Extra | What it adds |
|-------|-------------|
| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
| `[full]` | Both of the above |

pipx installs swll in its own isolated environment. Enabling semantic search in `swll setup` installs the `[full]` bundle — semantic search *and* document parsing — into that same environment, so you don't run pip or pipx yourself for that path. Document parsing on its own has no separate setup prompt yet; to add just that, run `pipx install 'swll[parse]'` (see below) — the same command `swll doctor` recommends.

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. 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, recreate the venv with a native interpreter: `pipx reinstall swll --python /opt/homebrew/bin/python3`. This avoids compatibility issues with native-extension dependencies.

</details>

### 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 all sources (with `[semantic]` extra) |

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 indexed scan directories 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 permission` | 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 — status, assignments, metadata |
| `swll delete` | Hard-delete a super entity (irreversible) |
| `swll doctor` | Post-install health check (Python version, platform, FDA, MCP wiring) |
| `swll upgrade` | Show the command that upgrades SWLL on this machine |
| `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 exposes indexed data with two-layer access control (visibility + access) — 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.

Full reference documentation — interfaces, data model, pipeline, content storage, and permission policies — lives in the project repository, which is private.

## 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

Proprietary — Copyright © 2026 SwellCity Group, All Rights Reserved. See the `LICENSE` file included with this package.
