contextify

Local-first context engine for Claude. Runs a tiny proxy on your Mac, reads recent Gmail, and injects relevant snippets into claude.ai prompts when they'd help. No servers, no uploads — your email and the retrieval model stay on your machine.

Requirements

• macOS 13+ on Apple Silicon (M1/M2/M3/M4). The local LLM uses MLX, which is Apple-Silicon-only.
• Node 20+ — https://nodejs.org or brew install node.
• A Gmail account you're willing to grant read-only access to.

No Python install needed. On first run, contextify fetches uv (a single static binary) into ~/.contextify/bin/ and uses it to provision a private Python + mlx-vlm environment in uv's global cache.

Install

npm install -g @nilayy/contextify

That drops a contextify binary onto your PATH. To upgrade later, re-run the same command — npm replaces the previous install in place.

Google OAuth setup

contextify does not ship a default OAuth client. Before first run, create your own:

1. Go to https://console.cloud.google.com/apis/credentials, create a Desktop app OAuth client.
2. Enable the Gmail API for the project.
3. Provide the credentials one of two ways:
   • Export GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your shell, or
   • Write ~/.contextify/google.json as {"clientId":"…","clientSecret":"…"}.

While the OAuth consent screen is in "Testing" mode, only accounts you've added as test users can authorize. The first time you grant access, Google will show an "App isn't verified" screen — click Advanced → Go to (app) (unsafe). Only Gmail read scope is requested. Tokens are stored at ~/.contextify/tokens/gmail.json and never leave your machine.

First run

contextify

Expect three things the first time, in this order:

1. uv + mlx-vlm bootstrap. contextify downloads uv (~30MB, one HTTPS GET) and uses it to install mlx-vlm into uv's cache. ~10–30 seconds total on a fresh machine. No prompts, just progress.
2. Google consent screen. A browser tab opens against the OAuth client you provisioned. See the Google OAuth setup section above.
3. macOS password. A Terminal sudo prompt for trusting a local-only CA cert + installing a PAC proxy entry. You can inspect what it does in src/setup.ts. Everything is reversible with contextify uninstall.

After that, indexing runs (3-month window by default), the local model warms up, and you can open claude.ai in your browser. Context injection happens transparently.

Ctrl-C stops the proxy and disables the PAC entry.

Commands

contextify                   # default: onboard + run proxy
contextify --months 6        # pin the Gmail window to 6 months
contextify doctor            # platform/deps/integration health report
contextify status            # list connected data sources
contextify connect gmail     # re-authorize Gmail
contextify flush             # clear parsed corpus + retrieval cache (keeps tokens)
contextify uninstall         # remove cert, PAC entry, sudoers rule; prompts to delete user data
contextify uninstall --all   # wipe everything non-interactively (system state, user data, global npm package)
contextify help              # show help

Set VERBOSE=1 (or --verbose) to see third-party log output.

Troubleshooting

• "mlx server not healthy within 600s": the local model is downloading. Check ~/.cache/huggingface/hub. Re-run with VERBOSE=1 to see MLX stdout.
• "Failed to download uv": check network access to GitHub. The fetch URL is https://github.com/astral-sh/uv/releases/latest/download/uv-aarch64-apple-darwin.tar.gz.
• mlx-vlm install seems stuck: ~/.contextify/bin/uv cache clean clears uv's cache; deleting ~/.contextify/bin/.mlx-vlm-ready forces a fresh install on next run.
• "Missing Google OAuth credentials": you haven't completed the Google OAuth setup step yet. Provision a Desktop OAuth client, then export GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET or write them to ~/.contextify/google.json.
• Everything seems broken: contextify doctor is the first stop. If that doesn't help, contextify uninstall (answer y when asked to delete user data) and retry.

Where state lives

• ~/.contextify/ — config, tokens, parsed corpus, retrieval cache
• ~/.contextify/bin/uv — the uv binary fetched on first run
• ~/.cache/uv/ — uv's shared cache (Python interpreters + installed packages, including mlx-vlm); shared with any other uv-using tool on your machine
• ~/.contextify/certs/ + keys/ — local CA material (machine-only)
• /Library/Keychains/System.keychain — the trusted root entry (named NodeMITMProxyCA)
• /etc/sudoers.d/claude-inject — allows non-interactive networksetup toggling

Development

git clone https://github.com/NilayYadav/contextify.git && cd contextify
npm install
npm run dev           # tsx watch
npm run build         # produces dist/
npm run doctor

Hot-path tests: npm run test:retrieval, npm run test:llm.

Releasing (maintainer notes)

./scripts/release.sh     # typecheck + build + npm version patch + npm pack

This writes contextify-<version>.tgz. Publish to npm with npm publish once you're happy with the build.

Contributing

Issues and PRs are welcome at https://github.com/NilayYadav/contextify. For anything non-trivial, please open an issue first to discuss the approach.

License

MIT — see LICENSE.