Lucy

Your work lives in Dropbox, iCloud Drive and on a drive under the desk. Your AI tools get wired into all of it, with full access, and none of them can tell you which copy of a file is the current one.

Lucy is a small local server that fixes both problems:

• One index. It maps every folder you approve, fingerprints each file with SHA-256 and tells you which copies match, which differ and which are only a cloud placeholder that was never downloaded.

• One gate. Claude Code, Codex or any MCP client asks Lucy for a file. Lucy answers with a short excerpt, secrets masked, from approved folders only. Every request is logged, allowed or denied.

It moves nothing, deletes nothing, downloads nothing and makes no network calls.

Install

Needs macOS, Python 3.11 or newer and uv.

git clone https://github.com/ckaico/lucy && cd lucy
uv sync
claude mcp add --scope user lucy -- "$PWD/bin/lucy" mcp

Any other MCP client: run bin/lucy mcp over stdio. For Codex, in ~/.codex/config.toml:

[mcp_servers.lucy]
command = "/path/to/lucy/bin/lucy"
args = ["mcp"]

Lucy keeps its config, catalog and log in ~/.lucy (set LUCY_HOME to move it).

Related MCP server: lupa-mcp

Approve a folder

Nothing is readable until you approve it. A source is one folder, tied to one project.

bin/lucy source-add film-dropbox --kind dropbox --root ~/Dropbox/Film --project film --exclude private
bin/lucy source-add film-icloud  --kind icloud  --root ~/Library/Mobile\ Documents/com~apple~CloudDocs/Film --project film
bin/lucy source-add film-raid    --kind raid    --root /Volumes/MY_RAID/Film --project film
bin/lucy scan

--exclude keeps a subfolder out of the index and blocks reads of it. A raid source is pinned to the volume's identity, so a different drive mounted at the same path is not trusted. If a drive is unplugged, Lucy says so. It never concludes your files are gone.

Which copy is current?

bin/lucy versions film HANDOFF.md

{
  "asset": "HANDOFF.md",
  "copies": 3,
  "verdict": "divergent: no history proves which is current; needs your decision",
  "versions": [
    { "sha256": "64550b1c…", "copies": [ { "source": "film-raid" }, { "source": "film-dropbox" } ] },
    { "sha256": "a3a0fab0…", "copies": [ { "source": "film-icloud" } ] }
  ]
}

(Output shortened.) Two copies match, one differs. Lucy will not pick a winner from modified dates, because dates lie across sync services. It names a newer version only when it has watched one replace the other.

What an assistant can and cannot do

$ bin/lucy read film-dropbox ../../.ssh/id_ed25519
{ "error": "Denied", "detail": "path must be relative to the source root, with no '..'" }

Everyday commands

repo-audit uses gitleaks and osv-scanner when they are installed, and reports which checks did not run.

What it does not do

• No encryption. Snapshots are plain local copies. Encrypted backups with keys you hold are planned.

• No malware scanning.

• No Dropbox, iCloud or Google Drive API. Lucy sees the folders synced to this Mac.

• No sharing between machines yet, and no remote access. There is no network endpoint.

• macOS only.

The full list, with what is tested and what is not: docs/STATUS.md. How it is built and what it defends against: docs/ARCHITECTURE.md.

Where it is going

1. Now: one index. Your files stay where they are. Lucy maps them and guards the door.

2. Next: one network. Every Mac you own in one view, Google Drive, a live board for every project, encrypted backups.

3. Later: one server. Your clouds and drives as one pool, with a database and logins for the apps you build.

Only the first is built. Early access to the rest: lucy.so.

Tests

.venv/bin/python -m unittest tests.test_acceptance -v

19 tests on throwaway folders: traversal and symlink escape, cross-project access, instructions hidden in documents, secret redaction, revoked sources, a disconnected drive, stale writes, and a check that Lucy's own code contains no network calls.

Security

Found a way past the gate? See SECURITY.md.

Licence

Apache 2.0. See LICENSE and NOTICE. © 2026 Christian Kai (CKAI).