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. 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 it to an existing install, run pipx install 'swll[full]' --force (see below) — the command swll doctor and swll search name for a pipx install.

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

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 exposes indexed data through three layers of access control: a status filter, then visibility and permission policies. 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.