DEV Community: Praveen Kumar

PixelBreak: I Built a Local-First Tool That Blocks Bad Commits Before They Break Your Frontend

Praveen Kumar — Fri, 23 Oct 2026 15:03:52 +0000

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

What I Built

PixelBreak is a pre-commit hook + CLI tool that automatically catches responsive layout failures and visual regressions before they land in your repo — without any manual steps, subscriptions, or cloud services.

Every time you git commit, PixelBreak:

Scans your running app at every configured viewport width (375px → 1920px) using a real Chromium browser
Detects horizontal overflow and element clipping with deterministic pixel measurements
Compares screenshots against the previous committed version automatically — no manual baseline setup
Blocks the commit if anything breaks and opens a localhost dashboard showing exactly what changed

Who gets to be lazier: frontend developers who used to manually resize their browser at 5+ widths after every CSS change, or pay for Percy/Chromatic subscriptions. With PixelBreak, you just commit. The tool does the rest.

Demo

PixelBreak Dashboard — 6 findings blocked across 375px, 768px, 1024px, 1280px, 1440px, 1920px

Visual regression finding — Baseline (before), Current (after your change), Diff (changed pixels highlighted)

Since PixelBreak is a local-first tool, here's what a real terminal run looks like:

# Developer changes a CSS variable and tries to commit
git commit -m "style: update primary color"

# PixelBreak fires automatically
🔍 [PixelBreak] Running pre-commit checks...
🚀 Starting scan for project 'my-app'...
   Base URL: http://localhost:4173
   Profile:  responsive
   Widths:   [375, 768, 1024, 1280, 1440, 1920]px
   Git baseline: 1 staged file(s) detected — comparing against HEAD automatically.

📊 Scan Complete: 6 viewports, 8 findings

  🚨 BLOCKED [HIGH] horizontal-overflow @ 375px
     Element: #metrics-card overflows viewport by 857px

  🚨 BLOCKED [HIGH] horizontal-overflow @ 768px
     Element: #metrics-card overflows viewport by 464px

  🚨 BLOCKED [MODERATE] visual-regression @ 1024px
     0.09% pixel diff — 787 pixels changed

❌ Commit Gate: BLOCKED
   Dashboard: http://localhost:3847

Clone and try it yourself:

git clone https://github.com/praveen-pravi6B/pixelbreak
cd pixelbreak && pnpm install && pnpm build
pnpm demo
node apps/runner/dist/cli.js init
node apps/runner/dist/cli.js baseline update
# Change fixtures/broken-demo/src/style.css and commit

Code

praveen-pravi6B / pixelbreak

Local-first frontend regression testing — responsive breakpoint detection, visual diffs, and local AI explanations. Blocks bad commits before they ship.

PixelBreak

Local-first responsive breakpoint detection and visual regression testing — no cloud, no account, no drama.

PixelBreak checks your frontend before every Git commit. It tests only the viewport widths you configure, detects layout failures and visual regressions, shows evidence in a localhost dashboard, and uses a local LLM to explain issues and suggest CSS fixes — without sending your source code or screenshots to any cloud service.

Why PixelBreak?

Find where it breaks. Deterministic horizontal-overflow and layout-clipping detection at exactly the breakpoints your app supports.
See what changed. Pixel-level screenshot diffs with bounding-box evidence and diff overlays.
Understand the cause. A local LLM explains findings and proposes CSS patches — all on your machine.
Block bad commits. A severity-gated pre-commit hook stops high and critical regressions before they land.
Stay private. Zero telemetry. Zero cloud calls. No API key required.

Core Modules

Module	What it does
Breakpoint Detective	Configured

…

View on GitHub

How I Built It

Open-source AI: llama.cpp running Qwen2.5-Coder-Instruct (GGUF, Q4_K_M quantization) locally on port 8080. No API key, no cloud, no bundled weights.

The AI is the explanation layer — not the detection layer. Detection is fully deterministic:

Detection (no AI involved):

@pixelbreak/layout-analyzer — injects JavaScript into Playwright pages to measure scrollWidth > clientWidth and element clipping geometry
@pixelbreak/visual-diff — uses pixelmatch to compare screenshots pixel-by-pixel and generate diff PNGs

AI layer (llama.cpp + Qwen2.5-Coder):

After deterministic detection blocks a commit, the AI receives: finding summary, measured pixel geometry, relevant computed CSS
Returns structured JSON: summary, likely cause, supporting evidence, and a CSS patch proposal
All responses are validated with a Zod schema — malformed output is rejected, never silently accepted
The model cannot change severity, waive findings, or apply patches. severity: finding.severity is copied from the finding object, never from the AI response.

Git-aware automatic baselines:

The most important UX decision: instead of requiring pixelbreak baseline update before every scan, PixelBreak uses git show HEAD:<file> to automatically get the previous version of staged files as the baseline. You just commit — no manual setup.

Stack:

pnpm workspaces monorepo (TypeScript, ESM throughout)
Playwright for Chromium automation
pixelmatch for pixel comparison
Zod for all schema validation
Commander.js for CLI
React + Vite for the localhost dashboard
Node.js built-in http for the dashboard server (no Express)

Why Does Open Innovation Matter?

I could have built this on Percy, Chromatic, or the Applitools API. But every hosted visual regression tool:

Sends your screenshots to their servers — a non-starter for internal dashboards, confidential UIs, or enterprise apps
Requires a subscription — free tiers run out, pricing changes, vendor disappears
Locks you into their severity rules — you file a ticket if you disagree
Breaks when you're offline or behind a corporate firewall

Open innovation made this possible in four concrete ways:

1. The AI runs on your hardware. Qwen2.5-Coder-Instruct via llama.cpp — download once, run forever, cost $0. No API key. No data leaving your machine. A team building a hospital admin panel can use PixelBreak without worrying about screenshots of patient data touching a third-party server.

2. You own the severity rules. The policy engine is a configurable YAML file. If your team disagrees with how a 0.08% pixel diff is classified, you change .pixelbreak.yml. No support ticket.

3. You can audit everything. When a security review found 9 vulnerabilities in my own code (command injection, path traversal, prototype pollution via YAML), I could read the exact lines, understand the attack vectors, fix them, and write tests that prove they're fixed. That's not possible with a black-box SaaS.

4. No lock-in by design. The AI adapter speaks the OpenAI-compatible /v1/chat/completions API. Swap llama.cpp for Ollama, LM Studio, or any future local inference server — zero code changes.

My Agent Session

Built with Claude Code across two sessions — foundation phases on a personal machine, AI engine + dashboard + security hardening in this session:

PixelBreak: Building a Local-First Frontend Regression Tool for Hacktoberfest 2026

You

Clone praveen-pravi6B/pixelbreak, add README, check CONTRIBUTORS.md, LICENSE already exists. Check planner file and implementation summary, then plan and execute. Switch to personal GitHub profile first.

Agent

▸ Bash gh auth switch --user praveen-pravi6B

Input

$ gh auth switch --user praveen-pravi6B

Output

Switched active account to praveen-pravi6B

▸ Read IMPLEMENTATION_STATUS.md

Input

IMPLEMENTATION_STATUS.md

Output

Phase A-D complete. Phase E (Local AI), F (Dashboard), G (Release Readiness) pending. 25 tests passing.

Switched to personal profile. Repo has Phases A-D complete (Foundation, Breakpoint Detective, PixelTruth, Policy Engine). Missing: README, CONTRIBUTING, CONTRIBUTORS, THIRD_PARTY_NOTICES, ai-engine package, dashboard app.

You

Switch to plan mode — full check then tell me.

Agent

Explored the full monorepo with 3 parallel agents.

Missing files: README.md, CONTRIBUTING.md, CONTRIBUTORS.md, THIRD_PARTY_NOTICES.md
Missing packages: packages/ai-engine/, apps/dashboard/
Phases A-D complete: 6 packages, 1 CLI app, 25 tests

Hacktoberfest Week 3 deadline: October 25 2026. Theme: Slow and Steady — open-source AI that rewards laziness/automates tedious tasks.

4-day plan:
- Day 1: Documentation files
- Day 2: Phase E — packages/ai-engine/ (llama.cpp adapter)
- Day 3: Phase F — apps/dashboard/ (React + Vite)
- Day 4: Phase G — docs, verification, DEV post

You

Plan approved — execute.

Agent

▸ Write README.md — 11.5KB comprehensive guide

Input

README.md — 11.5KB comprehensive guide

Output

Created: product overview, CLI reference, severity policy, local AI setup, waiver system, privacy section

▸ Write CONTRIBUTING.md, CONTRIBUTORS.md, THIRD_PARTY_NOTICES.md

Input

CONTRIBUTING.md, CONTRIBUTORS.md, THIRD_PARTY_NOTICES.md

Output

All created with correct content

Day 1 complete. Starting Phase E — Local AI Engine.

You

Start Phase E.

Agent

Building packages/ai-engine/ — llama.cpp HTTP adapter.

Key design constraints:
- Connects ONLY to local llama.cpp endpoint (http://localhost:8080)
- AI CANNOT change severity, waive findings, update baselines, or apply patches
- All output tagged isHypothesis: true
- Patch proposals are previews — never auto-applied
- If model unavailable: clear error, no silent pass

▸ Write packages/ai-engine/src/types.ts

Input

packages/ai-engine/src/types.ts

Output

AiExplanation, PatchProposal, AiStatus types — isHypothesis always true

▸ Write packages/ai-engine/src/prompts.ts

Input

packages/ai-engine/src/prompts.ts

Output

SYSTEM_PROMPT enforcing: cannot change severity, cannot waive, cannot auto-apply patches. buildExplanationPrompt() sends minimum evidence.

▸ Write packages/ai-engine/src/validator.ts

Input

packages/ai-engine/src/validator.ts

Output

Zod schema AiExplanationResponseSchema — rejects malformed JSON, missing fields, empty strings

▸ Write packages/ai-engine/src/adapter.ts

Input

packages/ai-engine/src/adapter.ts

Output

LlamaCppAdapter: checkStatus() + explainFinding(). Uses execFileSync array args (no shell injection). AiUnavailableError and AiResponseError custom error types.

▸ Write packages/ai-engine/test/ai-engine.test.ts

Input

packages/ai-engine/test/ai-engine.test.ts

Output

14 unit tests: valid response parsing, null patch, non-JSON rejection, schema validation, AiUnavailableError on ECONNREFUSED, severity immutability verified, empty choices array, HTTP 403/500

▸ Bash pnpm test

Input

$ pnpm test

Output

44/44 tests passing

You

Start Phase F.

Agent

Building apps/dashboard/ (React + Vite) + report persistence + HTTP server.

Architecture:
- report-store.ts: saves ScanReport JSON to .pixelbreak/reports/
- dashboard-server.ts: Node.js http module server port 3847 (no Express)
- React app fetches /api/reports/latest on load

▸ Write apps/dashboard/src/components/ScanSummary.tsx

Input

apps/dashboard/src/components/ScanSummary.tsx

Output

PASS/BLOCK banner, Blocked/Waived/Allowed counts, severity pips

▸ Write apps/dashboard/src/components/FindingDetail.tsx

Input

apps/dashboard/src/components/FindingDetail.tsx

Output

Baseline / Current / Diff screenshots side-by-side, evidence geometry, computed CSS

▸ Write apps/dashboard/src/components/AiPanel.tsx

Input

apps/dashboard/src/components/AiPanel.tsx

Output

HYPOTHESIS NOT VERIFIED banner always shown. Summary, cause, evidence, limitations.

▸ Write apps/dashboard/src/components/PatchReview.tsx

Input

apps/dashboard/src/components/PatchReview.tsx

Output

Diff syntax highlighting, copy-to-clipboard only — never writes to files

▸ Write apps/dashboard/src/components/WaiverFlow.tsx

Input

apps/dashboard/src/components/WaiverFlow.tsx

Output

Generates .pixelbreak-waivers.yml YAML snippet — user copies manually, dashboard never writes files

▸ Bash pnpm build && pnpm test

Input

$ pnpm build && pnpm test

Output

All 10 packages built. 44/44 tests pass.

You

Start Phase G.

Agent

▸ Write docs/local-model-setup.md

Input

docs/local-model-setup.md

Output

llama.cpp install, Qwen2.5-Coder GGUF download, server startup, hardware requirements, troubleshooting

▸ Write docs/configuration.md

Input

docs/configuration.md

Output

Full .pixelbreak.yml field reference

▸ Write docs/severity-policy.md

Input

docs/severity-policy.md

Output

Severity thresholds, commit gate logic, waiver rules, AI constraints table

▸ Write docs/privacy.md

Input

docs/privacy.md

Output

What stays local, what is never transmitted, local AI data flow

▸ Bash pnpm build && pnpm test

Input

$ pnpm build && pnpm test

Output

Test Files 10 passed. Tests 44 passed. Duration 20.96s

You

Try test cases: multiple cases and execute them.

Agent

Running 5 test cases:

Case 1: JS comment change — git baseline detects no visual impact → BLOCKED by pre-existing overflow only (no visual regression reported)

Case 2: CSS color change #6366f1 → #e11d48 — 8 findings: HIGH overflow at 375/768/1024px + MODERATE visual-regression at 5 viewports → BLOCKED

Case 3: Fix overflow (flex-wrap: wrap) — overflow fixed but visual regression HIGH (layout shifted >3%) → still BLOCKED

Case 4: Full fix + intentional layout approval → BYPASS commit, then:

Case 5: Non-visual JS change on fixed app — 0 findings → PASS ✅

Key insight: git-aware baseline correctly distinguishes JS-only changes from CSS/visual changes without any manual baseline update step.

You

Security review — I want this safe before publishing as a package.

Agent

Full security audit found 9 vulnerabilities. Fixed all:

▸ Write apps/runner/src/git-baseline.ts

Input

apps/runner/src/git-baseline.ts

Output

CRITICAL: execSync string interpolation → execFileSync array args (command injection prevention). CRITICAL: per-file restoration guarantee in withHeadVersions. HIGH: skip symlinks + files >50MB.

▸ Edit apps/runner/src/dashboard-server.ts

Input

apps/runner/src/dashboard-server.ts

Output

CRITICAL: path traversal fix — resolve relative to outputDir not CWD. Reject symlinks in artifact serving.

▸ Edit apps/runner/src/cli.ts

Input

apps/runner/src/cli.ts

Output

HIGH: exec (shell) → execFile for openBrowser. Init command now auto-adds .pixelbreak/ to .gitignore.

▸ Write packages/policy-engine/src/waivers.ts

Input

packages/policy-engine/src/waivers.ts

Output

HIGH: Zod .strict() schema rejects __proto__ and unknown keys (prototype pollution prevention)

▸ Edit packages/config/src/loader.ts

Input

packages/config/src/loader.ts

Output

HIGH: --config path validated within project directory (path traversal prevention)

▸ Edit apps/runner/src/scanner.ts

Input

apps/runner/src/scanner.ts

Output

HIGH: page.goto throws loudly on unreachable app. Empty widths guard. 5min timeout. Random scan ID suffix.

▸ Bash pnpm test

Input

$ pnpm test

Output

Test Files 14 passed. Tests 84 passed. 0 failed.

Agent

PixelBreak complete and published to GitHub.

GitHub: https://github.com/praveen-pravi6B/pixelbreak
Tests: 84/84 passing
Security: 9 vulnerabilities fixed (3 CRITICAL, 6 HIGH)
CI: Build + Test + Size Labeler + Security Audit all passing
Branch protection: PRs required, owner bypass enabled
Deadline: October 25 2026

The Lazy Payoff

Before PixelBreak, a developer changing a CSS file would need to:

Open browser dev tools → resize to 375px → does it look right? (memory-based)
Resize to 768px → check again
Resize to 1024px → check again
Resize to 1280px, 1440px, 1920px → check, check, check
Compare visually against "what it looked like before" → impossible from memory

Time per CSS change: 5–10 minutes if done properly. Realistically: skipped 90% of the time.

With PixelBreak: 0 extra minutes. The commit either goes through or it doesn't.

During this week's build, PixelBreak caught:

A min-width: 1200px on a flex container that caused 857px overflow at 375px — completely broken on mobile, would have shipped
A color variable change creating 787 changed pixels at 1024px — would have passed code review unnoticed
A table that overflowed at 375px when the metrics container was fixed — a bug introduced by fixing another bug, caught automatically

Community Wisdom: Visual regression testing for modern web apps by Rizwan Saleem — the hosted tool landscape that shaped the decision to go local-first.

MailMate AI Desktop — Open-Source Email Assistant That Summarizes, Prioritizes, and Creates Tasks Locally

Praveen Kumar — Sat, 17 Oct 2026 06:50:20 +0000

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

What I Built

Most people manage their inbox by reading every email and deciding what matters. That's the problem.

MailMate AI Desktop flips this: two open-weight models read your Gmail first, summarize every email into 1–2 sentences, classify it by priority, and deliver only what needs your attention — directly to your Telegram. Your data never leaves your machine.

Who would pay for this: Freelancers, consultants, indie founders, and anyone whose inbox is a productivity tax. A tool that reads 80 emails and surfaces the 3 that matter — with context — is easily worth $10–20/month. The local-first approach makes it viable for anyone who can't feed client emails to a cloud API.

The Pipeline

Gmail (read-only)
  → Normalize email
  → Qwen2.5-0.5B via vLLM   ← summarize to 1-2 sentences  (local, free)
  → Laya typed-decision engine ← classify actionability + priority  (local CPU)
  → Application-side policy  ← decide what is permitted
  → SQLite                   ← persist if approved
  → Telegram bot             ← summary + notification / Yes/No confirmation
  → Google Calendar          ← separate explicit step, never automatic

Two open-weight models, two jobs:

Model	Job	Runs on
`Qwen/Qwen2.5-0.5B-Instruct`	Summarize each email into 1–2 sentences	Local vLLM (CPU)
`convaiinnovations/laya` (typed-decisions)	Classify actionability + priority	Local CPU

The summarizer runs first. Laya then classifies the summary — not the raw email. Cleaner signal, better decisions.

Priority System

Priority	Meaning	What happens
🔴 P0	Critical incident / immediate risk	Task created automatically
🟠 P1	Important with a clear deadline	Asks for your confirmation
🟡 P2	Routine actionable	Asks for your confirmation
⚪ OTHER	Informational	Summary only

Key safety rule: A model prediction alone never authorises anything. An explicit policy module enforces the rules: ambiguous deadlines are never auto-scheduled, P1/P2 tasks require your confirmation, calendar events are always a separate explicit step.

Demo

Step 1 — Bot starts up, /start shows the full priority system:

Step 2 — First Gmail poll: 10 real inbox emails summarized and classified. AI-generated summary shown for each email. Footer: "Processed 10 emails — no tasks":

Step 3 — User sends /poll from Telegram after new test emails arrive. Bot responds immediately: "Polling Gmail now...":

Step 4 — /poll results. P0 critical security breach: task created automatically + Google Calendar event scheduled at 09:00 IST. P1 design review: AI summary shown, deadline extracted, Yes/No confirmation buttons appear:

Step 5 — User clicks "Yes, create task". Task confirmed instantly. Google Calendar event created for P1 at 09:00 IST on 2026-10-28:

Step 6 — Full batch summary for the /poll run. Important/Tasks section shows P0 (auto-created) and P1 (awaiting confirmation). Updates section shows remaining emails with AI summaries:

Step 7 — Google Calendar showing both events created from the pipeline:

Step 8 — vLLM running Qwen2.5-0.5B locally, processing emails on CPU, zero cloud cost:

Step 9 — macOS menu bar app: ✉ icon in the tray, click to see active tasks and trigger a poll:

Why Open Innovation Made This Possible

Zero running cost. Both models run locally on a MacBook Intel — no API bills, no per-token charges. That's what makes a Side Hustle viable: the marginal cost of processing 100 emails a day is electricity.

Complete privacy. Your inbox never touches a third-party server. OAuth tokens stay on disk. The SQLite database is local. For freelancers handling client emails, this is non-negotiable.

Swappable components. Because both models are open-weight and self-hosted, I can swap the summarizer for a better model as they improve, fine-tune Laya on my own email patterns, or run the whole stack on a Raspberry Pi. Closed APIs don't give you that.

Explicit policy, not prompt magic. The decision logic is a readable Python module with a clear routing table — not a prompt hoping a model will "be careful." You can read it, audit it, change it. That's only possible because the classification is a typed-decision engine, not a generative black box.

Build Session

This project was built end-to-end in a single Claude Code session — 10 milestones, 365 tests, live integration testing with real Gmail and Telegram.

Building MailMate AI Desktop — Local-First Email Assistant with Two Open-Weight Models

You

Let's go ahead with the planner file and build MailMate AI Desktop — a local-first email assistant that summarizes, prioritizes, and creates tasks from Gmail.

Agent

Starting with the project planner inspection and reference repo analysis. The PI version uses HuggingFace generative models and systemd — we'll replace those with Laya (typed-decision engine) and a Python-native pipeline.

▸ Read docs/mailmate-ai-desktop-planner.md

Input

docs/mailmate-ai-desktop-planner.md

Output

Planner loaded — 10 milestones from Laya engine to desktop UI

You

Fix the deadline state — I want NONE, CLEAR, AMBIGUOUS instead of a boolean.

Agent

Added DeadlineState enum and updated decide() with new routing: P0 always creates task (any deadline), P1/P2 need CLEAR deadline for confirmation, AMBIGUOUS → summarize only. 14 tests passing.

▸ Write app/policy/decision_policy.py

Input

app/policy/decision_policy.py

Output

DeadlineState enum added, decide() updated, 14 tests pass

You

Go ahead with Milestone 2 — SQLite task store.

Agent

Built TaskStore with idempotency via UNIQUE source_email_id constraint. DuplicateEmailError on reprocessing. In-memory mode uses persistent connection for tests. 26 tests passing.

▸ Write app/storage/task_store.py

Input

app/storage/task_store.py

Output

TaskStore with create, get, list, update_status, update_confirmation, set_calendar_event_id

You

Go ahead with Milestone 3 — connect Laya to policy.

Agent

Built ClassificationResult dataclass, classify_email() wrapper, and apply_policy() firewall. All Laya calls mocked in tests — no model loads. 78 tests passing. Key safety: model predictions alone cannot create tasks.

▸ Write app/laya_engine/classifier.py

Input

app/laya_engine/classifier.py

Output

ClassificationResult + classify_email() with normalization to REVIEW on unknown labels

You

Go ahead with Milestone 4 — email normalization and task extraction.

Agent

Built NormalizedEmail and TaskCandidate models. Regex-based deadline detector: ISO dates → CLEAR, relative terms (tomorrow, ASAP, next Friday, bare day names) → AMBIGUOUS, nothing → NONE. Multiple dates → AMBIGUOUS. 134 tests passing.

▸ Write app/services/task_extractor.py

Input

app/services/task_extractor.py

Output

detect_deadline_state() with CLEAR/AMBIGUOUS/NONE classification

You

Go ahead with Milestone 5 — orchestration and idempotency.

Agent

Built process_email() pipeline: idempotency check → summarize → detect deadline → classify → policy → persist → return result. dry_run=True default. notify=True only after successful DB commit. 167 tests passing.

▸ Write app/services/orchestrator.py

Input

app/services/orchestrator.py

Output

OrchestrationResult with status SKIPPED/DRY_RUN/TASK_CREATED/AWAITING_CONFIRMATION/NO_ACTION/NEEDS_REVIEW/ERROR

You

Go ahead with Milestone 6 — Telegram notifications.

Agent

Built NotificationTransport ABC, MockTransport, TelegramTransport. P2 confirmation via inline buttons: confirm:<task_id> / decline:<task_id>. handle_callback() with 48h timeout window. Declined tasks stay DECLINED, cannot be re-confirmed. 212 tests passing.

▸ Write app/integrations/telegram.py

Input

app/integrations/telegram.py

Output

TelegramTransport reads TELEGRAM_BOT_TOKEN from env, logs only 8-char prefix

You

Go ahead with Milestone 7 — Google Calendar.

Agent

Built CalendarTransport ABC with MockCalendarTransport and GoogleCalendarTransport (live_writes=True gate). schedule_event() runs 6 eligibility checks before any API call: duplicate, declined status, non-CLEAR deadline, missing deadline, missing time, missing timezone. 245 tests passing.

▸ Write app/services/calendar_service.py

Input

app/services/calendar_service.py

Output

check_eligibility() + schedule_event() with CREATED/DUPLICATE/INELIGIBLE/MISSING_TIME/MISSING_TIMEZONE/ERROR

You

Go ahead with Milestone 8 — Gmail.

Agent

Built GmailTransport ABC, MockGmailTransport, GmailClient with gmail.readonly scope. MIME parser handles text/plain, text/html, multipart/alternative (prefers plain), multipart/mixed. fetch_new_emails() pre-filters by email_has_task() before fetching body. 276 tests passing.

▸ Write app/integrations/gmail.py

Input

app/integrations/gmail.py

Output

MIME parsing + load_credentials() OAuth with token auto-refresh

You

Go ahead with Milestone 9 — desktop UI.

Agent

Built macOS menu bar app via rumps. Tray icon ✉/⏳/⚠ cycles with pipeline state. P2 tasks show Confirm/Decline sub-menus. Confirm/Decline/Complete all go through existing confirmation_handler. Timer-based polling with threading lock. 300 tests passing.

▸ Write app/ui/menu_bar.py

Input

app/ui/menu_bar.py

Output

MailMateApp(rumps.App) with task menu, command handling, live/dry-run mode

You

Go ahead with Milestone 10 — holdout validation.

Agent

Built 24-example human-reviewed holdout set. End-to-end integration tests covering duplicate processing, failure recovery, declined confirmation safety, ambiguous-deadline safety, notification guard. 361 tests passing.

▸ Write tests/fixtures/holdout_emails.json

Input

tests/fixtures/holdout_emails.json

Output

24 holdout examples: newsletters, P0 incidents, P1 deadlines, P2 routine, ambiguous dates, mixed content

You

Let's change the logic — P0 always creates a task, P1/P2 need a clear deadline for confirmation, otherwise summarize.

Agent

Updated policy routing table: P0 + any deadline → CREATE_TASK_AND_NOTIFY. P1/P2 + CLEAR → ASK_CONFIRMATION. P1/P2 + NONE/AMBIGUOUS → SUMMARIZE_ONLY. Removed CLARIFY_DEADLINE as a policy outcome — simpler, more intuitive. 365 tests passing.

▸ Edit app/policy/decision_policy.py

Input

app/policy/decision_policy.py

Output

New routing: P0 always creates, P1/P2 need CLEAR deadline

You

Add AI email summarization — I want actual summaries not just subject lines.

Agent

Found vLLM running locally with Qwen/Qwen2.5-0.5B-Instruct at localhost:8000. Built summarizer.py using OpenAI-compatible API. Pipeline updated: summarize first → pass summary to Laya (cleaner signal). Summary shown in every Telegram notification — batch summary, task created, P2 confirmation. HF Inference API as fallback (requires PRO credits). 365 tests passing.

▸ Write app/services/summarizer.py

Input

app/services/summarizer.py

Output

summarize_email() via local vLLM primary, HF API fallback, empty string on failure

You

Run live mode — send test emails, trigger /poll from Telegram.

Agent

Live pipeline confirmed end-to-end: Gmail fetch → vLLM summary → Laya classification → policy → SQLite → Telegram (batch summary + task notifications + P2 Yes/No) → Google Calendar event creation. P0 Security breach → task auto-created + calendar event. P1 Design review → AI summary shown + Yes/No buttons → confirmed → calendar event created. P2 meeting notes → summary only. OTHER → summary only.

Tech Stack

Qwen/Qwen2.5-0.5B-Instruct via vLLM — local summarisation
convaiinnovations/laya (typed-decisions) — actionability + priority
Python 3.11 — pipeline, policy, storage
SQLite — local task store with idempotency (365 tests)
Telegram Bot API — notifications + inline confirmation buttons
Google Calendar API — scheduling (explicit step only)
Gmail API (read-only) — inbox polling
rumps — macOS menu bar app

GitHub

praveen-pravi6B / mailmate-ai-desktop

Local-first macOS email assistant — Laya typed decisions, SQLite, Telegram, Google Calendar

MailMate AI Desktop

A local-first macOS email assistant that identifies actionable emails applies an explicit decision policy, and surfaces tasks via a menu bar app and Telegram — without sending data to any cloud backend.

What it does

Gmail (read-only)
  → Normalize email
  → HuggingFace Summarizer      ← human-readable summary of each email
  → Laya typed-decision engine  ← actionability + priority classification
  → Application-side policy     ← what is permitted
  → SQLite task store           ← persist if approved
  → Telegram notification       ← summary + notify / ask for confirmation
  → Google Calendar             ← separate explicit step, never automatic

Two models, two jobs:

Model	Job	Runs on
`openai/gpt-oss-120b:fastest`	Summarize each email into 1-2 sentences	HuggingFace Inference API
`convaiinnovations/laya`	Classify actionability + priority	Local CPU

The model classifies; the policy decides; you confirm anything routine. No model output can bypass that chain.

Priority levels

Priority	Meaning	Policy
P0	Critical incident / immediate serious risk

…

View on GitHub

What I'd Build Next

A Telegram webhook loop so callbacks are instant
Fine-tune Laya on personal email patterns for better P2 accuracy
Windows/Linux tray support (replace rumps)
A paid tier with multi-account support

🌿 HearWild — An AI That Listens to Birds, Then Gets Out of Your Way

Praveen Kumar — Wed, 07 Oct 2026 20:23:17 +0000

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

What I Built

Most AI products are designed to keep us on our screens.

HearWild is designed to do the opposite.

HearWild is an open-source AI nature companion that lets you record a bird sound, identifies the bird using local AI, tells you a little about what you heard, and encourages you to go back outside.

The idea is simple:

Listen. Discover. Learn. Go outside.

You don't need to take a photo or know what bird you're looking at. Just point your microphone toward the sound, record for a few seconds, and let the AI listen.

When a bird is confidently identified, it is automatically added to your Flock and you earn XP:

🐦 New bird → +100 XP
🔁 Bird you've already discovered → +25 XP
⭐ Discover more birds → level up

The important part is what happens next.

HearWild doesn't try to keep you inside the app.

Once you've discovered the bird, the goal is to put the screen down and keep exploring.

It's built for anyone who's curious about nature, especially people who don't know much about birds but want a reason to step outside and pay attention to what's around them.

Demo

🎥 Watch the HearWild demo

The MVP currently runs locally:

Record a bird sound
        ↓
BirdNET V3 identifies it
        ↓
See the bird + confidence
        ↓
Bird is added to your Flock
        ↓
Earn XP
        ↓
🌿 Keep Exploring

Code

The complete source code is available on GitHub:

praveen-pravi6B / hearwild

HearWild is an open-source AI nature companion that lets you record a bird sound, identifies the bird using local AI, tells you a little about what you heard, and encourages you to go back outside.

HearWild 🌿

Listen to the world. Discover what lives in it.

HearWild is an open-source, offline-first AI nature companion that helps you identify birds by sound, build your personal flock, and get back outside.

It uses BirdNET V3 ONNX to identify bird sounds locally through a simple web interface.

The idea is simple:

Listen → Discover → Learn → Go outside.

🌿 Why HearWild?

AI should help you discover something outside — then get out of your way.

HearWild is designed around short interactions:

Record a bird sound for about 6 seconds.
Let local AI identify the bird.
Learn a little about what you heard.
Add confidently identified birds to your personal flock.
Earn XP as you discover more birds.
Put your phone away and keep exploring.

There are no accounts, feeds, maps, or endless scrolling.

✨ Features

🎙️ Identify birds by sound

Record a short bird sound directly from…

View on GitHub

How I Built It

The core of HearWild is BirdNET V3, running locally through its ONNX model.

I wanted the AI itself to be part of the open-source stack rather than simply calling a closed AI API.

🧠 The AI

HearWild uses:

BirdNET V3 → ONNX → local inference

The audio recorded by the browser is sent to a local FastAPI backend, converted to the required format using FFmpeg, and passed to BirdNET V3.

The model returns the predicted species and confidence.

I then use confidence-aware behaviour:

Confidence	HearWild's response
70%+	Confident identification → add to Flock + earn XP
20–69%	Possible identification → show result, but don't add
<20%	Unknown → don't pretend to know

That last part was important to me.

If the model isn't confident, HearWild doesn't pretend it knows the answer.

🏗️ Architecture

┌──────────────────────────┐
│       Vue 3 + Vite       │
│                          │
│  🎙️ Record bird sound    │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│         FastAPI          │
│                          │
│     Audio processing     │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│         FFmpeg           │
│      Audio conversion    │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│     BirdNET V3 ONNX      │
│                          │
│  Local bird identification│
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│         SQLite           │
│                          │
│       🐦 My Flock        │
└──────────────────────────┘

The frontend is built with Vue 3 + Vite and the backend uses Python + FastAPI.

SQLite keeps track of the birds I've discovered, how many times I've heard them, and my XP progression.

For bird imagery and short descriptions, HearWild uses Wikimedia when available.

Why Does Open Innovation Matter?

This project could have been built by calling a commercial bird-identification API.

But that would have missed one of the most interesting parts of the challenge for me.

I wanted the AI itself to be something I could run and understand locally.

Using an open model made it possible to:

Run bird identification locally
Avoid sending bird recordings to a proprietary AI service
Experiment with the model directly
Control the inference pipeline
Build without depending on an AI API subscription
Keep the project reproducible for other developers

More importantly, it changed the way I thought about the product.

The AI doesn't need to become the destination.

It can simply be the bridge between technology and the real world.

That's what I like about open innovation here: the model becomes a building block that anyone can experiment with and build something completely different around.

🌿 What I Learned

The biggest lesson from building HearWild was that an AI project doesn't necessarily need to give users more to look at.

It can help them notice what's already around them.

Birdsong is happening all the time.

Most of us just don't stop to listen.

So instead of building another AI assistant that says:

"Here are 10 things you can do on your screen..."

I wanted to build one that says:

"You heard a bird. Now go find it."

That's HearWild.

Listen to the world. Discover what lives in it.

🔗 Project

🐙 GitHub — HearWild
🌿 Hacktoberfest Open-Source AI Challenge

Building MailMate: My First AI Assistant Experiment 🤖📬

Praveen Kumar — Tue, 06 Oct 2026 18:43:33 +0000

I’ve been thinking about a simple problem:

What if my email could do more than just sit in my inbox waiting for me?

That question led me to start building MailMate.

MailMate is a lightweight AI-powered email assistant that I'm experimenting with on a Raspberry Pi.

The idea is simple:

📩 Fetch emails

🧠 Process them using AI

📝 Generate useful summaries

✅ Identify potential tasks or actions

🔔 Send the important information to me through Telegram

The interesting part isn't just summarizing emails.

I want to explore how far we can take the idea of an assistant that can understand context, identify intent, and help turn information into action.

Why MailMate?

I receive plenty of emails that don't require immediate attention.

But mixed in with them are things like:

An important request
Something I need to follow up on
A meeting invitation
A deadline
A notification that requires an action
Information that I'll probably need later

The problem isn't necessarily finding these emails.

It's knowing what matters.

That's the problem I'm trying to solve.

Starting small

I'm deliberately not trying to build a full-blown autonomous AI agent from the beginning.

The current workflow is intentionally simple:

Gmail → AI processing → Summary & task detection → Telegram

I'm building this incrementally and learning along the way.

Some of the things I want to explore next are:

⏰ Scheduled email processing
📅 Calendar and task integration
🔔 Better notification handling
👤 Multiple email accounts
🧠 Better context and task detection
🤖 More autonomous workflows

What I want to learn

This project is also an excuse to explore some interesting questions:

How should an AI assistant decide what is important?

How do we prevent an assistant from becoming noisy?

How much autonomy should we actually give it?

What should it remember?

And most importantly — how do we make it genuinely useful rather than just another AI wrapper?

MailMate is my attempt to explore those questions through a real project.

I'm building it in public, so I'll be sharing the architecture, experiments, mistakes, and lessons along the way.

🔗 The project is open on GitHub:

github.com/praveen-pravi6B/MailMate

If you're interested in AI assistants, automation, Raspberry Pi projects, or building AI tools from scratch, I'd love to hear what you're working on too.

Build. Learn. Experiment. Repeat. 🚀