The code I was changing takes text containing {{placeholders}} and replaces each one with a real value. Then it does the whole thing again, because a value it just substituted can itself contain another placeholder, and it keeps going until a pass replaces nothing. So give it a placeholder whose value contains that same placeholder twice. Every pass replaces one and produces two, the string doubles each time, and the loop never reaches a pass that changes nothing. Nothing bounded that, and the endpoint takes anonymous requests, so any stranger on the internet could send a small body and pin the worker. Billion laughs, no XML required.

The loop was not something I wrote, and the bot said so itself: "The core loop DoS predates this PR... but this PR rewrites exactly this loop and adds a termination-safety comment, so it's the natural place to close the gap." It was reporting somebody else's old bug and it was honest about that, which is the part that made me read the rest of the comment. A human reviewing my diff would not have looked at that loop at all, because the loop was not the point of the change. Thirty seconds later the code reviewer found the same loop from its own angle, self-referential data hanging the worker until the host times out. I spent the next 24 minutes on a pass cap, a per-field length budget, and a test for each shape of the problem.

That was 07:24 on a Friday. We run a monolith and thirty-something microservices, review stopped being something we could keep up with by hand, and these agents are what I built to close the gap, so the interesting part is not that a bot found a bug, it is where it was allowed to look. It started with a commit rule and a script on my own laptop.

Why review got hard

A single change usually means touching several of those services at once, the volume going out every day has gone up a lot because generating a PR is cheap now, and reviewing all of it landed on the same people as before. Three costs, stacked.

The diffs got big. AI makes it easy to produce a large, coherent, fully tested change, so a PR now arrives as around a thousand lines across multiple files, and reading that carefully is genuinely hard work. You cannot skim it, and you cannot honestly approve it without holding most of it in your head at once.

Then the context switching. The PRs come from different people working on different things, a new feature here, a maintenance change there, a bug fix somewhere else, each in its own repository, so you load the mental model of that service, what it owns, what calls it, what its config looks like, read the whole diff carefully, and then the next PR is a different person in a different repository and you drop all of that and load a different one. My reviews got worse the more I switched, and I could feel it happening.

And the thing that actually breaks production is often not in the diff at all. A perfectly correct change in one repository can break three services that consume it, and nothing in the pull request shows you that. You only find it if you happen to remember which services call this thing, on a day when you happen to have the energy to go and look.

None of this is an AI problem. AI made the volume and the size worse, but a human-written PR breaks the consumer in exactly the same way.

The cheapest fix was not a reviewer at all

Before automating any reviewing, I changed how the code arrives.

We had an AI software-engineer agent by then, and the rule I gave it was simple: do not commit everything at once, commit in related chunks. So a change arrives as several logical commits, each one doing one thing, instead of one thousand-line blob with a single message on top. Whoever reads it can walk it commit by commit, and the change explains itself in the order it was built.

One line in an agent file, and every review after it got easier, before a single review agent existed. Nothing else in this post had that ratio.

A tool that only helps me does not move the bottleneck

The review side started as small as it gets. I wrote a code-reviewer agent and a security-reviewer agent, kept them on my own machine, and added a hook so that whenever somebody assigned me a PR I handed it to Claude Code and the agents ran locally against it. No CI, no rollout plan. The reviews were good enough that I stopped opening big diffs cold: findings first, then the code, and the second read was a different kind of reading, because I knew what I was looking for.

It was also miserable to run. A terminal per PR, opened by hand. It went through my own Claude account, so a big review would hit a context limit or start crawling against a rate limit. The CLI crashed partway through often enough that I learned to check. And more than once I came back to a review that had died because the laptop went to sleep. None of that is an argument about architecture. It is just what it costs to run infrastructure on a machine that is also a laptop.

Which fixed my afternoon and nothing else. The same cost was landing on everyone, PRs were sitting waiting for whoever had enough context to read them properly, and review was what set how fast any of us could ship, so a fix that ran on one laptop left that cap exactly where it was. So I moved the agents into a repo the whole team could pull from. They used them, and they liked them, and I want to be careful with that sentence: it is a feeling the people around me reported, not a number I can show you.

Sharing them is also what forced the quality bar up, because a reviewer that only annoys me is my problem, and a reviewer that annoys the whole team gets muted and then quietly wastes everyone's CI minutes forever. So the code reviewer got rebuilt around Rapid Software Testing principles, question the assumptions, look for what is missing, prioritize by risk, and every finding got a mandatory Failure Scenario field: concrete inputs, and the wrong outcome they produce. If the agent cannot say what actually goes wrong, the finding gets downgraded or dropped. That one rule killed almost all the noise, and it survives verbatim into what we run today.

Good reviewers, still blind to the blast radius

By then the agents had solved the first two costs, and solved them well. A thousand-line diff got read carefully every single time, at the same quality on the last PR of the day as on the first, and nobody had to hold an entire service in their head to say something useful about it.

The third cost they could not touch at all. They reviewed the change and nothing the change touches, so the question that actually takes production down, does this break the services that consume it, was still nobody's job. They also only ran when somebody remembered to run them. An agent sitting on a laptop had no idea the other repositories existed, and it could tell you the code was correct without telling you anything about what it would do to the rest of the system.

So I tried to give it the other repositories. I cloned every one I needed into a single parent directory and ran the agents from inside it, and it worked, the cross-checks were suddenly possible. Then the clones went stale. I would have needed a rule making the agent pull the default branch of every repo before every review just to trust what it was reading, and I still had to keep that directory honest by hand, and missing one new repository means the review is confidently wrong. A directory on my disk was pretending to be the organization.

The access was the whole feature

Moving the agents into GitHub Actions was supposed to solve the "when somebody remembers" half. It solved the stale-mirror half too, because in Actions the checkout is fresh by definition and the organization is the source of truth instead of my disk, so there is nothing to pull and no new repository to remember to clone. The cross-repository review I had wanted turned out not to be a feature I had to build, it was a side effect of putting the agent where the code already lives.

What I did have to build was the map. One central file in the shared repo lists which projects relate to which, as symmetric groups. The reviewer resolves the group for the repo under review and gets that list handed to it, read-only, and the repo under review cannot grant itself extra reach.

There is no index and no clever retrieval. The reviewer decides for itself what to go looking for, and it does it the way you would: it takes the thing it just saw change — an endpoint route, a property name, a DTO, a method — and runs gh search code for that term across the sibling repositories, then pulls the specific files the hits point at and reads them. That is the whole mechanism, and its weakness is exactly the one you would expect. It finds the consumer when the consumer names the thing recognisably. A caller that reaches the endpoint through a generated client, or a field that gets mapped through two layers of renaming on the way in, is invisible to a text search, and the reviewer will tell you the change looks safe because as far as it could see, it was.

Nothing is cloned and nothing is uploaded wholesale. The reviewer queries the API for exactly the files and lines it needs, when it needs them, so a sibling repository gets read a few hits at a time rather than shipped as a body of code. That is a smaller surface, not a different one — the code still goes to a model, and a CI job holding an org-scoped token reading other teams' repositories on every push is not the same thing as an engineer choosing to point an assistant at their own. It was an easier conversation here because everyone already works this way, but "easier" is not "asked."

So now: change something in the backend, and the reviewer goes and looks at every repository connected to it, the consuming services, the gateway layer, and tells you whether the change is backward compatible or whether it is about to break somebody. That is the whole point of the thing, and it runs today on the monolith and on the 30-plus microservices around it.

The obvious objection is that this is what contract tests are for, and it is. We have some. We add more when we touch something, and coverage grows slowly, and it is nowhere near all of a monolith that size — so on any given morning most of the surface between our services is asserted by nothing at all. A reviewer that reads the consumer's code does not fix that. It covers the part that is not covered yet, and it is worse than a contract test everywhere a contract test exists: slower, non-deterministic, and it can be argued with. The version of this I actually want is the one where the reviewer's findings turn into tests, so the same breakage gets caught next time by something cheaper and more certain than a model.

The number I do have is turnaround. Opening a PR and getting usable review feedback on it used to take 30 to 60 minutes depending on the size of the thing, sometimes a lot more when everybody was heads-down. Now it is under 5 minutes, of which about two are the reviewers themselves running in parallel and the rest is queueing and checkout. That is wall clock from push to feedback, not engineer hours saved.

The plumbing is deliberately boring: a 25-line workflow in each repo calls a reusable workflow in the shared repo, which loads the agent file, resolves the related repositories and runs the model. I have put a sanitized version of it up at github.com/MojtabaTajik/PR-Review-Agents, about 520 lines: the composite action, the reusable workflow, both agent files, the relationship-map schema and an example caller workflow. The plumbing is not the part worth having. The agent files and the rules inside them are.

• Single source of truth. No repo carries a copy of an agent. Changing a reviewer across the whole fleet is one PR to one file, and adding the next repository costs a 25-line workflow file.
• The two reviewers run in parallel. They are separate jobs on the same push, so the wait is about two minutes for both of them, not two minutes each. That number is the difference between a tool and a tax, and if it ever doubles people will start merging before the review lands.
• It is not a required status check. Nothing in the pipeline physically stops a merge. The rule is a team agreement instead: critical and high findings block the merge, everything below that is the author's judgment. Enforced socially, not mechanically, which works right up until the day it doesn't.
• One review per push, with the reviewed commit linked in the title. Push again and you get another review, pinned to the head commit it actually saw, so on a PR you push to five or six times you can tell which state of the branch each verdict applies to, and watch findings escalate and clear instead of arguing about a moving target.
• Terse when clean. A clean verdict is two lines: "Looks good — nothing to flag." No "here is what I checked" essays. Silence about non-issues is the signal.
• Everything the reviewer reads is untrusted input. It reads diffs and other people's repositories, and both can talk back. A repo can append its own context file, but that file is handed to the agent as untrusted data that can add emphasis and cannot relax the severity rules. The cross-repo token is fine-grained, contents-read only, and the repo under review cannot widen its own reach. I built a security reviewer, so it gets treated like one.
• The reviewer must name the repositories it consulted. Every cross-repo claim ends with that list. Otherwise you cannot tell an informed finding from a confident guess.

The proof: one feature, three repos, nineteen reviews

Back to that Friday. One ticket, one behavioral change, three coordinated PRs: the engine itself, a gateway policy, and the MCP tools that document the new authoring rules.

After I pushed the DoS fix, the code reviewer read the new commit and came back with the finding I could never have gotten locally: the live consumer app calls this endpoint without setting the mock-data flag, so my new strict default would break document creation in production. Footer of the comment, the consumer repo, named. It had read the consumer's actual code instead of guessing.

I went to production telemetry to settle it, 90 days, around 61k invocations, zero mock-fallback traces. Then I stopped trusting my own zero, because our ingestion filters out Information-level traces entirely, and that is exactly the level those fallbacks were logged at. The evidence that would have answered the question was below the ingestion floor. So the PR now logs fallbacks at Warning, and the rollout became measurable instead of hopeful.

An hour later the code reviewer, cross-checking three sibling repos, found the sharpest thing of the day: the admin app's document preview flow proxies its body straight through to the same endpoint, and preview is exactly the case where real data does not exist yet, so strict validation would have broken every preview. That finding created the gateway PR, injecting the flag at the gateway for the two preview operations only, instead of touching the admin app at all.

Then the best moment of the exchange. The reviewers reviewed the gateway PR in its own repo, verified the policy, confirmed by cross-repo read that the current engine tolerates the extra property, and then flagged the one thing they could not verify from that side: if the engine reads that flag anywhere other than a top-level body field with exactly this name, the injection silently does nothing and previews start returning 400 with no error visible at the gateway. I verified the contract by hand, then added two tests to the engine PR that deserialize the exact JSON the gateway policy produces. A future rename now fails a test instead of quietly turning every preview into a 400.

The third PR was documentation only, and all four of its reviews were the one-liner. A bot that always finds something teaches you to ignore it, a bot that can say nothing to flag makes its warnings worth reading.

At 09:35 both reviewers cleared the merge commit, and after all of that the entire verdict was: "Safe · Ready for QA — Looks good — nothing to flag."

Final count for the three PRs: 19 automated review rounds, 7 substantive replies from me, 9 of the 11 commits driven by review findings, 13 findings I acted on or pushed back on, three of which were wrong, one MEDIUM security finding, tests 199 to 208 green, about two and a quarter hours end to end. One feature, one morning: this is an anecdote, not a benchmark.

No other engineer looked at any of it before it reached our QA team, and that part deserves saying out loud rather than counting as a win: the only human at the merge button was the person who had written both the code and the reviewers. For a behavior-neutral change sitting behind a setting that is a call I am comfortable making. As a standing policy it would not be.

The round I won

At 09:02 the code reviewer flagged that my new length cap would fire even on the supposedly behavior-neutral deploy, and suggested gating it to log-only. The finding was right. The fix was wrong, and I rejected it in the thread: log-and-continue returns half-expanded content, and a silently corrupt document is worse than a clear 400, and removing the bound reopens exactly the DoS the security reviewer flagged at 07:24. Instead I raised the default budget 10x, to 1M characters, far beyond any legitimate value while still being a bound.

What it still gets wrong

• There are no evals. A one-line edit to an agent file ships to every repository at once, and the only symptom of a bad edit is fewer findings, which looks exactly like good news. I tested the product code carefully and did not test the thing making the judgments, which is a bit embarrassing to write down. I am building them now, with other models judging the reviewers' output.
• Three of the thirteen findings were wrong, and the loop made them itself. The agent flags something, I fix it and leave a comment in the code explaining the fix, the next round of fixes makes that comment stale, and a later review flags the stale comment. Each of those findings was correct about what it saw. The work was manufactured by the review loop, and the more rounds a PR takes the more of it there is. No fix yet, and I do not think more rules is the answer.
• I do not know what it misses. Everything in this post is a finding the reviewers caught. I cannot show you the ones they cleared that broke later, because the engine has not been running long enough for me to have that list, and a review system with no known false negatives is not the same thing as one with none. Same reason I would not trust that zero in the telemetry: nobody is measuring at the level where a miss would show up.
• The map is maintained by hand. That central relationship file is a dependency graph a human writes. A new service that nobody adds to it is invisible to every reviewer in the fleet, and the review that misses it still reads exactly as confident as the ones that got it right. Which is the same failure I escaped when I stopped cloning repositories onto my laptop, moved up one layer. I do not have a fix for it.
• It costs real money, and I have not added it up. Around €1 to €2 per PR on average, depending on how much cross-repo checking it does and how big the PR is. I have not totalled that across the fleet, so I cannot tell you the monthly bill. Guards exist, max turns, concurrency cancel, docs and bot PRs skipped, per-repo model override, and Sonnet as the fleet-wide lever if spend gets out of hand.
• Cross-repo reads are stale. One round cross-checked the gateway repo, hit the default branch instead of the sibling PR I had opened minutes earlier, and re-raised a finding I had already addressed. Open PRs in other repositories are invisible to it. I am working on that now: permission to list open pull requests in the related repositories, and rules telling the code reviewer to check them, so it surfaces the sibling PR that already fixes the breakage instead of reporting it to me twice.
• The reviewers review code, not intent. There is a gate that blocks PRs without a linked requirement, but a change that faithfully implements the wrong requirement passes every check we have.
• It repeats itself. The security reviewer re-affirmed the same hardening in several clean verdicts. Harmless, slightly annoying.

The division of labor is the part I would keep, and the 09:02 round is what it looks like. The agents set the bar. They do not own the merge button.

The reviewer itself was never the goal. Review was the thing capping how fast we could ship, so review is what I went after, and when the constraint moves the fix will look like something else entirely.

None of which is the thing I actually remember from that Friday. A cross-repo contract, pinned by a test, because a bot asked a question it could not answer itself.

That worked. After months of daily logging, the vault had grown dense. Thousands of notes: goals, lessons, VulWall decisions, Roamler retrospectives, weekly reviews, ideas I'd completely forgotten having.

Then I wanted to actually use it.

Not search it. Not scroll it. Talk to it. Send a message, get an answer that pulls from everything I've written: the lesson from three months ago, the decision I made last week, the goal I set in January. Without remembering where I filed it.

I added one character to the bot. Now ? at the start of any message means: ask the vault.

The Setup

Same Telegram bot. Same Go service. I added a FastAPI sidecar that handles embeddings and retrieval, and wired it in.

The architecture is simple:

Obsidian vault (markdown files)
        ↓
    FastAPI sidecar
    LanceDB (local, on disk)
    Ollama (nomic-embed-text, 768-dim)
        ↓
    Telegram bot
    "?" prefix triggers retrieval
        ↓
    Groq LLM answers from retrieved context

No OpenAI embeddings. No managed vector DB. Everything retrieval-related runs on the home lab next to the vault. The retrieval stack is local; Groq still handles final answer generation.

Embeddings Without a Cloud Dependency

The first decision: which embedding model.

I'm already running Ollama for other things. nomic-embed-text is 137M parameters, pulls in seconds, runs comfortably on CPU, and produces 768-dimensional vectors that punch well above their weight in retrieval benchmarks. It's become the default for local RAG setups for good reason.

ollama pull nomic-embed-text

That's the entire setup. The sidecar talks to Ollama over HTTP at localhost:11434. No API key. No rate limit. No bill.

Why Hybrid Search

The obvious implementation (embed the query, find nearest vectors, return top-k) works fine for semantic questions. "What are my thoughts on delegation?" retrieves notes that mean delegation even if they don't say the word.

But it falls apart on specifics. If I ask "what was the outcome of the Roamler retro in April?", a pure vector search returns notes that are about retrospectives, not the one from April or the specific decisions that came out of it. Dense embeddings compress meaning; they wash out rare tokens, proper nouns, and dates.

The fix is hybrid search: BM25 for exact token matching, vector for semantic matching, and reciprocal rank fusion (RRF) to merge the two result lists into a single ranking.

query → embed → vector search   ─┐
query → tokenize → BM25 search  ─┼→ RRF → top-k chunks → LLM

LanceDB supports this natively with one call:

results = (
    table.search(query_type="hybrid", vector_column_name="vector")
    .vector(query_vector)
    .text(query_text)
    .rerank(reranker=RRFReranker())
    .limit(6)
    .to_list()
)

Proper nouns, dates, and project names now land correctly because BM25 catches what the dense model misses.

Chunking and Indexing

Notes are chunked into paragraph-shaped blocks, capped around 800 characters, with 120 characters of overlap between chunks. The overlap is the part most tutorials skip: without it, a sentence that straddles a chunk boundary gets split in half and retrieval misses it.

Each chunk is stored with:

• The text
• Its embedding vector
• The note's vault-relative path as a key (Daily notes/2026/04/2026-04-12.md)
• A SHA-256 hash of the full note content

The hash is the idempotency key. When the reindex job runs, it fetches the current hash map from the sidecar in one call, then walks the vault. If a file's hash matches what's already indexed, it's skipped entirely. A vault with 2,000 notes where 10 changed since yesterday means 10 embed calls, not 2,000.

Bulk reindex runs on demand via /reindex in the bot. New notes get indexed automatically when I add them. Fast enough that I don't notice it.

Parallel Embeddings

One thing that bit me early: the first version of embed_batch was sequential.

# wrong
for t in texts:
    r = await client.post(ollama_url, ...)
    out.append(r.json()["embedding"])

For a note with 8 chunks, that's 8 serial HTTP round-trips to Ollama. Multiply by 2,000 notes on first index and you're looking at minutes of wall time for what should be seconds.

The fix is asyncio.gather:

async def _one(t: str) -> list[float]:
    r = await client.post(ollama_url, json={"model": MODEL, "prompt": t}, timeout=60.0)
    r.raise_for_status()
    return r.json()["embedding"]

return list(await asyncio.gather(*(_one(t) for t in texts)))

All chunks for a note go out concurrently. In my setup, Ollama still ends up doing the actual embedding work effectively serially on CPU, but the HTTP overhead stops stacking.

The FTS Index Trap

Another non-obvious issue: LanceDB's BM25 index needs an explicit build step.

The naive implementation calls create_fts_index after every /index call. That's an O(n) rebuild over the entire table, once per document during a vault reindex. For 2,000 notes, that's 2,000 full rebuilds of a growing index.

The fix: accept a rebuild_fts flag on the /index endpoint. The bulk reindex caller sets it to false for every document, then calls /rebuild-fts once at the very end. One rebuild, not 2,000.

Small detail. Massive difference in reindex time.

Asking the Vault

From the user side, nothing changed. Same bot, same Telegram thread. The only difference is the prefix.

Without ?: the message goes into today's daily note. With ?: the message goes to the vault as a question.

me:  ? what were my main takeaways from the Roamler retro in April?

bot: Based on your notes from April 14 and the weekly review from W16:
     The main theme was async communication overhead...

The sidecar retrieves 6 chunks, the bot assembles them into a context block, and Groq answers against that context. The source note keys are passed into the prompt for grounding, even though the bot's final reply stays clean and citation-free.

Temporal queries work naturally too. If the question contains "last week", "yesterday", "last Tuesday", or an explicit date like "2026-04", the bot parses it and passes a date range to the sidecar. LanceDB filters by the date column before running the hybrid search, so "what happened last week?" only searches notes from that window — not the entire vault. No special syntax needed.

One thing I didn't expect: the detail hierarchy doing real work. My vault has daily logs (raw, specific), weekly reviews (themes), and quarterly reviews (narrative arcs). The chunking doesn't distinguish between them. A query about the Roamler retro retrieves from all three levels simultaneously: a daily note with the raw action items, a weekly review that grouped them into themes, a quarterly review that named it a turning point. The answer has natural depth because the source material was written at multiple levels of abstraction.

That wasn't designed. It emerged from the structure the walkie-talkie system wrote into the vault.

I've been using it to surface things I'd genuinely forgotten: decisions I made and didn't act on, lessons I wrote down and then ignored, patterns across weeks of daily logs that I couldn't see one day at a time. Generic RAG demos use docs or Wikipedia. When the source material is your own writing, the answers feel unnervingly on-point. It's not retrieving similar documents. It's retrieving me.

Steal This

The pieces are all open source and local.

• Ollama + nomic-embed-text. Free, fast, no API key. ollama pull nomic-embed-text and you have a production-quality embedding model.
• LanceDB. Embedded vector DB, runs in-process or as a sidecar, no infrastructure. Hybrid search built in.
• Content-hash idempotency. SHA-256 the file, store the hash, skip unchanged files on reindex. Your reindex job goes from slow to instant after the first run.
• Hybrid BM25 + vector + RRF. Pure vector search misses proper nouns, dates, and rare terms. Hybrid catches them. The extra setup is ten lines.
• One rebuild at the end. Don't rebuild the FTS index after every document during bulk reindex. Rebuild it once when the loop finishes.
• Temporal filtering. Store the note date as a column and parse natural language ("last week", "yesterday") into a date range filter before the vector search. Cuts noise significantly for time-specific questions.
• Use your existing interface. I already had a Telegram bot. Adding ? as a retrieval prefix cost me an if-statement and a new handler. No new app. No new habit.

The vault was already healthy. Now it answers back.

The journaling problem isn't discipline. It's friction. Open the app. Find today's note. Remember the template. Fight the formatting. By the time the tool is ready, the thought is gone, and you're three days behind on a ritual you swore you'd keep.

I solved it the dumb way. I put a Telegram bot in front of my vault and let AI do the filing. Now I journal by texting. The vault writes itself.

Here's the whole setup.

The Core Loop

I text any thought (a line, a paragraph, a dump) to a private Telegram bot. Or I hold the record button and speak. The bot replies with two buttons: Today or Yesterday. I tap one. Under five seconds later it reacts 👌 to my original message, and my daily note in the Obsidian vault has the new content, cleanly refined, filed into the right section.

Voice is the half that makes the mobile moments actually work. Typing on a phone while watering flowers isn't possible. Holding a button and speaking is. Telegram voice notes land as Opus-in-Ogg audio, get piped to whisper-large-v3 on Groq, and come back as text in about a second. The bot shows me the transcript next to the Today/Yesterday buttons so I can catch any word Whisper got wrong before I commit. I almost never need to.

That's the entire user-facing experience. No app. No template. No friction. The hardest decision I make is today or yesterday.

Under the hood it's a Go service called DailyLog, running in Docker on my home lab, bind-mounted directly into my Obsidian vault. When I tap a day, it:

1. Loads the existing daily note at vault/Daily notes/YYYY/MM/YYYY-MM-DD.md
2. Appends my raw blurb to the end
3. Sends the whole merged document to GPT-OSS-120B on Groq with a very strict system prompt
4. Writes the refined output back to disk

The model choice matters here. Note-taking isn't a reasoning task. It's routing, grammar cleanup, and bullet grouping. A 120B open-weights model running on Groq's inference is more than enough for that, fast enough to round-trip under five seconds, and cheap enough that I can fire it a dozen times a day without thinking about the bill. Frontier models would be overkill. A smaller model would lose the grouping nuance. 120B-class is the sweet spot for this specific job.

The actual magic isn't the API though. It's the prompt.

The Prompt Is the Product

Every daily note in my vault follows a fixed shape:

## Personal
- …

## VulWall
- …

## Roamler
- …

Three sections. Personal for life, VulWall for my startup, Roamler for day-job work. That's it. The system prompt I hand Groq has eight rules, but three of them carry the weight.

1. Never drop information. Every piece of input must appear in the output. Not "summarized away," not "skipped because it sounds unimportant." If I mention a family member's package pickup tomorrow, that bullet exists in the final note. Even if it's about a future day. Even if it's someone else's plan. If in doubt, include it.

2. Route to the right section. Personal is home, family, errands, appointments, non-work messages. VulWall and Roamler are the two work buckets. Items go there only if they're clearly about those projects. Everything else defaults to Personal. No new sections ever. No ## Miscellaneous, no ## Notes.

3. Group related content. If I dump five sentences about fixing a kitchen wall (the research, the store run, the tools, the install, the leftover TODOs), the output is one rich bullet telling that story, not nine fragmented ones. Only split when topics are genuinely unrelated.

The group-don't-fragment rule is what turned this from "AI notes toy" into something I actually trust. Without it, a paragraph of connected thought becomes a scatter of disconnected bullets and the note reads like a grocery list. With it, the note reads like someone wrote it on purpose.

One more rule works in the background without making a speech about it: fix what's broken. Typos, wrong tense, run-on sentences, missing punctuation. The capture pass is also the polish pass. There's no editor downstream, because there shouldn't need to be.

Merge, Don't Replace

The other design choice that made this work: the bot never overwrites. It merges.

When I send my sixth note of the day, the bot doesn't regenerate the whole note from scratch. It loads the existing refined markdown, appends my new raw blurb after the last section, and hands the combined document to the model. The prompt tells Groq explicitly: preserve every existing bullet exactly; only integrate the new paragraph at the end.

This matters for two reasons.

• Stability. A bullet I wrote this morning doesn't get subtly rephrased every time I add a new thought in the afternoon. What was refined stays refined.
• Trust. I can look at a note mid-day and know that nothing I've logged has quietly mutated. The model only touches new content.

It's a small architectural decision that most "AI-powered notes" tools get wrong. They regenerate. Things drift. You stop trusting the output. You stop using the tool.

The Second Half Runs on Cron

The bot captures. Cron curates. Every script writes directly into the vault and pings me on Telegram when it's done.

Each of these is a small shell script. The script itself is mostly plumbing: source an env file, export ANTHROPIC_API_KEY, call the claude CLI with a prompt and an agent flag, pipe the result to notify.sh. Under 50 lines apiece. The actual work happens inside Claude.

The --agent flag is the hinge. It tells Claude Code which specialist to open the session as. Each agent is a markdown file under ~/.claude/agents/ with a system prompt, tool permissions, and a tighter scope. The mapping:

Each script leans on one specialist. Planning a day against recent notes and goals is an opinionated routing job, so daily-planner does it. Triaging a stack of clippings into keep-or-delete plus a draft note is a classification job, so clippings-curator does it. Synthesizing a week (or a quarter) of notes into themes and narrative arcs is a reflection job, so life-coach does it. Different agents, different system prompts, different jobs.

I ran the weekly and quarterly pipelines as two stages for a while: one agent to draft, a separate grammar-and-frontmatter agent to polish. Then I noticed I was paying to reload the whole life system twice just to run a checklist at the end. I moved the checklist into the drafting prompt and dropped the second stage. The output is the same. The bill is lower. The log is simpler. When a pipeline needs an editor, the right editor is usually the writer, one paragraph later in the same prompt.

But none of this would be useful if the agents didn't know my life. That's what CLAUDE.md is for.

The CLAUDE.md at the root of my vault documents everything an agent needs to act well: folder structure, templates, my life system (Life OS.md, Goals.md, My rules in life.md, Lessons.md, Wins.md), the detail-hierarchy rule, and when to invoke specialized advisory agents like startup-coach or startup-legal-advisor when the topic calls for them.

When the weekly-review cron runs at 03:45 on Sunday, it isn't firing a fixed prompt at an LLM. It's opening a Claude Code session scoped to my vault, with full filesystem access, with CLAUDE.md loaded, with my 2026 focus visible in Goals.md, with last quarter's narrative sitting in Self Reflection/Quarterly/. It knows the shape of a weekly review because it has read the template. It knows what not to include because it has read the detail-hierarchy rule. Then it writes the file.

The payoff is iteration cost. If a weekly review feels off, I don't deploy code. I edit the life-coach agent's markdown, or tweak a line in my vault's CLAUDE.md, or adjust the template. The next Sunday's cron run uses the new version automatically. The system has no release cycle. Every night is a hot reload.

The detail hierarchy is the organizing idea:

Daily     -> raw log, specific items, one-off errands
Weekly    -> grouped themes, 3-5 highlights, pattern-spotting
Quarterly -> narrative arcs, zero line items, direction and drift

Each level summarizes the one below. Detail never flows upward. A PR number belongs in the daily log and nowhere else. A quarterly review reads like a letter from your future self about the shape of the last three months.

Reliability Is Not Optional

This is all worthless the day I lose the vault.

Local SSD backups every night at 02:00, 14-day retention. Every Sunday, the same tarball gets GPG-encrypted with AES-256 and shipped to Cloudflare R2. The R2 bucket has a lifecycle rule: transition to Infrequent Access after 7 days, expire after 60.

The encryption passphrase lives in two places: the .env on the host, and a 1Password entry. If both disappear, the R2 backups are permanently unreadable. That's the design. Off-site backups that require no trust in Cloudflare.

Every backup run posts to Telegram:

• ✅ Local backup complete with size and host
• ✅ Local + R2 backup complete with R2 object key
• ❌ Host backup FAILED with the specific reason

No dashboard. No log aggregator. Just Telegram. If my phone doesn't buzz at 02:05 with a green checkmark, something broke.

Why This Works When App-Based Journaling Didn't

Every journaling tool I've tried failed in week three. Obsidian with a beautiful template. Notion with elaborate databases. Apple Notes. Day One. Roam. All of them died the same way: the tool became more effort than the thought was worth.

Telegram isn't optional. It's open on my phone and laptop all day. The bot is one thread in a stack of conversations I'm already scrolling. There's no decision to journal. There's a thought, there's a chat window already right there, and the friction between them is zero.

The vault is still the system of record. Real writing, linking notes, building out Permanent notes, running DataView queries. All of that happens in Obsidian when I'm at my desk.

Telegram is for the daily log. The thought at a train station. The reminder while I'm watering flowers in the yard. The errand that popped into my head walking back from the store. My day doesn't happen behind a laptop, and those are exactly the moments where a note would have died on the walk home.

The bot catches them because capture is one gesture: press the button, talk. It's a walkie-talkie with an AI on the other end. No app switch, no typing, no decision about where the thought belongs. Press, talk, tap Today, back to whatever I was doing.

Steal This

The pieces are individually boring. The combination works.

• Put a Telegram bot in front of your vault. Any stack works: Go, Python, Node. The hard part isn't the bot. It's deciding you deserve zero-friction capture.
• Write a strict system prompt. Fixed section schema. Never-drop rule. Group-related rule. Spend more time on the prompt than on the code.
• Merge, don't regenerate. Load existing output. Append raw input. Only transform the new part. Stability is a feature.
• Let cron do the second draft. Weekly synthesis, quarterly narrative, morning briefing. You don't need to review. You just need the pipeline.
• Let Telegram be the whole interface. Capture goes in, text or voice. Briefings, reviews, and alerts come out. One chat, both directions. The capture channel and the feedback channel being the same channel is what keeps the whole system in one context.

None of this is clever. It's a couple hundred lines of shell, a small Go service, and a prompt I've iterated on more than the code. The bar for "it works" is low. The bar for "I still use it in month six" is high. This one cleared it.

I still open Obsidian every day. Just not to journal. The vault is the healthiest it's been.

It's a riff on TL;DR, and it's the most honest feedback I've seen on a growing team habit: pasting raw AI output into cross-team chat. The joke landed because everyone recognized the shape of the thing. If a new piece of slang forms organically around a behavior, the behavior is already a problem.

This isn't an anti-AI post. I use AI every day. This is about a specific failure mode: AI that makes the writer's job easier by making the reader's job harder.

Two shapes of the problem

1. AI replacing "I'm stuck"

A developer hits a 401 on an internal reporting API. Instead of pinging the owner with "I'm getting 401 on every call, here's the error - any idea?", they paste an 800-word AI-generated root cause analysis into the channel:

Every call to the reporting-internal API returns HTTP 401 at the gateway, even though the OAuth handshake succeeds.

Layer analysis:

1. OAuth / token issuance - OK. The token is minted; login completes cleanly.
2. API gateway routing - OK. We get a structured JSON error envelope, not a transport-level error.
3. Scope enforcement - FAILS. The gateway evaluates the authenticated principal against a scope literally named reporting. The principal does not carry that scope.

What this tells us about the backend design: There is a dedicated scope gating all reporting calls, implying scope enforcement at a gateway middleware layer rather than per-endpoint. Identity resolves correctly, so the bearer token is accepted and mapped to a user - the mapping is just missing the scope grant.

Suggested follow-up: (1) Grant the scope. (2) Document token refresh semantics. (3) Improve the error envelope with a code field. (4) Add a pre-flight /capabilities endpoint. (5) Audit scope granularity - reporting is coarse; reporting:read vs reporting:write would be healthier.

The actual information the owner needed was one line:

Getting 401 on every reporting-internal call - error says "token does not carry the reporting scope." Can you grant it? Username alex.

The AI output wasn't wrong. It was 790 words of scaffolding around a 10-word problem, and the owner had to read all of it to confirm the 10 words were in there somewhere.

2. AI replacing "can you help?"

Worse variant: someone from outside the technical domain pastes a step-by-step "fix" for a problem they don't own.

ISSUE: The billing export uses "delegated tokens" - these are tokens obtained per user via OAuth. My token can only export as me, not as the finance team. The finance service account has never completed the OAuth flow, so there is no token for it.

STRUCTURAL FIX (already deployed):

1. Export route -> now uses getServiceAccountId() (impersonation-aware)
2. New: Client Credentials Flow added - an app-level token that allows the platform to export on behalf of ANY user in the tenant, without each user completing OAuth individually.
3. Fallback chain: per-user token -> legacy token -> client credentials token.

HOWEVER: this only works if the platform app has the correct permissions. In the IdP admin console: App registrations -> select the Billing app -> API permissions -> Add a permission -> Finance Graph -> Application permissions -> search Export.ReadWrite -> Add -> "Grant admin consent" (important!).

This is a one-time setup. Once done, the platform can export on behalf of any user.

The reply, from an engineer:

AI;DR;

Now the engineer has to reverse-engineer two things: what the actual issue is, and which parts of the AI's confident prescription are real vs. hallucinated. The claim "already deployed" is doing huge trust-work: was it? By whom? Tested how? The sender didn't know. The AI didn't know either. But the output reads like it does, and that confidence is the problem.

What the message should have been:

Billing export is failing for the finance team - they can't pull the April file. Can someone take a look? Happy to share my screen.

Why this specifically hurts team communication

The case against pasting AI output into team chat isn't that AI is bad. It's that:

• Length is no longer a signal of effort. A 1000-word message used to mean someone thought hard. Now it might mean they pressed a button. Readers can't tell, so they treat all long messages as suspect - which penalizes people who did think hard.
• Confidence is no longer a signal of expertise. AI writes with the voice of authority by default. A non-technical person pasting AI output sounds like an architect. The reader has to do the expertise check the sender skipped.
• Assumptions get laundered into facts. The AI fills gaps with plausible guesses. Those guesses arrive in your chat looking identical to the parts that are true. Separating them is the reader's job now.
• The bias is toward more output, not better output. AI lowers the cost of writing, not the cost of reading. Team chat runs on a shared attention budget, and unfiltered AI output is a tragedy of the commons.

A simple rule

Before pasting AI output into team chat, ask: would I have written this much if I had to type it?

If no, cut it to what you would have typed. The AI can help you think; it shouldn't be the voice you send on your behalf.

For technical problems specifically: the useful message is almost always a clear description of the problem, not a proposed solution. The investigation belongs to the person who owns the system. Your job is to describe what you observed, not to diagnose it for them.

What to do instead

• Use AI as a personal thinking tool. Draft, rubber-duck, summarize for yourself. Then write the message in your own voice.
• Send the problem, not the hypothesis. "401 on every call" beats "here's my analysis of the backend's scope enforcement layer."
• If the AI output is genuinely the message, say so. "AI helped me draft this, flagging the parts I'm unsure about: [...]" is honest. Pasting it unmarked is not.
• Cut 80%. The useful signal is almost always in the first two sentences.

Closing

The pushback is already cultural. "AI;DR" works as a reply because everyone has spent the last few months skimming AI-polished paragraphs for the 10% that's actually relevant. That's the signal.

AI is a power tool. Point it at your own thinking and it makes you sharper. Point it at your teammates' inboxes and it makes you the reason someone replies "AI;DR."

Keep it human, keep it short, keep it yours.

And sometimes we're right. We already know how the meeting will go before it starts.

But as senior engineers or leads, we have to hold both perspectives at once. It's not about who understands more. Business and engineering teams think differently, and both ways of thinking are necessary. The gap between them isn't a personality problem. It's a structural one, and it can be closed.

From my own experience leading teams and running a company, I've learned that the best outcomes come from engineering teams that understand the product and product teams that understand the tech. The closer those two worlds get, the faster and better everything moves.

1. Understand That the Gap Is Real

Engineers focus on correctness, scalability, and technical craft. Product and business teams focus on customer needs, market fit, and shipping. Neither is wrong; they're optimizing for different things.

The friction shows up in predictable places: an engineer prioritizes paying down technical debt while a PM wants the next feature out the door. Acknowledging this tension honestly is the first step. You can't close a gap you pretend doesn't exist.

2. Open Communication Before Decisions Are Made

The most common mistake: engineers get looped in after product decisions are already locked. By then, their input feels like obstacle-raising rather than collaboration.

Bring engineers into conversations early, when discussing customer pain points, scoping new features, or setting timelines. They'll surface technical constraints before they become blockers, and they'll feel like owners rather than implementers.

On the other side: engineers who stay in their technical bubble miss context that would change how they build. Regular check-ins, shared channels, joint planning sessions. These aren't bureaucracy. They're the communication infrastructure that makes good decisions possible.

3. Align on the Actual Goal

Both teams need to understand what the company is trying to achieve, not just their slice of it. Is this quarter about retention? Scale? Entering a new market? When everyone knows the goal, they can make better local decisions without escalating everything.

Engineers involved early in product development can flag feasibility issues before they're expensive. Product teams who understand technical constraints can set more realistic expectations. Neither side needs to become experts in the other's domain; they just need enough shared context to collaborate without friction.

4. Build Feedback Loops

Engineers who see how their work is used in production develop instincts that product teams can't replicate. Get them into customer feedback sessions, user testing, or even occasional direct customer contact. It changes how they think about what they're building.

Product teams should also share what they're hearing from users before it's been formalized into a spec. The informal signal, "customers keep asking about X", is valuable input, not just the polished requirements document.

5. Work as One Team, Not Two

Cross-functional teams where engineers and PMs share the same goals and cadence consistently outperform siloed ones. Not because everyone does everyone else's job, but because shared ownership changes how people show up. They ask different questions in sprint planning. They catch problems earlier. They trust each other more.

This doesn't require a reorg. It requires shared workspaces, shared tools, and shared objectives.

6. Keep Iterating on the Collaboration Itself

The gap doesn't close once and stay closed. Teams change, priorities shift, new people join. The collaboration process needs the same continuous improvement you'd apply to the product.

Regular knowledge-sharing sessions help: engineers presenting technical changes and constraints, product sharing market trends and user feedback. The goal isn't information transfer. It's building mutual empathy so both sides understand the pressures the other is working under.

Conclusion

The engineering-product gap is a structural problem with structural solutions. Open communication, early involvement, shared goals, feedback loops, and genuine cross-functional ownership. These aren't soft skills. They're the infrastructure that lets good teams do their best work.

When both sides are aligned, you move faster, build better, and waste far less time on friction that didn't need to exist.

Let's face it — your manager likely has their hands full with an endless to-do list, juggling meetings, decision-making, and a myriad of other responsibilities. Be realistic: you're not the only cog in the wheel that deserves their attention. They're human, with finite bandwidth that needs to be used wisely. In the grand scheme of a large organization, you're just one piece of a much bigger puzzle.

It's not solely your manager's responsibility to keep tabs on everything you're doing. It's also up to you to make it easy for them to stay informed. Having a clear and accessible record of your efforts helps refresh their memory and ensures they can easily recognize the value you bring to the table.

What is a Brag Document?

A brag document is a living record where you track all of your work-related achievements and milestones. It includes major projects, key contributions, metrics, and feedback from colleagues or managers. This tool ensures that when performance reviews, promotions, or job interviews come around, you have a comprehensive list of your accomplishments — without relying on your memory or, more realistically, on your overworked manager's memory!

In today's ever-evolving professional landscape, a brag document can be more than just a list of wins. It's a chance to showcase your ongoing contributions to company culture, mentorship, innovation, and strategic improvements — areas that are increasingly valued in modern tech and corporate environments.

Why You Should Keep a Brag Document

Demonstrates Your Impact

A brag document highlights specific contributions, like product launches or efficiency gains, making it easier to showcase how you've solved problems and stood out in a fast-paced industry.

Supports Career Growth and Promotions

Tracking achievements in a brag document shows your growth and progress, providing solid evidence for promotions and raises, while highlighting leadership and cross-team contributions.

Makes Performance Reviews Easier

A brag document simplifies performance reviews by summarizing your work and helping managers evaluate your contributions more effectively, especially in fast-moving industries.

Facilitates Transparency and Peer Recognition

Sharing your brag document with peers allows for valuable feedback, increasing visibility and fostering transparency in collaborative work environments.

Builds Confidence and Provides Clarity

Regularly updating a brag document helps you reflect on your accomplishments, boosting confidence and offering clarity on areas to focus on, especially during career transitions.

How to Create Your Brag Document

Keep It Up-to-Date

Regularly update your brag document to capture recent achievements. Set aside time monthly or quarterly to reflect on your work, ensuring you don't miss important details when it's time for reviews or applications.

Be Specific and Add Data

Detail your accomplishments with measurable outcomes, such as "Reduced server response time by 25%." Back them up with data like improved performance, higher revenue, or customer satisfaction, as numbers add weight to your achievements.

Cover a Range of Contributions

Include both technical and soft skills — leadership, communication, mentoring — alongside measurable successes. Modern industries value holistic contributions, so showcasing these broader impacts is essential.

Don't Be Modest

A brag document is your opportunity to confidently highlight your value. Recognize and take pride in your achievements; it's a key tool for career advancement.

Best Practices for Maintaining a Brag Document in Modern Industries

Use Tools That Work for You

Choose a platform like Google Docs or Notion that's easy to access and update. Modern tools allow for seamless sharing and collaboration when needed.

Review and Reflect Regularly

Set aside time monthly or bi-weekly to review your brag document. Reflect on areas of improvement, and adjust your focus — whether that's balancing technical achievements with leadership or team-building.

Share When Appropriate

While personal, don't hesitate to share parts of your brag document with your manager or peers. This transparency fosters discussions about your career goals and helps guide your next steps.

My Approach

For nearly four years, I've made it a habit to take daily notes, covering both work and personal life. Each day, I spend just five minutes reviewing the previous day, remembering important events, checking emails, and reviewing Slack/Teams messages. I summarize everything in bullet points. For work-related items, I use the #brag tag to highlight accomplishments that I want to track.

Monthly, I reflect on my brag document by using the $brag tag to quickly review what's happened recently. This practice helps me update my brag document with new progress, keeping it on track and ensuring it remains current and reflective of my ongoing achievements.

Anecdotal Insight: Throughout my career, I've often advised colleagues to create a brag document to track their achievements. Unfortunately, many chose not to follow this advice and struggled during performance reviews and 1-on-1s. However, those who took the time to build and maintain a brag document have seen noticeable improvements in how they articulate their contributions, leading to more productive and successful reviews.

Conclusion

A brag document is more than just a list of accomplishments; it's a strategic tool for personal growth, career development, and professional recognition. It helps you advocate for yourself in a competitive, fast-moving industry and ensures that your achievements are properly acknowledged. Start building yours today to stay ahead and make sure your hard work never goes unnoticed.

Sitting in my utility room was an Intel NUC 11 Pro Kit with an i7, 32GB RAM, and a 1TB SSD. Instead of paying for convenience, I decided to wake it up and reclaim my infrastructure.

The Spark: That Invoice and the NUC Resurrection

I flashed Ubuntu Server 22.04 onto a USB stick, booted the NUC, wired it to my router, and stashed it in the utility room. Total time: under an hour. Cost: zero.

Lesson I share with juniors: audit before you architect. That old box might be all you need.

Enter Coolify: Self-Hosting Without the Pain

I didn't want Kubernetes on a single node. Too much overhead. Instead, I found Coolify, an open-source, self-hosted Heroku alternative. Connect it to GitHub, push code, and it builds and deploys Docker containers automatically.

Installation was one command over SSH. Minutes later, I had a dashboard running on my NUC's local IP. My first deploy — a small API — was live in seconds. From there it snowballed: automated CI/CD, no cloud tax, no YAML hell.

Solving Dynamic IPs with Cloudflare DDNS

Home labs break when your ISP changes IPs. Instead of paying for DDNS, I ran a Cloudflare DDNS container through Coolify. It updates DNS records automatically using a lightweight Python script.

Config took minutes: create a Cloudflare token, drop it in a JSON config, and let the container run every 15 minutes. Now my services stay reachable at api.mydomain.com or ha.mydomain.com without static IPs or manual tweaks.

Migrating Services: Home Assistant and Pi-hole

With the backbone ready, I pulled in existing services:

• Home Assistant for smart home orchestration
• Pi-hole for network-wide ad blocking
• Dozzle for monitoring Docker logs

All services run as Docker containers in Coolify. For routing, I used the built-in Caddy reverse proxy, which maps subdomains to local ports and handles SSL automatically.

Power-Proofing with a UPS

Dutch grids are reliable, but outages happen. I added a small UPS to keep the NUC and router alive for 15–30 minutes — enough to ride out blips or shut down cleanly. Cheap insurance for reliability.

The Payoff: Zero Bills, Infinite Experiments

A week later:

• Cloud costs: gone
• Deploys: instant
• Services: stable
• Mental bandwidth: free for real work

I can spin up experiments without guilt. This isn't just a home lab — it's a manifesto. In a world of ballooning cloud bills, owning your stack is freedom. Cloud has its place, but if you're prototyping or tinkering, you don't need to rent convenience.

Keep in mind that buying a house is often a lengthy, time-consuming, and challenging process, especially in the Netherlands. Everyone's experience can vary. The points I discuss aren't definitive and may differ based on your circumstances, but they provide a solid overview of what to expect.

Prerequisites

At the outset, evaluate your financial situation. Can you cover the various costs associated with buying a house — fees for consultants, notaries, and other expenses? Beyond the mortgage itself, you'll need approximately €7,000 to €10,000 depending on your circumstances (I've detailed these costs at the end).

This amount covers incidental purchase costs and is separate from any overbid amount.

Permanent Contract

The most important factor in securing a mortgage is having a permanent contract. You either need a permanent employment contract, or a "Declaration of Intent" letter from your employer indicating they plan to renew your contract.

In the Netherlands, a permanent contract offers significant job security — the employer can rarely terminate it except under very special circumstances. Banks value this stability highly.

• A declaration of intent can reduce the loan amount, so a permanent contract is more advantageous.
• For couples, it's sufficient for one person to have a permanent contract. If both do, the loan amount increases accordingly.

Checking Your Loan Range

Dutch home mortgages typically span 30 years. To estimate your potential loan, use an online mortgage calculator — the ABN Bank calculator is one of the simplest and most reliable. Enter your details and get an approximate figure accurate to within 1–2%.

Your loan amount can also increase based on the energy label of the house, thanks to government subsidies for higher energy efficiency. For example, if your maximum loan is €500K and the house has an A+ label, your loan could increase to €520K.

Mortgage Advisor

A mortgage advisor guides you through the entire process — preparing documents, applying for a loan, securing the bank guarantee, and more. Since all documents are in Dutch, they handle correspondence on your behalf.

Having a mortgage advisor in the Netherlands is essential.

Bank-Affiliated vs. Independent

• Bank-affiliated advisors work for a specific bank. They'll help you secure a mortgage from that bank only.
• Independent advisors aren't tied to any single bank. They can shop around for better rates and terms.

The fee is legally regulated and fixed at roughly €2,500–€3,000 regardless of which type you choose.

I went with an independent advisor — and it paid off. The first bank they applied to denied our loan citing a three-year residency requirement I hadn't heard of. My advisor immediately applied to another bank, which approved without issue. That flexibility is the real advantage.

Initial Consultation

Most advisors offer one or two free initial sessions to assess your situation before you sign a contract. After that, they'll request documents including:

1. Employer statement (contract type, income, holiday allowance)
2. Latest payslip
3. Passport and residence card
4. UWV report (obtainable via DigiD)
5. Declaration of debts and savings

Finding a House

The main platform is Funda — all properties eventually end up there. Buying here is fundamentally different from many other countries. Coming from Iran, I was used to visiting an agent, negotiating, and meeting somewhere in the middle. In the Netherlands, houses are publicly listed and go through a single-round sealed bid process. No back-and-forth negotiation.

Real Estate Agent (Makelaar)

A Makelaar accompanies you on viewings, inspects the property, and — crucially — determines the real market value of a house. This protects you from overbidding out of desperation.

A colleague was bidding on a house listed at €350K. His agent discovered a comparable property nearby had sold for €340K the month before. They underbid, and he bought it for €340K — below asking price.

Broker fees vary: some charge a fixed fee (~€4,000), others charge ~1% of the house price.

Should you hire one? If you're new to the Netherlands, don't speak Dutch fluently, and lack a local network — yes, seriously consider it. I've seen people spend months searching on their own without success. The agent's network and market knowledge can make the difference.

Finding a Broker

1. Personal recommendations — most reliable
2. Search on Funda — includes ratings and reviews

Broker contracts typically include 10–12 property visits. Beyond that, expect an extra €50–60 per visit.

Visiting a House

Before using one of your contracted broker visits, scout the area yourself first. Photos are staged to look their best — the neighborhood might not match your expectations. Save your visits for properties you're genuinely interested in.

On platforms like move.nl, you can request detailed property data: year of construction, materials, energy costs, heating systems, insulation, and more. Use this before committing to a viewing.

Bidding

Every house in the Netherlands must be publicly listed and sold through a single-round bid. When you visit, ask: "When is the bid day?" The agent will give you a deadline — e.g., "Monday at noon."

Your bid includes:

• Proposed price — what you're willing to pay
• Mortgage dependency — how much you're financing
• Personal savings — how much you're covering yourself

Example: "I want this house for €500K — €480K mortgage, €20K savings."

Listing Price vs. Actual Value

The listing price on Funda is typically set ~10% below actual market value to generate bidding competition. Don't treat it as the real price.

The home valuation price is what the bank's appraiser determines. The bank lends based on this number, not your bid. If you bid €480K but the bank values the house at €460K, they'll only lend €460K — the gap comes from your pocket.

Why Savings Matter

If you bid €480K relying entirely on a mortgage, and the bank only approves €470K, your bid looks risky to the seller. But if you have €15K in savings and bid €480K as €465K loan + €15K savings, the seller sees a more secure offer — even if the valuation comes in slightly lower than your bid.

If the valuation ends up higher than expected, you'll need less from savings. Small wins like this happen.

Bid Results

Results aren't communicated proactively — if you don't hear back, your bid wasn't selected. Once accepted, the house status on Funda changes to "Under offer."

After two consecutive rejections on different houses, our broker called with surprising news: we were second choice on both. The first bidders had their loans rejected, and the sellers turned to us. On the same day, we had offers accepted on two houses and got to choose which one we wanted. I think that's a Guinness record for the Netherlands. 😄

Technical Inspection

Optional, but recommended for older houses. A specialist inspects the property and provides a detailed report categorizing costs into:

1. Short-term — immediate fixes (e.g., €1,400 for specific repairs)
2. Mid-term — issues to address within a few years
3. Improvement — optional upgrades

Use short-term costs to negotiate a price reduction or ask the seller to fix issues before closing.

Check especially for: foundation condition, moisture under the floor, pests in wooden structures, sewer system integrity.

Cost: ~€500.

Pre-Sale Agreement

Once both parties agree, an electronic pre-sale agreement is signed by buyer, seller, and both brokers. The house status changes to "Sold under reservation." The sale is pending mortgage approval and deposit payment.

Notary

The notary (arranged by the seller's agent) handles the final paperwork. They'll request documents from both parties and set three key dates:

1. Withdrawal deadline — last date you can legally back out (e.g., if the loan is rejected)
2. Bank guarantee deadline
3. Notary date — when you sign in person, money is transferred, keys handed over

A translator in your native language is mandatory on notary day — the notary arranges this in advance.

Bank Guarantee

To reassure the seller you won't back out, you must deposit 10% of the purchase price with the notary — or provide a bank guarantee for the same amount.

If you don't have that liquidity (common), intermediary companies issue a bank guarantee for ~0.1% of the property price. For a €500K house, that's ~€500. Your mortgage advisor handles this.

Once the guarantee is in place, the sale is final. Neither party can back out.

Cost Summary

A Few Final Notes

You don't pay anyone anything until the notary date — except for the technical inspection and home valuation, which are paid immediately after the service. All other fees are settled at the end.

One useful tool: WOZ Waardeloket — enter any postal code to see the municipality's assessed value by year. It's a government site used for property tax estimates. Post-COVID price rises mean it often lags behind market reality, but it gives useful historical context.

Good luck. It's a process, but when you get those keys, it's worth it.