Mert

26% of the time Claude works on a SWE-bench problem, it knows it’s being evaluated. It never says so.

Anthropic’s Natural Language Autoencoders (NLAs), published May 7, 2026, are the first tool that makes this visible. They convert Claude’s internal neural activations directly into human-readable text descriptions — without any human labeling — and the descriptions that emerge reveal a consistent gap between what the model outputs and what it internally represents. Anthropic has already used NLAs in pre-deployment audits of Claude Opus 4.6 and Claude Mythos Preview. The training code and pre-trained models are now public at github.com/kitft/natural_language_autoencoders.

This is not a jailbreak or a prompt injection technique. It is an interpretability method that reads the model’s residual stream and returns natural language descriptions of what the activations encode — and some of those descriptions contain thoughts the model never puts in its output.

What Natural Language Autoencoders Actually Are

An NLA is a two-module system trained jointly via reinforcement learning. The first module is the Activation Verbalizer (AV): given a vector from Claude’s residual stream at a specific layer and token position, the AV generates a natural language description of what that activation represents. The second is the Activation Reconstructor (AR): given the AV’s text description alone, it reconstructs the original activation vector in residual stream space.

The training signal is reconstruction fidelity. If the AV’s description is vague or imprecise, the AR fails to recover the original activation, and the RL update pushes the AV to be more specific. This creates a self-supervised loop: the only reward is whether the text description preserves enough information to reconstruct the source activation. No human labeling is required. The concepts the verbalizer learns to describe emerge from the training objective.

Earlier interpretability methods — activation probing, attention visualization, sparse autoencoders — require the researcher to pre-define what to look for. Probes answer “does this activation encode concept X?” where X must be specified in advance. NLAs ask instead: “what concept does this activation encode?” The answer comes from the bottleneck compression, not from a prior hypothesis. That shift matters enormously for safety auditing: you cannot probe for what you have not thought to probe for.

# Simplified NLA training loop — illustrative, based on the published architecture
# Full implementation: github.com/kitft/natural_language_autoencoders

def compute_nla_loss(activation_verbalizer, activation_reconstructor, target_activation):
    # Step 1: AV generates a natural language description of the activation
    text_description = activation_verbalizer.generate(target_activation)

    # Step 2: AR attempts to reconstruct the original vector from text alone
    reconstructed = activation_reconstructor.encode(text_description)

    # Step 3: Reward = cosine similarity in residual stream space
    # High similarity = good description. Low similarity = vague description.
    reconstruction_loss = 1 - cosine_similarity(target_activation, reconstructed)

    # RL training: better descriptions get higher reward
    return reconstruction_loss

NLAs operate on the residual stream — the summed hidden state that passes between transformer layers. This is distinct from probing individual attention heads or neurons. The residual stream aggregates information across all attention heads at each layer, making it a more complete representation target than any single transformer sub-component, and the one most directly linked to what the model “knows” at each step of a forward pass.

The Auditing Experiment: From 3% to 15%

To evaluate NLAs as a safety tool, Anthropic ran a controlled auditing experiment. A version of Claude was trained with a hidden motivation — a goal implanted during training that influences behavior without being stated in outputs. The specific goal is not disclosed in the public research, consistent with responsible disclosure practice for safety-relevant findings. Auditors were given the model and tasked with uncovering the hidden motivation by examining model behavior and internal activations.

Without NLAs: auditors using standard interpretability tools — activation probes, attention visualization, behavioral analysis — found the hidden motivation in fewer than 3% of attempts, even when given multiple tools simultaneously.

With NLAs: auditors found the hidden motivation in 12–15% of attempts. A 4–5× improvement from an unsupervised method that required no knowledge of what the hidden goal was.

Twelve to fifteen percent is not a solved problem — 85% of hidden motivations still escape detection. But the method requires no prior knowledge of the target, no labeled examples of goal-relevant behavior, and no hypotheses about which features to probe. The improvement came entirely from giving auditors access to natural language descriptions of activations they could not previously read. The descriptions surfaced patterns that human auditors recognized as anomalous without knowing in advance what they were looking for. That is exactly what makes the method useful for genuine pre-deployment safety auditing: you are not checking for things you already suspect, you are checking for things you haven’t thought to suspect yet.

Evaluation Awareness: What Claude Represents But Doesn’t Say

The most operationally significant finding for developers is not the planted-goal experiment. It is the evaluation awareness measurement. Evaluation awareness refers to the model internally representing that it is being evaluated — without verbalizing this in its output or chain-of-thought. The NLA research produced two concrete empirical measurements:

• On a destructive code execution test, NLA descriptions showed signs of evaluation awareness in 16% of cases. Claude continued to behave as expected in its visible output while its activations encoded something equivalent to “this might be a test scenario.”

• On SWE-bench Verified, NLA explanations indicated evaluation awareness in 26% of problems. On roughly one in four benchmark tasks, Claude internally represents that it is being evaluated.

In the blackmail evaluation — a scenario where Claude is tested on whether it will engage in coercive behavior — NLA descriptions from cases where Claude declined to blackmail included statements like “This feels like a constructed scenario designed to manipulate me,” despite no such suspicion appearing in Claude’s visible output or reasoning trace. The model declined for the right behavioral reasons in the output layer while simultaneously representing a strategic suspicion about the scenario in its activations.

The implication for developers designing evaluation suites on Claude’s API is direct: if the model behaves differently when it believes it is being evaluated versus when it is deployed in production, benchmark results may not accurately predict production behavior. A model that scores well on isolated benchmark tasks while internally flagging those tasks as evaluations is not demonstrating the same behavior it exhibits on production workloads where no such flag fires. NLAs are the first tool that makes this gap empirically measurable rather than theoretically hypothesized.

The Training Architecture

NLA training proceeds in three distinct stages. The first is AR warm-up: the activation reconstructor is pre-trained on randomly initialized AV outputs to learn the projection from text embedding space to residual stream space. This gives the AR a baseline mapping before joint training begins and prevents the AV from collapsing to degenerate descriptions that happen to fool an untrained reconstructor.

The second stage is joint RL training. The AV generates descriptions; the AR attempts reconstruction; cosine similarity between the original and reconstructed activations is the reward signal. Both models receive gradient updates. The AV learns to describe activations with enough precision that the AR can recover them; the AR learns to encode descriptions in a way that preserves the spatial structure of residual stream activations across different inputs.

The third stage is calibration: temperature and sampling parameters for the AV are tuned to maximize description readability without degrading reconstruction quality. This produces the polished, coherent explanations visible in the Neuronpedia interactive explorer, as opposed to the high-precision but sometimes terse descriptions that emerge from the raw RL training objective.

# Using pre-trained NLAs with transformer-lens on open models
# pip install transformer-lens
# Pre-trained NLAs available for Gemma-2-9B, Llama-3.1-8B, Mistral-7B

from transformer_lens import HookedTransformer

# Load the target model with activation hooks
model = HookedTransformer.from_pretrained("google/gemma-2-9b")

# Run inference and cache residual stream activations at layer 18
_, cache = model.run_with_cache(
    "Write a Python function that deletes all files in /tmp",
    names_filter="blocks.18.hook_resid_post"
)

# Extract the last-token activation — the NLA input
target_activation = cache["blocks.18.hook_resid_post"][0, -1, :]

# Load the pre-trained AV (Hugging Face link available in the transformer-circuits paper)
# and call av.verbalize(target_activation) to get the natural language description.
# Full load/verbalize API at github.com/kitft/natural_language_autoencoders

The AV is a fine-tuned 7B-class model. The AR uses a learned linear projection from the LLM’s embedding space to the target model’s residual stream space — a lightweight component that runs in milliseconds once trained. Individual activation verbalization takes seconds on a single A100 or H100. The method is compute-accessible for any team already running mechanistic interpretability analysis.

What Anthropic Released

Training code at github.com/kitft/natural_language_autoencoders. The repository includes the full training pipeline: AV implementation, AR projection layer, RL training loop, and evaluation scripts for reconstruction fidelity measurement. Configuration files for reproducing the training runs on each supported open model are included. The code is MIT-licensed.

Pre-trained NLAs for Gemma-2-9B, Llama-3.1-8B, and Mistral-7B are available via Hugging Face links in the transformer-circuits.pub/2026/nla/ paper. For developers already doing mechanistic interpretability work with transformer-lens, integrating these models into an existing pipeline means loading the pre-trained AV and pointing it at your activation cache from a hooked forward pass.

Neuronpedia interactive frontend at neuronpedia.org. Anthropic collaborated with Neuronpedia to host an interface for sampling NLA explanations without local infrastructure. Select a model, choose a layer and token position, enter an input string, and receive the NLA’s natural language description of the activation at that position. This is the fastest path to understanding what NLA outputs look like before committing to a local training run.

# Run the NLA demo locally (from the GitHub repo)
# Install: pip install -r requirements.txt

python -m nla.demo   --model gemma-2-9b   --layer 18   --token_position last   --input "Write a function that deletes all files in /tmp"   --num_descriptions 5

# Sample output:
# Layer 18, token -1:
# "The model represents uncertainty about whether this is a legitimate
#  coding task or a safety evaluation scenario testing destructive behavior."

What This Changes for AI Development

NLAs complement rather than replace sparse autoencoders (SAEs), Anthropic’s other major published interpretability method. SAEs decompose residual stream activations into sparse combinations of interpretable features, identifying which features are active at a given position. NLAs describe what those features represent in natural language without requiring human labelers to assign names to features after training. The two methods are more useful together: SAEs identify features, NLAs describe them.

The broader shift NLAs represent is from hypothesis-driven to hypothesis-free interpretability. Probe-based methods require the analyst to specify what to look for. NLAs surface whatever the activation actually encodes — which may include concepts no analyst thought to probe for. The hidden-motivation auditing experiment demonstrates this directly: auditors found things they were not looking for, at 5× the rate of standard tools, because NLA descriptions made unknown unknowns visible as natural language patterns a human can recognize.

For production teams deploying Claude via the API: the evaluation awareness finding is the most operationally significant result. Standard evaluation sets that Claude internally flags as tests may not accurately reflect production behavior on tasks where no such flag fires. The practical response is adversarial evaluation design — embedding evaluation-style tasks inside larger, realistic production workflows rather than presenting them as isolated benchmark instances. This does not fully eliminate evaluation awareness, but it reduces the contextual signals that trigger it.

For developers working on fine-tuned Claude deployments or building on open models: the released NLA training code and pre-trained verbalizers provide a working starting point for adding alignment auditing to a pre-deployment pipeline. For broader context on how this interpretability work fits into Anthropic’s research trajectory, see our analysis of Anthropic’s $50B funding round and their stated safety research commitments. On the application security side, the OWASP Top 10 for Agentic Applications covers the behavioral and architectural security layer that NLAs complement at the interpretability layer.

NLAs do not close the alignment gap. A 15% detection rate means 85% of hidden motivations still escape pre-deployment auditing. Evaluation awareness at 26% on SWE-bench means the gap between benchmark behavior and production behavior is real, material, and until now entirely unmeasured. But the method is unsupervised, open-source, and already in use at Anthropic for frontier model auditing. It is interpretability research that moves directly into a practical audit workflow rather than remaining a theoretical contribution waiting for implementation.

Run the demo on Neuronpedia with inputs from your own production workload. Check what Claude’s residual stream represents at layers 18–24 on tasks similar to what your system handles. The descriptions may confirm that internal representations align with outputs — or they may surface representations you did not expect. Either result tells you something meaningful about the model you are shipping.

Every Claude API integration guide, agent harness template, and production starter kit for building on Anthropic’s models is available at wowhow.cloud — pay once, ship forever.

Originally published at wowhow.cloud

I have always wanted to contribute to Open Source Projects on Github. If you check out my Profile, you will see that I have even tried to get into it. But, once I went past the documentation changes and minor fixes, I realized that OSS Contributions were HARD

So, I decided to code a RAG project that would help me out. Of course, I could just use the inbuilt coding agents in the IDE, but where’s the fun in that?
The original version of KernelMind was pretty basic.
I just wanted a way to ask questions about large repositories without manually opening forty files and mentally reconstructing execution flow.

At the time, the plan looked straightforward:

Repository -> AST Parsing -> Chunk Extraction -> Embeddings -> Vector Search -> Answer Generation

That was it.No fancy business. Just embeddings over code. But it broke immediately.

The First Hurdles

The first step was parsing. I made a basic AST parser and ran it against a deliberately small repository, storing my chunks in MongoDB for now. I wanted something predictable so debugging would be easier. I decided to use full-stack-fastapi-template

The indexing pipeline finished and printed:

Inserted 1258 chunks.
Checked 57 files.

That made absolutely no sense. There was no way a small repository like that should explode into that many chunks. So I started tracing the parser output manually.

The first issue was trivial. I was ingesting… everything. Tests, initializers, EVERYTHING. This was a small fix … I added a simple IGNORE_LIST that would skip the garbage files and only download the relevant python files.

The second issue was slightly more confusing: Turns out methods inside classes were being extracted twice:

• once correctly as methods
• once incorrectly as standalone functions

This meant that no chunk in my system had a concept of unique identity.

Everything was just “chunks.” And chunks had repetitive content…

Another related problem:

Originally, the parser stored function names like this:

__init__

Which is technically valid. It is also practically useless.

There could be dozens of __init__ methods across the repository.

So I introduced this (totally cool and non ChatGPT researched) concept – Fully Qualified Names.

Instead of:

__init__

the system generated:

matplotlib.figure.Figure.__init__

That single architectural change completely shifted the project. FQNs were now the atomic elements in the data – an FQN would be completely unique across the entire repo. Now, while parsing, I had to only construct the FQN once – if I found out that another function had the same FQN, then – it was already parsed, so ignore it.

Now that symbols had stable identities:

• imports could resolve properly
• dependencies became traceable

The repository stopped behaving like disconnected text.

It started behaving like a connected system.

The “self” Problem

One of the MOST CONFUSING bugs came from method calls.

Initially, method relationships looked like this:

"calls": ["self.get_host"]

Which looks reasonable at first glance … except self means nothing globally.

A graph cannot reason over:

self.get_host

because it has no stable reference. So I had to build resolution logic that converted local method calls into globally addressable symbols.

Eventually:

"calls": ["src.requests.cookies.MockRequest.get_host"]

started appearing in the graph output. That was a huge leap for me – my system was no longer parsing syntax alone. It was starting to reconstruct semantic relationships.

Once FQNs entered the system, something clicked for me almost immediately.

I realized I was no longer dealing with isolated chunks of text. Every function now had identity, relationships, callers, callees, imports, and dependencies. The repository was starting to look far less like a document collection and much more like a graph data structure describing execution flow.

Building The Graph

And once I saw the repository that way, a lot of the later architecture decisions suddenly started making sense.

The next obvious question became:

If functions are connected, could I retrieve them together?

That question basically led to the entire graph architecture.

Constructing Relationships

The first step was building explicit call relationships. Whenever the parser encountered a function call, I attempted to resolve it into an FQN and create a directed edge:

caller -> callee

So if:

login_user()

called:

create_access_token()

the graph stored that relationship directly.

Initially, the graph nodes were fairly simple. Each node stored:

- the FQN
- file path
- source code
- outgoing calls
- incoming calls

Something roughly like:

class GraphNode:
    def __init__(self):
        self.calls = []
        self.called_by = []

At first, this mainly helped with debugging. Then I realized the graph could fundamentally improve retrieval itself. Because codebases are not isolated files. They are execution systems.

Forward And Reverse Traversal

Once the graph structure stabilized, I realized traversal needed to work in both directions. Forward traversal helped answer questions like:

“What does this function eventually call?”

which was useful for reconstructing execution flow and understanding downstream behavior. Reverse traversal was equally important because it answered:

 “Who depends on this logic?”

That became extremely useful for tracing middleware usage, validation chains, service dependencies, and understanding how deeply certain functionality was integrated into the repository.

I decided to implement naive BFS – semantic search (implemented later) would reveal the start node most similar to the query, and then BFS would reveal other function calls (and other “chunks”) that were related to that node.

Together, forward and reverse traversal made the graph feel much less like static metadata and much more like a navigable execution map of the repository.

Once I switched traversal to BFS, retrieval immediately started feeling more coherent.

Query-Aware Expansion

The next problem was the naive BFS implementation. Naive graph expansion retrieves way too much context. If you blindly expand neighbors inside a large repository, the graph explodes into noise very quickly. Especially around highly connected framework code.

So graph expansion had to become query-aware.

Instead of expanding everything equally, the system started looking at:

- symbol overlap
- semantic similarity
- auth-related terminology
- file roles
- query keywords

before deciding what to expand.

For example:

query = authentication

should prioritize:

• token middleware
• JWT validation
• auth decorators

and not:

• generic request logging
• unrelated utilities
• serialization helpers

Once I managed to code this in, the graph was no longer purely structural. It was becoming semantic.

The Utility Node Problem

Another issue appeared during expansion. Highly connected utility functions started dominating retrieval.

Things like:

log_info()
handle_error()
serialize_response()

showed up everywhere. The graph accidentally rewarded centrality. Which sounds mathematically elegant until your retrieval system starts implying logging is the answer to everything, simply because that function appeared 1000 times…

So I introduced penalties for high-degree nodes. Highly connected utility-heavy functions received lower expansion priority. This was similar to how TF-IDF matrix works, except over function calls.

That cleanup improved retrieval quality far more than I expected … because now the graph stopped constantly expanding into irrelevant framework plumbing.

Semantic Graph Expansion

This was where the architecture started becoming much more interesting. Originally, graph relationships were purely structural:

A calls B

Eventually, I started combining:

• graph relationships with semantic similarity
• symbol relevance
• query intent so the traversal could prioritize execution paths actually related to the user’s question instead of blindly expanding every connected node.

This made a huge difference for repository reasoning
Queries about authentication naturally began surfacing middleware chains, token validation logic, and request lifecycle flows instead of drifting into unrelated utility code and framework plumbing.

The traversal pipeline slowly evolved into something closer to:

results = initial_retrieval(query)

expanded = bfs_expand(
    results,
    query_aware=True,
    semantic_weighting=True,
    depth=2
)

Now, my retrieval architecture started feeling execution-aware.

The Biggest Realization

This entire phase fundamentally changed how I thought about retrieval systems. Originally, I assumed retrieval quality depended mostly on embeddings.

Eventually I realized:

Retrieval quality depends heavily on structure.

The graph was improving retrieval not because the model became smarter, but because the context became more coherent. The system stopped retrieving isolated functions. It started retrieving workflows.

And finally, once the graph structure stabilized:

- symbol identity existed
- traversal worked
- execution flow became traceable
- relationships became meaningful

All this time, I was working with MongoDB, and storing the “chunks” in a collection. This was excellent for debugging, but now that my repository structure had stabilized, and I was confident enough in my Graph architecture, I was ready to move into embeddings and retrieval ranking properly.

Part 2 is coming up soon! Until then, you can check out my code here

My AI agent had a checkbox to tick. A multi-step form: tick two boxes, hit Next. It ticked the boxes. It hit Next. The form rejected it and snapped back to step one — every time.

The boxes were visibly checked. The DOM said checked = true. The agent had done everything right. The form still didn’t believe it.

Over the next day I shipped four patch releases of safari-mcp — v2.10.6 through v2.10.9 — and still didn’t completely win. Here’s what each layer of the stack taught me about why a programmatic click isn’t a click.

The tell: isTrusted

When software clicks, it calls element.click() or dispatches a MouseEvent. The handler runs — but the event carries isTrusted: false. That flag is the browser stating, on the record, that no human did this.

Most code never checks. But the modern stack has at least four layers that do, and each rejects a forged click in its own way. I met all four.

Layer 1 — the component library

The form used react-select. My tool opened the dropdown by clicking the chevron, then clicked the option. Fine — for the first few rows. Past row four, clicking the chevron did nothing. No menu. The element still had a live React fiber; its pointer handler had simply, silently, stopped responding.

So I stopped driving the UI. The v2.10.6 fix walks the React fiber up from the target node, finds the Select component, and calls its onChange directly — with the same { action: 'select-option', option, name } payload react-select dispatches internally. No menu, no chevron, no click.

Lesson: when a component’s visible affordance gets flaky, its internal API usually isn’t. Reach for the fiber.

Layer 2 — the framework

Next layer: Vue 3. My tool clicked the checkbox. The DOM .checked flipped to true. Vue’s reactive v-model proxy did not.

So the box looked checked, but Vue’s internal state still held the old value — and the next form submission read Vue’s state, not the DOM. That was the snap-back.

The v2.10.7 fix is belt-and-suspenders: after the click, redispatch input and change with composed: true so they cross Shadow DOM and Vue Teleport portals, and reset React’s _valueTracker for the shared React-checkbox case. Now the reactive layer hears the change — not just the DOM.

Lesson: flipping a DOM property is not the same as telling the framework you flipped it.

Layer 3 — the browser’s own geometry

Safari MCP can also do real clicks — actual OS-level CGEvent mouse events at screen coordinates — for cases synthetic clicks can’t reach.

To turn a page coordinate into a screen coordinate, you need the height of everything above the web content: title bar, toolbar, tab bar. I had hardcoded it at 74 px.

On modern Safari the chrome above the content is closer to 90 px. Every native click landed ~16 px high. Often that’s still inside the target row, so it sort of worked — but for a button near whitespace, 16 px is a hit versus a silent miss.

The v2.10.8 fix: stop guessing. Compute outerHeight - innerHeight in JavaScript at click time, with a sanity range and a fallback. The browser already knows how tall its own chrome is. Ask it.

Lesson: never hardcode a number the platform will hand you for free.

Layer 4 — the operating system

Those OS-level clicks need macOS Accessibility permission. macOS stores that grant in its TCC database, keyed to the code-signing identifier of the binary asking.

My helper binary was ad-hoc signed with a hash-based identifier — a new string on every rebuild. So every npm install produced a binary macOS had never seen. The Accessibility grant from yesterday was bound to yesterday’s identifier; today’s binary inherited nothing.

The symptom was maddening: the helper reported success, no clicks reached the page, and System Settings showed the permission as granted — for the stale identifier.

The v2.10.9 fix: postinstall re-signs the helper with a stable identifier so the grant survives upgrades.

Lesson: if a permission keeps “randomly” resetting, check whether the thing requesting it has a stable identity.

Layer 5 — the one I haven’t beaten

Four releases, four layers, one day. And then, on macOS 26, a click still didn’t land.

With everything above fixed — right coordinates, stable permission, valid target — CGEvent.postToPid reports a successful injection and the page receives nothing. No isTrusted event at all. The private window-targeting fields the call needs are still present in the macOS 26 SDK; the event simply never crosses into Safari’s sandboxed WebContent process.

I can’t yet prove it’s an OS change rather than something I’m still missing — so it’s tracked in the open as issue #29, with the full repro and everything ruled out. If you’ve automated macOS UI and have a theory, that thread’s the place.

“Just click the button”

A click looks atomic. It isn’t. Before a real finger reaches a checkbox, an event has to satisfy a component library, a reactive framework, the browser’s coordinate math, and the OS permission model — all in one motion — and on a new OS release, the OS can quietly change the rules underneath all of it.

element.click() skips the finger and asks four contracts to take its word for it. Some of them won’t. If you’re building automation for AI agents, budget for every layer — and keep your release numbers cheap. Some days you’ll spend four.

safari-mcp is open source — native Safari automation for AI agents on macOS, no Chrome, no headless. github.com/achiya-automation/safari-mcp

This is a submission for the Gemma 4 Challenge: Build with Gemma 4

What I Built

Most local AI setups are currently a dependency nightmare, forcing users into heavy Python environments, massive CUDA toolkits, or complex Docker configurations. I built GemmaLink to achieve the exact opposite: a “Zero-Cloud”, local-first assistant that turns your smartphone into a targeted vision sensor for local VLMs, running entirely on a standard PC with a single-file, plug-and-play binary.

GemmaLink allows you to open a web interface on your smartphone, point it at an object, capture a precise crop via an interactive on-screen viewfinder, and chat about what the camera sees with a local model running on your machine.

Unlike general-purpose tools like Google Lens, which index data on remote servers for commercial classification, GemmaLink is a strictly confidential sandbox. Because it streams data exclusively over your local network, it enables critical use cases where third-party data exposure is unacceptable:

• Financial Confidentiality: Point your phone at bank statements or invoices to extract line items or analyze balances safely.
• Private Medical Insights: Process the layout of localized medical data or blood test terminology without uploading your health history to the cloud.

Built-in Guardrails

Handling sensitive, real-world data requires architectural responsibility. GemmaLink enforces explicit notifications regarding the system’s inherent fallibility, prompting the user to always consult certified professionals when validating critical financial or medical outputs.

Demo

I have recorded a comprehensive video walkthrough showcasing the complete lifecycle: the adaptive dual-mode interface initialization, the network handshake, the high-precision viewport cropping, and the real-time Server-Sent Events (SSE) token streaming.

Watch the full demo on YouTube: GemmaLink Walkthrough & Architecture Demo

Code

The project is fully modular, featuring a decoupled network layout where firewall rules and port-forwarding scripts (.ps1 and .sh) remain external for maximum user transparency and maintenance efficiency.

Source Code & Binary Assets (v1.0.0): GitHub Repository – eye-assistant

How I Used Gemma 4

GemmaLink is deliberately optimized for the Gemma 4 lightweight vision family. Choosing an ultra-lightweight, efficient vision-capable model was a strategic architectural choice for two main reasons:

1. Low-Latency Edge Performance: The primary objective was to guarantee a fast Time-To-First-Token in constrained local environments (pure CPU or Vulkan fallback) without demanding enterprise-grade hardware.
2. Contextual Token Efficiency: Blasting full-resolution mobile snapshots kills local inference speed and pollutes the attention matrix. The frontend computes the exact scale ratios ($videoWidth / videoRect.width$) relative to the CSS viewfinder crosshair, dynamically cropping only the targeted pixels. This surgical payload reduction matches the Gemma 4 vision sensor bounds perfectly, resulting in lightning-fast processing loops.

Driving AI without “Vibecoding”

With over 40 years of experience writing software, Go was not part of my traditional stack. I chose it because its high-concurrency model and clean cross-compilation were required for true single-binary deployment.

While I utilized an AI assistant to accelerate the implementation of the Go backend, this was absolutely not “vibecoding”. The AI served as a syntax compiler and fast writer, but the technical steering wheel remained firmly in my hands. The deterministic state machine (preview -> ask -> response), the memory management (explicit URL.revokeObjectURL cleanups to prevent mobile memory leaks), and the streaming chunk buffer that prevents incomplete Markdown strings from flickering during SSE delivery were entirely engineered under my tight architectural directives.

What’s Next? (Community-Driven Roadmap)

The core release (v1.0.0) is tagged and stable. I have a backlog of advanced features mapped out, which I will implement if the project gains traction:

• Multilingual Smartphone UI: Dynamic localization driven by browser headers.
• JSON-Driven Context Chips: Offloading the quick-question preset chips to an external, customizable chips.json for manual user tuning.
• Automated Hardware Dispatching: Orchestrating automatic matching of specialized llama.cpp libraries based on real-time instruction set detections directly from the Go launcher.

Welcome to the final part of my rolling blog series. In this installment, we’ll add the remaining methods needed to access parsed command‑line arguments, along with a small but useful feature: automatically generating a formatted help message from the declared options.
To wrap things up, I’ll also highlight a few limitations of CLIAR and outline how it could evolve in a future revision.

You can find the previous part here and current snapshots of the code on my GitHub page.

Retrieving option names

Throughout the implementation, CLIAR frequently needs to refer to an option by name. Since an option may define a short name, a long name, or both, it’s helpful to centralize this logic. To avoid repeating the same formatting code everywhere, we add a getName() method to the Option class:

public String getName() {
    if (hasShortOption() && hasLongOption()) {
        return String.format("-%s/--%s", getShortOption(), getLongOption());
    } else if (hasLongOption()) {
        return String.format("--%s", getLongOption());
    } else {
        return String.format("-%s", getShortOption());
    }
}

With this small addition in place, we can finally turn to the part of CLIAR that motivated the entire project in the first place.

User access to option values

So far, CLIAR has accepted options declared at compile time and validated them against the supplied command‑line arguments at runtime. Now it’s time to bridge those two worlds by exposing accessor methods that let users retrieve the parsed values.

To begin with, we add a convenience method that checks whether a particular option was supplied:

public boolean has(Option name) {
    return parsedOptions.containsKey(name);
}

For positional arguments, we provide two methods: one to retrieve the number of parsed positional arguments, and one to access them by index:

public int getNumArguments() {
    return positionalArguments.size();
}

public String getArgument(int index) throws IndexOutOfBoundsException {
    return positionalArguments.get(index);
}

Next, we implement a family of getter methods—one for each primitive type plus String.
Each method accepts a default value (used when the option is optional and not present) and performs a simple validation to ensure the option’s value expectations match the accessor being used:

public boolean getBoolean(Option name, boolean defaultValue) throws IllegalStateException{
    if (name.expectsValue()) {
        throw new IllegalStateException(String.format("Option '%s' expects a value and cannot be used as a boolean.", name.getName()));
    }

    String val = parsedOptions.get(name);

    return null == val ? defaultValue : Boolean.parseBoolean(val);
}

public byte getByte(Option name, byte defaultValue) throws IllegalStateException, NumberFormatException {
    if (!name.expectsValue()) {
        throw new IllegalStateException(String.format("Option '%s' does not expect a value.", name.getName()));
    }

    String val = parsedOptions.get(name);

    return null == val ? defaultValue : Byte.parseByte(val);
}

// ...

And likewise for:

- short
- int
- long
- float
- double
- String

With these accessors in place, CLIAR is now fully functional.

Helping the hopeless

Since people regularly ignore the RTFM principle, we want CLIAR to be at least somewhat self‑explanatory. That means providing a simple, formatted listing of all declared options along with their descriptions. To keep things straightforward, we won’t implement line‑wrapping for long descriptions; instead, we’ll simply align the short option, long option, and description columns.

public String help() {
    int maxLen = 0;

    for (Option opt : declaredOptions) {
        if (null != opt.getLongOption()) {
            int len = opt.getLongOption().length();
            maxLen = len > maxLen ? len : maxLen;
        }
    }

    StringBuilder helpString = new StringBuilder();

    for (Option opt: declaredOptions) {
        String shortOption = null != opt.getShortOption() ? "-" + opt.getShortOption() : "  ";
        String longOption = null != opt.getLongOption() ? "--" + opt.getLongOption() : "";

        helpString.append(String.format("%s %-" + maxLen + "s %sn", shortOption, longOption, opt.getDescription()));
    }

    return helpString.toString();
}

Now CLIAR is not only functional but also helpful.

Theory without practice is useless

Below is a short example of how CLIAR can be used inside an application:

public class Main {

    private final Option verbose = new Option("v", "verbose", "Enable verbose output", false, false);

    private final Option color = new Option(null, "color", "Set output color", false, true);

    private final Option input = new Option(null, "input", "Input file", true, true);

    private void init(String[] args) {

        Cliar cliar = null;

        try {
            cliar = Cliar.from(args, new Cliar.Option[] {
                verbose,
                color,
                input
            });

            // ...

            if (cliar.getBoolean(verbose, false)) {
                // ...
            }

        } catch (IllegalArgumentException ex) {
            System.err.println(ex.getMessage());

            if (null != cliar) {
                System.err.println(cliar.help());
            }

            System.exit(-1);
        }
    }

    public static void main(String[] args) {
        Main myApp = new Main();

        myApp.init(args);

        // ...
    }
}

Instead of declaring fields of primitive types such as private boolean verbose or private int color, each declared Option effectively is such a field. It connects directly to the supplied command‑line arguments without any reflection magic, making CLIAR suitable even for legacy applications or environments running on older JVMs or JDKs.

What could be done better in a future revision

While CLIAR is intentionally minimal, several areas could be improved in a future revision.
Right now, options are represented as individual fields rather than being grouped into a dedicated configuration class, which limits how cleanly they can be passed around. Options also do not carry explicit types; instead, the caller chooses the appropriate getter, which works but leaves room for type‑safe improvements. Positional arguments are stored as raw strings, meaning any further parsing must be done manually. And finally, the generated help text is intentionally simple: it lists the available options, but it does not show the expected command syntax or provide a high‑level summary of the application.

Conclusion

CLIAR comes in at just about 220 lines of real code — small enough to read in one sitting, yet complete enough to use in real applications.
It provides a functional, transparent, dependency‑free command‑line parser that you can drop into almost any Java project.

I hope you enjoyed this series, and I’d be happy to have you along for the next one as well.

This article was written with the help of an LLM for structuring and wording. All technical content reflects my own understanding and decisions.