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.

⚠️ Install with pipx, not pip. pipx puts the swll command on your PATH automatically; bare pip often doesn't — which leaves you with swll: command not found even though the install succeeded.

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

Requires Python 3.11+ and macOS 13+ or Linux. The install script checks your Python version and handles the rest:

curl -fsSL https://raw.githubusercontent.com/swllcty/swll/main/scripts/release/install.sh | bash

Or install with pipx directly:

pipx install swll

Either method installs three commands: swll (the CLI and indexing pipeline), swll-mcp (the MCP server for AI agents), and swll-api (the HTTP API). Optional extras add more:

To install with extras: use the full install script, or pipx install 'swll[full]'.

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. See Content Storage for the full breakdown.

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 with two-layer access control (visibility + access) — you decide what agents can see.

Documentation

• Interfaces — CLI commands, MCP tools, Python API
• Data Model — database schema
• Pipeline — indexing stages and configuration
• Content Storage — metadata vs. snippet vs. full-content tiers
• Permission Policies and Access Control — permission policies and access control

Contributing

Bug fixes, documentation, and tests welcome. For new features or architectural changes, open an issue first to discuss the approach.

Development setup

git clone https://github.com/swllcty/swll.git
cd swll
python3 -m venv venv
./venv/bin/pip install -e ".[dev]"

Running tests

./venv/bin/pytest tests/ -v --tb=short

Code style

• PEP 8
• Type hints on function signatures
• logging over print() in library code

Workflow

1. Fork the repository
2. Create a feature branch from main
3. Write tests (TDD preferred — tests before implementation)
4. Run the test suite
5. Submit a PR targeting main

Never commit API keys, tokens, or credentials. Report security vulnerabilities privately — see SECURITY.md.

Pull request expectations

• Tests must pass
• No breaking changes to existing CLI commands
• Fill out the PR template
• One logical change per PR

All PRs are reviewed by the maintainer. Expect reviews within one week. CI must pass before review begins.

No Contributor License Agreement required. By submitting a PR, you agree your contribution is licensed under the project's MIT License.

Community

• Code of Conduct
• Security Policy

License

MIT — see LICENSE.