SWLL

A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through MCP.

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.

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+):

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:

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

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 first, then run the pipx command above.

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

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

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

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:

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

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

Quick Start

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:

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

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.

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.

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