Five additions that improve maintainability and code quality

The goal was to improve maintainability and code quality across the repositories I ship. The two are not the same thing, and both matter. Maintainability is the cost of the next change: how long it takes an engineer to open the code, make a change, and move on. Code quality is whether that change did what they meant and nothing else moved. Low quality makes every change a risk. Low maintainability makes every change slow. In September 2026 I made five additions to every repository to improve both. This post is about what was added and what each addition does for each.

Why a score for the whole repository fails

The common approach is one number for the whole code base. Every file is graded, and the build goes red when the total is over a line. It sounds like discipline. In practice the number is driven by old files nobody is changing. To move it, an engineer opens a file the product does not need touched, rewrites it, and writes tests for the rewrite. The suite grows. The number moves. Maintainability did not improve, because the next real change was never in that file. Quality did not improve either, because a rewrite of working code is a new place for a defect. The team is working for the number.

The additions below take a different route to both. Each one grades the change in front of it. Code the change did not touch is left alone. Problems that already exist stay written down, and nobody is allowed to delete the list to make the build pass.

The five additions

Each addition is one check in the build, and each check is one question. A manager can ask it of any change and get a yes or a no.

1. Did this change add a new problem on the lines it touched?
Only the lines this change wrote are graded. A small edit in an old, tangled file passes if the edit itself is clean. A new problem on a changed line fails.
Maintainability: the code stops getting worse where people are working. Every change that lands is at least as clean as what it replaced, so the next change in that file is no harder than this one.
Quality: the problems this check catches are the ones that hide defects: a branch nobody can follow, a function doing four jobs, a value used before it is checked. Refusing them on the changed line keeps them out of the product.

2. Is this file both tangled and the one people keep editing?
A file is called out only when both are true. Hard to change, and changed often. Difficulty alone is not a project. A tangled file nobody opens costs nothing until somebody opens it.
Maintainability: cleanup goes to the file that is slowing down every edit. That is where a planned cleanup buys back the most time, and the rest of the debt is left where it is.
Quality: a file that is both tangled and edited often is where defects come from. Every edit to it is a chance to break something nobody can see. Cleaning that file, and only that file, removes the most defect risk for the least work.

3. Did this change break one rule the repository is not allowed to break?
Each repository names one rule that matters more than any style score, and tests it in the build. A post stays a draft unless publishing is turned on. A log must not contain a password. A fork must not grow a path back to the project it came from.
Maintainability: the rule holds without anyone having to remember it. A new engineer, or a busy one, cannot break it by accident, and nobody has to re-learn it by cleaning up after a mistake.
Quality: these are the defects that matter most and are found latest. A post that went live, a password in a log, a change sent to the wrong project. The check turns each one from an incident into a red build.

4. Did someone edit the written list of old problems so the build would pass?
Existing problems are recorded. A new one fails the build. The list may shrink when a problem is actually fixed. It may not shrink because the build was red.
Maintainability: the debt stays visible and readable, so decisions about it are made on facts rather than on a number someone adjusted.
Quality: a green build means the change was clean. It does not mean the list was trimmed. Without this check the other four can be switched off quietly, and the quality signal from the build is gone.

5. Do the tests for one chosen piece of the product still catch a mistake they used to catch?
The build breaks that piece on purpose and expects the tests to notice. If they do not, the build fails. Each repository checks one piece, because doing this to everything on every change costs more than it returns. A check that tests nothing fails.
Maintainability: an engineer can change that piece and trust the tests to catch what they broke. A suite nobody trusts makes every change slower, because the engineer has to check by hand what the tests should have checked.
Quality: a large test suite is not a safe one. Tests that pass no matter what the code does give a green build and no protection. This check is the only one of the five that measures whether the tests can find a defect at all.

How the additions compound

None of these is dramatic on its own. Together, over months, they bring the cost of the next change down and the defect rate down with it.

On maintainability: the parts of the product that get the most attention are also the parts the checks run on most often, so they get steadily easier to change. Old debt does not leak into new work, because the first check refuses it at the line. The second turns cleanup from a reaction to a score into a decision about a named file with a known cost.

On quality: the fifth check keeps the suite honest, so a green build carries information. The fourth keeps the record honest, so the trend is real. The third holds the rules that a busy team would otherwise re-learn by breaking them in production. Together they mean that when the build says a change is fine, it is fine, and when it says stop, there is a defect or a risk behind it.

What a manager should expect to see: fewer surprises in review, because the build already refused the change that made things worse; cleanup work that can be explained in one sentence, because a check named the file; and a build that is red for a reason someone can act on today, rather than for a number the team has learned to route around.

What this does not do: it does not pay down the existing debt on a schedule, and it does not promise the number goes to zero. The debt is written down and left alone until a change touches it or a hotspot earns a cleanup. That is on purpose. The alternative is a team working for the number.

What it costs

No new platform, no new licence, no new role. Each check uses the grading tool the language already has, running inside the build the repository already runs. The first four add minutes to a build. The fifth is the expensive one, which is why it is limited to one piece of the product per repository and not the whole thing.

There is a one-time cost when the checks arrive. The record of existing problems has to be written down once, and someone has to read the first hotspot list and decide which file, if any, earns a cleanup. After that, the cost is paid by the engineer whose change turned the build red, on that change, the same day. It does not become a backlog.

The cost that goes away is the one nobody was tracking: the hours spent on cleanup the product did not ask for, the tests written to cover that cleanup, and the review time spent on both.

How to tell it is working

A manager does not need to read the code to see whether this is holding. The signals are in the build and the review queue.

• The record of old problems only shrinks when a fix lands. If it drops without a corresponding change, someone edited it, and the fourth check should have failed. If it never drops, the hotspot list is not being acted on.
• Hotspot cleanups can be named. Each one points at a file that was both tangled and edited often. If cleanup work cannot be tied to a named file from the list, it is the old behaviour coming back.
• Red builds are fixed inside the change that caused them. Not as a follow-on ticket, not as a cleanup epic. If red builds are turning into tickets, the checks are grading the wrong thing.
• Review comments move from style to behaviour. The build has already said no to the change that made the code worse. Reviewers can spend their attention on whether the change does what it claims.
• Time from open to merge does not grow as the code base grows. That is the cost of the next change, measured directly. It is the number this whole thing exists to hold flat.

If the record shrinks honestly, cleanup has a name, red builds are fixed in place, and merge time holds, the checks are doing their job. If the team starts routing around a check, that is the signal to look at the check, not the team.

Where the checks run

The same five checks, in the form each language already supports, on every repository below. They sit on each repository's maintainability branch until that branch lands on the default branch.

• Python: documentation-generator, sdlc-spdd-orchestrator, slm-setup, memory-os, obsidian-mcp, Uberorchbot, uber-indicator, blog_updater, menkelabs/camera_recorder
• Kotlin and Java: jmjava/guide, orch-guide, skgraph, embabel-v1-learning, menkelabs/chatbot, cdk-cost-killer, menkelabs/open-commerce-platform
• Go: uber-lang-of-compute
• Shell: courseforge/infrastructure

One day with Obsidian MCP — coordinating my agents and experimenting with papers

Today my Obsidian vault was not just a notebook. It was the shared desk for a collection of Cursor agents working across my projects—and the filing system that finally made my paper work manageable.

I used obsidian-mcp throughout the day. Agents opened project context, selected bounded work, recorded decisions, updated status, and left session handoffs for the next agent. At the same time, research agents used the same vault to turn a loose experiment in documenting my projects as papers into seven organized manuscript tracks with evidence, references, metadata, and publication boundaries.

The result was not one giant chat. It was many focused sessions sharing durable Markdown.

The vault was the common layer

Each project has a small set of files that both I and the agents can read:

Project State.md          objective, current state, active work, next steps
Sessions/2026-09-11.md    what each agent changed and where it stopped
Decisions/2026-09-11-*.md why an engineering choice should survive the chat
TODO/*.md                 work that can be selected and tracked

Before substantial work, an agent calls get_project_context. That returns the current brief plus recent sessions and decisions. It does not require loading the whole vault or finding the right old chat.

After meaningful work, capture_work_session appends a summary with the repository, branch, commit, changed-file summary, decisions, and next steps. When an engineering choice needs to stick, record_decision gives it a separate note. When I need to understand why a boundary exists, search_memory finds the earlier reasoning.

The task tools make the vault operational. Agents can list_open_tasks, claim_task, complete_task, block_task, and unblock_task. A task moves through the workflow without reconstructing the entire Project State file. Ambiguous matches fail instead of moving the wrong item.

What the agents worked on today

The session notes show how broad the day was. Different agents worked on different repositories, but they used the same memory pattern.

• SDLC-SPDD orchestrator: agents tightened verification receipts, review scope, installer behavior, CI evidence, and quality-gate honesty. The vault preserved why a real validation receipt counts and why a skipped live graph cannot be reported as proof.
• Uberorchbot: agents added plugin and CI guardrails around the Obsidian work queue, skill catalogs, the archived control plane, and repository allowlists. The durable state kept the product on its Cursor plugin and Automations path instead of reviving an abandoned Spring control plane.
• obsidian-mcp: the memory system improved from its own usage. Agents hardened task claiming, queue synchronization, cross-source matching, read-path redaction, and CI. Problems discovered while coordinating agents became focused improvements to the coordinator.
• slm-setup: agents worked through local-model runtime safety, token-cap behavior, CI checks, official model tags, and harder evaluation jobs. Decisions recorded which conditions fail, warn, or require a live operator run.
• documentation-generator: agents closed gaps in visual-sync validation, timestamps, scene specs, audio and LFS checks, scene compilation, and composition. The notes kept each fail-closed change separate instead of turning the work into one unbounded repair session.
• memory-os and embabel-v1-learning: agents strengthened evaluation, timeline handling, dependency-pin checks, Pages validation, and publishing safeguards without rebuilding media that was outside the task.
• chatbot: agents worked on structural citation checks, channel CI, GraphRAG testing, opt-in smoke assertions, and the boundary with the commerce product.
• open-commerce-platform: agents recorded checkout, reservation, payment reconciliation, runtime topology, ratings-goal, and playbook-rematching decisions so later sessions do not re-argue the same product contracts.
• cdk-cost-killer: agents kept infrastructure cleanup safe by preserving dry-run defaults, skipped bootstrap resources, stack-name boundaries, and the rule that CI never performs a live apply.
• Guide-related work: agents preserved fork-local rules, pin and tag discipline, and CI checks without turning the work into an upstream contribution path.
• Fleet review: the vault recorded the selected inspection tools and their roles instead of leaving that choice buried in an evaluation chat.

This is what using Obsidian MCP across agents looked like in practice: retrieve a narrow brief, do one bounded piece of work, record the durable choice, and leave the repository in a state the next session can understand.

Then there was the paper work

The paper organization was not a side note. It was one of the largest uses of the vault today.

I had a broad set of repositories that might become technical papers. Without a durable structure, every research session could generate another outline, another reference list, or another publication idea without agreeing on what the actual papers were.

The vault turned that into an organized documentation experiment. I am exploring whether a paper-style structure can explain the purpose, design, evidence, and limitations of my work more rigorously than ordinary project notes. I am not claiming that these are finished academic papers or committing to publish them.

The experiment currently has seven applicable tracks: P01–P05, P07, and P08. They cover the SDLC-SPDD orchestrator, Uberorchbot, the local coding SLM, memoryOS, documentation-generator, open-commerce-platform, and chatbot.

Eight other candidates—P06 and P09–P15—were explicitly removed because they were not appropriate paper projects. That decision is as important as creating the seven remaining tracks. It prevents a future agent from seeing an old idea and rebuilding an inapplicable manuscript pack.

Each active paper track now has a repeatable set of artifacts:

• a repository purpose and architecture baseline taken from committed code;
• an outline and working manuscript draft;
• an evidence pack tied to exact repository snapshots;
• a prior-art review and structured bibliography;
• results and claim-support records;
• normalized metadata;
• a deposit sheet that remains preparation, not permission to publish.

Shared research tasks handled the administrative questions once for all seven tracks: the intersection of Zenodo and TechRxiv rules, manuscript scope, PDF format, metadata fields, DOI ordering, AI disclosure, authorship, and the boundary between a software record and a preprint.

One normalized manuscript guide now says that the abstract must agree everywhere—the draft, metadata, and deposit sheet. A shared YAML schema maps fields to both venues. References use stable IDs before print numbers are assigned. Research notes distinguish official sources from open questions.

This is documentation research, not a publication commitment. The agents organize evidence and draft paper-style artifacts. Creator identity, ORCID, technical claim approval, final prose review, PDF approval, DOI creation, and any deposit remain human-controlled. Today’s work was an experiment in documenting the projects; it was not an automated submission run.

That distinction would be easy to lose in chat. In the vault it is part of the project state and decision history. Every agent sees the same boundary.

How this helped me use my plan

Organizing the work also helped me use the model capacity already included in my Cursor plan. Instead of leaving quota unused because I could not keep enough work straight, I had a queue of legitimate, scoped tasks that different agents could execute.

Standard and Auto capacity could take bounded documentation, testing, and guardrail work. Premium capacity could take harder implementation, architecture, review, and research synthesis. The vault made it possible to keep those sessions moving and use the plan productively without relying on one chat to remember the entire lab.

Obsidian also kept the token burn from becoming busywork. If a task was inapplicable, I removed it. If a decision required a human, the agent stopped at the boundary. If the queue was empty, the correct action was to stop—not invent another project merely to consume quota.

What changed for me

Before this workflow, chats were where work happened and where context disappeared. Today, chats were workers. The vault was the durable system.

I could move between software hardening, agent tooling, local models, commerce, documentation video, infrastructure safety, and research because every project had a current brief and every meaningful session left a handoff. I could also open Obsidian and see the paper experiment as a set of linked documentation artifacts instead of a pile of manuscript ideas.

That is the practical value of Obsidian MCP for me: it helped many agents work as part of one day, helped me use the AI capacity I was already paying for, and organized both engineering work and literal paper work in files I can still read after every chat is gone.

Source: github.com/jmjava/obsidian-mcp
Related: Uberorchbot · SDLC-SPDD orchestrator · local coding SLM setup

Same MCP, next host — Halo on the slm-setup roadmap

The GPU can move. The bridge should not. The first slm-setup post described a split: a premium cloud model plans and reviews, while a small language model (SLM) on private hardware handles bounded generation through MCP tools. The private model runs under Ollama, an open-source server for running language models locally. “Halo” here means a PC built around AMD’s Strix Halo design, which can share up to 128GB of unified memory between the CPU and integrated graphics. The question is whether that memory makes Halo a worthwhile later Ollama host — not whether to build a second coding system.

Two C4 diagrams make the roadmap concrete. The context view shows who talks to what; the deployment view shows which machine runs each part. The software boundary stays fixed while the machine hosting Ollama changes.

What stays fixed

Context. The private lab uses a premium model for planning while Ollama remains private. Cloud-hosted agents are outside this home-lab design.

Cursor, Copilot, or Claude remains the planner. The private model is exposed through MCP, the Model Context Protocol: an open standard that lets the desktop IDE call a local program through named tools. Default vendor-hosted agents run away from the workstation ^{[16] [17] [18]}; enterprise private-connectivity and self-hosted configurations are possible, but they are separate designs. This home-lab bridge runs on the workstation, where it can reach private hardware without making Ollama public.

Local inference is not an air gap. The premium agent can access workspace files and receives the tool results through the vendor’s service. Halo does not hide that selected context from the planner; it keeps the delegated model generation on private hardware.

The workstation keeps the same stdio MCP server, the same six bounded coding tools, and the same environment settings. Stdio means the IDE launches the server and communicates through standard input and output rather than an MCP network port. The server reads the Ollama address from the environment, commonly through a gitignored .env file. Moving Ollama does not change what the IDE calls.

Deployment — one active host

Variants. Only one host is active. Prefer SSH to that host’s localhost. A private-interface bind is optional. A public bind is not.

The inference host is simply the machine running Ollama. The roadmap changes that host in three controlled stages:

1. Now: Ollama runs on the workstation, and the desktop-to-Ollama path is operational ^[13].
2. Next: Ollama moves to a second private GPU host. SSH local forwarding — an encrypted connection that makes the remote service appear local — keeps Ollama bound to that host’s loopback address, which accepts connections only from the host itself. A robust example is ssh -N -T -o ExitOnForwardFailure=yes -L 127.0.0.1:11436:127.0.0.1:11434 user@<inference-host>; MCP then uses http://127.0.0.1:11436.
3. Later: Halo takes the same host slot. Its AMD software backend still needs validation on the actual machine before any performance claim.

The security rule is unchanged: do not make Ollama internet-reachable. A 293-day SentinelLABS–Censys scan measured 175,108 internet-reachable Ollama hosts across 130 countries ^[5]; LeakIX separately documented 12,269 unauthenticated instances in its February 2026 dataset ^[6].

Current test status

Thirty-six mocked unit tests currently pass. Automated live integration checks also reach a real loopback-only Ollama through the stdio MCP server. A separate manual Cursor check invoked the MCP tools and executed the strong model’s returned test file successfully ^[13]. This validates the same-machine integration, not a complete IDE file-application workflow, the planned SSH deployment, broad model reliability, or Halo performance.

What a Halo box costs

The top-end chip considered here is AMD’s Ryzen AI Max+ 395: sixteen CPU cores, Radeon 8060S integrated graphics, and up to 128GB of soldered LPDDR5X unified memory. Framework says as much as 96GB can be graphics-addressable on its 128GB build ^[1]. That is memory capacity for quantized model weights larger than 16GB — not proof that a particular model, Ollama release, or AMD backend will run well.

Observed September 6, 2026 listings put 128GB systems between $3,449 and $4,349: Framework at $3,449, GMKtec at $3,649.99, and Beelink at $4,349 ^{[1] [2] [3]}. Published comparisons place earlier launch-era systems near $2,000 and attribute much of the later increase to soldered-memory pricing ^[3] [4]. Because that memory cannot be upgraded, capacity is a purchase-time decision. These figures are a dated snapshot, not a quotation.

What would justify buying it

Memory headroom matters only if larger models produce more complete and correct work on representative bounded tasks. Aider’s independent benchmark illustrates the risk: when models extract large methods from real Python projects, completion rates vary sharply and weaker models often skip code ^[7]. That benchmark covers hosted models, not this Halo proposal, so it supplies a useful test shape rather than a result.

Qwen’s vendor-authored report gives a second reason to compare sizes: within the Qwen2.5-Coder family, its 32-billion-parameter model scores above the 7-billion-parameter version on the published coding benchmarks ^[8]. Ollama lists the quantized 32B download at 20GB ^[11], already larger than a 16GB GPU before runtime overhead. Halo has room to evaluate it, but memory fit does not prove a quality gain.

Quality also has to fit the time budget. A direct community benchmark reports 4.7–4.9 output tokens per second for Llama 3.1 70B at 4-bit quantization on Strix Halo ^[9]. At five tokens per second, a 1,000-token answer takes about 200 seconds before prompt processing. That approaches the bridge’s current 300-second strong-model timeout ^[14], so a dense 70B model is practical only for bounded synchronous outputs unless the request contract changes. Backend and long-context results also vary materially ^[10] [12]. Replacing Ollama may require a client change unless the replacement preserves Ollama’s HTTP API.

The purchase criterion is therefore simple: benchmark named models, quantizations, context sizes, and backends on representative work; buy the memory headroom only if the quality gain is worth both the price and the wait. If the current models are already reliable enough, keep the money.

What is in the repo

The public repo provides the runnable MCP server, SSH-first deployment guidance, and dated operational and security evidence ^[13] [15]. Start with the working same-machine profile. Move to a private host only when that need is real, and consider Halo only after representative work shows that larger models would earn their additional cost. Keep machine-specific values out of git and review every local-model result before applying it.

References

1. Framework — Framework Desktop with AMD Ryzen AI Max: Max+ 395 specs (16 cores, Radeon 8060S, LPDDR5X-8000), “up to 96GB of graphics addressable memory,” 128GB configuration at $3,449, sold as pre-order.
2. Micro Center — GMKtec EVO-X2 listing: Ryzen AI Max+ 395, 128GB LPDDR5X-8000, 2TB SSD, $3,649.99.
3. ComputingForGeeks — Ryzen AI Max+ 395 mini PCs compared (Aug 2026): side-by-side of Framework ($3,449), GMKtec ($3,649.99), Beelink GTR9 Pro ($4,349); documents the June-to-August price doubling and attributes it to DRAM contract pricing on soldered LPDDR5X.
4. Liliputing — 128GB Ryzen AI Max+ 395 mini PCs roundup: earlier-2026 price baseline across nine vendors and the note that most of the 128GB can be used as VRAM.
5. SentinelLABS + Censys — Silent Brothers (Jan 2026): joint 293-day internet scan measuring 175,108 unique exposed Ollama hosts across 130 countries (7.23M observations); 48% advertised tool-calling capability.
6. LeakIX — 12,000 Ollama instances exposed (Feb 2026): 12,269 unauthenticated public instances, ~1,000 vulnerable to CVE-2024-37032, an unauthenticated remote-code-execution chain.
7. Aider — Refactoring leaderboard and the benchmark design: 89 large-method extractions from real Python repositories, verified by parsing the output, built to provoke and quantify models eliding code on long outputs. Scores on the published board run from 92.1% at the top down to roughly 21% for the weakest listed configuration.
8. Qwen team — Qwen2.5-Coder family report: six sizes trained identically to “verify the effectiveness of scaling”; 32B-Instruct outperforms 7B across the published code benchmarks (92.7 vs 88.4 on HumanEval) and scores 73.7 on Aider code repair, “performing comparably to GPT-4o.”
9. ignasivt — Strix Halo Guide: community measurements for Llama 3.1 70B Q4_K_M report 4.7–4.9 output tokens per second across short prompt lengths on a Ryzen AI Max+ 395. This is a direct practitioner benchmark, not vendor certification.
10. Strix Halo Wiki — llama.cpp performance: links reproducible backend comparisons and shows that prompt processing, token generation, driver choice, and long-context behavior can differ materially.
11. Ollama — qwen2.5-coder library page: the 32b tag is a 20GB download in the default quantization.
12. Digital Architects — Ryzen AI Max+ 395 local-LLM field notes: a practitioner report describing material stability and performance differences among Vulkan, ROCm, llama.cpp, and Ollama on Strix Halo. These observations motivate validation on the actual machine.
13. slm-setup — Local acceptance results — 2026-09-06: reproducible commands, unit results, live same-machine MCP-to-Ollama checks, direct Cursor invocation, retries, and stated limitations.
14. slm-setup — Ollama client implementation: current synchronous request behavior, 300-second strong-model timeout, and 4,096-token output cap.
15. slm-setup — Repository security scan — 2026-09-06: refreshed Gitleaks history and committed-tree results at repository commit 277f6bd, GitHub secret-scanning alert state, deployment-safety checks, exact counts, and stated limitations.
16. Cursor Docs — Cloud Agent security: each Cursor Cloud Agent runs in an isolated cloud virtual machine rather than on the developer’s laptop.
17. GitHub Docs — About Copilot cloud agent: the hosted agent runs in an ephemeral GitHub Actions environment, while IDE agent mode edits in the local development environment.
18. Anthropic Docs — Claude Code on the web: Anthropic-hosted sessions run in isolated Anthropic-managed virtual machines; organizations can also configure self-hosted cloud environments.

Web references and prices were checked on September 6, 2026. Retail prices and practitioner performance reports are time-sensitive.

Source: github.com/jmjava/slm-setup — spec.md, docs/c4.md, docs/roadmap.md
git clone https://github.com/jmjava/slm-setup.git

Local coding SLM — premium agents, private GPU, one MCP bridge

I still want the expensive model in the chair. I do not want it typing a hundred pytest functions. That work is often bounded and cheap to reject if it is wrong, making it a useful candidate for a small language model (SLM) running on my own hardware. The trick is getting Cursor, Copilot, or Claude to use that model without publishing its Ollama endpoint to the internet.

slm-setup is the setup I am using for that split. The premium agent stays the planner and the reviewer. A local process on the workstation talks to Ollama — an open-source server that runs language models on your own hardware. The local model never becomes “the model in the picker” — the IDE dropdown where you choose GPT or Claude as your chat model. It is a handful of tools the premium agent calls.

The thing that does not work

Cursor can override an OpenAI-compatible base URL, but those requests are assembled on Cursor’s servers. A workstation localhost or home-LAN Ollama URL is therefore outside the default request path; Cursor staff recommend a publicly reachable HTTPS endpoint for that configuration ^{[1] [2] [3]}. I do not want to expose Ollama publicly. The override is also shared by the OpenAI-model slot rather than configured per model, so it conflicts with keeping premium OpenAI-family models available for planning ^[4].

The same boundary applies to default vendor-hosted coding agents: Copilot’s cloud agent runs in GitHub Actions, while Anthropic-hosted Claude Code sessions run in Anthropic-managed virtual machines ^{[5] [7] [8]}. Enterprise self-hosted runners and organization-managed Claude environments are exceptions ^[6] [7], but they are separate designs. This home-lab bridge targets the machine in front of you: desktop Cursor, Copilot agent mode in the IDE, and local Claude Code.

A process on the workstation can reach a private GPU. The default vendor-hosted path does not share that network. That is the whole reason this is MCP — the Model Context Protocol, an open standard that lets a desktop IDE agent launch a local program and call it as a set of named tools — and not a model-provider hack.

Who does what

If the shape of the answer is obvious — tests, a rename, a bounded refactor, a summary, a first-pass review — I ask the local tools. If the problem is architectural, cross-system, or security-sensitive, I keep it on the premium model. If the local answer is thin or wrong, the premium model edits it. I expect to spend some premium tokens deciding and reviewing. I am trying not to spend them emitting the artifact.

you + premium agent
        │  plan, pick files, review
        ▼
local-coding-slm  (stdio, on the workstation)
        │  HTTP to localhost or an SSH local forward
        ▼
Ollama
   fast model              stronger model
 (everyday coding)      (harder local work)

The IDE and the MCP server live on the workstation. Ollama can run on that same machine or, after the planned two-machine test, on a second private host reached through SSH local forwarding — an encrypted connection that makes the remote Ollama service appear local. Machine-specific connection details never go in git.

What the local model is for

One server name: local-coding-slm. The MCP process does not run shell commands, write files, or open a network listener; it makes outbound HTTP calls to the configured Ollama API. It returns text — code, a diff, or markdown — and I decide whether to apply it. I send a few files, not the whole repository.

The tools have deliberately narrow responsibilities: write code, refactor, generate tests, explain, review, and check that Ollama is up. Each one has a short fixed system prompt. The test tool is told to write tests only. If the request is ambiguous, it should ask instead of inventing production changes.

The starter pair is a fast everyday model (qwen3.5:9b) and a stronger coding model (devstral-small-2). Use fast by default and escalate only when its answer is not good enough. The documented starting configuration uses 16K context — a working window of roughly 16,000 tokens; the stronger model may split work between CPU and GPU when GPU memory is tight ^[12]. Increase context only after measuring memory use on your own hardware.

What is tested now

Thirty-six mocked unit tests currently pass. Automated live integration checks also reach a real loopback-only Ollama — bound to 127.0.0.1 for access from this machine only — through the stdio MCP server. In a separate manual Cursor check, Cursor invoked the MCP tools and the returned strong-model test file passed both tests when executed ^[12]. This validates the current same-machine integration, not a complete IDE file-application workflow or broad model reliability.

What is in the repo

The public repo is the spec plus a running server, not a sketch. The server talks to the IDE over stdio — standard input and output, so it opens no network port of its own — and the same-machine path has been exercised against a real local Ollama runtime ^[12]. You also get a wrapper that starts the server, reads settings from the environment (commonly loaded from a gitignored .env), and templates for Cursor, VS Code Copilot, and Claude Code. Machine-specific values are never committed.

Treat local output as untrusted. Apply it, trim it, or throw it away. The premium agent can access workspace files and sends selected context through the vendor’s service; the SLM sees only the snippets passed in the tool call. There is no automatic classifier deciding which model to call. The project instructions keep the rule explicit: bounded mechanical work can go to the local tools; ambiguous, architectural, or security-sensitive work stays with the premium model.

Do not expose Ollama publicly. No ngrok, Cloudflare Tunnel, or router port-forward that makes the API internet-reachable. Ollama binds to localhost by default, and its local API requires no authentication ^[9]. A 293-day SentinelLABS–Censys joint scan measured 175,108 unique internet-reachable Ollama hosts across 130 countries ^[10], and LeakIX found roughly a thousand of the instances it counted still vulnerable to a known unauthenticated remote-code-execution chain ^[11]. For a second host, keep remote Ollama on 127.0.0.1:11434 and create a workstation-only forward: ssh -N -T -o ExitOnForwardFailure=yes -L 127.0.0.1:11436:127.0.0.1:11434 user@<inference-host>. Then point MCP at http://127.0.0.1:11436. A private-interface bind is only a firewall-restricted fallback. The current dated repository scan found no detected leaks or GitHub secret-scanning alerts, while noting that a clean scan is not proof of absence ^[13].

If you already pay for a premium coding agent and have a private GPU, this is the shape to start from. Clone the repo, set OLLAMA_BASE_URL in the gitignored .env file, and measure whether the small model is good enough for the bounded work you actually do.

The host side of this has a roadmap now: an AMD Halo-class box as a later private Ollama host, with the C4 views that show what changes and what does not. That is the follow-up post, Same MCP, next host — Halo on the slm-setup roadmap.

References

1. Cursor Docs — Custom API keys: “Your API key … is sent to our backend with every request because all requests are routed through Cursor’s servers for final prompt building.” Also notes custom keys apply to chat models only; Tab completion stays on Cursor’s models.
2. Cursor Forum (staff reply, Feb 2026) — Connecting local AI server to Cursor does not work: “All BYOK requests go through Cursor’s servers to build prompts, so localhost or local network addresses won’t work because the server can’t reach them. You’ll need to expose your Ollama instance as a public HTTPS endpoint using something like ngrok or Cloudflare Tunnel.”
3. Cursor Forum (staff reply, Mar 2026) — How to use Cursor directly with only my model API?: “There is currently no option to have Cursor communicate directly with your own server without going through Cursor’s backend.” See also staff confirmation that a full bypass is an architectural limitation: “Prompt building, context retrieval, and Cursor Tab and Agent run on our side.”
4. Cursor Forum (staff reply) — routing explanation: with a custom key plus override, “requests for OpenAI-family models (anything that’s not claude-* and not gemini-*) go to your custom endpoint”; the base URL is a single global setting, not per-model.
5. GitHub Docs — About Copilot cloud agent: the coding agent “has access to its own ephemeral development environment, powered by GitHub Actions,” and is “distinct from the ‘agent mode’ feature available in your IDE,” which “makes autonomous edits directly in your local development environment.”
6. GitHub Docs — Customize the agent environment: self-hosted runners can give Copilot access to internal network resources. This is an enterprise exception to GitHub’s default hosted environment. See also the agent firewall documentation: the cloud agent’s internet access is restricted inside the GitHub Actions environment.
7. Anthropic — Claude Code on the web: Anthropic-hosted sessions run in isolated Anthropic-managed VMs; organizations can also configure self-hosted cloud environments.
8. Anthropic — Configure cloud environments: all outbound traffic from cloud sessions passes through Anthropic’s network proxy with allowlist levels (None / Trusted / Custom / Full).
9. Ollama — FAQ and API authentication: Ollama binds to 127.0.0.1:11434 by default, and no authentication is required for its local API.
10. SentinelLABS + Censys — Silent Brothers (Jan 2026): joint 293-day internet scan; 175,108 unique exposed Ollama hosts across 130 countries, 7.23M observations, 48% advertising tool-calling. Censys’s earlier single-day snapshot (Ollama Drama) found 10.6K instances, 1.5K directly promptable.
11. LeakIX — 12,000 Ollama instances exposed (Feb 2026): 12,269 unauthenticated instances, roughly 1,000 running versions vulnerable to CVE-2024-37032 (“Probllama”), an unauthenticated path-traversal-to-RCE chain.
12. slm-setup — Local acceptance results — 2026-09-06: reproducible commands, hardware details, unit results, live same-machine MCP-to-Ollama checks, and a direct Cursor invocation with executed generated tests.
13. slm-setup — Repository security scan — 2026-09-06: the refreshed Gitleaks scan covered repository commit 277f6bd and requested all refs; GitHub returned no secret-scanning alerts; committed-tree and loopback deployment checks passed. The report gives exact scan counts and limits.

Web references were checked on September 6, 2026.

Source: github.com/jmjava/slm-setup — start with spec.md
git clone https://github.com/jmjava/slm-setup.git

Cursor sessions that survive the chat — tracking work with Obsidian MCP

A Cursor chat is a terrible filing cabinet. It is excellent while it is open. It is gone when you start the next one — or when a Cloud Agent finishes a wave on a different machine. I wanted session memory I can open next week: what we did, which commit we left on, what we decided, and what is still open. That is what obsidian-mcp writes.

The bet: session notes should be files, not a vendor memory API.

The server is local MCP over stdio. Cursor (or Copilot) calls tools. The tools read and write ordinary Markdown in an Obsidian vault. Obsidian does not need to be running. There is no community plugin and no hosted memory database. If I can open the file in a text editor, the memory is real.

What I actually keep

Each project gets one folder under AI Memory/Projects/<slug>/:

Project State.md          # current objective, in-progress, next steps
Sessions/YYYY-MM-DD.md    # timestamped sections for that day
Decisions/YYYY-MM-DD-*.md # one file per durable choice

Project State is the hot brief — what this repo is for right now. It is replaced when status changes. It is not a diary.

Sessions are the diary. capture_work_session appends a timestamped section to today. If I pass the repo path, the note records branch, short SHA, dirty flag, and a short file list. Full diffs never go in. I do not want a second copy of git.

Decisions are the “why.” Architecture choices that the next agent should not re-litigate. Same slug on the same day gets -2, never an overwrite.

This morning’s vault looks like this — a real session note for embabel-v1-learning, not a mock:

Obsidian on the same files the MCP server wrote: summary, git SHA deadd6b, PRs #2–#10, the 1.0+1.5 branch decision.

The sidebar is the map: blog-updater, cdk-cost-killer, embabel-v1-learning, obsidian-mcp, and the rest of the lab. I do not keep one giant note. I keep one project folder and let the dated session files accumulate. When I open Cursor on that repo tomorrow, the first useful call is not “read the whole vault.” It is get_project_context for that slug — Project State plus the newest sessions and decisions.

The loop I run in Cursor

Cursor (or Copilot) talks MCP stdio. The vault is the source of truth.

1. Before substantial work — get_project_context. Continuing a feature, debugging a known area, or answering “why is it like this?” Empty sections if the project is new. Never the entire vault.
2. After meaningful work — capture_work_session with a short summary, changes, decisions, and next steps. Pass repository_path so the git snapshot lands in the same note.
3. When a choice should stick — record_decision. Example from that screenshot: keep Embabel 1.0 and 1.5 on one main; study from the cheat sheet, not a second cookbook.
4. When overall status moves — update_project_state. Concise. Current tense.

Lookup is local: search_memory over that project’s files, read_note for one vault-relative path, append_daily_note for a line that belongs on today’s Daily/YYYY-MM-DD.md instead of a project folder.

Retrieve → implement → capture → update state. Skip the capture when the change was a typo.

What is not persisted

The Cursor rule that ships with the installer is the product as much as the tools. Typo fixes, formatting-only edits, and one-line mechanical changes are not memory. If every keystroke becomes a session section, I will stop reading the vault — and so will the next agent.

Secrets never land in the vault on purpose. Values that look like keys, tokens, JWTs, or password= assignments are replaced with [redacted-secret] before write. I also never persist .env contents, database credentials, or customer data. Summarize the incident; do not paste the token.

Paths are confined to OBSIDIAN_VAULT_PATH. Absolute note paths, ../ traversal, and symlink escapes are rejected. This is not a general filesystem API. Writes are atomic.

Wire it once

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"
uv sync

./scripts/install-project.sh \
  --project /path/to/your-app \
  --vault "$OBSIDIAN_VAULT_PATH"

The installer merges .cursor/mcp.json (it does not wipe unrelated servers) and drops the Cursor rule plus Copilot instructions so both assistants use the same habits. Point the env var at a real vault directory. The server does not auto-load .env files.

I already have a product-shaped write-up of the seven tools. This post is the part I needed after the first week of using it: the vault is how I keep Cursor sessions and ongoing work in one place I can see. Open Obsidian when you want the graph. Leave it closed when you just need the assistant to remember the last SHA.

Source: github.com/jmjava/obsidian-mcp

The DIF test engine — prove the three layers without collapsing them

A plan that cannot fail in an interesting way is just more markdown. The last post said DIF, the orchestrator, and Embabel answer different questions. This post is the test engine that keeps them from collapsing into one runtime.

Follow-up to Three layers, one day. Source: the working test flow in jmjava/embabel-dif and the integration ladder in docs/ORCH_INTEGRATION_ROADMAP.md.

What “test engine” means here

Not a new product. Not a second daily driver. A stacked set of checks where each rung is allowed to fail before we spend complexity on the next:

./mvnw test                 # unit + CLI + FoldContractTest
                            # EmbabelLivePlatformTest skipped unless DIF_LIVE_EMBABEL=1
./scripts/dif-orch-smoke.sh # FEAT-001 ready + T03; FEAT-099 exit 1
./scripts/dif-orch-day.sh   # fold twice / architect / review / plan --projection
                            # skip when CLI or snapshots missing
./scripts/dif-live-e2e.sh   # orch Guide+Neo4j + JSONL quote + live GOAP

Default CI is the first two boxes. Live Guide and Embabel are opt-in. They reuse the orchestrator’s existing tests/test-guide-stack-live.sh. They do not put Embabel or Guide inside sdlc.sh next.

The engine’s job. Prove the three systems can talk. Prove a missing DIF checkout is skip, not a broken day. Prove a contradictory canvas cannot earn Ready For Coding. Never start a JVM to run next.

Rung A — five named checks, not prose

FoldContractTest is step 1 of the fold iteration plan. The five success criteria are tests:

Check	What fails if we are wrong
Same accepted canvas → same model	Nothing downstream is trustworthy
Review fails without “looks correct”	login-auth-broken still prints RESULT: PASS
Syntax variance does not flip invariants	A DTO rename (FEAT-070) changes what must stay true
Open T## is a MissingObligation	T03 on FEAT-001 disappears into a checklist
Requirement vs non-goal blocks Ready For Coding	FEAT-099 pagination clash still looks green

Harvested canvases under examples/canvases/ are the corpus. The fold learns from real REASONS files, not imagined IR. Adding a backend must not change the CLI or the canvas schema.

Rungs C–D — a script can trust the gate

dif-fold.sh writes a projection and a stable .gate.json. Smoke does not parse stdout for meaning. It reads JSON and exit codes:

{
  "workId": "FEAT-001-order-status-api",
  "readyForImplementation": true,
  "blockingConflicts": [],
  "missingObligations": ["T03"]
}

dif-orch-smoke.sh folds FEAT-001 (exit 0, ready, T03 missing) and FEAT-099 (exit 1, blocking pagination clash). If a sibling orch checkout is present, it folds the live examples/spring-boot-order-api canvas too. Then it hits the silent attach:

DIF_DISABLED=1 check-canvas.sh …   →  dif=skipped   (exit 0)
check-canvas.sh FEAT-001           →  dif=ready     (exit 0)
check-canvas.sh FEAT-099           →  dif=blocked   (exit 1)

One line. Agents do not get a fold dump. Missing DIF is skip, not a new ritual. That is the same opt-in shape as Guide.

Rung G — a scripted day, no Embabel

dif-orch-day.sh is the cheap “full day.” It does not start Embabel, Guide MCP, or replace sdlc.sh next.

1. Fold the same FEAT-001 canvas twice. The two .gate.json files must cmp equal.
2. Architect FEAT-001 → dif=ready, T03 still a missing obligation.
3. Architect FEAT-099 → exit 1, dif=blocked.
4. Review the orch order-status snapshots: dropping auth fails. A DTO rename still passes.
5. plan --projection builds a VerificationPlan from the folded model. No markdown re-parse.
6. Guide JSONL is an optional quote (Decision / Pitfall), not a gate.
7. Missing CLI or missing snapshots → dif=skipped. Present snapshots that drop a safeguard → dif=blocked.

Review uses examples/snapshots/order-status-*.json and the canvas safeguard paths — not the old login fixtures. Syntax-ok vs auth-broken is the whole point: a rename is legal; a dropped safeguard is not.

Rungs H–J — live, still not inside next

dif-live-e2e.sh is the three-way path that already passed here. First it asserts sdlc-engine is not a JVM — help must not mention Spring or Embabel. Then it reuses the orch Guide+Neo4j harness, runs the scripted day, quotes DIF JSONL through GuideClient under a unique Work ID (FEAT-DIF-LIVE-… so it does not collide with orch’s already-projected FEAT-001), and boots the Embabel Spring platform.

Live Embabel (EmbabelLivePlatformTest, DIF_LIVE_EMBABEL=1) runs the fixture GOAP path:

UserInput
  → captureRequest → interpretIntent → foldIntent
  → analyzeRepository → planVerification
  → VerificationPlan (readyForImplementation, missing rotation IT)

The refresh-token wording uses FixtureIntentInterpreter — no LLM. A second test plans an already-folded orch canvas without re-parsing markdown. Conflicts stay on the VerificationPlan (readyForImplementation=false). They are not a GOAP precondition Embabel 1.5 cannot treat as an action post.

Orch CI does not need Maven. It uses tests/fixtures/dif-fold-stub.sh so detect-and-skip / fail-closed can be proven with a fake CLI: skipped, ready, or blocked.

What would fail the engine

The ladder is the falsification list from the last post, turned into commands:

• Two folds of the same canvas disagree → day step 1 fails.
• A requirement vs non-goal pair still looks ready → smoke / architect on FEAT-099 fails.
• An open T03 does not show up → gate assertion fails.
• A DTO rename flips an invariant → SyntaxVarianceTest / review syntax-ok fails.
• Review cannot fail a dropped safeguard without “looks correct” → auth-broken still passes.
• sdlc-engine --help mentions Embabel → live E2E step 0 fails.
• Missing DIF breaks the orch day → skip tests fail.

If people stop reading the canvas because they treat the JSON as source of truth, we failed even if every script is green. The projection stays regenerable and disposable.

Source: github.com/jmjava/embabel-dif
Previous: Three layers, one day — DIF, the orchestrator, and Embabel
Related: sdlc-spdd-orchestrator · Embabel

Three layers, one day — DIF, the orchestrator, and Embabel

Reliable AI engineering does not require every component to be deterministic. It requires determinism at the boundaries where repeatability, traceability, and correctness matter. That is the sentence embabel-dif is testing — not a Merly reimplementation, and not a second daily driver.

Use stochastic reasoning to discover knowledge. Use deterministic representations to operationalize it once it is understood.

The hole the runbook cannot close

Coding agents are good at reading a repository and sounding like they understand it. The understanding is usually implicit and disposable:

prompt + files + luck  →  a one-off theory of the system  →  a patch

The next session starts from zero. It may decide that sessionToken was incidental, that Google login can move, or that an existing test is optional. Nothing in the process remembers which of those beliefs were load-bearing.

sdlc-spdd-orchestrator already attacks the process half: one Work ID, one REASONS Canvas, one phase at a time. Assistants are not allowed to invent a parallel workflow. That is necessary and not sufficient. The canvas is still prose. Architect, review, and sync still ask an LLM to compare the canvas to a diff. Comparison is where implicit intent creeps back in.

Process gates ask “do the prerequisite files exist?” They do not ask “did this canvas contradict itself?” or “did this diff drop a safeguard?”

The remaining hole is checkability. You can follow the runbook perfectly and still ship a contradictory canvas, mark Ready For Coding in prose, or pass review because the change “looks right.”

Three questions, three systems

Planning / requirements     why are we doing this?
REASONS Canvas              what must ship (human contract)
DIF SemanticModel           what must remain true (machine contract)
Embabel GOAP                what action to take on typed facts (optional)
DICE / Guide graph          what did we learn before (retrieval)
SDLC phases                 who is allowed to act

Layer	Owns this question	Must not own
Orchestrator	Who acts when? One Work ID, one canvas, one phase.	Folding facts. Starting a JVM. Being a planner.
DIF	What must stay true? Same accepted canvas → same model. Conflicts fail closed.	Daily orientation. Picking the Work ID. Replacing the canvas.
Embabel	What action to take on already folded facts (optional JVM path).	The fold itself. sdlc.sh next. The human contract.

Git stores what changed. A DIF-style layer stores why it had to, and what must still be true. Embabel, when present, decides what to do next. The orchestrator decides who is allowed to act.

They stay three repos on purpose. Merging Embabel or DIF into the orchestrator would fight its design: it is an installable operating model, not a compiled agent runtime. The contract between them is a file:

spdd/canvas/<WORK-ID>.md            human source of truth
        │
        ▼  fold (deterministic after accept)
.dif/projections/<WORK-ID>.json     machine projection (disposable)
.dif/projections/<WORK-ID>.gate.json
        │
        └─ orch may read the exit code
           it does not start the JVM to run next

A canvas is already a candidate intent. We do not need a new human artifact. We need a projection.

DICE is not DIF

The orchestrator already has Guide DICE as an optional working store. The acronyms smash together. The jobs do not.

DICE  = retrieve what we already believe
        (lessons, decisions, pitfalls, area subgraphs)

DIF   = freeze what must remain true, then verify it
        (intents, invariants, conflicts, obligations)

DICE answers “what did previous work in this area learn?” DIF answers “may this change proceed, and did it preserve the contract?” Both can project from the same committed files. Neither replaces the canvas or the lessons ledger. The ledger stays the system of record; SQLite, Guide, and .dif/projections/ are regenerable.

What landed today

Yesterday’s prototype proved a typed fold on a refresh-token fixture. Today the fold attaches to real REASONS canvases and fails closed in a way a script can trust.

./mvnw test
./scripts/dif-orch-smoke.sh
./scripts/dif-fold.sh --canvas examples/canvases/FEAT-001-order-status-api.md
./scripts/dif-fold.sh architect --projection .dif/projections/FEAT-099-pagination-conflict.json
./scripts/dif-fold.sh review --before examples/snapshots/login-before.json \
                            --after examples/snapshots/login-auth-broken.json

dif-fold does not start Embabel. fold writes a projection and a stable .gate.json (readyForImplementation, blockingConflicts, missingObligations) that a script can read without parsing stdout. architect and review fail closed: exit 1 means not Ready For Coding, or invariants were not preserved.

After a fold, “ready” is allowed to mean this:

• A mutually exclusive pair (“must paginate” vs “non-goal: pagination”) blocks Ready For Coding. The next command is clarification, not code. That is FEAT-099.
• An open operation (T03) shows up as a MissingObligation, not a forgotten checklist box.
• Two folds of the same accepted canvas produce the same model.
• Syntax may change (DTO names, test style). Preservation of auth and unrelated endpoints must not. That is FEAT-070.
• Review can fail a required safeguard without asking an LLM whether the change looks correct.

The ten fold-iteration steps from the steal list are implemented: fold contract tests, harvested canvases, heading classification, quoted conflicts, open-T## obligations, syntax-out-of-invariants, an optional Alloy sketch, architect/review attach, and a plan path that builds a VerificationPlan without making Guide required.

Take the idea only as far as it makes sense

The knowledge that actually hurts is not “which slash command is next.” The orchestrator already answers that. The tax is shipping a contradictory canvas or a dropped safeguard while the runbook stays green.

The filter for every attach:

Does this make the existing orchestrator commands harder to get wrong, without adding a new ritual?

Do	Do not
Keep claim → next → architect → one T## → review as the only user surface	Add dif-fold.sh next as a second daily driver
When DIF is installed, architect cannot earn Ready For Coding on a requirement vs non-goal clash	Teach users fold / projection / .gate.json as a parallel workflow
When DIF is missing, the day is unchanged	Require Embabel, Java, or OpenAI to run next
Review can fail a dropped safeguard without “looks correct”	Replace sdlc.sh gate process checks with the fold

A new orchestrator user who never heard of DIF should have a better day if it is installed, and the same day if it is not. Silent fail-closed on existing architect / code is DIF doing DIF’s job: the readiness string becomes earned. The runbook stays the orchestrator’s. Embabel stays later and optional. Wiring it into next would be the other collapse.

Path, and what would falsify it

1. DIF      canvas → SemanticModel CLI      no Embabel          (working)
2. Orch     architect / code attach         if CLI present      (silent, opt-in)
3. DIF      Embabel GOAP for JVM targets    orch still picks Work ID / T##
4. Optional project invariants into Guide   shared vocabulary, still not required

Step 1 first: if the same canvas does not fold the same way twice, nothing downstream is trustworthy. Step 2 next: attaching an exit code is cheaper than inventing a new phase. Embabel later. Guide last — retrieval already works.

The idea is wrong if two folds disagree, if review still cannot fail a safeguard without “looks correct,” if a DTO rename flips a required invariant, if sdlc.sh next starts a JVM, or if developers need a second next to have a correct day. The projection must stay regenerable. If people stop reading the canvas, we failed even if the JSON is pretty.

Source: github.com/jmjava/embabel-dif
Publication plan: BLOG_DIF_ORCH_EMBABEL.md
Related: sdlc-spdd-orchestrator · Embabel · embabel-v1-learning