DEV Community: Hardik

Sloth Sorter 🦥 — a local LLM tidies my Downloads folder, and every move can be undone

Hardik — Fri, 23 Oct 2026 19:45:47 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

My Downloads folder is where files go to be forgotten. Some examples:

invoice_final_v2.pdf
scan0003.pdf, which turns out to be a bank statement
document(7).pdf, which is actually lecture slides
three copies of setup.exe
a dozen Screenshot 2026-…png files

Sorting it by hand is exactly the kind of chore I keep putting off, so I built something that does it for me while I do nothing. Sloths would approve.

Sloth Sorter is a small, offline-first file tidier with a friendly web UI. You point it at the folders you never clean, like Downloads and Desktop. It then:

sorts files into category folders: Finance, Study, Personal & ID, Screenshots, Installers and so on
renames vague documents to something human, so scan0003.pdf becomes Supermarket Bank Statement Sep 2026.pdf
archives files you haven't touched in months into _Archive/<year>/
runs on a schedule, either applying changes automatically or preparing a plan for you to approve

The thing I cared about most was trust. A tool that moves my files around has to be boringly safe:

It never deletes and never overwrites anything. Name clashes become report (1).pdf.
Every run starts as a plan. You see a preview table, can untick rows or change a category or name, and only then press Sort everything.
Every move is written to a journal before it happens, and every run has an Undo button. Undo restores the original names and locations and cleans up the empty folders it created.
It skips anything risky: hidden files, shortcuts, half-finished downloads (.crdownload, .part), files modified in the last 10 minutes, and system folders like C:\Windows or AppData.

Demo

The UI is a little flat-2D "desktop" with rolling hills and drifting clouds:

Windows you can drag, minimise and bring to the front.
A taskbar with a Start menu, a live clock and the active model's name.
A dusk theme.
A sloth hanging from a branch, which sleeps when idle, says "sorting... slowly" while it works, and looks pleased when it's done.

Everything is drawn in inline SVG and CSS. The page loads nothing from the internet: no CDN, no web fonts.

Code

hardikgaikwad / Sloth-Sorter

Sloth Sorter 🦥

Sloths move about one metre a minute, and they still get where they're going. Sloth Sorter works at the same steady pace on your Downloads, Desktop and other cluttered folders It sorts files into tidy category folders, gives vague documents sensible names, and archives things you haven't touched in ages. It runs entirely on your own computer. A local language model served by Ollama helps only where simple rules can't decide.

It never deletes anything and never overwrites anything, and every run can be undone.

60-second quickstart

pip install -e .            # from this folder (Python 3.10+)
ollama list                 # optional: check Ollama is running and has at least one model
sloth-sorter                # or: python -m slothsorter

Your browser opens http://127.0.0.1:8484. Then:

In My Folders, add a folder such as C:\Users\you\Downloads. Type the path or use Browse….
Press Preview plan. Nothing…

View on GitHub

Try it on your own machine:

git clone https://github.com/hardikgaikwad/Sloth-Sorter.git
cd Sloth-Sorter
pip install -e .
python scripts/make_demo_clutter.py   # optional: a safe folder full of fake clutter
python -m slothsorter                 # opens http://127.0.0.1:8484

How I Built It

Stack: Python with FastAPI and uvicorn, SQLite, pypdf, python-docx and Pillow. The frontend is one static HTML/CSS/vanilla-JS page with no build step. The open-weight models are served locally by Ollama. I tested with Llama 3.2 (3B) and Qwen 2.5 (7B) on a laptop with a 4 GB GPU.

The key design decision is that rules go first and the LLM only gets the hard cases.

Rules, with no model call.
- Extensions decide installers, archives, video, audio, code, spreadsheets and slides.
- Filename patterns catch screenshots ("Screenshot", "Screen Shot", "Snip").
- A screen-sized PNG with no camera data is probably a screenshot.
- A JPEG with camera EXIF data is a photo.

In my test folder, this handled 18 of 29 files instantly.

The LLM handles documents and unknown files. For a PDF, DOCX, TXT, MD or CSV, I extract about 1,500 characters of text and send the filename plus that excerpt to Ollama's /api/chat. The request uses temperature: 0 and a JSON schema in format, so the model must pick a category from a fixed list and propose a short name:

"format": {
  "type": "object",
  "properties": {
    "category":       {"type": "string", "enum": list(CATEGORIES)},
    "suggested_name": {"type": "string"},
    "confidence":     {"type": "string", "enum": ["low", "medium", "high"]},
    "reason":         {"type": "string"},
  },
  "required": ["category", "suggested_name", "confidence", "reason"],
}

Code checks everything the model says.
- The model never produces paths. A path-like answer such as C:\Windows\… or ../../ falls back to the original name.
- Names are sanitised. Illegal Windows characters and reserved names like CON are removed, names are capped at 80 characters, and the original extension is always kept.
- Unknown categories are rejected.
- Low-confidence answers keep the original name and are flagged "needs review" in the plan.

Results are cached by content hash, model and prompt version, so re-running a plan is instant.

Two things I learned along the way:

Small models love CamelCase. Both models first returned names like AcmeHostingInvoice4471. One concrete example in the system prompt fixed it: "2–8 plain words separated by spaces, e.g. 'Acme Hosting Invoice Sep 2026'". Now I get Acme Hosting Invoice Sep 2026.pdf.
localhost cost me 4 seconds on Windows. When Ollama was off, localhost tried ::1 first and Windows retried the refused connection before falling back. Ollama listens on 127.0.0.1, so I connect there directly. If Ollama dies in the middle of a run, Sloth Sorter stops calling it and sorts the remaining files by type, instead of waiting on each one.

If Ollama isn't running at all, nothing breaks. The app switches to rules-only mode and shows a banner explaining ollama serve and ollama pull <model>. It never pulls a model itself. It reads your installed models from /api/tags, auto-picks a small chat model, and lets you switch from a dropdown at any time.

The scheduler is a background thread inside the server: no cron, no Celery.

Runs never overlap.
Catch-up: if the laptop was off when a run was due, it does one catch-up pass after start-up, not one for every missed slot.
Safe test interface: the whole web API listens on 127.0.0.1 only, with Host/Origin checks and a per-session token, so other websites in your browser can't call it.

There are 96 pytest tests. They cover:

the folder safety rules and the filename sanitiser
name collisions
the LLM path, using a mocked Ollama that returns bad JSON, unknown categories and path-like names
apply, journal and undo, with byte-for-byte restore checks
the scheduler, using a fake clock
the API's CSRF protections

Why Does Open Innovation Matter?

Because the files in my Downloads folder are the most private data I have. That test folder alone held a bank statement, a passport detail, a CV and invoices. A file tidier only works if it can read your files, and I'm not willing to upload my bank statements to a cloud API just to get them sorted.

Open-weight models running locally through Ollama make this possible:

Nothing leaves the machine. The only network traffic is to 127.0.0.1:11434.
It costs nothing to run. It can sort thousands of files on a schedule, every day, forever, with no API bill and no rate limit.
It keeps working offline, on a train, or after some company changes its pricing.
You choose the model. Use whatever you already have installed, and swap it from a dropdown. A 3B model is enough for "is this an invoice or lecture notes?"

The Lazy Payoff

I tested on a folder of 33 realistic clutter files: invoices, a bank statement, lecture notes, a CV, installers, screenshots and photos. These are measured numbers from the end-to-end runs, not guesses.

	Llama 3.2 3B	Qwen 2.5 7B	Rules only (Ollama off)
Files sent to the LLM	11 of 29	11 of 29	0
Correct category	26 / 29	27 / 29	22 / 29
Time to build the plan	11.9 s	65.3 s	0.3 s
Per LLM file	~1.1 s	~5.9 s	n/a
Undo restored everything byte-for-byte	✅	✅	✅

Doing this by hand means opening each mystery PDF, deciding where it goes, renaming it and dragging it. At roughly 20 seconds per file, the 28 files it moved represent about 9 minutes of chores, replaced by about 12 seconds of the sloth thinking and one click from me. The app keeps a running "estimated time saved" counter (files moved × seconds per file, adjustable in Settings and clearly labelled as an estimate). Set a daily schedule on Downloads and that counter keeps growing while you do nothing at all, which is the whole point. 🦥

The misses were reasonable judgement calls rather than disasters:

A CSV of rent and grocery transactions went to Spreadsheets instead of Finance.
A README about printer drivers was labelled Installers. The model flagged it as low confidence, so it kept its name and was marked for review.

And thanks to Undo, a wrong guess costs one click.

LocalAudit: an AI security auditor that never sees your secrets and never leaves your laptop

Hardik — Fri, 16 Oct 2026 09:21:01 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

LocalAudit is a command-line security auditor for source code that runs 100% on your own machine. Point it at a repo and a few seconds later you get a clean HTML report (plus JSON and Markdown) listing hardcoded secrets, injection risks, insecure configuration and unpinned dependencies. Each finding comes with the file and line, the code around it, a plain-English explanation and a concrete fix.

The design rule I cared most about: the LLM never detects anything. Deterministic rules find the issues: 24 code-pattern rules for Python/Django/Flask and JavaScript/Node, 10 built-in secret detectors (AWS, Stripe, Slack, GitHub, Google, JWTs, private keys, high-entropy strings...) and dependency checks. A local open-weight model then triages each finding. It explains it, judges whether it's likely a false positive in context, and writes a fix. If the model is unavailable, you still get the full report.

Who would pay for this? People who need a security pass on code they aren't allowed to upload anywhere:

Freelancers and small agencies working on client code under NDA. A fixed-fee "pre-handoff security check" with a professional report as the deliverable is an easy add-on to sell.
Solo founders about to launch who can't justify an enterprise SAST subscription.
Consultants who want a fast first pass before a manual review.

For all of them, the cloud AI code-review tools have the same problem: your client's source code goes to someone else's server. LocalAudit's answer is that it doesn't go anywhere.

Demo

The demo scans the bundled examples/vulnerable_app, a deliberately insecure Django + Node app full of fake credentials. The rules-only scan takes about a second and finds 43 issues (4 critical, 16 high), for a risk score of 100/100. A few things worth watching for:

Secrets are masked everywhere. You'll only ever see AKIA****. Even a private key's body is replaced with **** before any snippet is built, so raw secrets never reach the report, the console or the model's prompt.
The model catches a decoy. The app contains subprocess.check_output("df -h /", shell=True). The rule correctly flags shell=True, but the command is a constant with no user input. The local model marked it as a likely false positive. LocalAudit doesn't delete it: it moves it to a separate "Likely false positives" section for a human to confirm.
It falls back gracefully. Stop Ollama and the tool prints the exact command to fix it (ollama pull qwen2.5-coder:7b), then carries on with the rules-only report.

Code

hardikgaikwad / localaudit

LocalAudit

A command-line security audit tool for source code repositories that runs 100% locally.

Deterministic rules find the issues: built-in secret detection, about 25 code-pattern rules for Python/Django/Flask, JavaScript/Node and generic files, and dependency pinning checks.
A local LLM triages them through Ollama. For each finding it explains the issue in plain language, judges whether it is likely a false positive, and suggests a concrete fix.
The LLM never detects vulnerabilities, and it never deletes a finding. Anything it judges a likely false positive goes into a separate section for you to review.
The report is complete and useful without the LLM (--no-llm, or when Ollama isn't running).

Output: a self-contained report.html (no CDN or external requests, and it prints cleanly to PDF), plus report.json and report.md.

60-second quickstart

# 1. Get the model (one time, ~4.7 GB)
ollama pull qwen2.5-coder:7b
# 2. Install

…

View on GitHub

ollama pull qwen2.5-coder:7b
pip install -e .
localaudit scan examples/vulnerable_app
# open localaudit-report/report.html

Useful flags: --no-llm, --min-severity high, --max-llm-findings 10, --model <any Ollama model>, and --fail-on high (exits with code 1, for CI).

How I Built It

The open-source AI at the core:

Ollama for local inference over its HTTP API.
Qwen2.5-Coder 7B, an open-weight coding model. It's the default, and you can swap it with --model or LOCALAUDIT_MODEL.

How the pipeline works:

Scan. Walk the repo, skipping .git, node_modules, venvs, build output, binaries, files over 1 MB and anything in .localauditignore.
Detect and redact. Run the secret detectors first and redact every detected value from the file text. Only then run the code rules and build snippets, which is how masking is guaranteed everywhere downstream.
Triage. Send each finding, highest severity first, to the local model. The request includes the rule description, the file path and the masked snippet. It runs at temperature 0, and Ollama's format parameter enforces a JSON schema, so the model must return {explanation, risk_in_context, likely_false_positive, confidence, suggested_fix, fixed_code_example}. Invalid JSON gets one retry, then the finding is marked "LLM triage unavailable".
Cache. Results are cached on disk, keyed by model + rule + snippet, so reruns are instant.
Report. Render a single self-contained HTML file with no CDNs or external requests, plus a print stylesheet so "Save as PDF" gives a client-ready document.

The stack is deliberately small: Python 3.10+, requests, jinja2 and pytest, with 110 tests. Those tests include a mocked Ollama covering invalid JSON, timeouts and the server going down mid-run.

I built it with an AI coding agent (Claude Code) doing much of the implementation while I directed the design and reviewed the results. One moment I liked: testing caught a regex bug where a bare password = "..." wasn't detected. Because the masker only masks what the detector finds, that password was showing up unmasked as a context line in a neighbouring finding's snippet. It's fixed now, and there's a regression test for it.

Why Does Open Innovation Matter?

For this product, open weights aren't a nice-to-have. They're the reason it can exist.

Privacy is the product. The customers I described can't send client code to a third-party API. A local open-weight model is the only way to give them AI explanations without breaking that rule. Nothing leaves the laptop.
The economics work. There's no per-token bill, so you can rescan on every commit, or scan a whole agency's worth of repos, for zero marginal cost. A paid API would make a cheap fixed-fee audit service hard to sustain.
No lock-in. Switching models is one flag. When a better open coding model ships, users upgrade by running ollama pull, not by renegotiating a contract.
Trust comes from transparency. The rules are plain regexes in a readable list, the model is inspectable, and the report says clearly which parts are deterministic and which are advisory.

Honest limitations:

Detection is regex-based and line-by-line, so it misses multi-line patterns and logic bugs.
A small model can misjudge a finding, which is why "false positives" are never deleted and still count toward --fail-on.
Speed depends on your hardware. On my machine the 7B model is split between CPU and GPU and takes about a minute per finding. A GPU that fits the whole model is much faster.
It isn't a pentest. It's a fast, private first pass.

My Agent Session

[AGENT_SESSION_PLACEHOLDER]

Changes from the template, and why:

"My First User" is removed. You don't have one yet, and the template says to delete the section in that case. It's where the bonus points are, though. If a friend or client runs it on their repo before the deadline, add the section back with what they said, even a sentence or two.
"Prize Categories" is removed. None of the 17 partner categories apply: LocalAudit uses Qwen, not Gemma, and doesn't use GitHub Copilot or any other parclearly which parts are deterministic and which are advisory.

Honest limitations:

Detection is regex-based and line-by-line, so it misses multi-line patterns and logic bugs.
A small model can misjudge a finding, which is why "false positives" are never deleted and still count toward --fail-on.
Speed depends on your hardware. On my machine the 7B model is split between CPU and GPU and takes about a minute per finding. A GPU that fits the whole model is much faster.
It isn't a pentest. It's a fast, private first pass.

My Agent Session

Building LocalAudit: a local-only AI security auditor (Claude Code session)

You

Build "LocalAudit": a command-line security audit tool for source code repositories that runs 100% locally. Deterministic rules detect issues, and a local LLM served by Ollama triages and explains them. Build it in the CURRENT working directory (do not create a nested project folder). Keep the scope tight: a small, clean, working tool beats a large, fragile one.

Core principle

The LLM NEVER detects vulnerabilities. Rules find candidate findings; the LLM only (a) explains each finding in plain language, (b) judges whether it is likely a false positive given the surrounding code, and (c) suggests a concrete fix. The tool must still produce a complete, useful report with --no-llm or when Ollama is unreachable.

Stack (keep it minimal)

Python 3.10+, standard library plus requests and jinja2 only. Use argparse for the CLI. Use pytest for tests.
Ollama HTTP API at http://localhost:11434 (/api/chat, stream=false). Default model qwen2.5-coder:7b, overridable with --model and the env var LOCALAUDIT_MODEL.
Package layout: localaudit/ (cli.py, scanner.py, rules.py, secrets.py, llm.py, report.py, models.py, templates/report.html.j2), tests/, examples/vulnerable_app/, README.md, requirements.txt, pyproject.toml (installable with a localaudit console script).

Features

Scanner
- Walk the target path; skip .git, node_modules, venv/.venv, pycache, dist, build, binaries, and files over 1 MB. Respect a simple .localauditignore (one glob per line).
- Each Finding has: id, rule_id, title, severity (critical/high/medium/low/info), category, file, line, snippet (the line plus 3 lines of context either side), and the matched text.
Secret detection (secrets.py), built in with no external tools
- Regexes for: AWS access key IDs, private key blocks, GitHub tokens, Slack tokens, Stripe live keys, Google API keys, JWTs, and generic password/secret/api_key/token = "<literal>" assignments.
- A Shannon-entropy check for high-entropy string literals assigned to suspicious variable names.
- Ignore obvious placeholders (changeme, your_key_here, example, xxx, <...>, ${...}, os.environ lookups).
- ALWAYS mask secret values in all output (show the first 4 characters then ****). Real secret values must never appear in the report, the console, or the LLM prompt.
Code-pattern rules (rules.py), a data-driven list of regex rules with language filters, severity, CWE id, and a short description. Include about 15-20 rules such as:
- Python/Django/Flask: DEBUG = True, ALLOWED_HOSTS = ['*'], hardcoded SECRET_KEY, eval/exec, pickle.loads, yaml.load without SafeLoader, subprocess with shell=True, os.system, string-formatted SQL passed to execute()/raw(), verify=False in requests, weak hashes (md5/sha1) for passwords, CORS_ALLOW_ALL_ORIGINS = True, csrf_exempt, mark_safe, Flask app.run(debug=True).
- JS/Node: eval(, child_process.exec with template strings, innerHTML =, dangerouslySetInnerHTML, rejectUnauthorized: false, Math.random used for tokens, wildcard CORS.
- Generic: private IPs/internal URLs hardcoded, TODO/FIXME mentioning security or auth, chmod 777.
Dependency check (optional, graceful)
- Parse requirements.txt and package.json. Flag unpinned Python dependencies (low severity).
- If pip-audit is installed, run it on requirements.txt and import its results as findings. If not installed, print a one-line notice and continue. Never fail because a tool is missing.
LLM triage (llm.py)
- For each finding (highest severity first, capped by --max-llm-findings, default 25), send the rule description, masked snippet, and file path to Ollama.
- Require structured JSON output using Ollama's format parameter with a JSON schema: {explanation, risk_in_context, likely_false_positive (bool), confidence (low/medium/high), suggested_fix, fixed_code_example}. Temperature 0, num_ctx 4096, request timeout 120s, one retry on invalid JSON, then fall back to marking the finding "LLM triage unavailable".
- Cache results on disk in .localaudit_cache/ keyed by a hash of (model + rule_id + snippet) so reruns are fast.
- Check Ollama availability up front (GET /api/tags). If Ollama is down or the model is not pulled, print the exact command to fix it (ollama pull <model>) and continue in --no-llm mode instead of crashing.
- The LLM may downgrade a finding as a likely false positive but must never silently delete it. Show it in a separate "Likely false positives" section.
Reporting (report.py)
- Output a single self-contained HTML report (inline CSS, no external requests, no CDN) with: title and scan metadata (path, date, model used, duration, files scanned), a severity summary with counts, a risk score out of 100, findings grouped by severity (each with file:line, code snippet, explanation, fix, and fix example), a collapsed "Likely false positives" section, and a print stylesheet so Save as PDF from the browser looks clean.
- Also write report.json (machine-readable) and report.md.
- CLI flags: localaudit scan PATH [--model M] [--out DIR] [--no-llm] [--max-llm-findings N] [--min-severity LEVEL] [--format html,json,md] [--fail-on LEVEL]. --fail-on returns exit code 1 if any finding is at or above that severity (for CI use). Show a concise coloured console summary and a progress indicator during LLM triage.
Demo and tests
- Create examples/vulnerable_app/: a small intentionally vulnerable Django-style app and a small Node file, with fake credentials, that triggers most of the rules. Add a prominent comment that it is intentionally insecure.
- pytest tests: each rule fires on a known-bad snippet and does not fire on a safe one; secrets are masked; placeholders are ignored; the scanner finds the expected findings in the example app; the LLM module is tested with a mocked HTTP response (including invalid JSON and Ollama-down cases); --no-llm end-to-end run produces all three report f [... truncated 1197 chars]

Agent

Plan: models → rules/secrets → scanner → report (with --no-llm) → tests → LLM module → README and example app → run tests, run the scan, check whether Ollama is available.

▸ Bash {"command": "ls -la && python --version && pip --version && python -c \"impor...

Input

$ {"command": "ls -la && python --version && pip --version && python -c \"import requests, jinja2, pytest; print('ok')\"; which pip-audit ollama; curl - [... trimmed]

Output

total 0
drwxr-xr-x 1 <user> 197609 0 Oct 16 13:04 .
drwxr-xr-x 1 <user> 197609 0 Nov  3  2025 ..
Python 3.14.7
pip 26.2 [... trimmed]

Empty directory; Python 3.14; jinja2 is missing; Ollama is installed but not answering on :11434 right now. Writing the package now.

▸ Bash {"command": "mkdir -p localaudit/templates tests examples/vulnerable_app && c...

Input

$ {"command": "mkdir -p localaudit/templates tests examples/vulnerable_app && cat > requirements.txt <<'EOF'\nrequests>=2.28\njinja2>=3.1\nEOF\ncat > py [... trimmed]

Output

(Bash completed with no output)

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\models.py", "content": "\"\"...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\models.py", "content": "\"\"\"Core data types shared across LocalAudit.\"\"\"\n\nfrom __future__ impo [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\models.py (file state is current in your context — no need  [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\secrets.py", "content": "\"\...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\secrets.py", "content": "\"\"\"Built-in secret detection: provider-specific regexes, generic assignme [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\secrets.py (file state is current in your context — no need [... trimmed]

Fixing one thing: provider-specific keys (e.g. a live Stripe key used as an os.environ.get default) should still be caught; only the generic/entropy checks should skip env lookups.

▸ Bash {"command": "python - <<'EOF'\np='localaudit/secrets.py'\ns=open(p).read()\ns...

Input

$ {"command": "python - <<'EOF'\np='localaudit/secrets.py'\ns=open(p).read()\ns=s.replace(\"\"\"    for idx, line in enumerate(lines, start=1):\n        [... trimmed]

Output

(Bash completed with no output)

Now the code-pattern rules.

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\rules.py", "content": "\"\"\...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\rules.py", "content": "\"\"\"Data-driven code-pattern rules.\n\nTo add a rule, append a `Rule(...)` t [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\rules.py (file state is current in your context — no need t [... trimmed]

Adding snippet_start to Finding so reports can number snippet lines, then the scanner (including dependency checks).

▸ Bash {"command": "python - <<'EOF'\np='localaudit/models.py'\ns=open(p).read()\ns=...

Input

$ {"command": "python - <<'EOF'\np='localaudit/models.py'\ns=open(p).read()\ns=s.replace(\"\"\"    snippet: str\n    match: str\n    description\"\"\",\ [... trimmed]

Output

(Bash completed with no output)

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\scanner.py", "content": "\"\...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\scanner.py", "content": "\"\"\"Walk a target path and run secret, code-pattern and dependency checks. [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\scanner.py (file state is current in your context — no need [... trimmed]

Making dependency checks also work on redacted text (a requirements line could carry a tokenized URL):

▸ Bash {"command": "python - <<'EOF'\np='localaudit/scanner.py'\ns=open(p).read()\no...

Input

$ {"command": "python - <<'EOF'\np='localaudit/scanner.py'\ns=open(p).read()\nold=\"\"\"        name = path.name.lower()\n        if name.startswith(\"r [... trimmed]

Output

(Bash completed with no output)

That package.json line is needlessly convoluted; simplifying it.

▸ Edit {"replace_all": false, "file_path": "<projects>\\LocalSec\\localaudit\\scanne...

Input

{"replace_all": false, "file_path": "<projects>\\LocalSec\\localaudit\\scanner.py", "old_string": "                result.findings.extend(check_packag [... trimmed]

Output

The file <projects>\LocalSec\localaudit\scanner.py has been updated successfully.

Now the reporting module and HTML template.

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\report.py", "content": "\"\"...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\report.py", "content": "\"\"\"Render scan results as self-contained HTML, JSON and Markdown.\"\"\"\n\ [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\report.py (file state is current in your context — no need  [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\templates\\report.html.j2", ...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\templates\\report.html.j2", "content": "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\" [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\templates\report.html.j2 (file state is current in your con [... trimmed]

Now the LLM triage module.

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\llm.py", "content": "\"\"\"L...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\llm.py", "content": "\"\"\"Local LLM triage through the Ollama HTTP API.\n\nThe model never detects i [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\llm.py (file state is current in your context — no need to  [... trimmed]

Progress should show before each (possibly slow) request, not after. Adjusting:

▸ Bash {"command": "python - <<'EOF'\np='localaudit/llm.py'\ns=open(p).read()\ns=s.r...

Input

$ {"command": "python - <<'EOF'\np='localaudit/llm.py'\ns=open(p).read()\ns=s.replace(\"progress: Optional[Callable[[int, int, Finding, bool], None]] =  [... trimmed]

Output

207:                    progress: Optional[Callable[[int, int, Finding], None]] = None) -> dict:
219:        if progress [... trimmed]

Now the CLI.

▸ Write {"file_path": "<projects>\\LocalSec\\localaudit\\cli.py", "content": "\"\"\"C...

Input

{"file_path": "<projects>\\LocalSec\\localaudit\\cli.py", "content": "\"\"\"Command-line interface: `localaudit scan PATH ...`.\"\"\"\n\nfrom __future [... trimmed]

Output

File created successfully at: <projects>\LocalSec\localaudit\cli.py (file state is current in your context — no need to  [... trimmed]

▸ Bash {"command": "cat > localaudit/__main__.py <<'EOF'\nimport sys\n\nfrom .cli im...

Input

$ {"command": "cat > localaudit/__main__.py <<'EOF'\nimport sys\n\nfrom .cli import main\n\nsys.exit(main())\nEOF\nmkdir -p examples/vulnerable_app/shop [... trimmed]

Output

done

Install and do a first rules-only scan:

▸ Bash {"command": "pip install -q -e \".[dev]\" 2>&1 | tail -3; localaudit scan exa...

Input

$ {"command": "pip install -q -e \".[dev]\" 2>&1 | tail -3; localaudit scan examples/vulnerable_app --no-llm --out \"$TEMP/la-out\" 2>&1", "description" [... trimmed]

Output

Exit code 127
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script- [... trimmed]

The console script installed to a user Scripts dir that isn't on PATH; I'll call it by full path for now (and mention it at the end).

▸ Bash {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"...

Input

$ {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"; \"$LA\" scan examples/vulnerable_app --no-llm --out \"$TEMP/la-out\"; e [... trimmed]

Output

Exit code 1
Traceback (most recent call last):
  File "<frozen runpy>", line 203, in _run_module_as_main
  File "<froz [... trimmed]

The heredoc turned \\n into a real newline. Fixing:

▸ Read {"file_path": "<projects>\\LocalSec\\localaudit\\scanner.py", "offset": 264, ...

Input

{
  "file_path": "<projects>\\LocalSec\\localaudit\\scanner.py",
  "offset": 264,
  "limit": 8
}

Output

264          name = path.name.lower()
265         is_req = name.startswith("requirements") and name.endswith(".txt")
266  [... trimmed]

▸ Edit {"replace_all": false, "file_path": "<projects>\\LocalSec\\localaudit\\scanne...

Input

{"replace_all": false, "file_path": "<projects>\\LocalSec\\localaudit\\scanner.py", "old_string": "            safe_text = \"\n\".join(", "new_string" [... trimmed]

Output

The file <projects>\LocalSec\localaudit\scanner.py has been updated successfully.

▸ Bash {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"...

Input

$ {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"; \"$LA\" scan examples/vulnerable_app --no-llm --out \"$TEMP/la-out\"; e [... trimmed]

Output

LocalAudit 0.1.0  scanning <projects>\LocalSec\examples\vulnerable_app
Scanned 10 files (0 skipped), 42 findings at or  [... trimmed]

42 findings, secrets masked. One miss: "PASSWORD": "Sup3****" in the settings dict wasn't flagged. Debugging:

▸ Bash {"command": "python -c \"\nfrom localaudit import secrets as s\nline=' ...

Input

$ {"command": "python -c \"\nfrom localaudit import secrets as s\nline='        \\\"PASSWORD\\\": \\\"Sup3****\\\",'\nprint(s.GENERIC_ASSIGNMENT.search( [... trimmed]

Output

None
False None

> pip-audit not installed; skipping known-vulnerability check (pip install pip-audit to enable).

##  [... trimmed]

▸ Bash {"command": "python -c \"\nfrom localaudit import secrets as s\nimport re\npr...

Input

$ {"command": "python -c \"\nfrom localaudit import secrets as s\nimport re\nprint(repr(s.GENERIC_ASSIGNMENT.pattern))\nfor l in ['PASSWORD: \\\"Sup3*** [... trimmed]

Output

'(?ix)\n    ["\']?(?P<name>\\b[A-Za-z_][A-Za-z0-9_]*?(?:password|passwd|pwd|secret|api_?key|token)[A-Za-z0-9_]*)\\b["\'] [... trimmed]

Bug: \b[A-Za-z_] must consume one char before the keyword, so a bare password/token/secret name never matched. Fixing both regexes:

▸ Bash {"command": "sed -i 's/(?P<name>\\\\b\\[A-Za-z_\\]\\[A-Za-z0-9_\\]\\*?/(?P<na...

Input

$ {"command": "sed -i 's/(?P<name>\\\\b\\[A-Za-z_\\]\\[A-Za-z0-9_\\]\\*?/(?P<name>\\\\b[A-Za-z0-9_]*?/' localaudit/secrets.py && grep -n \"P<name>\" loc [... trimmed]

Output

80:    ["']?(?P<name>\b[A-Za-z_][A-Za-z0-9_]*?(?:password|passwd|pwd|secret|api_?key|token)[A-Za-z0-9_]*)\b["']?
89:     [... trimmed]

Sed didn't match; using a Python replace instead.

▸ Bash {"command": "python - <<'EOF'\np='localaudit/secrets.py'\ns=open(p).read()\no...

Input

$ {"command": "python - <<'EOF'\np='localaudit/secrets.py'\ns=open(p).read()\nold=r'(?P<name>\\b[A-Za-z_][A-Za-z0-9_]*?'\nassert s.count(old)==2\ns=s.re [... trimmed]

Output

PASSWORD: "Sup3****" [('secret-generic-assignment', 'Sup3****')]
password = "Sup3****" [('secret-generic-assignment', ' [... trimmed]

Now the tests.

▸ Write {"file_path": "<projects>\\LocalSec\\tests\\test_rules.py", "content": "impor...

Input

{"file_path": "<projects>\\LocalSec\\tests\\test_rules.py", "content": "import pytest\n\nfrom localaudit.rules import RULES, get_rule, rules_for\n\n#  [... trimmed]

Output

File created successfully at: <projects>\LocalSec\tests\test_rules.py (file state is current in your context — no need t [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\tests\\test_secrets.py", "content": "imp...

Input

{"file_path": "<projects>\\LocalSec\\tests\\test_secrets.py", "content": "import pytest\n\nfrom localaudit import secrets\nfrom localaudit.scanner imp [... trimmed]

Output

File created successfully at: <projects>\LocalSec\tests\test_secrets.py (file state is current in your context — no need [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\tests\\test_scanner.py", "content": "fro...

Input

{"file_path": "<projects>\\LocalSec\\tests\\test_scanner.py", "content": "from pathlib import Path\n\nfrom localaudit import scanner\nfrom localaudit. [... trimmed]

Output

File created successfully at: <projects>\LocalSec\tests\test_scanner.py (file state is current in your context — no need [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\tests\\test_llm.py", "content": "import ...

Input

{"file_path": "<projects>\\LocalSec\\tests\\test_llm.py", "content": "import json\n\nimport pytest\nimport requests\n\nfrom localaudit import llm, rep [... trimmed]

Output

File created successfully at: <projects>\LocalSec\tests\test_llm.py (file state is current in your context — no need to  [... trimmed]

▸ Write {"file_path": "<projects>\\LocalSec\\tests\\test_cli.py", "content": "import ...

Input

{"file_path": "<projects>\\LocalSec\\tests\\test_cli.py", "content": "import json\nimport re\nfrom pathlib import Path\n\nimport pytest\n\nfrom locala [... trimmed]

Output

File created successfully at: <projects>\LocalSec\tests\test_cli.py (file state is current in your context — no need to  [... trimmed]

▸ Bash {"command": "python -m pytest -q 2>&1 | tail -40", "description": "Run the te...

Input

$ {"command": "python -m pytest -q 2>&1 | tail -40", "description": "Run the test suite"}

Output

.............F.......................................................... [ 65%]
......................................  [... trimmed]

The three test findings share a snippet, so the cache answered them (correct behavior — the test was wrong). Giving each a distinct snippet:

▸ Bash {"command": "python - <<'EOF'\np='tests/test_llm.py'\ns=open(p).read()\nold='...

Input

$ {"command": "python - <<'EOF'\np='tests/test_llm.py'\ns=open(p).read()\nold='''    findings = [make_finding(severity=\"low\", line=1), make_finding(se [... trimmed]

Output

........................................................................ [ 65%]
......................................  [... trimmed]

110 passing. Now I want to actually look at the HTML report. Checking for a headless browser to screenshot it:

▸ Bash {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"...

Input

$ {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"; \"$LA\" scan examples/vulnerable_app --no-llm --out \"$TEMP/la-out\" >/ [... trimmed]

Output

/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe
/c/Program Files/Google/Chrome/Application/chrome.exe

▸ Bash {"command": "SP=\"~/AppData/Local/Temp/claude/<project-id>/5982a5be-821b-4a50...

Input

$ {"command": "SP=\"~/AppData/Local/Temp/claude/<project-id>/5982a5be-821b-4a50-8648-c43f4c26c75d/scratchpad\"; mkdir -p \"$SP\"; CH=\"/c/Program Files/ [... trimmed]

Output

total 452
drwxr-xr-x 1 <user> 197609      0 Oct 16 13:20 .
drwxr-xr-x 1 <user> 197609      0 Oct 16 13:07 ..
-rw-r--r--  [... trimmed]

▸ Read {"file_path": "~\\AppData\\Local\\Temp\\claude\\<project-id>\\5982a5be-821b-4...

Input

{
  "file_path": "~\\AppData\\Local\\Temp\\claude\\<project-id>\\5982a5be-821b-4a50-8648-c43f4c26c75d\\scratchpad\\shot.png"
}

Output

[image]

▸ Read {"file_path": "~\\AppData\\Local\\Temp\\claude\\<project-id>\\5982a5be-821b-4...

Input

{
  "file_path": "~\\AppData\\Local\\Temp\\claude\\<project-id>\\5982a5be-821b-4a50-8648-c43f4c26c75d\\scratchpad\\report.pdf",
  "pages": "1-2"
}

Output

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to ena [... trimmed]

▸ Bash {"command": "curl -s -m 3 http://localhost:11434/api/tags; echo \"rc=$?\"; ls...

Input

$ {"command": "curl -s -m 3 http://localhost:11434/api/tags; echo \"rc=$?\"; ls ~/.ollama/models/manifests/registry.ollama.ai/library/ 2>/dev/null; ls ~ [... trimmed]

Output

Exit code 2
{"models":[{"name":"qwen2.5-coder:3b","model":"qwen2.5-coder:3b","modified_at":"2026-10-16T13:15:26+05:30"," [... trimmed]

Ollama is up now and qwen2.5-coder:7b is pulled, so I'm running a real LLM scan (default cap: 25 findings):

▸ Bash {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"...

Input

$ {"command": "LA=\"~/AppData/Roaming/Python/Python314/Scripts/localaudit.exe\"; time \"$LA\" scan examples/vulnerable_app --out \"$TEMP/la-llm\" 2>&1 | [... trimmed]

Output

Command did not complete within its 600s timeout and was moved to the background (ID: bcv7500is). Output is being writte [... trimmed]

It's slow (>10 min so far). While it runs, I'll check its progress and write the README.

▸ Bash {"command": "ls .localaudit_cache | wc -l; tail -c 600 \"~/AppData/Local/Temp...

Input

$ {"command": "ls .localaudit_cache | wc -l; tail -c 600 \"~/AppData/Local/Temp/claude/<project-id>/f0d03b42-0e55-44bb-ae6d-75f69b9bc920/tasks/bcv7500is [... trimmed]

Output

11

NAME                ID              SIZE      PROCESSOR          CONTEXT    UNTIL              
qwen2.5-coder:7b     [... trimmed]

About 55 s per finding: the 7B model is split 55/45 CPU/GPU on this machine, so 11 of the 25 findings are done so far. Writing the README in the meantime.

▸ Write {"file_path": "<projects>\\LocalSec\\README.md", "content": "# LocalAudit\n\n...

Input

{"file_path": "<projects>\\LocalSec\\README.md", "content": "# LocalAudit\n\nA command-line security audit tool for source code repositories that runs [... trimmed]

Output

The server-side auto mode classifier gave no verdict (it skipped this action), so auto mode cannot determine the safety  [... trimmed]

▸ Bash {"command": "ls .localaudit_cache | wc -l", "description": "Count cached tria...

Input

$ {"command": "ls .localaudit_cache | wc -l", "description": "Count cached triage results"}

Output

▸ ToolSearch {"query": "select:Monitor", "max_results": 1}

Input

{
  "query": "select:Monitor",
  "max_results": 1
}

Output

[image]

▸ Monitor {"command": "until [ -f \"$TEMP/la-llm/report.json\" ]; do sleep 15; done; ec...

Input

{"command": "until [ -f \"$TEMP/la-llm/report.json\" ]; do sleep 15; done; echo \"LLM scan finished\"; ls <projects>/LocalSec/.localaudit_cache | wc - [... trimmed]

Output

Monitor started (task b8oml6ciw, expires in 30m unless the source ends first; you get one notice at expiry — re-arm if y [... trimmed]

The monitor is armed and I'll be notified when the report lands. Meanwhile I'm checking that the python -m localaudit fallback works, since the console script isn't on PATH here:

▸ Bash {"command": "python -m localaudit scan examples/vulnerable_app --no-llm --for...

Input

$ {"command": "python -m localaudit scan examples/vulnerable_app --no-llm --format md --out \"$TEMP/la-m\" --fail-on high | tail -3; echo \"exit=$?\"; p [... trimmed]

Output

wrote ~\AppData\Local\Temp\la-m\report.md
FAIL: 20 finding(s) at or above 'high'.
exit=0
localaudit 0.1.0

(exit=0 there is from tail, which ends the pipe; the exit code 1 itself is covered by test_fail_on.) Waiting for the LLM scan to finish.

You

write the README with bash instead

Agent

I'll write the README with a bash heredoc, as you asked. I also see that you stopped the LLM scan and its monitor.

▸ Bash {"command": "cat > README.md <<'EOF'\n# LocalAudit\n\nA command-line security...

Input

$ {"command": "cat > README.md <<'EOF'\n# LocalAudit\n\nA command-line security audit tool for source code repositories that runs **100% locally**.\n\n- [... trimmed]

Output

Exit code 2
/usr/bin/bash: -c: line 102: unexpected EOF while looking for matching `''

The heredoc didn't parse, probably because of the apostrophes in the body. Checking with a minimal test:

▸ Bash {"command": "cat > \"$TEMP/t.txt\" <<'EOF'\nit's `x` and \"y\" ${z} \\b\nEOF\...

Input

$ {"command": "cat > \"$TEMP/t.txt\" <<'EOF'\nit's `x` and \"y\" ${z} \\b\nEOF\ncat \"$TEMP/t.txt\"", "description": "Test heredoc with apostrophes and  [... trimmed]

Output

it's `x` and "y" ${z} \b

A small heredoc works, so something in the body is breaking it. Writing the README in parts to find the culprit:

▸ Bash {"command": "cat > README.md <<'README_END'\n# LocalAudit\n\nA command-line s...

Input

$ {"command": "cat > README.md <<'README_END'\n# LocalAudit\n\nA command-line security audit tool for source code repositories that runs **100% locally* [... trimmed]

Output

57 README.md

▸ Bash {"command": "cat >> README.md <<'README_END'\n## What it checks\n\n**Secrets*...

Input

$ {"command": "cat >> README.md <<'README_END'\n## What it checks\n\n**Secrets** (`localaudit/secrets.py`, no external tools): AWS access key IDs, priva [... trimmed]

Output

81 README.md

▸ Bash {"command": "cat >> README.md <<'README_END'\n## LLM triage\n\nFor each findi...

Input

$ {"command": "cat >> README.md <<'README_END'\n## LLM triage\n\nFor each finding, highest severity first up to `--max-llm-findings`, LocalAudit sends t [... trimmed]

Output

102 README.md

▸ Bash {"command": "cat >> README.md <<'README_END'\n## Adding a rule\n\nAppend a `R...

Input

$ {"command": "cat >> README.md <<'README_END'\n## Adding a rule\n\nAppend a `Rule` to `RULES` in `localaudit/rules.py`:\n\n```python\nRule(\"py-tempfil [... trimmed]

Output

136 README.md
9
23

▸ Bash {"command": "python -c \"\nimport json,glob\nfor p in glob.glob('.localaudit_...

Input

$ {"command": "python -c \"\nimport json,glob\nfor p in glob.glob('.localaudit_cache/*.json'):\n    t=json.load(open(p))\n    print(('FP ' if t['likely_ [... trimmed]

Output

hig | The code contains a hardcoded GitHub personal access token, which is a critical security risk.  || FIX: Remove the [... trimmed]

LocalAudit is built in the current directory and the README is now written. All 110 tests pass, and the rules-only scan of the demo app produces all three reports with every secret masked. A full scan with the LLM never finished, because you stopped it after 23 of the 25 findings had been triaged.

Rules-only scan of examples/vulnerable_app: 43 findings (4 critical, 16 high, 15 medium, 8 low) and a risk score of 100/100. I viewed the HTML report in headless Chrome and it renders cleanly. I also checked every output (HTML, JSON, Markdown, console) for each fake secret, and none of the real values appear anywhere.

LLM run (qwen2.5-coder:7b): about 55 seconds per finding, because the model is split 55% CPU / 45% GPU on your machine. All 23 results I read from the cache were valid JSON and made sense:
- The SQL injection, pickle, eval and secret findings were explained correctly, with the right fixes (parameterised queries, yaml.safe_load, execFile, environment variables).
- It correctly marked the deliberate decoy, subprocess.check_output("df -h /", shell=True) with no user input, as a likely false positive.
- The run never wrote a report, so I haven't seen the "Likely false positives" section filled with real model output. That path is covered by a mocked test.

How to run it:
pip install -e ".[dev]" python -m localaudit scan examples/vulnerable_app --no-llm python -m localaudit scan examples/vulnerable_app --max-llm-findings 5 # with the LLM pytest
On your machine pip put localaudit.exe in ~\AppData\Roaming\Python\Python314\Scripts, which isn't on PATH. Add that folder to PATH to use the localaudit command directly, or use python -m localaudit as above. A rerun of the LLM scan reuses the 23 cached results, so only the remaining 2 hit the model.

Things I fixed or decided along the way:
- I found and fixed a bug where bare names like password = "..." weren't detected as secrets. Because of it, an unmasked password was showing up as a context line in another finding's snippet. There's now a regression test for this.
- Live provider keys (Stripe, AWS and so on) are still flagged when used as an os.environ.get default. Only the generic checks skip environment lookups.
- --fail-on also counts findings the LLM marked as likely false positives, so the model can't turn a CI gate green on its own.

Not verified:
- pip-audit isn't installed. The "not installed" notice is checked on a real scan, but importing pip-audit results is only tested with a mocked output.
- I didn't look at the PDF output of the print stylesheet (no PDF renderer here). Chrome produced the PDF without errors.

Small deviations from the spec:
- The Django SECRET_KEY check sits in secrets.py rather than rules.py, so its value gets masked like any other secret.
- The dependency checks live in scanner.py.
- I added localaudit/__main__.py so python -m localaudit works.

You

Is this a command line based tool?

Agent

Yes, it's purely a command-line tool. There's no GUI, web server or interactive mode. You run one command, it scans and writes its reports, then exits:

python -m localaudit scan PATH [--model M] [--out DIR] [--no-llm] [--max-llm-findings N]
                               [--min-severity LEVEL] [--format html,json,md] [--fail-on LEVEL]

Terminal output: a coloured summary with counts by severity, the risk score and the top findings, plus a progress line while the LLM triages.
Files: report.html, report.json and report.md in the output folder (./localaudit-report by default).
Exit code: 0 normally, 1 when --fail-on is triggered, 2 for bad arguments. That lets it run in CI scripts.

The HTML report is the only visual part. It's a static file you open in a browser after the scan, not a running app.

Once the Scripts folder is on your PATH (see my last message), you can type localaudit scan ... instead of python -m localaudit scan .... Both run the same entry point.

You

what codebase did you test it with?

Agent

I only tested it on code I wrote myself during this session. I haven't run it on any real-world codebase. Specifically:

examples/vulnerable_app/, the demo app I wrote for this project: about 10 files, made up of a Django-style settings.py, views.py and integrations.py, plus a Node server.js, a React widget.jsx, requirements.txt, package.json and deploy.sh. It's deliberately vulnerable, with fake credentials. All the scan results I reported (the 43 findings and the LLM triage) come from this app.
One-line snippets in the unit tests, a known-bad and a safe example for each rule and secret pattern.
Small temporary folders created by the tests, to check the skipped folders, binary and oversized files, and .localauditignore.

That's a real limitation. I wrote the rules and the demo app together, so the app naturally triggers them. The run tells you the tool works end to end. It doesn't tell you how it performs on code it wasn't designed around: how many false positives it produces, what it misses, how fast it runs on thousands of files, or how it handles unusual encodings and minified files.

To get a meaningful answer, the next step is a rules-only scan of a real project. It's quick and makes no LLM calls. A few options:
- One of your own repositories. This is the most useful, because you can judge which findings are real.
- A well-known open-source Django or Express project. I'd need to clone it, which means a network download.
- LocalAudit's own source. This is the quickest. It should be mostly clean, but the test files are full of deliberately bad snippets, so it's a good false-positive check.

Do you want me to run one of these? If you have a repository in mind, give me the path.

You

I have a project that i need to be audited, How can I test that? The codebase is locally saved

Agent

Point the tool at the project folder. Start with a quick rules-only scan, then add the LLM for the most serious findings.

1. Rules-only scan (seconds, no Ollama needed)

cd <projects>\LocalSec
python -m localaudit scan "D:\path\to\your\project" --no-llm --out "D:\audit\myproject"

Use your project's real path, and put quotes around it if it contains spaces. Writing the reports outside the project keeps them out of your repository. When it finishes, open D:\audit\myproject\report.html in a browser.

2. Reduce the noise if needed

If a lot of findings come from folders that aren't your code (vendored libraries, generated files, test fixtures), create a file called .localauditignore in the project's root folder:

vendor/
static/libs/
*.min.js
tests/fixtures/*

Then run the scan again. .git, node_modules, venv, dist and build are already skipped automatically.

3. Add LLM triage for the worst findings

Make sure Ollama is running, then:

python -m localaudit scan "D:\path\to\your\project" --min-severity high --max-llm-findings 10 --out "D:\audit\myproject"

On your machine the 7B model takes about a minute per finding, so 10 findings is roughly 10 minutes. For quicker but rougher triage, add --model qwen2.5-coder:3b. Results are cached, so running the same scan again is fast.

Things to keep in mind
- Nothing leaves your machine. The scan and the model both run locally, and secrets are masked in the reports.
- The one exception is pip-audit. If you install it, it looks up your dependency names and versions online. It isn't installed right now, so nothing goes out.
- This is the tool's first run on real code. Expect some false positives, and some real issues it can't catch, such as multi-line patterns, logic flaws and broken access control.
- It's a first pass, not a full audit. Treat the findings as a checklist to review, not as a verdict. If the project is going to production or handles sensitive data, it still needs a proper review.

If you tell me the project's path, I can run the rules-only scan, go through the findings with you, and tune the ignore file or rules wherever they're noisy.

You

PS ~> python -m localaudit scan "<projects>\getpyqjec" --min-severity high --max-findings 10 --out "<projects>"
usage: localaudit [-h] [--version] {scan} ...
localaudit: error: unrecognized arguments: --max-findings 10
PS ~> localaudit scan "<projects>\getpyqjec" --min-severity high --max-findings 10 --out "<projects>"
localaudit : The term 'localaudit' is not recognized
as the name of a cmdlet, function, script file, or
operable program. Check the spelling of the name, or
if a path was included, verify that the path is
correct and try again.
At line:1 char:1
+ localaudit scan "<projects>\getpyqjec"
--min-severity high ...
+ ~~~~~~~~~~
+ CategoryInfo : ObjectNotFound: (localau
dit:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException

PS ~>

Agent

There were two separate problems.

1. The option name was wrong (my fault). I mixed up the name in my message at one point. The correct option is --max-llm-findings, not --max-findings. The python -m localaudit form did work: it started and only rejected that one option.

2. localaudit isn't recognized because its install folder isn't on your PATH. Use python -m localaudit for now.

Run this:

python -m localaudit scan "<projects>\getpyqjec" --min-severity high --max-llm-findings 10 --out "<projects>\getpyqjec-audit"

I also changed --out to a new subfolder. With --out "<projects>", the three report files would go straight into your Project folder alongside your other projects. When it finishes, open <projects>\getpyqjec-audit\report.html. Make sure Ollama is running first, and expect up to about 10 minutes for the LLM step.

If you want plain localaudit ... to work, run this once in PowerShell, then open a new terminal:

$p = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$p;~\AppData\Roaming\Python\Python314\Scripts", "User")

If you'd rather I run the scan here and go through the findings with you, just say so.

You

What is the command to run the application on examples you created, because i would not like to record my project findings and post it on dev

Agent

Run these from the LocalSec folder, since the demo app path is relative to it:

cd <projects>\LocalSec

# Rules only (finishes in about a second)
python -m localaudit scan examples\vulnerable_app --no-llm --out demo-report

# With LLM triage
python -m localaudit scan examples\vulnerable_app --max-llm-findings 10 --out demo-report

Then open demo-report\report.html in a browser.

For a recording:
- Everything in the demo is safe to show. The credentials are fake and masked in the output.
- The LLM run will look instant. 23 results from the earlier run are cached, so --max-llm-findings 10 answers straight from the cache.
- To show the model working live, first run Remove-Item -Recurse .localaudit_cache. Each finding then takes about a minute on your machine, so a small cap like --max-llm-findings 3 keeps the video short.
- Good spots to point out in the report: the subprocess ... "df -h /" finding is the decoy the model marked as a likely false positive, and the private key block shows its body replaced with ****.
- The report header shows your local path (<projects>\LocalSec\...). If that matters to you, crop it or run from a neutral folder.

I can also draft the DEV post text for you to review.

You

give me steps to connect this to a fresh github repo and push everything with commit statement

Agent

Here are the steps. Run everything in PowerShell from the project folder.

1. Create an empty repository on GitHub

Go to github.com/new and name it (for example localaudit). Leave all of the "Add README / .gitignore / license" boxes unticked, because the project already has those files and an extra initial commit on GitHub would make the first push fail.

2. Commit and push

cd <projects>\LocalSec

# Keep demo report output out of the repo (build artefacts and the LLM cache are already ignored)
Add-Content .gitignore "demo-report/"

git init
git add .
git status          # check the list: no demo-report, .localaudit_cache, __pycache__ or *.egg-info
git commit -m "Initial release of LocalAudit: local-only security audit CLI" -m "Deterministic rules detect secrets, insecure code patterns and unpinned dependencies; a local Ollama model only explains findings, flags likely false positives and suggests fixes. Outputs self-contained HTML, JSON and Markdown reports. Includes an intentionally vulnerable demo app and a pytest suite."
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/localaudit.git
git push -u origin main

Replace YOUR-USERNAME with your GitHub username. If git commit complains that it doesn't know who you are, run these once and commit again:

git config --global user.name "Your Name"
git config --global user.email "[REDACTED]"

3. GitHub may block the push at first

The demo app and tests contain fake keys in real formats, such as ghp_..., sk_live_..., xoxb-... and AIza.... GitHub's secret-scanning push protection may reject the push with a message like "Push cannot contain secrets". That is expected, because the demo is designed to trip exactly these detectors. To get past it:
- The error lists each detected value with a link. Open each link and choose "It's used in tests" to allow it.
- Run git push -u origin main again.

All of these values are made up. Still, read the list in the error before allowing anything, to confirm each flagged file is under examples/vulnerable_app/ or tests/.

If you have the GitHub CLI (gh) installed and logged in, you can skip creating the repo on the website. After the git commit line, run gh repo create localaudit --public --source . --push.

I can also run the git steps here for you. You would still create the repo and approve the push yourself.

You

git push -u origin main
Enumerating objects: 38, done.
Counting objects: 100% (38/38), done.
Delta compression using up to 20 threads
Compressing objects: 100% (35/35), done.
Writing objects: 100% (38/38), 40.87 KiB | 5.11 MiB/s, done.
Total 38 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: error: GH013: Repository rule violations found for refs/heads/main.
remote:
remote: - GITHUB PUSH PROTECTION
remote: —————————————————————————————————————————
remote: Resolve the following violations before pushing again
remote:
remote: - Push cannot contain secrets
remote:
remote:
remote: (?) Learn how to resolve a blocked push
remote: https://docs.github.com/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line#resolving-a-blocked-push
remote:
remote:
remote: —— Slack API Token ———————————————————————————————————
remote: locations:
remote: - commit: [REDACTED]
remote: path: examples/vulnerable_app/shop/integrations.py:6
remote:
remote: (?) To push, remove secret from commit(s) or follow this URL to allow the secret
remote: <push-protection-bypass-link>
remote:
remote:
remote: —— Stripe API Key ————————————————————————————————————
remote: locations:
remote: - commit: [REDACTED]
remote: path: examples/vulnerable_app/shop/integrations.py:7
remote: - commit: [REDACTED]
remote: path: tests/test_scanner.py:11
remote: - commit: [REDACTED]
remote: path: tests/test_secrets.py:11
remote: - commit: [REDACTED]
remote: path: tests/test_secrets.py:11
remote: - commit: [REDACTED]
remote: path: tests/test_secrets.py:59
remote:
remote: (?) To push, remove secret from commit(s) or follow this URL to allow the secret
remote: <push-protection-bypass-link>
remote:
remote:
remote: —— Slack API Token ———————————————————————————————————
remote: locations:
remote: - commit: [REDACTED]
remote: path: tests/test_secrets.py:10
remote: - commit: [REDACTED]
remote: path: tests/test_secrets.py:10
remote:
remote: (?) To push, remove secret from commit(s) or follow this URL to allow the secret
remote: <push-protection-bypass-link>
remote:
remote:
remote: —— Amazon AWS Access Key ID ——————————————————————————
remote: locations:
remote: - commit: [REDACTED]
remote: path: examples/vulnerable_app/shop/settings.py:18
remote: - commit: [REDACTED]
remote: path: tests/test_scanner.py:10
remote:
remote: (?) To push, remove secret from commit(s) or follow this URL to allow the secret
remote: <push-protection-bypass-link>
remote:
remote:
remote: —— Amazon AWS Secret Access Key ——————————————————————
remote: locations:
remote: - commit: [REDACTED]
remote: path: examples/vulnerable_app/shop/settings.py:19
remote: - commit: [REDACTED]
remote: path: tests/test_scanner.py:10
remote:
remote: (?) To push, remove secret from commit(s) or follow this URL to allow the secret
remote: <push-protection-bypass-link>
remote:
remote:
remote:
To https://github.com/hardikgaikwad/localaudit.git
! [remote rejected] main -> main (push declined due to repository rule violations)
error: failed to push some refs to 'https://github.com/hardikgaikwad/localaudit.git'

Agent

That's the expected block. GitHub flagged five fake values, and every location is either in examples/vulnerable_app/ or in tests/. They are the made-up keys I wrote so the scanner has something to find, not real credentials.

To push:

Open each of the 5 links from the error while signed in as hardikgaikwad:
- Slack token (integrations.py): <push-protection-bypass-link>
- Stripe key: <push-protection-bypass-link>
- Slack token (tests): <push-protection-bypass-link>
- AWS access key ID: <push-protection-bypass-link>
- AWS secret access key: <push-protection-bypass-link>
On each page, choose "It's used in tests" and click Allow secret.
Push again within a couple of hours, while the allowances are still valid. You don't need to change the commit: powershell git push -u origin main

What to expect afterwards:
- If the repo is public, GitHub may still open secret-scanning alerts for these values under the repo's Security tab. Close them as "Used in tests".
- GitHub may also pass the AWS, Slack and Stripe values to those providers to check. They're fake, so nothing happens.
- The fake GitHub token, Google key and JWT weren't flagged. GitHub's checks for those formats are stricter, and my made-up values don't pass them. That's fine.

If you'd rather not bypass push protection: I can change the tests to build the fake keys at runtime (for example "sk_" + "live_" + ...), so the literal strings never appear in them. The demo app has to keep literal keys in its files, though, or the scanner has nothing to find. That would cut the flags down to the demo files, but you'd still need to allow those, so the five-click route above is simpler.

You

Make sure the README mentions that there are fake API keys in the example application

Agent

▸ Grep {"pattern": "Demo app|vulnerable demo app|You can try it without", "path": "<...

Input

{
  "pattern": "Demo app|vulnerable demo app|You can try it without",
  "path": "<projects>\\LocalSec\\README.md",
  "output_mode": "content"
}

Output

21:# 3. Scan the intentionally vulnerable demo app
26:You can try it without Ollama: `localaudit scan examples/vulnerabl [... trimmed]

▸ Read {"file_path": "<projects>\\LocalSec\\README.md", "offset": 24, "limit": 4}

Input

{
  "file_path": "<projects>\\LocalSec\\README.md",
  "offset": 24,
  "limit": 4
}

Output

24   ```
25  
26  You can try it without Ollama: `localaudit scan examples/vulnerable_app --no-llm`.
27

▸ Read {"file_path": "<projects>\\LocalSec\\README.md", "offset": 132}

Input

{
  "file_path": "<projects>\\LocalSec\\README.md",
  "offset": 132
}

Output

132  - **This is not a replacement for a professional penetration test** or a full SAST/SCA product.
133 
134 ## Demo app [... trimmed]

▸ Edit {"replace_all": false, "file_path": "<projects>\\LocalSec\\README.md", "old_s...

Input

{"replace_all": false, "file_path": "<projects>\\LocalSec\\README.md", "old_string": "You can try it without Ollama: `localaudit scan examples/vulnera [... trimmed]

Output

The server-side auto mode classifier gave no verdict (it skipped this action), so auto mode cannot determine the safety  [... trimmed]

▸ Edit {"replace_all": false, "file_path": "<projects>\\LocalSec\\README.md", "old_s...

Input

{"replace_all": false, "file_path": "<projects>\\LocalSec\\README.md", "old_string": "`examples/vulnerable_app/` is **intentionally insecure**, and al [... trimmed]

Output

The server-side auto mode classifier gave no verdict (it skipped this action), so auto mode cannot determine the safety  [... trimmed]

I couldn't make this change. Auto mode's safety check returned no verdict for both README edits, the same thing that happened with the first README write. I haven't routed around it this time. You approved using Bash for that earlier write, but I won't assume that approval carries over to this edit.

You have two options:
- Tell me to use Bash again and I'll apply both changes that way.
- Paste them in yourself. Here is the exact text.

1. In the quickstart, directly after the line You can try it without Ollama: `localaudit scan examples/vulnerable_app --no-llm`. add:

> **Heads-up: the demo app contains fake API keys.** `examples/vulnerable_app/` and the tests include made-up credentials in real formats (AWS, Stripe, Slack, GitHub, Google, a JWT, a private key block) so the secret rules have something to find. None of them are real or valid. See [Demo app](#demo-app).

2. Replace everything under ## Demo app (the last section) with:

`examples/vulnerable_app/` is **intentionally insecure**. It exists only to show the rules firing. Don't deploy or copy it.

**It contains fake API keys and credentials.** To exercise the secret detector, the demo app and the tests (`tests/test_secrets.py`, `tests/test_scanner.py`) hold made-up values in the exact formats of real ones:

| Kind | Where |
|---|---|
| AWS access key ID and secret access key | `shop/settings.py` |
| Database password, Django `SECRET_KEY` | `shop/settings.py` |
| GitHub token, Slack bot token, Stripe live key, Google API key, JWT, signing salt | `shop/integrations.py` |
| RSA private key block | `shop/integrations.py` |

These values are **not real, have never been valid, and grant access to nothing**. They were invented for this project. Some contain `FAKE` or `NOTAREALKEY`, but not all of them do, because real formats don't always leave room for it.

Because they match real formats, other secret scanners will flag them too. GitHub's push protection blocks the first push until you allow each one as "used in tests". Repository secret-scanning alerts can be closed as "used in tests". If you fork this project, expect the same.

Never replace them with real credentials, even for testing.

After the README is updated, commit it and push. You still need to allow the five flagged values first, using the links from the push error, because the blocked first commit is part of this push.

git add README.md
git commit -m "Document fake API keys in demo app and tests"
git push -u origin main

You

use bash to update README

Agent

▸ Bash {"command": "cat > \"$TEMP/la_quick.md\" <<'README_END'\n\n> **Heads-up: the ...

Input

$ {"command": "cat > \"$TEMP/la_quick.md\" <<'README_END'\n\n> **Heads-up: the demo app contains fake API keys.** `examples/vulnerable_app/` and the tes [... trimmed]

Output

ok

▸ Bash {"command": "python - <<'PY'\nimport os\nt = os.environ[\"TEMP\"]\nquick = op...

Input

$ {"command": "python - <<'PY'\nimport os\nt = os.environ[\"TEMP\"]\nquick = open(os.path.join(t, \"la_quick.md\"), encoding=\"utf-8\").read().rstrip(\" [... trimmed]

Output

28:> **Heads-up: the demo app contains fake API keys.** `examples/vulnerable_app/` and the tests include made-up credent [... trimmed]

I updated the README using Bash, and it now says clearly that the demo app contains fake API keys:

Quickstart (line 28): a short notice right under the demo command saying the demo app and tests contain made-up credentials in real formats. It links to the Demo app section.
Demo app section: rewritten with a table of every fake credential and the file it's in. It says the values are invented and grant access to nothing, warns that GitHub push protection and other secret scanners will flag them, and says never to replace them with real credentials.

To publish it, first allow the five flagged values using the links from the push error, since the blocked commit is still part of this push. Then run:

git add README.md
git commit -m "Document fake API keys in demo app and tests"
git push -u origin main

You

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Demo

Code

How I Built It

Why Does Open Innovation Matter?

My Agent Session

My First User

Prize Categories

Use this as the template and rewrite this for the devpost, leave placeholders for demo and github embeds. Tell me separately how to add devrelay session in the submission

Agent

I'll look up the challenge details and the session-embed instructions first, so the prize categories and embed syntax are accurate rather than guessed.

▸ Skill {"skill": "devrelay-sessions"}

Input

{
  "skill": "devrelay-sessions"
}

Output

Launching skill: devrelay-sessions

▸ ToolSearch {"query": "select:mcp__devrelay-gateway__get_challenges,mcp__devrelay-gateway...

Input

{
  "query": "select:mcp__devrelay-gateway__get_challenges,mcp__devrelay-gateway__get_challenge_details",
  "max_results": 2
}

Output

[image]
[image]

▸ mcp__devrelay-gateway__get_challenges {}

Input

{
}

Output

{"Ok":[{"id":82,"title":"Hacktoberfest Open-Source AI Challenge: Week 4","slug":"hacktoberfest-week4-2026-10-26","descri [... trimmed]

Here's the post, ready to paste into DEV. I checked the details against the live challenge page:
- Theme: Side Hustle.
- Deadline: October 18, 11:59 PM PDT, which is two days from now.
- Required tag: #hf26challenge.

---
title: LocalAudit: an AI security auditor that never sees your secrets and never leaves your laptop
published: false
tags: hf26challenge, security, opensource, ai
---

*This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle](https://dev.to/challenges/hacktoberfest-week2-2026-10-12)*

## What I Built

**LocalAudit** is a command-line security auditor for source code that runs 100% on your own machine. Point it at a repo and a few seconds later you get a clean HTML report (plus JSON and Markdown) listing hardcoded secrets, injection risks, insecure configuration and unpinned dependencies. Each finding comes with the file and line, the code around it, a plain-English explanation and a concrete fix.

The design rule I cared most about: **the LLM never detects anything.** Deterministic rules find the issues: 24 code-pattern rules for Python/Django/Flask and JavaScript/Node, 10 built-in secret detectors (AWS, Stripe, Slack, GitHub, Google, JWTs, private keys, high-entropy strings...) and dependency checks. A local open-weight model then *triages* each finding. It explains it, judges whether it's likely a false positive in context, and writes a fix. If the model is unavailable, you still get the full report.

**Who would pay for this?** People who need a security pass on code they aren't allowed to upload anywhere:

- **Freelancers and small agencies** working on client code under NDA. A fixed-fee "pre-handoff security check" with a professional report as the deliverable is an easy add-on to sell.
- **Solo founders** about to launch who can't justify an enterprise SAST subscription.
- **Consultants** who want a fast first pass before a manual review.

For all of them, the cloud AI code-review tools have the same problem: *your client's source code goes to someone else's server.* LocalAudit's answer is that it doesn't go anywhere.

## Demo

<!-- DEMO VIDEO: paste your video link below, e.g. {% embed https://www.youtube.com/watch?v=... %} -->
[DEMO_VIDEO_PLACEHOLDER]

The demo scans the bundled `examples/vulnerable_app`, a deliberately insecure Django + Node app full of **fake** credentials. The rules-only scan takes about a second and finds 43 issues (4 critical, 16 high), for a risk score of 100/100. A few things worth watching for:

- **Secrets are masked everywhere.** You'll only ever see `AKIA****`. Even a private key's body is replaced with `****` before any snippet is built, so raw secrets never reach the report, the console or the model's prompt.
- **The model catches a decoy.** The app contains `subprocess.check_output("df -h /", shell=True)`. The rule correctly flags `shell=True`, but the command is a constant with no user input. The local model marked it as a *likely false positive*. LocalAudit doesn't delete it: it moves it to a separate "Likely false positives" section for a human to confirm.
- **It falls back gracefully.** Stop Ollama and the tool prints the exact command to fix it (`ollama pull qwen2.5-coder:7b`), then carries on with the rules-only report.

## Code

<!-- GITHUB EMBED: e.g. {% github hardikgaikwad/localaudit %} -->
[GITHUB_EMBED_PLACEHOLDER]

```bash
ollama pull qwen2.5-coder:7b
pip install -e .
localaudit scan examples/vulnerable_app
# open localaudit-report/report.html
```

Useful flags: `--no-llm`, `--min-severity high`, `--max-llm-findings 10`, `--model <any Ollama model>`, and `--fail-on high` (exits with code 1, for CI).

## How I Built It

**The open-source AI at the core:**

- **[Ollama](https://ollama.com)** for local inference over its HTTP API.
- **Qwen2.5-Coder 7B**, an open-weight coding model. It's the default, and you can swap it with `--model` or `LOCALAUDIT_MODEL`.

**How the pipeline works:**

1. **Scan.** Walk the repo, skipping `.git`, `node_modules`, venvs, build output, binaries, files over 1 MB and anything in `.localauditignore`.
2. **Detect and redact.** Run the secret detectors first and redact every detected value from the file text. Only then run the code rules and build snippets, which is how masking is guaranteed everywhere downstream.
3. **Triage.** Send each finding, highest severity first, to the local model. The request includes the rule description, the file path and the *masked* snippet. It runs at temperature 0, and Ollama's `format` parameter enforces a JSON schema, so the model must return `{explanation, risk_in_context, likely_false_positive, confidence, suggested_fix, fixed_code_example}`. Invalid JSON gets one retry, then the finding is marked "LLM triage unavailable".
4. **Cache.** Results are cached on disk, keyed by model + rule + snippet, so reruns are instant.
5. **Report.** Render a single self-contained HTML file with no CDNs or external requests, plus a print stylesheet so "Save as PDF" gives a client-ready document.

The stack is deliberately small: Python 3.10+, `requests`, `jinja2` and pytest, with 110 tests. Those tests include a mocked Ollama covering invalid JSON, timeouts and the server going down mid-run.

I built it with an AI coding agent (Claude Code) doing much of the implementation while I directed the design and reviewed the results. One moment I liked: testing caught a regex bug where a bare `password = "..."` wasn't detected. Because the masker only masks what the detector finds, that password was showing up unmasked as a *context line* in a neighbouring finding's snippet. It's fixed now, and there's a regression test for it.

## Why Does Open Innovation Matter?

For this product, open weights aren't a nice-to-have. They're the reason it can exist.

- **Privacy is the product.** The customers I described *can't* send client code to a third-party API. A local open-weight model is the only way to give them AI explanation
[... truncated 3409 chars]

You

Sure save the devrelay session

Agent

I'll start by finding this session's transcript on disk.

▸ Bash {"command": "ls -la ~/.claude/projects/<project-id>/ 2>&1 | head -20", "descr...

Input

$ {"command": "ls -la ~/.claude/projects/<project-id>/ 2>&1 | head -20", "description": "List Claude Code transcripts for this project"}

Output

total 3952
drwxr-xr-x 1 <user> 197609       0 Oct 16 13:21 .
drwxr-xr-x 1 <user> 197609       0 Oct 16 13:07 ..
-rw-r--r [... trimmed]

There are two transcript files, so the session probably continued from one file into the other. Checking how each is structured:

▸ Bash {"command": "cd ~/.claude/projects/<project-id>/ && python - <<'PY'\nimport j...

Input

$ {"command": "cd ~/.claude/projects/<project-id>/ && python - <<'PY'\nimport json\nfor fn in [\"5982a5be-821b-4a50-8648-c43f4c26c75d.jsonl\",\"f0d03b42 [... trimmed]

Output

5982a5be {'mode': 17, 'permission-mode': 17, 'atis-latch': 17, 'file-history-snapshot': 1, 'user': 38, 'attachment': 69, [... trimmed]

▸ Bash {"command": "mkdir -p \"$TEMP/la-session\" && cat > \"$TEMP/la-session/build....

Input

$ {"command": "mkdir -p \"$TEMP/la-session\" && cat > \"$TEMP/la-session/build.py\" <<'PY'\nimport json, re, sys, os\nsys.path.insert(0, r\"<projects>\\ [... trimmed]

Output

messages: 26  bytes: 204597
     70  fake keys (explicit list)
     26  ~
     13  </?pasted_content[^>]*>
     10   [... trimmed]

The transcript is built: 26 messages, about 200 KB. Only one project path was replaced, though, which seems too low. Before going further I'll grep the output for anything that still leaks:

▸ Bash {"command": "cd \"$TEMP/la-session\" && for p in GetItDone <user> gmail 'sk_l...

Input

$ {"command": "cd \"$TEMP/la-session\" && for p in GetItDone <user> gmail 'sk_live_[A-Za-z0-9]{6}' 'ghp_[A-Za-z0-9]{6}' 'xox[bp]-[0-9]' 'AKIA[A-Z0-9]{6} [... trimmed]

Output

GetItDone                        54
<user>                            38
gmail                            0
sk_live_[A-Z [... trimmed]

The scrub is incomplete: 54 project paths and some home-directory paths are still in there. Debugging the path regex:

▸ Bash {"command": "cd \"$TEMP/la-session\" && grep -oE '.{30}<user>.{20}' transcrip...

Input

$ {"command": "cd \"$TEMP/la-session\" && grep -oE '.{30}<user>.{20}' transcript.json | sort | uniq -c | sort -rn | head -8; python -c \"\nimport re\nrx [... trimmed]

Output

2 file_path\": \"~\\\\AppData\\\\Local
      1 ut": "total 452\ndrwxr-xr-x 1 <user> 197609      0 Oct 1
      1 undExcep [... trimmed]

A Game That Replaces Doomscrolling, Powered by Local AI (Ollama)

Hardik — Thu, 08 Oct 2026 14:56:45 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Field Dex is a pixel-art creature-collecting game where the creatures are real. You photograph a bird, a tree, a beetle or a flower on your normal iPhone camera, and when you get home you open the day's photos like a pack of trading cards.

My laptop identifies every photo with a local vision model and rolls a rarity, from Common to Legendary. It writes the card's flavour text, pays out XP, and dresses your pixel avatar in gear you unlock. Each day, finding something new also unlocks the next chapter of a story starring you, which ends on a cliffhanger. The only way to read what happens next is to go back outside.

It's for anyone who has caught themselves scrolling when they meant to go for a walk, and for people who like collecting things. That includes me.

Why a game?

I didn't want to build something that politely suggests going outside. Doomscrolling works because of three things: you don't know what the next swipe will show, there is always one more to see, and nothing ever finishes. So I tried to copy the mechanics but not the screen:

Doomscrolling	Field Dex
Unpredictable next item	A rarity roll when you flip each card
Endless feed	A Dex with `???` slots for every creature you haven't found yet
Reward is on the screen	Reward is only earned outside, then opened at home
No "done" state	A new Wanted poster every day and a story that never quite ends

The screen is the shortest part of the day. The photo walk is the game, and the pack opening is the reward at the end of it.

The game, in detail

The Wanted poster. Every day the game posts a bounty such as "a bee on a yellow flower". It's described by what you can see, never by species name, so the vision model can actually check whether your photo matches. A match is worth +50 XP.

Rarity is a mix of luck and effort. A harder subject (birds beat plants), a first-ever species, a sharp photo and a shot taken within about 75 minutes of sunrise or sunset all raise your odds. The final roll is seeded from the photo's hash, so re-uploading can't reroll it. From my simulation of 10,000 rolls, a good photo of a new bird comes out Rare 57% of the time, Epic 31% and Legendary 12%. A repeat plant is Common about three times out of four, so a Legendary actually feels like an event.

score  = KIND_BASE[kind]                       # birds are harder than plants
score += NEW_SPECIES_BONUS if is_new else 0    # first time you've seen it
score += (quality - 3) * 0.5                   # sharp photo beats a blurry one
score += 1.0 if golden_hour else 0             # dawn and dusk are luckier
score += (rng.random() ** 2) * 4.5             # the surprise, skewed low

It can't be gamed easily. It rejects photos of screens, photos with no living thing, photos more than a week old, and anything you've uploaded before. The rarity and XP rules are plain Python code, not model output, so the AI can't be flattered or prompted into handing out a Legendary.

Nothing is spoiled early. Your XP bar and Dex count only change when you flip a card, not when the laptop finishes processing it. The surprise is always saved for the flip.

The pixel world. Your avatar is drawn from text grids on a canvas, with no image files. It gains a camera, binoculars, a leaf crown, a bug net or a cape as you hit milestones. Each card's artwork is your own photo, shrunk and colour-reduced into pixel art, and tapping it shows the original. Sound effects are synthesised live with WebAudio, so there are no audio files either, and nothing loads from the internet.

Soft pressure on purpose. There are no streaks to lose and nothing is ever taken away. I wanted to pull people outside, not punish them for staying in.

Demo

Code

hardikgaikwad / FieldDex

A local 'touch grass' gamified application to get you off your screen.

Field Dex

A pixel-art creature collecting game played in the real world. You photograph living things outside, then come home and open them like a card pack. A local open-weight vision model identifies each find. A rarity roll, XP, levels, gear for your pixel avatar, and a story that continues one chapter at a time are what bring you back the next day.

Everything runs on your own laptop through Ollama. No accounts, no cloud, no API keys. Your photos never leave your devices.

Today · Reveal · Dex · Story. Screenshots use sample photos from Wikimedia Commons.

How a day works

Outside: use the normal iPhone Camera. No app, no laptop, no signal needed.
Home: the laptop is on your iPhone's Personal Hotspot. Open Field Dex in Safari, tap Open today's pack, and pick today's photos.
On the laptop:
- qwen2.5vl:3b identifies each photo (about 6 s…

View on GitHub

The README has setup steps, a map of the code and the screenshots. Everything runs with pip install -r requirements.txt and two ollama pull commands.

How I Built It

The constraint that shaped everything

My first idea was a "side quest generator": a local agent reads your profile and free time and hands you a short outdoor mission. I built it and it worked. Then I noticed the obvious problem: my laptop can't come outside with me, and it gets its internet from my iPhone's hotspot. A quest app that only works at a desk is useless.

So I flipped the design instead of fighting it. The phone collects outside; the laptop thinks at home. The iPhone camera needs no app and no signal. Back home, Safari talks to the laptop over the hotspot. That delay between taking the photo and seeing the card turned out to be the best part of the design, because it's exactly the gap between pulling the lever and seeing what you won.

 OUTSIDE                         HOME (same hotspot)
┌──────────────┐   upload   ┌───────────────────────────────┐
│ iPhone camera│ ─────────▶ │ FastAPI + SQLite              │
│ (no app, no  │            │   ├─ Pillow: HEIC → JPEG, pixel art
│  signal)     │ ◀───────── │   ├─ qwen2.5vl:3b  → what is it?
└──────────────┘   cards    │   ├─ game.py       → rarity, XP, unlocks
   Safari UI                │   └─ qwen2.5:3b    → card text, story
                            └───────────────────────────────┘
                                   all via Ollama, on the laptop

The open models

qwen2.5vl:3b (open-weight vision-language model) looks at each photo and returns structured JSON: what the subject is, its visible features, a category, a confidence, whether it's a photo of a screen, and a photo-quality score.
qwen2.5:3b (open-weight text model) writes each card's flavour text and stats, the daily Wanted poster, and the story chapters.
Ollama runs both, locally. Its structured-output mode takes a JSON schema, which forces the answer into a shape my code can trust.

The whole thing runs on a laptop with an RTX 3050 with 4 GB of VRAM. Identifying a photo takes roughly 6–9 seconds, and a batch of six photos, with their cards and the story chapter, finished in about 90 seconds. Setting the context window to 4,096 tokens kept the text model entirely on the GPU. Ollama's default context pushed a third of it onto the CPU.

The idea that made small models usable

Three-billion-parameter models are good at some things and bad at others, so the pipeline gives each part to whoever is good at it:

The model describes and names things, and writes. It's good at that.
Python decides rarity, XP, levels, unlocks and rejections. These are deterministic, testable and can't be talked into cheating.

Two real examples of that split paying off:

The model names well and categorises badly. On my test photos it called the peacock "Indian Peafowl" correctly, then filed it under "animal". A butterfly became a "plant". So the name now decides the category through a small vocabulary map, and the model's own category is only a fallback.
Field order matters. I originally asked "is this a living thing?" first, and the model confidently said a tree beside a building was not. Reordering the schema so it describes first, then classifies, then judges fixed that case. It still labelled a hibiscus flower as "none" until the name-based category rule above caught it. Both fixes together got all six of my test photos right, including rejecting a street scene with no living thing in it.

A pipeline detail that matters on 4 GB

Ollama can only keep one model loaded on a card this small. Processing photo-by-photo would swap vision and text models back and forth every time. So a batch runs all vision calls first, then all text calls, and the models swap once per batch.

Other things worth saying

One background worker processes the queue while the page polls for progress, so uploading returns instantly and the "developing film" screen shows live progress.
A real bug I hit: uploading a duplicate photo left a SQLite transaction open and locked the worker out of the database. I fixed it with autocommit and wrote a regression test. The project has 11 tests covering the game rules, the vision-category logic and that bug.
The UI has no build step. It's plain HTML, CSS and JavaScript, with bundled pixel fonts (Press Start 2P and Pixelify Sans, both under the SIL Open Font License).

Where the small models struggle (honestly)

Flavour text sometimes invents facts. One card claimed a peafowl is "a master of disguise".
Names are sometimes vague. A photo of a big tree came back as just "Tree".
The stats on each card (charm, stealth, grit) are made up by the model for fun, not real biology.
Story chapters stay in the right world and use the day's finds, but the prose can be clumsy. One chapter said "Mynah, the Mynah, sang a song".
Telling lookalike species apart is beyond a 3B model, so I treat the names as a fun guess, not a field guide.

Taking It Outside

[TODO before publishing: replace this block with your real photo walk.]
Where did you go? How many photos? What was your best and worst find? Did a Wanted poster make you walk somewhere you wouldn't have? How did it feel to open the pack afterwards compared with scrolling? Add 2–3 real screenshots or photos.

Why Does Open Innovation Matter?

I could have built this around a hosted vision API in an afternoon. I'm glad I didn't, for four reasons that are specific to this app:

My photos are my life. A folder of "what I saw on my walks" shows where I go and when, which is exactly what you shouldn't hand to a server you don't control. Field Dex never sends a photo anywhere. Nothing in the app calls out to the internet: no CDN, no analytics, no fonts fetched from a server, and inference is a call to localhost.
The cost is zero, which changes the design. A game that rewards you for taking more photos only works if each one is free. With a per-image API price, I'd have been quietly discouraging the very behaviour the game exists to encourage. I also ran dozens of prompt and pipeline experiments in one evening without watching a bill or a rate limit.
Open weights let me constrain the model. Because I run the stack myself, I could force structured JSON output, control the context window to fit a 4 GB card, run the vision and text models in a deliberate order, and keep the rules in code rather than trusting a prompt. That's how a 3B model became reliable enough to ship.
I can change it. The models are two lines in profile.yaml. Any vision model Ollama can run can be dropped in, and when a better small model ships next month, the game gets better without me touching the code. (I only tested qwen2.5vl:3b and qwen2.5:3b end to end, so I can't promise how others compare.)

The honest trade-off: a hosted frontier model would identify species more accurately and write better prose. For a game about the act of going outside, I think "mostly right, private, free and mine" beats "perfectly right and rented".

Built on open-weight models (Qwen2.5-VL and Qwen2.5) running through Ollama, with the session saved through DevRelay.

No More TeX Errors: Meet CVstart, a 100% Private AI Resume Builder

Hardik — Sun, 04 Oct 2026 11:20:14 +0000

What I Built
I built CVstart—a local-first, AI-powered agentic LaTeX resume builder designed for anyone who loves the typographical beauty of LaTeX but dreads fighting syntax errors, brittle formatting, and margin spills.

Demo

Code

hardikgaikwad / CVStart

Local LLM AI Resume Builder in Latex

CVstart

A Local-First, AI-Powered Agentic LaTeX Resume Builder

Overview

CVstart empowers software engineers, students, and professionals to create, edit, format, compile, inspect, and export stunning LaTeX resumes using natural language—without needing to write or debug complex LaTeX syntax.

Unlike conventional AI resume tools that merely generate raw text and dump it into an unverified document, CVstart features a true agentic compile-inspect-correct loop:

The AI translates user facts or instructions into a structured change plan.
The LaTeX engine compiles the source in a secure, sandboxed local environment.
The geometry inspection engine analyzes the resulting PDF text bounding boxes, density, margins, and page spills using PyMuPDF.
If an overflow or layout flaw is detected, the agent autonomously executes targeted corrections (up to 3 bounded iterations) to produce a flawless document.
All operations run 100% locally on your machine using Ollama and local compilation—zero cloud calls, zero telemetry, absolute privacy.

…

View on GitHub

Who I Built It For
I built this for my close friend Abhinav, a final year B. preparing for backend and development roles.

Abhinav faced two frustrating roadblocks:

The "LaTeX Tax": Every time he tailored his resume for a job, he spent 80% of his time debugging cryptic TeX compilation errors (! LaTeX Error: Missing $ inserted, bad table line breaks, or bullet points overflowing onto page 2 by three lonely lines).
The Cloud Privacy Dilemma: He refused to paste his unredacted career history, private internal team metrics, home address, and compensation notes into closed cloud LLM websites. A resume contains your most sensitive personal and career data, and the idea of feeding it into closed AI APIs that log prompts and train on user inputs felt unacceptable.
The Solution
CVstart solves both problems:

100% Local-First & Air-Gapped: Powered entirely by open-weight models (llama3.2, qwen2.5) running locally via Ollama, with an embedded local LaTeX compiler. Zero cloud calls, zero telemetry, absolute data sovereignty.
Agentic Compile-Inspect-Correct Loop: Instead of generating raw markdown and hoping for the best, CVstart compiles the document in a sandboxed local environment, analyzes the PDF page geometry with PyMuPDF, detects vertical density and page spills, and autonomously adjusts vertical spacing and padding to fit exactly on a single page.
Editorial Document Editor Experience: Built with a minimal, light-mode, distraction-free aesthetic with square geometry, clean monochrome typography, and no AI chat-bubble clutter.
Demo
CVstart runs as a desktop application with a single CLI command (CVstart). It features a real-time split workspace: structured section editing on the left, an authentic rendered document sheet on the right, and an integrated AI utility panel.

Workflow Highlights
Single-Command Launch: Typing CVstart in the terminal runs system readiness checks (Python, Tectonic compiler, Ollama models), migrations, and opens the local interface at http://127.0.0.1:9999/.
Natural Language Assistant: Ask the local model to "Strengthen action verbs under my latest backend role and emphasize distributed systems metrics." The assistant returns a structured Change Plan with a color-coded diff review card (Accept / Discard).
Live PDF Rendering: Every accepted change re-renders the LaTeX PDF in sub-second time, displaying the high-resolution document directly on the neutral canvas with zoom and pan controls.
One-Click Export: Download publication-ready PDFs or export the raw .tex source files.
Code
CVstart is open-source under the MIT License:

Repository URL: https://github.com/hardikgaikwad/CVstart

Tech Stack
Backend: Python 3.10+, Django REST Framework, SQLite
Frontend: React 19, TypeScript, Tailwind CSS, Lucide Icons
Local AI Inference: Ollama HTTP Client (llama3.2:3b, qwen2.5:7b, llama3.2-vision)
Compilation Engine: Sandboxed Tectonic LaTeX compiler (zero shell escapes)
Geometry Inspection: PyMuPDF (fitz) for printable bounding box measurement and layout density analysis
How I Built It
CVstart is architected around open-source AI and local tooling:

Local AI Inference with Ollama: We integrated local open-weight models using Ollama's HTTP API. llama3.2:latest (3.2B) is used as an ultra-fast model for rapid structured JSON planning, summary rewrites, and skill categorizations, while qwen2.5:latest (7.6B) handles advanced technical reasoning to ensure strict schema validation.

Guardrailed Agentic Change Planner: When a user asks for edits, CVstart outputs a strictly structured JSON change plan (summary, affected_sections, proposed_structured_data). An anti-hallucination guardrail verifies that the AI didn't invent non-existent company names or degrees that weren't present in the user's ground-truth profile. The user retains complete control with an auditable visual diff review card.

PyMuPDF Layout Inspection Loop: One of the hardest parts of resume formatting is preventing an accidental 2-line spill onto page 2. We built a closed-loop inspector using PyMuPDF (fitz). It computes vertical density, printable margins, and total word count. If an overflow is detected, the agent autonomously invokes a micro-refinement pass, adjusting LaTeX font size and list separations until the document fits cleanly on exactly 1 page.

Why Does Open Innovation Matter?
Open innovation made CVstart possible in ways closed commercial APIs simply could not:

True Privacy & Data Sovereignty: Closed proprietary AI APIs require transmitting sensitive personal information—employment history, contact info, patents, and compensation metrics—to third-party cloud servers. With open-weight models running on Ollama, all data stays strictly on the user's machine. Zero data leakage, zero tracking.
No Paywalls or Subscriptions: Job hunting is stressful enough without having to pay a $25/month SaaS fee to export your own resume. Open-source models mean free, unlimited compilations and edits forever, even when you're completely offline.
Deterministic, Introspectable Tooling: Closed chatbots trap users in conversational black boxes. Open weights enabled us to build a transparent, introspectable loop: translating natural language into validated schemas, compiling with a local TeX engine, and measuring physical bounding boxes with PyMuPDF.