DEV Community: James Ngandu

Requiem: a crash post-mortem that speaks as the program that died

James Ngandu — Tue, 27 Oct 2026 08:04:36 +0000

This is a submission for the Hacktoberfest Open Source AI Challenge: Week 4 - Ghost in the Machine.

What I built

Requiem is a CLI that gives every crashed program a funeral. When a command fails, Requiem produces an obituary card with the cause of death, a suggested fix, and a first person eulogy written as if the program itself were speaking.

GitHub repo

Demo

PYTHONPATH=. python3 -m requiem run -- python3 examples/lost_config.py

┌─ REQUIEM ─────────────────────────────────────────────────────┐
│ requiem-733bae  python3 examples/lost_config.py  132ms       │
│ died of missing key 'bob' in config dictionary.              │
├──────────────────────────────────────────────────────────────┤
│ WHERE                                                        │
│   examples/lost_config.py:14 in load_user                   │
│     user = config["users"][user_id]                          │
│ CAUSE                                                        │
│   missing key 'bob' in config dictionary.                    │
│ FIX                                                          │
│   add 'bob' to config dictionary.                            │
│ EULOGY                                                       │
│   I was a program. I existed to process requests, to         │
│   organize data.                                             │
└──────────────────────────────────────────────────────────────┘

A segfault gets the same treatment:

make examples/segv && PYTHONPATH=. python3 -m requiem run -- ./examples/segv

┌─ REQUIEM ─────────────────────────────────────────────────────┐
│ requiem-e9b362  ./examples/segv  1ms                         │
│ died of segmentation fault                                   │
├──────────────────────────────────────────────────────────────┤
│ WHERE                                                        │
│   killed by SIGSEGV                                          │
│ CAUSE                                                        │
│   segmentation fault                                         │
│ FIX                                                          │
│   null                                                       │
│ EULOGY                                                       │
│   I trusted a pointer I had no right to trust. Now I return  │
│   to /dev/null.                                              │
└──────────────────────────────────────────────────────────────┘

How it works

Requiem is a hybrid: code does what code must, the model gives the program a voice.

Capture runs the command with subprocess and records exit code, signal, duration, and the last chunk of stderr and stdout.
Coroner parses Python tracebacks, maps signals to names, reads the failing source line off disk, and redacts secrets before anything leaves the process.
Ghost talks to a local llama-server running Gemma 3 1B via llama.cpp. It asks for a terse diagnosis and a first person eulogy, caches results, and falls back to deterministic output if the model is offline.
Graveyard stores every obituary in data/obituaries.jsonl. Use requiem list and requiem show <id> to browse them. The terminal renders a clean obituary card.

All of this is stdlib Python, about 400 lines. No API keys. No network calls when using --no-model.

Why open innovation matters

Crash logs are sensitive. A traceback can contain file paths, hostnames, SQL, auth headers, customer data, or tokens. Sending that to a cloud crash explainer leaks private information. Requiem runs inference on your own machine and redacts secrets before the model ever sees them.

It works offline. The model, prompt, logic, and examples are all local. Swap the GGUF, edit the prompt, read every line. With --no-model it is fully deterministic and works in air gapped environments.

It is inspectable. Redaction rules, traceback parsing, and the eulogy prompt are all visible and easy to change. Open tools let you reason about your failures without handing them to a third party.

Prize categories

Best Use of Gemma - Gemma 3 1B runs locally through llama.cpp and llama-server to write the eulogy and diagnosis.

Try it

git clone https://github.com/mukuvi/requiem
cd requiem
make demo
make test

Every crash gets a funeral.

Dozer: a folder tidier that works while you sleep

James Ngandu — Thu, 22 Oct 2026 11:29:26 +0000

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

What I Built

My Downloads folder is not a storage problem. It is a stack of small decisions I keep postponing. Every file asks a small question: is this an invoice, a screenshot, something I should keep at all? Answering forty of them is not hard. It is just relentless.

Dozer reads a folder one level deep, one file at a time, with Gemma 3 1B running on the same machine through llama.cpp. Then it:

Files each file into Invoices/, Documents/, Reading/, Photos/, Screenshots/, Installers/, Archives/, Code/ or Duplicates/.
Renames only the files whose names carry no information. a1b2c3d4e5f6a7b8.pdf became 2026-10-08_certificate-of-participation.pdf. kasha-hardware-invoice.pdf was left exactly as it was.
Leaves a file alone when it is not sure, when it is empty, when the type is unknown, or when you touched it in the last ten minutes.
Never deletes and never overwrites. A name collision gets a -2.
Writes every move to data/runs.jsonl, and undo puts the whole run back.
Works at a pace you choose, with a budget, so an interrupted night resumes where it stopped.

It is for anyone whose Downloads folder has become the place where decisions go to wait. You set it going before bed, and the only thing waiting for you in the morning is a short note.

Demo

The whole thing is three commands:

make install && make models && make llama
make demo     # dashboard on a throwaway copy

Or against your real folder:

make scan ROOT=~/Downloads
make night ROOT=~/Downloads

This is a real scan of the 19-file folder that ships in samples/, trimmed to keep it readable:

Dozer · /tmp/dozer-demo
19 files · 13 to file · 6 left alone · 9 folders
asked the local model about 4 of 19 files, 4 answered from cache

DOCUMENTS/
  2026-10-08_certificate-of-participation.pdf
    from a1b2c3d4e5f6a7b8.pdf · 95% · The text is a certificate, which is a document.
  2026-09-22_tenancy-agreement.pdf
    from download (3).pdf · 80% · the text reads like a tenancy agreement
  random_notes.txt
    80% · the text reads like meeting notes

INVOICES/
  2026-10-12_tax-invoice.pdf
    from scan_0042.pdf · 85% · the text reads like a tax invoice
  statement-oct.pdf
    85% · the text reads like an account statement

READING/
  doc_8831.pdf
    80% · the text reads like a book

LEFT ALONE
  data_dump.csv - I'm not sure what this is.
  empty.txt - empty file
  notes.txt - This file contains a list of vegetables and spices. It's not a standard document type.
  recent-scan.pdf - touched 1 minute ago, still in use
  ubuntu-notes.md - The text is too short to determine the category.
  weird.xyz - not a type Dozer knows

Then the overnight pass:

$ make night ROOT=/tmp/dozer-demo PACE=2
[1/13] a1b2c3d4e5f6a7b8.pdf -> Documents/2026-10-08_certificate-of-participation.pdf
[2/13] doc_8831.pdf -> Reading/doc_8831.pdf
[3/13] download (3).pdf -> Documents/2026-09-22_tenancy-agreement.pdf
...
[13/13] VSCodeUserSetup-x64-1.94.2.exe -> Installers/VSCodeUserSetup-x64-1.94.2.exe

MORNING NOTE
  I left 6 files alone. I filed 13 files into 3 Documents, 2 Invoices, 2
  Reading. 4 of them needed the model and the rest were rules. The pass took 24
  seconds and nothing left this machine.

And the folder afterwards:

/tmp/dozer-demo
├── Archives/        node-v22.11.0-linux-x64.tar.xz
├── Code/            scrape.py
├── Documents/       2026-09-22_tenancy-agreement.pdf
│                    2026-10-08_certificate-of-participation.pdf
│                    random_notes.txt
├── Duplicates/      IMG_20260918_0712 (1).heic
├── Installers/      VSCodeUserSetup-x64-1.94.2.exe
├── Invoices/        2026-10-12_tax-invoice.pdf
│                    statement-oct.pdf
├── Photos/          IMG_20260918_0712.heic
├── Reading/         doc_8831.pdf
│                    thinking-fast-and-slow.epub
├── Screenshots/     Screenshot 2026-10-20 at 09.14.02.png
├── data_dump.csv
├── empty.txt
├── notes.txt
├── recent-scan.pdf
├── ubuntu-notes.md
└── weird.xyz

The six files still in the root are the point.

Code

mukuvi / dozer

A folder tidier that works while you sleep, with Gemma 3 1B running locally.

Dozer

A folder tidier that works while you sleep, with an open-weight model at the core.

Dozer reads your Downloads one file at a time with Gemma 3 1B running through llama.cpp on your own machine. It files invoices, documents, installers, photos duplicates and the rest into folders, renames the files that have useless names, and leaves everything it is not sure about exactly where it is.

No API key. No upload. No account.

Write-up: Dozer: a folder tidier that works while you sleep.

What it actually does

Files the mess in one folder, one level deep.
Renames only files whose names carry no information (scan_0042.pdf, IMG_2301.HEIC download (3).pdf). A name a human chose is left alone.
Keeps identical files in Duplicates/ instead of deleting anything.
Leaves files alone when it is not sure, when the file is empty, when the type is unknown, or…

View on GitHub

MIT licensed, 27 tests that run without a model. make test on a clean checkout.

How I Built It

flowchart LR
  A[Folder, one level deep] --> B[hash + short text preview]
  B --> C{extension or text rule?}
  C -->|yes| D[category + confidence]
  C -->|no| E[Gemma 3 1B in a warm llama-server]
  E --> D
  D --> F{confidence >= 0.75?}
  F -->|yes| G[folder + safe name]
  F -->|no| H[left alone, with the reason]
  G --> I[apply one file at a time]
  I --> J[(data/runs.jsonl)]
  J --> K[undo]

Three decisions make a 1B model trustworthy enough to move files.

Rules first. An .exe is an installer. A document with Tax Invoice and Amount due in the text is an invoice. In the scan above, 15 of 19 files never reached the model. Rules are free, instant and predictable, and they leave the model only the cases that are actually ambiguous.

A confidence floor. Below 0.75 Dozer does nothing and says why. data_dump.csv is still in the folder because the model answered other at 0.0 confidence and said "I'm not sure what this is." That is a correct answer. A tidier that guesses is worse than a folder.

A warm server, not a subprocess per file. Every call goes to one llama-server on localhost, with the prompt prefix cached. On this 2015 dual-core laptop the difference is large. Loading the model per file costs more than the answer, and the shared prefix means the instructions are evaluated once per run instead of once per file. A fresh ambiguous file takes about thirty seconds here. The first one in a run also pays for loading 806 MB.

Model answers are also cached by content hash, so a second pass over a folder you already scanned costs nothing. That is why the demo above says "4 needed the model, 4 answered from cache."

The safety rules are simple. No symlinks, no subfolders, no deletion, no overwrite, and no rename of a name a person wrote. undo reverses the last run in order and refuses to overwrite a file you put back yourself.

What it got wrong

Three things, and they are the interesting part.

It called a book chapter a document. doc_8831.pdf starts with "Chapter 3: Trees and Recursion", and the model filed it under Documents at 95% confidence. The fix was one rule, not a bigger model or a longer prompt: text with Chapter N, Table of Contents or an ISBN is reading. Rules are how you correct a small model.

The kind field was noisy. Asked about a certificate, it returned kind: "tax invoice". The prompt's examples were doing more work than the instruction, so I removed them.

It invented file names in the morning note. I wanted the model to write the note you see at 7am. It produced "I left 6 files, including the one named 'Project Alpha'". There is no Project Alpha in the folder. The note is a template now.

That is the rule I ended up with. The model answers one narrow question, says how sure it is, and code checks the answer. It does not get to tell me what happened.

Why Does Open Innovation Matter?

The folder never leaves the machine. Downloads is where bank statements, contracts, ID scans and photos of your kitchen end up. A closed sorter has to upload them to read them. Running the weights locally means there is no trust boundary to audit, because there is no boundary.

It works with no network. After the one-time model download, the scanner, the rules, the model and the log are all on disk. On a metered or unreliable connection that matters more than any feature.

You can change the sorter. Swapping Gemma for a bigger model, a different quantisation, or a model fine-tuned on your own vendor names is a path and an environment variable. The prompt is a string in the repo. When it behaved badly I could read it and fix it the same afternoon.

It costs nothing per file. No per-document price, no rate limit, no key that expires. The run above cost nothing, which matters most for the person with a full folder and no budget for another subscription.

My Agent Session

I built this with an agent, and the session is saved. It includes the benchmark that pushed me from a subprocess per file to a warm server, and the moment the model invented a file name in the morning note:

Building Dozer: a local folder tidier for Hacktoberfest Week 3

You

Proceed with the Hacktoberfest Week 3 challenge (Slow and Steady). Build something with open-source AI that rewards laziness.

Agent

Plan: a local folder tidier called Dozer. Gemma 3 1B through llama.cpp decides where a file belongs; deterministic rules handle the obvious cases; anything below 0.75 confidence is left exactly where it is. Python + FastAPI, JSONL log, undo, and a paced overnight mode.

▸ get_challenges Week 3 details

Input

Week 3 details

Output

Week 3 runs Oct 19-25, theme 'Slow and Steady': build something that rewards laziness. Judging: writing quality weighted most, then theme relevance, creativity, technical execution.

Agent

First I checked the hardware. An i5-5200U with 4 threads, and the machine was already loaded. A quick llama-bench run showed 3.81 t/s prompt and 0.19 t/s generation. Loading the 806 MB model per file with llama-cli would make the tool unusable, so the model layer became a warm llama-server with prefix caching instead.

▸ llama-bench gemma-3-1b-it-Q4_K_M, 4 threads, pp32/tg8

Input

gemma-3-1b-it-Q4_K_M, 4 threads, pp32/tg8

Output

pp32: 3.81 t/s, tg8: 0.19 t/s

Agent

The core is plan.py. Extension and text rules run first, so most files never reach the model. Rules also produce the safe filenames: only names with no information (scan_0042, IMG_2301, a 16-character hash) get renamed, and only when the model or a rule has a title to offer. Duplicates are compared by SHA-256 and moved to Duplicates/ instead of being deleted.

▸ pytest tests/test_plan.py

Input

tests/test_plan.py

Output

Failed: two tests assumed a .pdf extension meant pdftotext could read plain text. Fixed by using the real sample PDFs, and an autouse fixture that keeps tests away from the local model.

Agent

Then the first real scan. The model called a book chapter (doc_8831.pdf, 'Chapter 3: Trees and Recursion') a Document at 95% confidence, and its 'why' text was boilerplate. I did not reach for a bigger model. I added one rule: text with 'Chapter N', 'Table of Contents' or an ISBN is Reading. That is the lesson the post is built around.

Agent

I also tried letting the model write the morning note. It produced: "I left 6 files, including the one named 'Project Alpha'" - there is no Project Alpha in the folder. It invented file names. The note became a deterministic template, and the model is now trusted with exactly one decision: the category.

Agent

Final run on the 19-file sample folder: 13 filed, 6 left alone, 9 folders, 3 renames, 4 files needed the model. Paced at 2 seconds per file, the pass took 24 seconds. A fresh ambiguous file costs about 28 seconds on this laptop, and answers are cached by content hash so the next scan is instant.

▸ cli.py night night /tmp/dozer-demo --pace 2

Input

night /tmp/dozer-demo --pace 2

Output

13 files moved in 24 seconds. Morning note: I left 6 files alone. I filed 13 files into 3 Documents, 2 Invoices, 2 Reading. 4 of them needed the model and the rest were rules.

Agent

Shipped: 27 tests passing, dashboard screenshots from a real run, README, MIT license, render.yaml for the hosted demo. The repo is github.com/mukuvi/dozer and the Week 3 post is on DEV with the #hf26challenge tag.

The Lazy Payoff

Thirteen files moved without me. Three names got better. One duplicate pair got separated, and neither copy was deleted.

The numbers are less flattering than a pitch. The six files left alone are six decisions I still have to make. Dozer did not remove the work. It batched it and moved it to a moment when I might feel like doing it. What it did remove was the interruption: you open the folder for one file and leave twenty minutes later with nothing decided.

Machine time: 24 seconds, paced at two seconds per file. Human time: one glance at a morning note.

Prize Categories

Best Use of Gemma: Gemma 3 1B (Q4_K_M, 806 MB) does every ambiguous classification, running locally through llama.cpp.
Best Use of Render: render.yaml deploys the dashboard as a hosted demo. The free instance cannot hold a 0.8 GB model, so the hosted demo runs the rule engine only, on a throwaway copy of the sample folder, and the UI says so. The model path is the one you run at home.

Built for Hacktoberfest 2026. No API key, no upload, no account, and nothing leaves the machine.

Quiet Ledger: a receipt sorter that never uploads your receipts

James Ngandu — Sun, 18 Oct 2026 17:37:15 +0000

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

What I Built

Quiet Ledger is a receipt and invoice sorter for one-person businesses, and it runs entirely on your own machine.

You drop a PDF invoice, a photo of a receipt, or paste the text. Gemma 3 1B reads it locally, drafts a bookkeeping entry, and shows it to you. You fix anything it got wrong, and then you export a CSV with the columns an accountant actually wants.

That is the whole loop. It exists because I watched a friend who freelances spend the last Sunday of every month with a shoebox of receipts, a bank statement, and a spreadsheet. The work is not hard. It is just relentless, and every cloud tool wants the receipts uploaded to a server first.

Three things make it different from the receipt apps I tried:

The document never leaves the laptop. No upload, no account, no API key, no per-document fee.
The model drafts; you approve. This is not a black box that files your taxes. It is a fast first pass you correct in a few seconds.
The output is a file you own. data/receipts.jsonl on disk, and a CSV you can hand to anyone.

It reads the things a freelancer's shoebox actually contains: supermarket receipts, a hardware store tax invoice, a design retainer from another country. It keeps currencies separate instead of quietly adding shillings to dollars, which is the kind of bug that ruins a month.

Demo

The demo is three commands, because the whole point is that it runs where the documents are:

make install && make models && make llama
export LLAMA_BIN="$PWD/.llama.cpp/build/bin/llama-cli"
make run            # http://127.0.0.1:8000

There is no hosted demo link, and that is deliberate: hosting it would mean uploading other people's receipts, which is the exact thing this project refuses to do. The repo ships three sample documents so the screenshot above is reproducible from a clean clone.

What a real run looks like. I dropped the sample tax invoice PDF, and 43 seconds later on four CPU cores this came back:

{
  "date": "2026-10-12",
  "vendor": "KASHA HARDWARE LTD",
  "category": "hardware",
  "total": 4850.0,
  "currency": "KES",
  "tax": 620.0,
  "payment_method": "mpesa",
  "invoice_number": "INV-2026-1044",
  "extracted_by": "gemma-3-1b-it"
}

And the export:

date,vendor,category,total,currency,tax,payment_method,invoice_number
2026-10-15,MAMA NJERI'S KITCHEN,meals,1400.00,KES,,cash,
2026-10-12,KASHA HARDWARE LTD,hardware,4850.00,KES,620.00,mpesa,INV-2026-1044
2026-10-09,Northwind Studio LLC,professional-services,2083.20,USD,163.20,bank transfer,NW-8841

Code

https://github.com/mukuvi/quiet-ledger (MIT licensed).

How I Built It

A small FastAPI server, a single-page PWA, and the plumbing from my last offline project, collapsed into one app: Gemma 3 1B with llama.cpp, plus pdftotext and tesseract for getting text out of files.

flowchart LR
  A[PDF / photo / paste] --> B[FastAPI]
  B --> C[pdftotext or tesseract]
  C --> D[Gemma 3 1B via llama.cpp]
  D --> E[normalise + sanity checks]
  E --> F[you approve or fix]
  F --> G[(data/receipts.jsonl)]
  G --> H[CSV for the accountant]

The model gets a strict, JSON-only prompt at temperature 0. No chat, no markdown, no commentary, and an explicit instruction to return null rather than invent a value:

- Return JSON only. No markdown, no explanation, no commentary.
- Use null when a value is not printed on the receipt. Never invent values.
- "total" is the final amount paid. If the receipt shows both a subtotal
  and a total or amount due, use the final amount due, never the subtotal.
- "tax" is the tax or VAT amount in money, not the tax rate.

That last pair of rules exists because I watched the model get both wrong.

The normaliser is where the real work is. A 1B model is a good reader and a mediocre accountant. Three failure modes showed up in my own test runs, and each one is now handled in code rather than papered over:

It returned 16%, the VAT rate, in the tax field. Money and rates are now parsed differently, and a tax amount smaller than one percent of the total is treated as a rate and replaced with the printed tax line.
It returned the subtotal as the total on an invoice that also had an Amount due line. The printed amount due now wins over the model's answer.
It labelled a hardware purchase other. When the model has no useful opinion, a keyword pass over the receipt text gets a second chance, so hardware wins over other.

Everything else is deliberately boring. Amounts lose their symbols and separators, dates become ISO, categories map onto a fixed list of twelve, and a payment method of M-PESA becomes mpesa so it does not split into three spellings. Files are deduplicated by SHA-256, so dragging the same receipt in twice does nothing.

Storage is JSON Lines. Not Postgres, not SQLite, not a vector database. A freelancer has a few thousand receipts, not a data warehouse, and a plain file is easier to back up, grep, and explain.

If no model is on disk, the app still runs and labels every entry fallback-parser. I did that on purpose: someone should be able to clone the repo, see the workflow, and decide whether the model is worth the download before committing to it.

Who Would Pay For This

The person I built it for is a freelancer or a two-person studio with client receipts in three currencies and an accountant who charges by the hour to sort them.

The pitch is not "another subscription". It is:

Privacy that is real, not a policy page. Client names, supplier prices, and where you were on a Tuesday never leave the machine. For anyone under a confidentiality clause, that is the product.
Zero marginal cost. No per-receipt pricing and no seat count. The download is 0.8 GB, once.
It works where the work happens. A market trader with a laptop and no reliable connection can sort receipts in the evening. A cloud tool cannot.
The accountant gets the same CSV either way. The value is the hour back, not a new format to learn.

The honest price for this is low, and that is fine. A tool that costs nothing to run can be priced at what the saved time is worth, and the model can be swapped for a bigger one later without renegotiating a contract.

Why Does Open Innovation Matter?

Every part of this that matters is open, and each one is a practical advantage rather than a slogan.

The document stays private because inference is local. A receipt is one of the most sensitive documents a small business owns. A closed sorter has to move it to a server to read it. Running the weights on the same laptop means there is no trust boundary to audit, because there is no boundary.

It runs with no network. The model, the prompt, and the parser are all on disk. The app is a PWA that opens offline. In a place where connectivity is metered or missing, the open version is not a worse version of the cloud one. It is the only version that works.

I can change the accountant. Gemma runs from a local GGUF file, so moving to a larger Gemma, a different quantisation, or a different model entirely is an environment variable, not a vendor conversation. A regional list of vendor names and tax labels is a fine-tuning run away. That kind of adaptation is impossible when the model is someone else's endpoint.

I can inspect the reasoning. When the model put a tax rate in the tax field, I could read the prompt, change it, and re-run the same document. With a closed API I would be guessing at what changed between two versions.

The cost stays at zero. No API key, no rate limit, no bill that grows with how diligent you are about keeping receipts. That matters most for the people who most need the tool.

The open pieces are not a licensing detail here. They are the reason the product can promise privacy, offline use, and a price of nothing.

Prize Categories

Best Use of Gemma: Gemma 3 1B runs locally through llama.cpp and does every extraction in the app. Its output is then validated by the normaliser, which is the part that makes a 1B model trustworthy enough for bookkeeping.

Built for Hacktoberfest 2026. No API key, no upload, no outbound calls when you sort a receipt.

Field notes from running small services

James Ngandu — Tue, 06 Oct 2026 12:46:34 +0000

I keep a running list of the things I do on every small service I run. None of it is clever. All of it has saved me at least once. I wrote up the full setup in You probably do not need Kubernetes. These are the notes I actually come back to.

Harden the box before anything else

Before the app goes anywhere near a server, the server has to be safe to expose. No root login. Key-only SSH. A firewall open on 80, 443, and SSH, and nothing else. Something like fail2ban to cut down the noise.

The step people skip is disabling password authentication. Do it only after you have confirmed key login works in a second session. I have locked myself out doing it the fast way, and it is a bad hour.

Bind the app to localhost

One line, worth more than most of the architecture decisions I make:

ports:
  - "127.0.0.1:3000:3000"

The app port is reachable only from the machine itself, so the reverse proxy is the only door in. If the proxy config breaks, you have a broken site, not an exposed service.

Check the certificate now, not later

certbot renew --dry-run

Five seconds. If it fails, I want to know today rather than the morning a certificate expires and the site goes red.

A deploy you can reverse is a deploy you will actually do

If deploying feels dangerous, you avoid it, and then you ship one scary change. The fix is small and reversible deploys. On a push, run the tests, and if they pass, update the box. Keep secrets in the platform, never in the repo. Keep the previous version one step away.

Minimum observability

A server you cannot see is a server you are guessing about. For a small service that means a health check that reflects real readiness, an external monitor that pages you when it stops answering, and logs you can read. That is enough. Collecting more than that, before there is a question to answer, is procrastination wearing a dashboard.

Reach for Kubernetes late

Kubernetes earns its keep when there are several services that scale independently, or a team that deploys without you, or a scheduler with real work to do. Until then it is a second job you volunteered for. I would rather run one box I understand than a cluster I have to look up.

The part that is not technical

The same shape of work shows up outside infrastructure. Leading the IEEE student branch at university was the same problem: limited time, unclear requirements, people with different goals. The clarity is the job. The tools are secondary.

None of these notes are original. They are just the ones that keep being true. If you run a small service, the boring version you understand will almost always beat the impressive version you do not.

Infrastructure was not where I started

James Ngandu — Tue, 06 Oct 2026 12:43:45 +0000

Infrastructure was not where I started.

I started in C. Pointers, arrays, strings, then memory allocation, linked lists, and eventually a shell. For months the work was small and low level: read a line, parse it, fork, exec, wait. Debug a segfault until it finally made sense. Recompile.

At the time it did not feel like infrastructure. It felt like fighting the machine. The compiler disagreed with me constantly. Memory had to be handed back by hand. Almost nothing was convenient.

Then I moved into Linux administration, Docker, CI/CD, and running production systems. And I kept noticing that the hard part was familiar.

When a container exits with code 137, that is the OOM killer, and it helps that I once had to think about how memory is actually used. When a process will not die, signals stopped being mysterious back in the shell project. When a service will not start, reading the log and following the failure chain is the same skill as tracing why a pointer wrote to the wrong place.

The language changed. The habit did not. The habit is this: understand the layer below the one you work in, so that when something breaks you can reason about why instead of guessing.

That is the thing ALX actually gave me, more than any single technology. It made being lost normal, and it made me comfortable opening the box.

If you are in the middle of the low level work right now, and it feels disconnected from the jobs you want, this is what I would say. The specific skills transfer less than you expect. The instincts transfer more. And the instincts are the part nobody can take from you.

Still learning. Still running small things on a single box more often than not.

You probably do not need Kubernetes

James Ngandu — Tue, 06 Oct 2026 12:42:16 +0000

Every few months I talk to someone who wants to put a small app on Kubernetes. Usually the app is one container, a database, and a handful of users. Often it is not even in production yet.

Kubernetes is excellent at a specific job: running many services, across many machines, with a team that deploys independently. If that is not your situation, it is a large amount of complexity you are taking on for a problem you do not have.

Most of my services run on a single VPS, and this is roughly how I set one up.

Harden the box first

Before anything runs, the server needs to be safe to expose. That means no root login, no password authentication, a firewall with only the ports I need, and something like fail2ban to cut down the noise. It is ten minutes of work, once.

The step people skip is disabling password authentication, because it is the one that can lock you out. Confirm your key login works in a second session before you close the first. I have gotten that wrong, and it is a bad hour.

The app runs in a container, bound to localhost

I run almost everything in Docker. One detail matters more than the rest: I bind the app port to 127.0.0.1 instead of exposing it.

ports:
  - "127.0.0.1:3000:3000"

That single choice means the container is never directly reachable from the internet. Only the reverse proxy in front of it can talk to it. If I misconfigure the proxy, the worst case is a broken site, not an open service.

Nginx sits in front and terminates TLS

Nginx does three jobs for me. It proxies to the app, it terminates HTTPS, and it is the layer I edit when routing changes or a new domain shows up. Certbot handles the certificates, including the renewal timer, so I am not the renewal timer.

The one check I run on every new server is certbot renew --dry-run. If that fails, I want to know today rather than the morning a certificate expires.

Deploys should not need me

The pipeline is short on purpose. On a push to main, GitHub Actions runs the tests, and if they pass it updates the box and restarts the container. Secrets live in GitHub, never in the repository, and the change is small enough that rolling back is just pointing at the previous commit.

A deploy I can reverse in a minute is a deploy I am willing to run often. That matters more than any particular tool.

Can I see it?

A server I cannot observe is a server I am guessing about. I want a health check that reflects real readiness, an external monitor that pings it and shouts at me when it stops answering, and logs I can actually read. That is enough for a small service. Collecting more than that, before there is a question to answer, is usually procrastination wearing a dashboard.

When I would actually reach for Kubernetes

When there are several services that scale independently, or a team that needs to deploy without asking me, or a scheduler with real work to do. When the complexity is buying something I need.

Until then: one box, a few containers, a proxy, and a pipeline I understand end to end. It runs, I can reason about it at 2am, and I can replace it when the requirements change.

That is usually the right trade. The impressive setup can wait until the boring one stops being enough.

My ALX journey: from Hello World in C to a load balancer and my own shell

James Ngandu — Tue, 06 Oct 2026 12:35:24 +0000

ALX is the software engineering programme that half of tech Twitter in Africa either went through or is currently grinding through. It is run by ALX Africa, built on the Holberton School curriculum, sponsored through the Mastercard Foundation, and it does not cost the learner anything. Twelve months, no lectures, project after project, and a peer learning model that takes a few weeks to get used to.

This is what that year looked like for me, and what is sitting in my repos to show for it.

How the programme works

It runs in sprints. You start with foundations, then move into a specialization. You advance by finishing projects, not by passing an exam. There is a completion cutoff around 80 percent of the projects across the sprints, with a minimum average in each one. Nobody stands in front of a class. You read the material, you attempt the project, you get stuck, you ask the people around you, and you submit.

The curriculum is deliberately vague in places, and that is the point. The phrase they use is owning your own learning, and after a few months it stops sounding like a slogan.

Foundations: Git, the command line, and C

The first thing you learn is that the terminal is not scary. Git and command line basics come before any real code, then Bash, and then C, which is where the real work started.

My alx-low_level_programming repo is the record of that stretch. It starts with a Hello World and works through variables, conditions, loops, and functions. Then debugging. Then the thing that humbles everyone: pointers. Pointers, arrays, and strings get four separate project sets. After that come recursion, static and dynamic libraries, command line arguments, malloc and free, the preprocessor, structs, function pointers, variadic functions, singly and doubly linked lists, bit manipulation, file I/O, hash tables, Makefiles, and search algorithms.

Somewhere in there you also reimplement formatted output, which is the moment variadic functions stop being a curiosity, and later you build a working shell: read a line, parse it, fork, exec, wait, and loop. That shell project is where all the small pieces suddenly have to work together in one program, and it is the closest the low level work gets to feeling like an actual system.

Higher level: Python and JavaScript

Then the language changes and the ideas stay the same. My alx-higher_level_programming repo goes from Python fundamentals (loops, imports, modules) into data structures, exceptions, classes, inheritance, test driven development, and a project called almost a circle that builds a small shape hierarchy from scratch. Later it moves into object relational mapping, network requests, and then JavaScript: the warm up, then objects, scopes, and closures, then web scraping and jQuery.

The interesting part is not learning a second language. It is noticing how much of C follows you into Python. Memory, references, and what an object actually is stop being abstract once you have spent months managing all of it by hand.

System engineering and DevOps

The third thread is the one that changed how I think about software the most. My alx-system_engineering-devops repo covers shell basics, permissions, redirections, variables, loops, conditions and parsing, processes and signals, and regular expressions. From there it goes where most beginner courses never do:

Networking, in two parts.
Web infrastructure design, the diagrams that explain how a request actually reaches an application.
SSH, and hardening it.
A web server, then an application server.
A load balancer, and later HTTPS and SSL certificates.
MySQL, including primary and replica setups.
APIs, and then advanced API work.
Web stack debugging, four separate rounds of it.
Webstack monitoring.

The web stack debugging projects are brutal, and I mean that as a compliment. You get a broken server and no description of what is wrong, and you have to find it. That is closer to the real job than any tutorial.

What ALX actually taught me

Less about any single language, and more about process. How to read documentation, how to break a big problem into pieces, how to ask a good question, and how to keep going when a project makes no sense for the first two hours. The deadlines are real and the volume is high, so you also learn to ship something that works instead of something perfect.

The other thing is people. The peer model is not decoration. A lot of what I know came from sitting with someone late at night tracing a segfault until one of us saw it. A lecture does not give you that.

If you are in ALX right now

A few things I would tell anyone in the middle of it:

Do not skip the low level work. It is the foundation everything else sits on.
Write down what broke and how you fixed it. It becomes your own documentation.
Ask for help earlier. Suffering for six hours before asking is not discipline, it is wasted time.
Push your work to GitHub as you go. Those repos are a portfolio at the end, and they are the reason people believe you when you describe what you can do.
Do not compare your progress to the person next to you. The sprints are hard for everyone, in different places.

The repos

alx-low_level_programming: C, from Hello World to a working shell.
alx-higher_level_programming: Python and JavaScript.
alx-system_engineering-devops: shell, networking, servers, and the debugging that comes with them.

If you are going through ALX, or thinking about starting, and you want to compare notes, the comments are open.

I built ARN.IO, a reading companion that keeps your place and your notes

James Ngandu — Tue, 06 Oct 2026 12:26:33 +0000

Browsers are good at showing you a page and bad at remembering it. Read a book online, close the tab, and a week later you are scrolling to find your place and wondering what you highlighted. ARN.IO is a small attempt to fix that.

It is a digital library and reading companion. You browse a collection, read chapter by chapter in the browser, and the app keeps track of where you are, so picking a book back up does not start with hunting for your place.

What it does

A curated library you can search by title, author, or genre.
Reading in the browser, one chapter at a time.
Progress per book, with the current chapter and a percentage, plus reading streaks that count minutes and pages.
Notes attached to a specific book and chapter, so the note lives next to the thing it is about instead of in a separate app.
Upload your own documents. PDF, Word, TXT, Markdown, HTML, and RTF are accepted and split into chapters automatically.
An AI reading assistant you can ask about themes, characters, summaries, or what to read next.

About the AI part, honestly

The assistant works out of the box. It ships with built-in keyword matched responses, so there is no API key to paste and nothing to pay for, and it still answers the common questions about a book. That was deliberate. I wanted someone to clone the repo, run it, and have the assistant actually reply instead of showing a configuration error. The chat is per book and the history is kept, so if you want to wire it to a real model later the interface is already there.

How it is put together

It is split into a client and a server. There is a run.sh at the root if you want to start everything at once.

chmod +x run.sh
./run.sh

There is also a docker-compose.yml with separate Dockerfiles for the client and the server, if you would rather not install anything locally.

Notes on the upload

Splitting a document into chapters across six formats is the fiddliest part of the feature. A PDF and a Markdown file do not agree on what a chapter even is, so the splitting is a best effort and you can always fix it by hand afterwards.

What it is not

There is no feed, no recommendations pushing you toward the next purchase, and no social layer. It is a reading tool, and it tries to stay out of the way.

Try it

Repo: https://github.com/mukuvi/ARN.IO

It is JavaScript end to end and it runs locally in a couple of commands. If you read and you lose track like I do, or you just want a small project to poke at the document parsing, the issues are open.

Also on DEV: if you are trying to make your first open source contribution, I wrote about a repo where contributing means adding yourself to it.

I built a site where your first open source contribution is adding yourself to it

James Ngandu — Tue, 06 Oct 2026 12:26:31 +0000

Plenty of people never make their first pull request. The commands are rarely the reason. You can learn git add, git commit, and git push in an afternoon. What stops people is that the repo they pick has no reason to care whether they showed up, and nothing visibly changes when they are finished.

So I built FREE-OPEN. It is a small React site, and the contribution is literally you. You fork it, add yourself to one JSON file, and open a pull request. When it is merged, your card appears on the contributors page of the live site. That is the whole thing. No issue to claim, no build system to learn, no review gauntlet waiting for you.

What your first contribution looks like

Fork the repo, clone your fork, and install dependencies:

git clone https://github.com/<YOUR-USERNAME>/FREE-OPEN.git
cd FREE-OPEN
npm install

Create a branch, open src/data/contributors.json, and add yourself to the end of the array:

{
  "name": "Your Full Name",
  "github": "your-github-username",
  "linkedin": "your-linkedin-slug",
  "twitter": "your-twitter-handle"
}

Run npm run dev, check that your card shows up at /contributors, then commit, push, and open the pull request. Once it is merged your card is on the live site.

Why a JSON file

I wanted the first contribution to be as small as possible. Adding one object to one file means you cannot really break anything, and if two people do it at the same time the conflict is a one-line fix. The point is not the JSON. The point is that you run the whole loop once, fork, branch, commit, push, pull request, merge, and then you look at the site and your name is there.

The stack

React 18, Vite, Tailwind CSS, and React Router. Nothing exotic. Vite because the dev server is fast enough that a newcomer does not sit around wondering if something is broken. Tailwind because the site has a dark mode and I did not want to hand-write a second stylesheet. React Router for the contributors and about pages.

What the repo is for

The repo has picked up 19 forks, and it has become a place to practise the boring, real parts of contributing: writing a branch name, writing a commit message that says what you did, writing a PR description that a maintainer can act on. Those are the things that get you through your first job, and you can practise them here without a deadline.

The lesson I keep coming back to is simple. People will contribute if the barrier is one file and the reward is visible. A lot of projects get the first half right and forget the second.

It is not finished

There is a CONTRIBUTING.md, a code of conduct, and issue templates for bugs, features, and improvements, so there is more to do than just add a card. The site itself is plain on purpose. I would rather it stay readable than clever.

Try it

Live site: https://free-open.vercel.app/
Repo: https://github.com/mukuvi/FREE-OPEN

If you have never opened a pull request, this is a good place to start and I will review it. If you maintain a repo and you are trying to get first-timers through the door, take the idea. Make the first step tiny and make the result visible.

Also on DEV: I wrote about ARN.IO, a reading companion that keeps your place and your notes, if you want another look at how I build things end to end.

Touch Grass Birder: a bird call identifier that works with no signal

James Ngandu — Tue, 06 Oct 2026 05:11:27 +0000

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

What I Built

Touch Grass Birder identifies bird calls, and it does the whole thing on your own machine.

You tap Listen, hold your phone up while a bird sings for about six seconds, and it tells you what you are hearing. Then you put the phone away and go look for the bird. That is the point: the screen is only in the way for a moment.

I built it for the places where phone apps tend to fall over. A trailhead with one bar. A tent before sunrise. A park where the warblers are moving through and you have no idea what you are listening to.

What it does:

Records six seconds of audio in the browser and encodes it to WAV on the device.
Identifies the species locally with BirdNET, the open acoustic classifier from the Cornell Lab of Ornithology.
Writes a short field note about the bird with Gemma 3 1B, an open-weight model running through llama.cpp.
Keeps a field log of everything you have heard, in a plain JSON Lines file you own.
Installs as a PWA and keeps working with the network turned off.

There is no API key, no audio upload, and no network round trip.

Demo

Live demo: https://touch-grass-birder.onrender.com

The hosted demo runs BirdNET, so you can point it at a recording right now. Gemma field notes only work when you run it yourself, because a free Render instance is too small for the 0.8 GB model. Run make models && make run for those.

Code

https://github.com/mukuvi/touch-grass-birder (MIT licensed).

How I Built It

Two open models run on the device, wired together behind a small FastAPI server.

flowchart LR
  A[Phone browser<br/>records 6s, encodes WAV] --> B[FastAPI]
  B --> C[ffmpeg<br/>decode to 16-bit mono WAV]
  C --> D[BirdNET acoustic model<br/>open, local inference]
  D --> E[species + confidence]
  E --> F[Gemma 3 1B<br/>open-weight via llama.cpp]
  F --> G[plain-language field note]
  E --> H[(data/sightings.jsonl<br/>your field log)]
  G --> A
  H --> A

The pieces:

Browser side: the MediaRecorder API captures six seconds, an AudioContext decodes it, and a small function in app.js writes a real 16-bit mono WAV Blob before it is sent. The server never has to touch the audio to get a usable clip.
BirdNET does the acoustic work. It is trained on thousands of species for passive acoustic monitoring, and it is the reason this works offline at all. It loads through the LiteRT runtime and stays warm in memory after the first call.
Gemma 3 1B (Q4_K_M, about 0.8 GB) runs through the llama.cpp CLI to write a two or three sentence field note: what the bird sounds like, where and when you would hear it, and one field mark to look for. If the model is not on disk, the app skips the note and still identifies the bird.
FastAPI ties it together with four endpoints (/api/identify, /api/sightings, /api/health, and the static app). The field log is data/sightings.jsonl.

Everything is overridable with environment variables (LLAMA_BIN, GEMMA_MODEL, MIN_CONF, LLAMA_THREADS, BIRDER_DATA_DIR), so the same code runs on a laptop, a Raspberry Pi, or something sitting next to a phone.

Why Does Open Innovation Matter?

The short version: this project only exists because the models are open.

The best places to hear birds are the places with no signal, and a cloud API cannot run there at all. Every closed identifier needs a round trip to a server. Running BirdNET on the device means the app is not a worse version of a cloud tool in the backcountry. It is the only version that works there. The recording is six seconds because nothing has to be uploaded and there is no spinner to wait on. The answer is already on the phone.

A rare sighting is sensitive. A closed app can learn where you were and when, which matters if you are near a nesting site or reporting a scarce species. Here the only record is a line in a file you own, on hardware you control. There is no server for it to go to.

Open weights also mean I can change the model. Gemma runs from a local GGUF file, so moving to a larger Gemma, a different quantization, or a different model entirely is a path and an environment variable, not a conversation with a vendor. I can fine-tune on a regional species list later. The classifier itself, BirdNET, is open and inspectable, which feels important when the output is a claim about a living thing.

And it costs nothing to run. No per-identification fee, no rate limit, no key that expires. A birder on a budget, a school group, or a citizen science project can run it as long as they want.

The open parts are the point. For this app the offline, private, zero-cost version is simply the better one.

My Agent Session

I built this with an agent. The session is saved, so you can see how it went:

Building Touch Grass Birder for the HF26 Week 1 challenge

You

Pasted the Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) announcement: build something with open-source AI at its core that gets people outdoors, due Oct 11. Can you do this?

Agent

I checked the workspace. There is already a project: Touch Grass Birder, a bird-call identifier (BirdNET + Gemma 3 1B) that runs fully locally. Tests pass. I loaded the challenge skill and confirmed Week 1 is active (id 79, due Oct 12 06:59 UTC).

▸ get_challenges list active DEV challenges

Input

list active DEV challenges

Output

Week 1 (id 79) active: theme Touch Grass, $2450 across 17 winners, judging = writing quality, relevance, creativity, technical execution, partner tech. Requires tag #hf26challenge.

You

Scope: Draft the DEV post, repo polish + commit, deploy to Render, save + embed the agent session, do it all end-to-end.

Agent

Audited the code (identify.py via BirdNET/LiteRT, fieldnotes.py via llama.cpp Gemma 3 1B, FastAPI main.py, PWA static app, 3 passing tests). Drafted the full submission post to docs/dev-submission-draft.md and added an MIT LICENSE.

▸ pytest uv run pytest -q

Input

uv run pytest -q

Output

3 passed in 2.09s

▸ git ls-remote git@github.com:mukuvi/touch-grass-birder.git

Input

git@github.com:mukuvi/touch-grass-birder.git

Output

Repository not found. Found the real repo at mukuvi/-touch-grass-birder (leading dash) with Apache-2.0 LICENSE; README/pyproject declared MIT. Local git history was an unrelated snapshot.

You

Decisions: rename repo to touch-grass-birder, use MIT license, deploy a BirdNET-only demo on Render free tier (Gemma notes run locally).

Agent

Reconciled the local repo onto the real remote, replaced Apache-2.0 LICENSE with MIT (matching README/pyproject), committed the post draft + license, and pushed to GitHub.

▸ git push git push git@github.com:mukuvi/-touch-grass-birder.git main

Input

git push git@github.com:mukuvi/-touch-grass-birder.git main

Output

25ba8b6..40b587d main -> main

You

proceed bro, you got all the keys

Agent

Verified the push landed, pointed local origin at the real repo, and set out the remaining steps: rename on GitHub (needs a one-click settings change from the user - SSH cannot rename repos), deploy the Render blueprint, embed this saved agent session in the post, then publish the draft.

Prize Categories

Best Use of Gemma: Gemma 3 1B runs locally through llama.cpp and writes the field notes.
Best Use of Render: the live demo runs on Render with the included render.yaml.

Built for Hacktoberfest 2026. Files, models, and data stay on the machine, with no key, no upload, and no network.