1. Install
Pick one. The Claude Code plugin is the easiest: it adds a guided skill that explains results and fixes problems with you.
Claude Code desktop app
- Open the plugin settings.
- Add the marketplace
contentasoftware/appledger. - Install appledger.
- Start a new session.
Claude Code in a terminal
$ claude plugin install appledger@appledger
Then start a new claude session.
Command line only
$ python -m appledger path/to/app
No Claude Code needed. Needs Python 3.10+.
It runs AppLedger's tools and installs Python for you. Install it once, then restart Claude Code. Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" · macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh (uv install guide). No uv? Claude can still check your app with the command line version.
Prefer only the MCP server, without the skill? claude mcp add appledger -- uvx --from appledger appledger-mcp. These steps are for AppLedger 0.2.0.
2. Connect a computer
Optional, but it gives you one dashboard with every app, its grade, score trend and history.
- Log in at appledger.net/app (or create a free account).
- Click Connect a computer and copy the key. It starts with
al_. - Tell Claude “Connect AppLedger with this key: al_…” or run
python -m appledger --connect al_…
The key is saved in ~/.appledger/key. The APPLEDGER_KEY environment variable overrides it. python -m appledger --disconnect removes it. Revoke a key any time in the dashboard.
3. Add an app
An app appears in your dashboard the first time it's checked from a connected computer, or when you add it on the web.
From Claude Code
Open the app's folder and say “Add this app to AppLedger” or “Is my app safe?” Claude shows what will be sent and asks before uploading.
From a terminal
The first check of a folder asks you to confirm the upload.
In the web app
Click Add app. Register an app without code, or upload a zip (up to 10 MB) to check it in the browser. Secret files in the zip are dropped and the zip is deleted after the scan.
Each check writes report.html, fix-prompt.md and findings.json to a .appledger folder in the app.
What gets uploaded
In the default hosted mode, only files Git would commit leave your computer.
| Group | Files | Notes |
|---|---|---|
| Sent | Files Git would commit: tracked files plus new files that aren't ignored | .gitignore is honoured even outside Git. Sent over HTTPS, deleted right after the scan |
| Never sent | .env, .env.*, *.pem, *.key, *.p12, *.pfx, SSH keys, .npmrc, .pypirc, .netrc, *credentials*.json, service-account*.json, secrets.*, folders cert, certs, secrets, .ssh, .aws, .claude/settings.local.json, Terraform state, password files (*.passwd), Ansible Vault files, Kubernetes/Helm secret manifests, certificates | Even if Git tracks them. .env.example, .sample and .template are sent. The server drops secret files again as a second safety net |
| Skipped | Dependencies (node_modules and similar), build output, images, video and other media, documents and data files (CSV, spreadsheets, slides, SQL, logs, data dumps), files over 1 MB | Not needed for the scan, and data files often hold business or personal data |
See the exact list, with the reason each file is left out, without uploading anything:
A committed or unignored secret file shows up as a problem
The check names the file; its content is never sent. Anyone who can see the repository can read it, so create new keys at each provider, revoke the old ones, and add the file to .gitignore.
The full list of secret file patterns is in uploadpolicy.py. How long we keep what: privacy policy.
Local mode
Your code never leaves your computer. You install the two scanners yourself.
- Trivy:
winget install AquaSecurity.Trivy(Windows),brew install trivy(macOS), or see trivy.dev (Linux). - Opengrep: download it from the releases page and put it on your PATH.
- Rules:
git clone --depth 1 https://github.com/opengrep/opengrep-rules.git ~/.appledger/opengrep-rules - Check:
python -m appledger --doctor - Run with
--local, or setAPPLEDGER_MODE=local(also works for the Claude Code plugin; restart Claude Code after setting it).
Only a summary is saved: app name, score, grade, problem counts, the problems found (level and a short title, up to 60) and the scanners used. Never the code or file paths. Add --no-dashboard to skip even that, or ask Claude not to save to the dashboard.
Schedule checks
Run this once in a terminal. It keeps checking even when Claude Code is closed.
$ python -m appledger --schedules # list scheduled checks
$ python -m appledger path/to/app --schedule off # stop
Windows
Adds a task to Task Scheduler. Use py -m appledger if python isn't found.
macOS
Adds a cron entry (crontab -l shows it). Checks run while the Mac is awake. For apps in Documents or Desktop, cron may need Full Disk Access.
Linux
Adds a cron entry (crontab -l shows it). Needs a running cron service.
--yes is your one-time consent to upload for unattended hosted checks; check --list-files first. Add --local to schedule local checks instead. --quiet prints one line per check.
Troubleshooting
I installed the plugin but Claude doesn't know about AppLedger
Start a new session; plugins load when a session starts. Type /plugin to see whether appledger is installed and enabled.
“claude” is not recognised as a command
The Claude Code command isn't on your PATH, which is common if you only use the desktop app. Install the plugin from the desktop app's plugin settings instead (add the marketplace contentasoftware/appledger), or install the Claude Code command line tool.
The AppLedger tools don't start (uv or uvx not found)
The plugin starts its server with uv. Install it with winget install astral-sh.uv (Windows) or brew install uv (macOS), or see uv's install guide, then restart Claude Code.
“This AppLedger connection key was revoked or is wrong”
The key was revoked in the dashboard or mistyped. Create a new one under Connect a computer and connect again. Checks still work without a key; they just aren't saved to the dashboard.
A script or scheduled run stops and asks for confirmation
The first hosted check of a folder needs your consent, and a non-interactive run can't ask. Check --list-files, then add --yes. Or use --local.
Local mode says a scanner is missing
Run python -m appledger --doctor. It shows which scanners and rules it found. Make sure Trivy and Opengrep are on your PATH, then open a new terminal.