CatchMe - Moses Yebei

The Problem

Developers who use large‑language‑model (LLM) agents often lose context: the agents cannot recall what the user has typed, opened, or edited outside the current session. Re‑creating that personal history requires manual logging or external services that break privacy.

What This Does

catchme captures a user’s digital footprint locally and exposes it through a lightweight CLI skill. The core collector lives in catchme/recorder.py and the platform‑specific recorders under catchme/recorders/. Configuration lives in catchme/config.py, which is imported by 18 other modules – it is the primary hub for paths, storage locations, and LLM settings. The data model is defined in catchme/store.py and persisted as plain files, keeping the system “vectorless” and privacy‑first.

How It Is Wired

Execution starts at catchme/__main__.py, which parses CLI arguments and calls catchme/run.py::main(). run.py imports a wide set of sub‑modules (catchme/engine.py, catchme/web.py, the pipeline package, etc.) and orchestrates the workflow:

Configuration load – catchme/config.py reads catchme/services/config.example.json and environment overrides.
Recorder startup – catchme/recorder.py instantiates platform‑specific recorders (catchme/recorders/keyboard_*.py, mouse.py, clipboard.py, etc.) and registers callbacks.
Event capture – each recorder writes raw events to catchme/store.py, which provides add_event() and query() helpers.
Pipeline processing – user‑triggered commands (e.g., catchme retrieve) invoke catchme/pipelines/retrieve.py. This module pulls stored events, passes them through catchme/services/llm.py (LLM provider defined in catchme/services/providers.py), and returns a synthesized answer.
Web UI – catchme/web.py launches an Express‑based server (detected in the repo) serving the static UI in catchme/static/. The UI loads catchme/static/js/app.js, which calls the backend endpoints to fetch activity trees (tree.js) and chat logs.

The most connected modules are catchme/config (imported by 18 modules, no outgoing imports) and catchme/run (imports 10 others, instability 0.91). These act as blast‑radius points: changes to config.py or run.py propagate widely.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/CatchMe
cd CatchMe

# Install the package (pyproject.toml is the manifest)
pip install -e .

# Optional: edit the example config
cp catchme/services/config.example.json catchme/services/config.json
# adjust paths, LLM API key, etc.

# Start the recorder (captures keyboard, mouse, clipboard, etc.)
python -m catchme

# Query the memory via CLI
python -m catchme retrieve --query "What files did I edit yesterday?"

To run the optional web UI:

# Install Node dependencies (express is listed in package.json)
npm install   # or pnpm install if a lockfile existed
npm start     # runs the Express server defined in catchme/web.py

(If the repo does not contain a package.json, the UI can be served directly by the Python server.)

Real‑World Use

A developer integrates catchme into their daily workflow. While coding, the keyboard recorder logs every keystroke and file save. Later, they ask their Claude‑based assistant: catchme retrieve --query "What function did I refactor last week?". The request travels from the CLI → run.py → pipelines/retrieve.py → services/llm.py, which calls the configured OpenAI model and returns the relevant snippet from the locally stored event log. No external database is involved, preserving privacy.

Code Health & Issues

High – lockfile missing – pyproject.toml declares dependencies but no lockfile; reproducibility is at risk.
Medium – Dependabot not configured – no .github/dependabot.yml; security updates are manual.
Medium – No dependency scan in CI – .github/workflows/ci.yml lacks a vulnerability‑review step.
Medium – Large binary assets – assets/catchme-logo.png (≈10 MB) inflates repo size; consider Git LFS.
Medium – Checkout persists token – CI checkout keeps the GitHub token; set persist-credentials: false.
Low – Workflow timeout missing – CI jobs have no timeout-minutes; add a reasonable bound.

Additional observations: the codebase relies heavily on broad except: clauses (e.g., in recorder.py and services/llm.py), deep nesting (up to six levels), and several files exceed 800 lines, making maintenance harder. The static assets and UI are JavaScript‑heavy, but no package-lock.json or similar lockfile exists.

The Bottom Line

CatchMe provides a functional, locally‑hosted memory layer for LLM agents with clear entry points and a modest dependency surface. The architecture is understandable, but the hub module (config.py) and the oversized pipeline files pose a maintenance risk. Adding a lockfile, automated dependency scanning, and refactoring the large modules would improve reliability for production use. The project is suitable for teams that need privacy‑first personal context and are comfortable addressing the highlighted code‑health concerns.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

107 files

Python48
JavaScript17
Markdown8
CSS6
YAML2
JSON2

ExpressKubernetes

Module dependencies

The 10 most depended-upon modules of 65, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_catchme_config["config"] n1_catchme_static_js_utils["utils"] n2_catchme_recorder["recorder"] n3_catchme_store["store"] n4_catchme_services___init__["__init__"] n5_catchme_services_llm["llm"] n6_catchme_pipelines_retrieve["retrieve"] n7_catchme_pipelines_tree["tree"] n8_catchme_pipelines_filter["filter"] n9_catchme_pipelines_summarize["summarize"] n8_catchme_pipelines_filter --> n3_catchme_store n8_catchme_pipelines_filter --> n4_catchme_services___init__ n6_catchme_pipelines_retrieve --> n5_catchme_services_llm n6_catchme_pipelines_retrieve --> n0_catchme_config n6_catchme_pipelines_retrieve --> n4_catchme_services___init__ n6_catchme_pipelines_retrieve --> n9_catchme_pipelines_summarize n9_catchme_pipelines_summarize --> n5_catchme_services_llm n9_catchme_pipelines_summarize --> n8_catchme_pipelines_filter n9_catchme_pipelines_summarize --> n7_catchme_pipelines_tree n9_catchme_pipelines_summarize --> n0_catchme_config n9_catchme_pipelines_summarize --> n4_catchme_services___init__ n7_catchme_pipelines_tree --> n3_catchme_store n7_catchme_pipelines_tree --> n8_catchme_pipelines_filter n7_catchme_pipelines_tree --> n0_catchme_config n4_catchme_services___init__ --> n0_catchme_config n5_catchme_services_llm --> n0_catchme_config n5_catchme_services_llm --> n4_catchme_services___init__

Dependencies

12 of 19 declared dependencies are a major version behind. Resolved 19 of 19 against the registry.

Package	Declared	Latest	Behind
`pywin32`	>=306; sys_platform ==	312	6 major
`websockets`	>=12.0	17.0.1	5 major
`openai`	>=1.0	3.1.0	2 major
`pillow`	>=10.0	12.3.0	2 major
`psutil`	>=5.9	7.2.2	2 major
`pyobjc-framework-cocoa`	>=10.0; sys_platform ==	12.2.2	2 major
`pyobjc-framework-quartz`	>=10.0; sys_platform ==	12.2.2	2 major
`pyobjc-framework-screencapturekit`	>=10.0; sys_platform ==	12.2.2	2 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium4

low1

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium3 occurrences

assets/catchme-logo.png

3 blobs over 5MB: catchme-logo.png 10.5MB, catchme_logo.png 10.5MB, catchme_logo.png 10.5MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.