Eugene Petrenko

IntelliJ Plugin Hot-Reload: HTTP 413

2026-04-17T00:00:00+00:00

185 MB. That’s where my IntelliJ plugin stopped hot-reloading.

I’ve been working on MCP Steroid, an IntelliJ plugin that exposes IDE APIs to LLM agents via an MCP server. It bundles a Kotlin compiler, an OCR engine, and enough other dependencies to reach 185 MB as a ZIP.

That size mattered because MCP Steroid changes fast. An agent tries a skill, hits an edge case, I fix the handler, redeploy, and the agent tries again. Restarting the IDE for every build kills that feedback loop. That is why I built intellij-plugin-hot-reload (background post): an HTTP endpoint on IntelliJ’s built-in server on port 63342 that deploys plugins without a restart. My Gradle deployPlugin task finds running IDEs via marker files, POSTs the ZIP, and the IDE reloads the plugin on the fly.

Then I got this:

→ http://localhost:63342/api/plugin-hot-reload
  ✗ HTTP 413

The Investigation

I first assumed the bug was in my handler. It wasn’t. IntelliJ returned 413 before my code ever ran. curl -v showed the same thing:

curl -v -X POST "http://localhost:63342/api/plugin-hot-reload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@mcp-steroid-185mb.zip"

> Content-Length: 194059789
> Expect: 100-continue
>
< HTTP/1.1 413 Request Entity Too Large
< content-length: 0

An empty body. No hint. Just 413.

IntelliJ’s built-in HTTP server uses Netty. The HttpRequestHandler extension point receives a FullHttpRequest. That word matters. Netty’s HttpObjectAggregator builds the full request body before the handler runs, and it returns 413 when the request exceeds its limit.

The aggregator is added in NettyUtil.addHttpServerCodec():

pipeline.addLast("httpObjectAggregator", new HttpObjectAggregator(MAX_CONTENT_LENGTH));

And MAX_CONTENT_LENGTH comes from NettyUtil.java:

public static final int MAX_CONTENT_LENGTH;

static {
  int maxContentLength = 180;
  try {
    maxContentLength = Integer.parseInt(
      System.getProperty("ide.netty.max.frame.size.in.mb", "180")
    ) * 1024 * 1024;
  } catch (NumberFormatException ignore) {
  }
  MAX_CONTENT_LENGTH = maxContentLength;
}

180 MB. My ZIP is 185 MB.

The pipeline is wired in PortUnificationServerHandler:

else if (isHttp(magic1, magic2)) {
  NettyUtil.addHttpServerCodec(pipeline);
  pipeline.addLast("delegatingHttpHandler", delegatingHttpRequestHandler);
}

Every request on IntelliJ’s built-in server goes through that path. There is no per-handler override. Once I saw that, the shape of the problem changed: fight the limit, or stop uploading the body.

First Idea: Another HTTP Server

My first workaround was obvious: spin up a separate Netty or Ktor server with a larger body limit. It was the idea that my AI Agent suggested as a too straightforward solution that I rejected. Too much work for that simple use-case.

It would work, but it would also mean:

Managing a second server lifecycle, plus port allocation and conflicts
Teaching every client a second endpoint convention
Debugging one more moving part when reload fails
Reimplementing authentication, TLS, and shutdown concerns the built-in server already handles

I rejected building it. Then I ask to find a better solution.

Better Solution: Pass a Local Path

The hot-reload plugin and the Gradle build run on the same machine. The ZIP already exists on disk. I was uploading 185 MB over loopback so the server could write it to a temp file and hand that path to PluginInstaller.installAndLoadDynamicPlugin().

The file was already local. I only needed to pass the path.

On the server side, the handler checks a query parameter before touching the request body:

val localDiskFile = urlDecoder.parameters()["local-disk-file"]?.firstOrNull()
if (localDiskFile != null) {
  val file = Path.of(localDiskFile)
  if (!Files.exists(file)) {
    return sendError(
      context,
      request,
      HttpResponseStatus.BAD_REQUEST,
      "File not found: $localDiskFile"
    )
  }

  return executeReload(context) { reloadService, progress ->
    reloadService.reloadPluginFromZipFile(file, progress)
  }
}

reloadPluginFromZipFile reads the ZIP from disk, extracts the plugin ID, and passes the path to IntelliJ’s installAndLoadDynamicPlugin(). My code never creates a 185 MB byte array.

On the client side, the Gradle task got smaller too:

val encodedPath = URLEncoder.encode(zip.absolutePath, Charsets.UTF_8)
val conn = (
  URI("$url?local-disk-file=$encodedPath").toURL().openConnection() as HttpURLConnection
).apply {
  requestMethod = "POST"
  doOutput = false
  doInput = true
  setRequestProperty("Authorization", token)
  connectTimeout = 5_000
  readTimeout = 300_000
}

check(conn.responseCode in 200..299) { "HTTP ${conn.responseCode}" }
conn.inputStream.bufferedReader().lineSequence().forEach { println("  $it") }

No body. No Content-Type. Just a short authenticated POST with a local path.

Why This Is Better

This wasn’t just a workaround. It was the design I should’ve used from the start.

The body-upload path forces Netty to aggregate the entire ZIP before my handler runs. At 185 MB, that’s a large allocation even on the happy path. If someone gets the Bearer token, it is also an easy memory amplifier.

The file-path flow avoids that:

No 185 MB buffer. The HTTP layer sees an empty body and hands a Path to the plugin installer.
The ZIP stays on disk instead of moving through a socket and an in-memory aggregator.
The handler can verify existence, size, and, if needed, a checksum before the reload starts.
More secure: you need a plugin file on the disk, even if you can reach the localhost-bound web-server and somehow know the token.

This is not a dramatic security boundary change. The caller is already authenticated and trusted to supply a local path. But it replaces “accept arbitrary bytes over the network” with “read this specific file.” That’s a better default.

I kept the body-upload path for plugins under 180 MB and for the rare case where client and server do not share a filesystem. Backward compatibility was just an early if in the handler.

The Result

→ http://localhost:63342/api/plugin-hot-reload?local-disk-file=%2Fpath%2Fto%2Fplugin.zip
  Authorization: Bearer $TOKEN
  Starting plugin hot reload, zip size: 193,995,401 bytes
  Plugin ID: com.jonnyzzz.mcp-steroid
  Unloading existing plugin: MCP Steroid
  Plugin unloaded successfully
  Installing and loading plugin: MCP Steroid (0.92.0)
  Plugin MCP Steroid reloaded successfully
  SUCCESS

185 MB plugin. Zero bytes in the request body. Full hot reload in under 10 seconds. Better security.

Takeaways

When an error is opaque, read the source. The 413 had zero diagnostic information. Reading IntelliJ’s NettyUtil.java made the limit obvious.
Question the transport, not just the limit. My first instinct was “make the limit bigger.” The better question was “why am I transferring this data at all?”
Localhost is still a network hop. Even loopback HTTP goes through TCP, Netty codecs, and aggregation. A local path skips that entire stack.
Global system properties are not a great API. ide.netty.max.frame.size.in.mb is global and resolved at class load time. Not something I want users editing in idea.vmoptions.

The hot-reload plugin with ?local-disk-file= support is at jonnyzzz/intellij-plugin-hot-reload (v1.0.0). If your IntelliJ plugin is creeping toward 180 MB — or you just want a tighter plugin development loop — give it a try.

I’m looking forward to seeing that functionality supported natively in IntelliJ and IntelliJ SDK. That will make IntelliJ plugin development much easier. Promote that post, and I’ll be happy to contribute the fixes.

Building an IntelliJ Plugin That Works Across Multiple IDE Versions: 7 Approaches

2026-04-15T00:00:00+00:00

I have been building MCP Steroid — an IntelliJ plugin that gives AI Agents access to the full IntelliJ Platform API at runtime. The plugin needs to work across IntelliJ 2025.3 (build 253), 2026.1 (build 261), and the upcoming 2026.2 EAP.

Right now the plugin uses a workaround: pin a specific Kotlin compiler version that happens to be binary-compatible one IJ generation before and after the target. It works — but it becomes more fragile with every Kotlin release, and with the K2.2 → K2.3 break between IJ 253 and 261, it is reaching its limit.

I also cannot just drop support for IJ 253. That version family covers Android Studio forks. Dropping it and then needing it back later is expensive — users do not return easily once they are forced to an alternative. So 253 stays as the floor, and I need to support everything up through the current EAP trunk.

That sounds like a sinceBuild / untilBuild problem. It is not.

When I started investigating, I found three separate, deeply entangled problems — and one of them has no elegant solution in the current Gradle toolchain. This post is the story of those problems and the seven approaches I explored. The PoC for approaches 1 + 5 is at github.com/jonnyzzz/ij-multi-version.

The Problem in Concrete Terms
The Seven Approaches
The Single-Invocation Approach: What JetBrains Uses Internally
Build-time Verification: ClassFile Reference Checking
Build Issues I Hit Along the Way
Scoring Summary
What JetBrains Could Do Better
Where to Start
What I Am Doing for MCP Steroid

The Problem in Concrete Terms

The Kotlin Version Coupling

IntelliJ is built with Kotlin and bundles Kotlin libraries. When your plugin runs inside IJ, it uses the IDE’s bundled Kotlin runtime — not the one you compiled against. A plugin should try the best to avoid bundinng Kotlin libaries, which are present in the IDE classpath. JetBrains documents the version mapping officially on the Configuring Kotlin Support page:

IJ Version	Bundled Kotlin stdlib
2026.1 (261)	2.3.20
2025.3 (253)	2.2.20
2025.2 (252)	2.1.20
2025.1 (251)	2.1.10
2024.3 (243)	2.0.21
2024.2 (242)	1.9.24

The 2.2.20 → 2.3.20 jump between 253 and 261 is not a routine version bump. JetBrains confirmed directly on the platform forum:

“unfortunately it’s indeed impossible to use kotlin 2.2.20 anymore for IJ 261. 2.3.0/2.3.10 should be used instead.” — Anna Kozlova (JetBrains), IJ Platform Forum, Feb 2026

This matters specifically if your plugin uses Kotlin compiler APIs — PSI trees, the Analysis API, anything from org.jetbrains.kotlin.compiler.client.impl. Binary metadata changed between K2.2 and K2.3 in a way that is not backward-compatible for compiler uses.

Kotlin version dimension: not only must the plugin be compiled against the right Kotlin, but the Kotlin compiler it invokes at runtime must also match the bundled version in the running IDE. And the Kotlin libraries (such as Kotlin Coroutines) must be compatible.

For MCP Steroid, which executes Kotlin code snippets programmatically, we use the dedicated kotlinc compiler binary. The version of the compiler is selected specifically to support the 2.2 version in 253, and 2.4.0-beta in the recent versions of IntelliJ. Thanks to the binary backward/forward compatibility, that is possible, and it simplifies the plugin’s setup a lot. We are not using the embedded Kotlin compiler because it’s not included in all IntelliJ-based IDEs, e.g., Rider, PyCharm.

The PlatformKotlinVersions map in the IJ Platform Gradle Plugin initially lacked a 261 entry, silently defaulting to K2.2.20. This caused cryptic compile failures with no diagnostic. Fixed in IJPGP v2.12.0 (released 2026-03-06), which mapped 261 → 2.3.10. The final IJ 2026.1 GA ships 2.3.20, as Kotlin 2.3.20 was released ten days after the IJPGP fix landed.

If your plugin does not use compiler APIs — only pure Kotlin language features — the situation is less severe. The intellij-rust plugin handles this by pinning apiVersion.set(KotlinVersion.KOTLIN_1_8) even when the IDE bundles 2.x, trading access to newer language features for version-range freedom. A valid strategy if your plugin does not need Kotlin 1.9+ features.

You Cannot Parametrize the Kotlin Compiler in Gradle

This is the root cause of why all the “just add a flag” solutions fail.

In a standard Gradle build, the Kotlin compiler version is a global property — it comes from plugins { kotlin("jvm") version "X.Y.Z" } in build.gradle.kts. There is no built-in mechanism to compile one subproject with KGP 2.2.x and another with KGP 2.3.x in the same build invocation. The IJ Platform Gradle Plugin resolves the target SDK classpath per subproject, but the Kotlin language and API version is a property of the KGP loaded into Gradle’s script classloader — not of the SDK.

One Gradle invocation, one KGP version, period. This is the constraint that drives the entire multi-subproject architecture. Any solution to the multi-version problem that requires different Kotlin compiler versions must use separate Gradle invocations: separate subprojects, separate CI jobs, or Docker containers.

Alternative – use different Kotlin plugin versions in different sibling projects, and patent Gradle projects must not have KGP in the classpath. That makes setup even more complicated.

Bundled Libraries Change Between IJ Versions

It is not just Kotlin. IntelliJ also bundles:

kotlinx.coroutines: Since IJ 2024.2, JetBrains ships a patched fork at github.com/JetBrains/intellij-deps-kotlinx.coroutines under the org.jetbrains.intellij.deps.kotlinx group. If your plugin bundles its own coroutines version, you will hit ClassCastException at runtime when the bundled and shipped versions load the same class name through different classloaders. The fix: declare coroutines as compileOnly and set kotlin.stdlib.default.dependency=false. But that means compiling against the oldest bundled version you support.

Pro-Tip: Set up the assertion to verify all the bundled libraries to your plugin. Verify that the you are not re-packaging the same libraries into your plugin’s lib folder.

Approximate bundled versions: IJ 252 → kotlinx-coroutines 1.10.1-intellij-4; IJ 261 → 1.10.2-intellij-1 (aws-toolkit-jetbrains PR #6331). The IJ 253 version is not in the official docs table but follows the same pattern.

Kotlin serialization and other bundled libraries follow the same pattern.

IJ Platform APIs Change Without a Stability SLA

JetBrains does not publish a formal API stability SLA. Per-API signals:

@ApiStatus.ScheduledForRemoval(inVersion="...") — will be removed; the version attribute tells you when to act
@ApiStatus.Internal — no compatibility promise; may break in a patch release
@ApiStatus.Experimental — subject to change without notice

The API changes list for 2026 documents what broke. Deprecated APIs are typically removed after 2–4 major versions. Plugin Verifier warnings on EAP builds give 1–3 months of lead time — but only if you are running Plugin Verifier against those EAP builds.

One concrete 2025.3 change: the unified IJ distribution merged Community and Ultimate, deprecating intellijIdeaCommunity() in the Gradle plugin in favour of intellijIdea(). The EAP SNAPSHOT artifacts still accept the old function call for now, but new plugin projects should use intellijIdea() from the start.

The Seven Approaches

Option 1: Symlinks + Multiple Gradle Subprojects

Create one Gradle subproject per target IJ version. Each has its own build.gradle.kts with the correct kotlinLang and ijSdk constants. Shared plugin sources live in src-includes/. Each subproject includes the shared sources via filesystem symlinks into src-symlink/.

Why symlinks? IntelliJ IDEA requires that each source root has a unique physical path. Two modules pointing to the same directory confuse IDEA’s indexing. Symlinks give each module a unique path that points to the same files.

“It creates quite a horrible setup on the IntelliJ side… because there is no standard way to mount the same sources for multiple modules.”

The source directory naming convention:

src-includes/main/
├── kotlin/          ← always compiled for all versions
├── java/            ← always compiled
├── resources/       ← always compiled
├── src-253/         ← only when ijMajor == 253
├── src-261/         ← only when ijMajor == 261
├── src-253-since/   ← when ijMajor >= 253
└── src-261-until/   ← when ijMajor <= 261

Each subproject resolves which directories to link via a regex:

fun folderMatchesMarker(folderName: String): Boolean {
    if (folderName in setOf("java", "kotlin", "resources")) return true
    val m = Regex("""src-(\d{3})(?:-(since|until))?""").matchEntire(folderName)
        ?: error("Unrecognized directory '$folderName' in src-includes/")
    val nnn = m.groupValues[1].toInt()
    return when (m.groupValues[2]) {
        "since" -> ijMajor >= nnn
        "until" -> ijMajor <= nnn
        else    -> ijMajor == nnn
    }
}

The PoC also includes a checkVersionCoverage task that validates there are no gaps in the supported version range. It uses the IJ build-number formula — (year − 2000) × 10 + quarter, with valid quarters 1–3 — to detect if, say, you support 253 and 261 but skipped 262 entirely when 262 was required to be listed. Coverage gaps are caught at configuration time.

Adding a new version: create ij-plugin/ij-NNN-kXY/build.gradle.kts (copy from existing, change three constants at the top), add to gradle/ij-builds.properties.

# gradle/ij-builds.properties
combinations=ij-253-k22,ij-261-k23

Production precedent: This approach is used in production with the IDE Services plugin, supporting two years of IJ versions. It works.

The advantage: One ./gradlew build compiles all versions. API breakages surface as compiler errors immediately across the full version matrix. And the right-click on the selected runIde task would start the debugger with the selected version in the Click.

The cost: The symlink layer is unfamiliar to most developers. IDEA’s module tree grows with the version count. Building all versions locally is slower than building one. Dependency resolution will take more time, since you need more heavy IDE packages to download. The versioned source folders appears to have more code, one must carefully design and authorize and new code added to the folders like src-251.

Verdict: Best compile-time safety. Highest build complexity. Proven in production.

Option 2: Branch per IJ Version

Maintain a separate Git branch per major IJ version. Build and deploy from the correct branch.

Every bug fix must be cherry-picked to all active branches. If you have three branches — main, 253, 252 — a single commit becomes three cherry-picks. Cherry-picks diverge. After six months you have three codebases that are supposed to be the same plugin but differ in subtle ways you cannot easily diff.

“The changes must be cherry-picked to all branches to make it work. And it’s definitely quite easy to fail it. We did that before.”

JetBrains’ SDK documentation acknowledges branches as a last resort: “In certain scenarios where fundamental incompatibilities cannot be resolved through conditional logic, maintaining separate branches for each major IDE version may be necessary.” Last resort is the right framing.

Verdict: Simple per-branch build. Terrible long-term maintenance. Hard no.

Agentic That is easy to implement with AI Agent and clear instructions to follow.

Option 3: Reflection

Call version-dependent APIs via Java reflection. Detect the IJ version at startup and Method.invoke() the right implementation.

// Do not do this
val method = try {
    WindowManager::class.java.getMethod("getAllProjectFrames")
} catch (e: NoSuchMethodException) {
    WindowManager::class.java.getMethod("getProjectFrameHelpers") // renamed in IJ 261
}

Reflection turns build-time errors into runtime errors. If JetBrains removes the API entirely, you will not know until a user reports a NoSuchMethodException in production. The IDE cannot help you — no autocomplete, no “find usages”, no refactoring support.

“The reflection will hide all the potential problems in the future and will create a much more problematic approach.”

Verdict: Rejected. The ease of implementation does not justify losing compile-time safety.

Option 4: Shims / Typed Adapters

Create a thin adapter layer — small modules, one per version-incompatible API surface. Each shim implements a shared interface. A selector class picks the right implementation at runtime.

// Shared interface
interface WindowLister {
    fun listProjectWindows(): List<IdeFrame>
}

// shim-253 — compiled against IJ 253 SDK
class WindowLister253 : WindowLister {
    override fun listProjectWindows() =
        WindowManager.getInstance().getAllProjectFrames().toList()
}

// shim-261 — compiled against IJ 261 SDK
class WindowLister261 : WindowLister {
    override fun listProjectWindows() =
        WindowManager.getInstance().getProjectFrameHelpers().toList()
}

// Runtime selection
val lister: WindowLister = when {
    ApplicationInfo.getInstance().build.baselineVersion >= 261 -> WindowLister261()
    else -> WindowLister253()
}

The bazelbuild/intellij Bazel plugin is the canonical production example. They maintain sdkcompat/v252/, sdkcompat/v253/, sdkcompat/v261/ — supporting two stable versions simultaneously plus one under-development. Their three patterns: Compat (static utility class), Adapter (superclass constructor changed), and Wrapper (new interface in superclass constructor). Every compat change is marked // #api252 to indicate the last version requiring it — makes cleanup obvious when that version is dropped.

The aws-toolkit-jetbrains uses a simpler variant: versioned source directories src-243-253/ and src-261+/ within a single Gradle project. When PyAddSdkPanel was removed in IJ 261, its usage moved to src-243-253/ and the replacement went into src-261+/.

The critical discipline constraint: all classes across version-specific directories must expose the same public API surface. You can only change implementations, not add or remove methods. This is hard to enforce without tooling and compounds in cost as the number of shimmed APIs grows.

What makes this better than reflection: Shim implementations are compiled. API removal in a shim generates a compile error, not a runtime exception. IDE tooling works normally inside shims.

What makes this incomplete: Main plugin code is still compiled against one SDK only. An API removed in a newer IJ generates no compile error unless it is already behind a shim.

The HaxeFoundation/intellij-haxe plugin tried this pattern and eventually dropped it: “maintaining a code base that can compile to multiple versions is a lot of work.” They now track only the latest IJ version. The discipline required is real, and for a small team it compounds quickly.

Verdict: Right tool for specific known API divergences. Not a whole-project strategy. Apply reactively when Option 7 surfaces a specific API break.

Option 5: Template Build Scripts

Each IJ version gets a fully self-contained build.gradle.kts with all version constants inlined. No convention plugins. No shared buildSrc task classes. Each file can be read top-to-bottom and the entire build is understandable.

// ── Version declarations ──────────────────────────────────────────────
val ijMajor      = 253                 // IJ major build number
val ijSdk        = "253-EAP-SNAPSHOT"  // SDK artifact version
val kotlinLang   = "2.2"               // Kotlin language/API level
val needsNightly = false               // true = requires JetBrains VPN

A configuration-time assertion catches obvious mismatches before SDK downloads:

run {
    fun String.toMajorMinor(): Pair<Int, Int> {
        val p = split(".")
        return (p.getOrNull(0)?.toIntOrNull() ?: 0) to (p.getOrNull(1)?.toIntOrNull() ?: 0)
    }
    val kgpVersion = extensions.getByType<KotlinJvmProjectExtension>().coreLibrariesVersion
    val (pMaj, pMin) = kgpVersion.toMajorMinor()
    val (lMaj, lMin) = kotlinLang.toMajorMinor()
    check(pMaj > lMaj || (pMaj == lMaj && pMin >= lMin)) {
        "[ij-$ijMajor] KGP $kgpVersion is older than declared language level $kotlinLang. " +
        "Raise kotlinJvmPluginVersion in gradle.properties."
    }
}

Adding a new version: copy the file, change the three constants. No convention-plugin archaeology. New contributors can understand the entire build by reading one file.

This is really an organizational principle for Option 1 — or for the single-invocation CI pattern — rather than a standalone multi-version strategy. But it is worth naming explicitly because getting the build organization right makes all other options more maintainable.

Verdict: Essential organizational discipline. Use inside whichever multi-version strategy you choose. Works especially well combined with Option 1.

Option 6: Simplify IntelliJ’s API Surface (Long-term)

For MCP Steroid, the IJ plugin ultimately does two things:

Execute code: run a Kotlin snippet against the IDE’s JVM at the AI Agent’s request
Show a confirmation dialogue when the Agent wants to do something irreversible

If these two APIs were built into IntelliJ Platform itself, the plugin would become trivial. All real logic moves to the CLI side. The CLI deals with port discovery, plugin updates, and versioning. The plugin just exposes two endpoints.

This is the direction MCP Steroid is already moving. The CLI gets richer; the plugin gets simpler. Every feature that migrates from ij-plugin/ to kotlin-cli/ or mcp-core/ removes one class of API compatibility problem.

The platform’s RPC layer (com.intellij.platform.rpc) became public in 2025.3 and 2026.1, but it serves the IDE-internal frontend/backend split for remote development — not external CLI delegation. There is no announced timeline for a public POST /execute API. Not before IJ 2026.2, which is roughly a year away.

Practical implication: Architect for this direction now. Every refactoring that moves logic out of the IJ plugin is a step in the right direction, regardless of whether Option 6 itself ships.

Verdict: Correct long-term direction. Not a solution for the next 12 months.

Option 7: Docker-based Build Compatibility Tests

Keep the main build simple — one version per Gradle invocation, selected by a property. Add a separate test-integration module with JUnit 5 tests that run ./gradlew buildPlugin -Pmcp.platform.version=$version inside a Docker container per target IJ version.

@Test
fun `build plugin with IntelliJ 2025_3`() = buildPluginWithVersion("2025.3")

@Test
fun `build plugin with IntelliJ 2026_1`() = buildPluginWithVersion("2026.1")

@Test
fun `build plugin with IntelliJ 2026_2 EAP`() = buildPluginWithVersion("262-EAP-SNAPSHOT")

EAP versions use the 3-digit build-number format (262-EAP-SNAPSHOT, not 2026.2-EAP-SNAPSHOT), resolved from the public snapshots() Maven repo (https://www.jetbrains.com/intellij-repository/snapshots) via useInstaller = false. Nightly builds (262-SNAPSHOT, or LATEST-TRUNK-SNAPSHOT for the rolling trunk tip) require the nightly() repo (https://www.jetbrains.com/intellij-repository/nightly) and IJPGP ≥ 2.14.0. Released versions ("2025.3", "2026.1") use the default installer mode.

LATEST-TRUNK-SNAPSHOT is particularly valuable: it automatically follows the current trunk regardless of major version — when 262 ships and 263 trunk starts, it tracks 263. This gives 1–3 months of early warning before API breaks appear in a numbered EAP.

Each test:

Updates a bare git clone of the current repo into a cached workspace via git fetch
Syncs uncommitted local changes via rsync --delete — so local work in progress is tested, not just what is committed
Runs ./gradlew buildPlugin -Pmcp.platform.version=X inside the container
Fails the JUnit test if the build fails

The caching layer is what makes this practical

A cold Docker build downloads a full IJ SDK — roughly 3.3 GB extracted. Slow the first time. Three-layer caching makes subsequent runs fast:

Cache layer	Host path	What is stored
Bare git clone	`build/build-compat/repo-cache/`	Updated via `git fetch`; fast local clone
Per-version workspace	`build/build-compat/workspace/<version>/`	Gradle incremental state
Shared Gradle home	`build/build-compat/gradle-cache/`	IJ SDK JARs, dependency downloads

With warm caches: rsync copies only changed files, Gradle runs incrementally, the build completes in minutes instead of the initial 10–20 minutes.

Why this fits mcp-steroid best

The single ij-plugin/build.gradle.kts already uses -Pmcp.platform.version=2025.3
There is already a test-integration module
Adding a new IJ version is one @Test method
The main build stays fast — ./gradlew build is one version, no Docker overhead
API breaks surface as build failures in CI, at test time rather than local build time
Parallelism is at the JUnit level — multiple containers can run simultaneously

The tradeoff: Compile errors only appear when running integration tests, not in ./gradlew build. For CI this is fine. For local development you rely on the IDE’s inspections and Plugin Verifier.

Key gap vs. Option 1: Kotlin compiler version is still global. If IJ 261 requires K2.3 and the build is configured for K2.2, the Docker test catches it — but not the main local build. Mitigated by the checkBundledKotlinCompatibility task and explicitly pinning kotlinVersion per target platform.

Verdict: Best fit for mcp-steroid today. Already implemented as a pending change.

The Single-Invocation Approach: What JetBrains Uses Internally

Some JetBrains plugins use a simpler model: one Gradle invocation builds exactly one IJ version, selected by a system property. CI runs N parallel jobs — one per version. This is probably the most common internal approach at JetBrains for multi-version plugin builds.

One version per Gradle invocation

./gradlew build -DplatformVersion=253

A version config data class carries all version-specific coordinates:

data class PluginVersionConfig(
    val id: String,          // "251", "252", "253", "261"
    val ideaVersion: String, // e.g. "253.27604" — exact build number
    val kotlinVersion: String,
    // ... other SDK/product version fields ...
)

CI runs N parallel jobs — one per version. No symlinks needed, because only one version is built per Gradle invocation and IDEA only sees one set of source roots at a time.

Source directory selection

private fun SourceDirectorySet.versionedSrcDirs(basePath: String) {
    when (getCurrentVersion().id) {
        "253" -> {
            srcDir("src-252-since/$basePath")
            srcDir("src-253-since/$basePath")
            srcDir("src-253/$basePath")
            srcDir("src-253-until/$basePath")
        }
        "261" -> {
            srcDir("src-252-since/$basePath")
            srcDir("src-253-since/$basePath")
            srcDir("src-261-since/$basePath")
            srcDir("src-261/$basePath")
        }
        else -> error("Unsupported IDE version: ${getCurrentVersion().id}")
    }
}

How it compares to the multi-subproject PoC

Aspect	Single-invocation approach	Multi-subproject PoC
Versions per Gradle invocation	1 (flag-selected)	All (one subproject each)
Symlinks needed	No — single invocation sees one source set	Yes — IDEA needs unique paths per module
Source dir matching	Explicit `when` switch	Regex `src-(\d{3})(?:-(since\\|until))?`
Version data	20+ fields per version	3 fields: `ijMajor`, `ijSdk`, `kotlinLang`
New version effort	Add `when` branch + version config object	Copy build file, change 3 constants
Single-command full matrix	Requires N parallel CI jobs	`./gradlew build`

The intellij-rust plugin used a similar per-version properties file pattern: gradle-252.properties, gradle-253.properties, etc., with CI passing -PplatformVersion=$ to select among them.

Build-time Verification: ClassFile Reference Checking

Beyond compilation against the right SDK, there is a verification gap: do all the classes, methods, and fields your plugin references actually exist on the IJ classpath at runtime?

The PoC implements a three-tier answer to this, built around a standalone :check-class-refs Gradle application module that uses ByteBuddy’s shaded ASM to inspect compiled bytecode. Each tier catches a different category of API change.

Tier 1 — `verifyClassRefs`: erased-descriptor existence check

Walks every .class file in the compiled plugin. For each method call site, extracts the owner class + method name + full JVM descriptor (which encodes the erased return type and parameter types). Checks that this exact (owner, name, descriptor) exists somewhere in the owner class’s hierarchy on the compileClasspath.

This catches:

Class removed: com.intellij.MissingClass not on classpath → NoClassDefFoundError
Return type changed to a different class: method getFrame() changed from returning com.intellij.openapi.util.Pair to kotlin.Pair — both classes exist, but the JVM descriptor changed from ()Lcom/intellij/openapi/util/Pair; to ()Lkotlin/Pair;, so the call site’s INVOKEVIRTUAL finds no matching method → NoSuchMethodError
Parameter type changed: same mechanism, different position in the descriptor

When a method is missing but a same-named method with a different descriptor is found, the report shows the alternative:

[verifyClassRefs-261] 1 method(s) not found (descriptor mismatch or removed):
  - com.intellij.openapi.wm.WindowManager#getAllProjectFrames ()[Lcom/intellij/openapi/wm/IdeFrame;
      ↳ 'getAllProjectFrames' exists with different descriptor: ()Ljava/util/List;

Tier 2 — `verifyApiSignatures`: generic signature comparison

The erased-descriptor check has a blind spot. Java/Kotlin generics are erased at bytecode level: List<OldType> and List<NewType> both compile to Ljava/util/List;. The JVM links the call successfully in both cases — but the caller may receive elements of an unexpected type and get a ClassCastException later at the use site.

Real-world case — mcp-steroid#18: StatusBarEx.getBackgroundProcessModels() changed its return type from List<com.intellij.openapi.util.Pair<TaskInfo, ProgressModel>> to List<kotlin.Pair<TaskInfo, ProgressModel>> between IJ 261 and IJ 262. Both types erase to ()Ljava/util/List; — identical JVM descriptor. The plugin compiled, linked, and passed every standard check. At runtime on IJ 262, iterating the list and accessing .first/.second on elements assumed to be c.i.o.u.Pair threw a ClassCastException. Plugin Verifier does not catch this (confirmed from source at commit 1d14a2b: it resolves methods by erased descriptor only; Signature attributes are parsed for display in error messages but never compared for compatibility).

The JVM class file format stores the un-erased generic type in a separate Signature attribute alongside the descriptor. This attribute is what the Kotlin compiler uses to reconstruct generic types for type checking, but the JVM itself ignores it for method dispatch.

The solution is a two-phase workflow:

Capture (run once against the base IJ version, commit the result):

./gradlew :ij-plugin:ij-253-k22:captureApiSignatures

For every method and field call site in the plugin, this looks up the member in the IJ 253 SDK and records its Signature attribute into ij-plugin/api-signatures.txt:

METHOD  com.intellij.util.containers.ContainerUtil#map  (Ljava/util/Collection;...)Ljava/util/List;  (Ljava/util/Collection<TT;>;...)Ljava/util/List<TR;>;
FIELD   com.intellij.openapi.util.Pair#first             Ljava/lang/Object;                           NONE

NONE means no Signature attribute — a raw or primitive type, nothing to compare.

Verify (runs on every ./gradlew check for all versions):

For each entry in the snapshot, looks up the same (owner, name, erased-descriptor) in the current SDK and compares Signature attributes. A change that passes verifyClassRefs (same erased descriptor) but changes the generic parameter is caught here:

[verifyApiSignatures-261] GENERIC SIGNATURE CHANGED:
  METHOD com.intellij.Foo#getItems ()Ljava/util/List;
    was : ()Ljava/util/List<Lcom/example/OldType;>;
    now : ()Ljava/util/List<Ljava/lang/String;>;
    → METHOD com.intellij.Foo#getItems ()Ljava/util/List;

The last line is the ready-to-paste entry for signature-exceptions.txt if you have verified the change is safe at your call sites. Known-safe changes accumulate there over time; everything else is a build failure.

The Gradle wiring in each version subproject:

// ij-NNN-kXY/build.gradle.kts
val snapshotFile   = parent!!.projectDir.resolve("api-signatures.txt")
val exceptionsFile = parent!!.projectDir.resolve("signature-exceptions.txt")
val compileCP      = configurations.named("compileClasspath")

val verifyApiSignatures by tasks.registering(JavaExec::class) {
    val reportOut = layout.buildDirectory.file("reports/verify-api-signatures-$ijMajor.txt")
    outputs.file(reportOut)
    argumentProviders.add(CommandLineArgumentProvider {
        buildList {
            add("--mode"); add("verify")
            compileCP.get().files.forEach { add("--classpath"); add(it.absolutePath) }
            add("--snapshot");   add(snapshotFile.absolutePath)
            if (exceptionsFile.exists()) { add("--exceptions"); add(exceptionsFile.absolutePath) }
            add("--report"); add(reportOut.get().asFile.absolutePath)
        }
    })
    onlyIf { snapshotFile.exists() }
}
tasks.named("check") { dependsOn(verifyClassRefs, verifyApiSignatures) }

What this still cannot catch: a Signature attribute that was null in both SDK versions (method returning a raw List with no generics at all). There is nothing to compare. This is not a regression — the call was already unchecked by the compiler. The only tool that would catch such type changes is recompilation against the new SDK, which is exactly what the multi-subproject build (Option 1) provides.

Tier 3 — Plugin Verifier: full JLS binary compatibility

Plugin Verifier (verifyPlugin task from IJPGP) is the most thorough check. It verifies binary compatibility against the full JVM specification: access modifiers, method overrides, interface contracts, deprecated/removed members.

It covers cases the bytecode-ASM tiers do not:

Access narrowed: a method changed from public to protected or internal — the erased descriptor is identical, the Signature attribute unchanged, but the JVM throws IllegalAccessError at the call site
Abstract method added to an interface your plugin implements: the plugin class is now missing a required implementation — AbstractMethodError at runtime
@ApiStatus.ScheduledForRemoval warnings: flags APIs your plugin uses that will be removed in a future IJ version, before they actually disappear

What Plugin Verifier cannot catch — confirmed from source (cloned at commit 1d14a2b):

MethodResolver.kt resolves every method call using name + erased descriptor only — the matching predicate at every call site is it.name == methodName && it.descriptor == methodDescriptor (lines 160, 172, 184, 216, 381, 391). The JVM Signature attribute (which carries the un-erased generic types) is exposed on the Method interface but only ever read in LocationsPresentation.kt — to produce human-readable error message text, never to detect an incompatibility. TypeInstructionVerifier.kt handles CHECKCAST by resolving the target class for existence only; there is no safety check on what the cast might actually receive.

The companion ide-diff-builder tool (which computes @ApiStatus.AvailableSince changelogs between two IDE builds) has the same gap: ApiDiffBuilder.kt line 48 keys methods on it.name + it.descriptor — erased descriptor only. ApiSignature.MethodSignature stores the generic signature: String? field, but no ApiEvent subclass for a signature change exists (ApiEvent.kt), and no code ever compares the field between old and new SDK.

Known pitfall with EAP builds: pluginVerification { ides { recommended() } } silently resolves to zero IDEs when sinceBuild targets an unreleased platform. IJPGP v2.12.0 (issue #2090) added a warning, but the check is still skipped. Always verify that the resolved IDE list is non-empty when running against EAP builds.

Comparison

	`verifyClassRefs`	`verifyApiSignatures`	Plugin Verifier
Class removed	✓	✓ (via snapshot MISSING)	✓
Method/field removed	✓	✓	✓
Return/param type changed (erased, e.g. `Pair`→`kotlin.Pair`)	✓	✓	✓
Generic param changed (`List<A>`→`List<B>`, same erased descriptor)	✗	✓ ← unique value	✗ (uses erased descriptors only; `Signature` attributes read for display, never compared)
Access modifier narrowed	✗	✗	✓
Abstract method added	✗	✗	✓
`@ScheduledForRemoval` warnings	✗	✗	✓
Classpath source	Already-resolved `compileClasspath`	Already-resolved `compileClasspath`	`local(intellijPlatform.platformPath.toFile())` (no extra download) or downloads separate IDE
Wired to `./gradlew check`	Yes	Yes	No (requires explicit `tasks.check { dependsOn("verifyPlugin") }`)
Cold-start speed	Seconds	Seconds	~5–15 s with local SDK; 10–20 min if downloading
Requires snapshot file	No	Yes (run `captureApiSignatures` once against base SDK)	No

The intended usage: verifyClassRefs and verifyApiSignatures run on every build as a fast first gate. Plugin Verifier runs in CI pre-release (or on demand) as the thorough audit. A failure in the fast gate is a definite bug. A clean fast gate with a Plugin Verifier failure means an access or override issue — the rarer category.

mcp-steroid#18 is the concrete case that motivated Tier 2: getBackgroundProcessModels() changing from List<c.i.o.u.Pair> to List<kotlin.Pair> passes both verifyClassRefs and Plugin Verifier (same erased descriptor ()Ljava/util/List;; cast target class still exists). verifyApiSignatures catches it by comparing Signature attributes — the unique capability verified against Plugin Verifier source code.

Build Issues I Hit Along the Way

These affect any IJ plugin on IJPGP 2.x with Gradle 9.4. Worth knowing before you hit them.

Missing mavenCentral() in repositories {}

intellijPlatform { defaultRepositories() } adds JetBrains repositories only. KGP 2.3.0’s kotlin-build-tools-compat and kotlin-build-tools-impl live on Maven Central. Build fails with a confusing message:

Could not resolve kotlin-build-tools-compat:2.3.0.
No repositories are defined for configuration ':ij-253-k22:compileClasspath'.

Fix: add mavenCentral() at the outer repositories {} level, not inside intellijPlatform {}:

repositories {
    maven { url = uri("https://cache-redirector.jetbrains.com/maven-central") }
    mavenCentral()
    intellijPlatform {
        defaultRepositories()
        snapshots()
    }
}

patchPluginXml → linkSources dependency missing (Gradle 9.4 strict mode)

The IJ Platform Gradle Plugin’s patchPluginXml resolves plugin.xml from source roots that are populated by linkSources. Gradle 9.4 strict task-dependency validation rejects this:

Task 'patchPluginXml' uses output of task 'linkSources' without declaring an explicit dependency.

Fix:

tasks.matching { it.name == "patchPluginXml" }.configureEach { dependsOn(linkSources) }

kotlin.stdlib.default.dependency=false breaks filename-based stdlib detection

This property prevents KGP from adding kotlin-stdlib-X.Y.Z.jar to compileClasspath as a standalone artifact. It is required for IJ plugins (otherwise you bundle stdlib alongside the bundled one), but it breaks any task that finds the Kotlin version by searching compileClasspath for a file matching kotlin-stdlib*.jar. The stdlib lives inside the bundled Kotlin plugin JARs in the IJ SDK — not as a recognizable standalone JAR.

Note: for standalone application modules that are NOT IJ plugins (like check-class-refs), you need implementation(kotlin("stdlib")) explicitly, because this property applies globally and those modules do need their own stdlib.

Scoring Summary

Approach	Compile Safety	Build Simplicity	CI Speed	Dev Speed	Maintenance	mcp-steroid fit	Total
1 — Multi-subproject + symlinks	5	2	3	3	3	2	18
2 — Branch per version	2	4	3	5	1	1	16
3 — Reflection	1	5	5	5	2	1	19 ❌
4 — Shims / typed adapters	3	3	4	4	3	3	20
5 — Template build scripts	4	4	3	3	4	2	20
6 — HTTP API in IJ (long-term)	5	5	5	5	5	2	27 ⏳
7 — Docker compat tests	3	5	3	5	5	5	26 ✅
single-invocation (JetBrains internal)	3	4	4	5	4	3	23

Dimensions scored 1–5: Compile-time safety (do API breakages surface at build time across all supported versions?), Build simplicity (cognitive load to add a new IJ version), CI speed on warm cache, Dev loop speed for ./gradlew build, Maintenance per new IJ major, and fit for MCP Steroid’s current single-project structure.

What JetBrains Could Do Better

A prominent, versioned Kotlin compatibility matrix: The information exists in IJPGP’s PlatformKotlinVersions map and on the using-kotlin.html page, but the map was missing 261 until IJPGP v2.12.0 — causing cryptic failures for everyone targeting 261 EAP. A prominently linked table that stays ahead of each EAP release would save many hours.

A multi-version build template: The IntelliJ Platform Plugin Template is excellent for single-version plugins. A companion template showing the single-invocation approach or the Docker compat-test approach would let teams start from a working multi-version structure rather than improvising from scattered blog posts.

Plugin Verifier wired to check by default: Plugin Verifier is the most thorough binary compat check available, but it requires explicit invocation. The silent failure of recommended() against unreleased platforms — where verification appears to pass but zero IDEs were checked — means many plugins ship without ever running the tool. Making it a default-on gate (with the resolved-IDEs warning visible) would catch more regressions earlier.

Where to Start

Different teams come to this problem from different starting points.

Building a new plugin from scratch: Start with Option 7 — Docker build compatibility tests. Zero migration cost, CI coverage across your target versions from day one. When tests surface a specific API divergence, add an Option 4 shim for that API only. Use Option 5 template build scripts to keep each version’s build.gradle.kts readable top-to-bottom.

Existing single-version plugin expanding to additional IDE versions: Option 7 is the lowest-friction path. The main build stays unchanged — you are adding CI visibility, not restructuring the project. Option 4 shims come next, reactively, as Docker tests fail.

Already on a multi-subproject setup: The PoC documents specific gaps worth watching — the checkVersionCoverage task for version range completeness, the ByteBuddy class-ref verifier as a fast ./gradlew check gate, and the Gradle 9.4 strict-mode dependency issues that affect any multi-project build upgrading to Gradle 9.x.

What I Am Doing for MCP Steroid

Short-term:

Ship Option 7 — the Docker compat tests. Already implemented as a pending change. Zero migration cost; the main build stays fast; IJ 2025.3, 2026.1, and 2026.2 EAP are covered.
Pin K2.3 for IJ 261 builds — explicitly set kotlinVersion = "2.3.20" when -Pmcp.platform.version=2026.1. The checkBundledKotlinCompatibility task catches mismatches.
Option 4 reactively — if the Docker tests surface a specific API break, add a shim for that API only. listProjectWindows is the first candidate. No pre-built shims for hypothetical future breaks.
Keep moving logic to the CLI — every feature migrated from ij-plugin/ to kotlin-cli/ or mcp-core/ removes a class of version-compatibility problem. The plugin becomes thinner; the version-sensitive surface shrinks. Option 6 is a year away, but the architectural direction is correct and every step toward it pays off now.

The multi-version PoC is at github.com/jonnyzzz/ij-multi-version. MCP Steroid is at github.com/JetBrains/mcp-steroid.

Building an IJ plugin that spans multiple major IDE versions? I hope this saves you some time. Reach out on LinkedIn or GitHub if something here needs correcting, you need my help, or if you have found a better approach.

Booting NVIDIA Jetson AGX Thor: Headless, from macOS, via Serial Console

2026-04-09T00:00:00+00:00

A small, heavy box arrived at the desk. Inside: an NVIDIA Jetson AGX Thor Developer Kit. No monitor. No keyboard. No display port handy. The task: flash JetPack 7.0, configure it headlessly from macOS, and get Docker and Tailscale running. Simple enough on paper.

It turns out there is one non-obvious failure mode that is not well documented. The OOBE wizard — the first-boot configuration screen — does not appear on the serial port you expect. NVIDIA’s own forum has a thread about it. After hitting the same wall, we worked through the workaround. This post is the reference we wish had existed.

The Hardware

The Jetson AGX Thor Developer Kit carries the T5000 SoM with a Blackwell GPU — the same architecture as the DGX Spark (GB10). The core specs that matter for AI workloads are strikingly close between the two boxes:

Component	Jetson AGX Thor (T5000)	DGX Spark (GB10)
GPU architecture	Blackwell	Grace Blackwell
Unified memory	128 GB LPDDR5x	128 GB LPDDR5x
Memory bandwidth	276 GB/s	273 GB/s
AI performance	1,035 TOPS (FP8)	1,000 TOPS
CPU	14-core Arm Neoverse	20-core Arm (Cortex-X925/A725)
Power	40–130 W	~60 W
Price	$3,499	$4,699
Primary target	Edge / robotics / physical AI	Desktop LLM inference

The 128 GB unified memory is the number that matters most for LLM inference — it determines the maximum model size you can load. Both boxes hold the same amount, so they can run similarly-sized models. Compute performance is also in the same range.

Where they differ: the DGX Spark has a stronger CPU subsystem and its software stack (JetPack included) is more tuned for large model serving out of the box. The Thor is built for edge deployment — robotics, physical AI, sensor pipelines — with different peripherals (GPIO, camera inputs, QSFP28 networking) and a wider power envelope (up to 130 W peak, as low as 40 W idle). Think of the Spark as a desktop inference server; the Thor as a compute node that ships inside a robot or a rack at the edge.

For our purposes — running inference workloads on a local GPU node — the Thor is a perfectly capable alternative to the Spark, and at $1,200 less.

After the software setup below, the Thor we configured looks like this:

Component	Detail
Device	NVIDIA Jetson AGX Thor Developer Kit (T5000 SoM)
OS	Ubuntu 24.04.3 LTS
Kernel	6.8.12-tegra
Jetson Linux (L4T)	R38, REVISION 4.0
NVIDIA Driver	580.00
CUDA	13.0

The I/O side of the board has a row of ports. From left to right (roughly): two USB-A 3.2 ports, USB-C 5a (recovery mode, PD Sink 140W), USB-C 5b (data, PD Sink 140W), DisplayPort, HDMI, an RJ45 at 5 Gbps, and a QSFP28 quad-port at 25 Gbps each. Behind the magnetic lid cover on the top of the device: the Debug-USB port, the one with the serial console.

That lid cover is where the setup begins.

Prerequisites

USB flash drive, 16 GB or larger (we used a 61.5 GB SanDisk)
Mac with ≥25 GB free storage
USB-C cable (one is enough)
picocom installed: brew install picocom
The JetPack ISO (3.9 GB download, see below)

Step 1: Download the ISO

curl -L -o jetson-thor-r38.4.iso \
  "https://developer.nvidia.com/downloads/embedded/L4T/r38_Release_v4.0/release/jetsoninstaller-r38.4.0-2025-12-30-17-00-37-arm64.iso"
# 3.9 GB, 4,207,276,032 bytes

The ISO is on NVIDIA’s JetPack downloads page.

Step 2: Write the ISO to USB (macOS)

diskutil list external  # find your USB drive, e.g. /dev/disk4
diskutil unmountDisk /dev/disk4
sudo dd if=jetson-thor-r38.4.iso of=/dev/rdisk4 bs=4m
diskutil eject /dev/disk4

We wrote 4,207,276,032 bytes in 45.7 seconds (~92 MB/s). After dd completes, macOS will show a dialog: “The disk you inserted was not readable.” Click Eject or Ignore — the Jetson ISO9660 filesystem is not macOS-compatible by design. The USB stick is fine.

Step 3: Connect the Serial Console

Open the magnetic lid cover on the top of the Thor (see the picture above). Connect a USB-C cable from your Mac to the Debug-USB port inside.

macOS exposes four serial devices for this port. Different boot stages use different ones:

macOS device suffix	Boot stage	Notes
`/dev/cu.usbmodem…B4`	UEFI / GRUB menu	This is the interactive one
`/dev/cu.usbmodem…B2`	Kernel dmesg	Useful to watch progress
`/dev/cu.usbmodem…B?`	Other subsystems	Usually quiet during install

Open two terminal tabs:

# Tab 1 — GRUB and UEFI interaction
picocom -b 115200 /dev/cu.usbmodemTOPOA735A12B4

# Tab 2 — kernel messages
picocom -b 115200 /dev/cu.usbmodemTOPOA735A12B2

Your device names will differ from ours — the TOPOA735A12 part comes from the board serial number. Use ls /dev/cu.usbmodem* to see what appeared after connecting the cable.

To exit picocom when you are done: Ctrl-A, then Ctrl-X. Set your terminal size to 242×61 for proper display — especially relevant during the OOBE wizard later.

Two notes from hard experience:

/dev/cu.debug-console does not work for any stage. Ignore it.
screen has reliability issues with these devices. Use picocom.

Step 4: Boot from USB and Flash to NVMe

Insert the USB stick into one of the USB-A ports on the I/O side of the Thor
Power on (press the power button)
In Tab 1 (B4): press Enter at the pre-boot prompt, wait for the GRUB menu
In the GRUB menu, select: “Flash Jetson AGX Thor Developer Kit on NVMe r38.4.0”

The GRUB menu also offers a “USB” flash target — do not use that. It installs onto the USB stick itself, not the internal NVMe SSD.

After you confirm the selection, switch to Tab 2 (B2). The kernel will print boot messages for a minute, then go silent. That silence lasts about 10 minutes. This is the actual installation. The installer output goes to ttyUTC0 (a hardware UART, not accessible from the USB serial ports), so there is nothing to watch. This is normal. Do not power-cycle.

Installation is complete when Tab 2 shows:

[   12.260117] nvidia-modeset: WARNING: HW supports 8 heads. Limiting to 4 heads
[   12.260117] Please complete NVIDIA OOBE on the serial port provided by Jetson's USB device mode connection. e.g.
  /dev/ttyACMx where x can 0, 1, 2 etc.

Note the ttyACMx hint in the message — that is a Linux device path. On macOS there is no ttyACM. Ignore that hint. The correct macOS device appears after the cable swap below.

Remove the USB stick. Do not power off yet.

Step 5: The OOBE Trap

This is the part that caught us. The message above says to complete OOBE on “the serial port provided by Jetson’s USB device mode connection.” On the Debug-USB port (the one behind the lid), the OOBE wizard does not appear. Nothing shows. You wait. Still nothing.

This is a known JetPack 7.0 limitation. NVIDIA has acknowledged it on the developer forum (thread here) with a fix targeted for 7.1. The workaround:

Disconnect the USB-C cable from the Debug-USB port (behind the lid)
Reconnect the same cable to the USB-C port 5b on the I/O side (the middle USB-C port, next to the two USB-A ports)
A new tty device appears on macOS. It keeps the same board-serial prefix as the Debug-USB devices but with a different suffix — on our board it was B6:
```
ls /dev/tty.usbmodem*    # find the new device
picocom -b 115200 /dev/tty.usbmodemTOPOA735A12B6
```
The OOBE wizard appears in text mode

Step through the wizard:

Accept the EULA
Create a user account
Set the hostname
Configure network — select enP2p1s0 for the RJ45 Ethernet
Set timezone

After completing OOBE the device reboots into a fresh Ubuntu 24.04.3 system.

Step 6: SSH Setup

Once the device is on the network, set up key-based SSH from macOS so you never need the serial console again.

# Generate a dedicated key
ssh-keygen -t ed25519 -f ~/.ssh/thor-04 -N "" -C "jonnyzzz@thor-04"

# Upload the key (first time needs the password)
expect <<'EXPECT'
set pub [exec cat ~/.ssh/thor-04.pub]
spawn ssh -o StrictHostKeyChecking=no -o PubkeyAuthentication=no jetbrains@thor-04 \
  "mkdir -p ~/.ssh && echo '$pub' >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
expect "*assword*"
send "jetbrains\r"
expect eof
EXPECT

Add to ~/.ssh/config:

Host thor-04 thor-04.local
    HostName thor-04
    User jetbrains
    IdentityFile ~/.ssh/thor-04
    IdentitiesOnly yes

Test it: ssh thor-04 should land you at a Linux thor-04 6.8.12-tegra aarch64 prompt without a password.

Step 7: Post-Install Configuration

With SSH working, the rest is straightforward over the network:

Passwordless sudo:

ssh thor-04
sudo usermod -aG sudo jetbrains
echo "jetbrains ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/jetbrains

Basic tools:

sudo apt-get install -y curl mc vim

Tailscale (if you want the device on your VPN):

curl -fsSL https://tailscale.com/install.sh | sh

Docker:

sudo apt-get update && sudo apt-get install -y docker.io
sudo usermod -aG docker jetbrains
sudo systemctl enable docker && sudo systemctl restart docker

After a logout/login cycle, docker ps works without sudo. We got Docker 29.1.3.

UEFI and ISO Compatibility

One more thing worth knowing before you try to reinstall later. There is a UEFI version dependency between the ISO revision and the firmware on the board:

UEFI Version	ISO r38.2	ISO r38.4	Notes
r38.0.0 (factory)	Yes	Yes	No settings change needed
r38.2.x	Yes	Yes	Enable Display Handoff mode before USB
r38.4.x	No	Yes	Cannot downgrade to an older ISO

If you flashed once with r38.4.x and want to reinstall: you must use the r38.4 ISO. Downgrading the UEFI is not supported.

For reinstalls with UEFI r38.2.x, before inserting the USB stick, go into: UEFI → Device Manager → NVIDIA Configuration → Boot Configuration → SOC Display Hand-Off Mode → “Auto”, Method → “efifb”.

What Came Out the Other Side

After following this path, the Thor is running:

Ubuntu 24.04.3 LTS, kernel 6.8.12-tegra
CUDA 13.0, NVIDIA driver 580.00
Docker 29.1.3
Tailscale, SSH key auth, passwordless sudo

The device is now a GPU node on our local network. Next: run inference workloads on it. The Jetson AGX Thor with its NVIDIA Thor GPU and unified memory is a different beast from the DGX Spark we covered in earlier posts — smaller footprint, ARM architecture, different memory model. The setup experience surfaced a few quirks specific to JetPack 7.0 that we have not seen documented well elsewhere.

If you run into the OOBE freeze, check the USB-C port. That one confused us for a while.

Questions or corrections: reach me on LinkedIn or X.

IntelliJ as a Skill Factory

2026-04-08T00:00:00+00:00

Every time your agent needs to use an IntelliJ API it hasn’t seen before, it burns tokens figuring out PSI trees and threading rules. It tries something, gets a compilation error, tries again, gets a wrong result, tries a third time. Eventually it works. Then the next agent – or the same agent in a new session – starts the whole cycle over.

I open-sourced MCP Steroid yesterday. That post covered the what and why. This one is about the pattern that makes the plugin actually useful day to day: skills.

Two Islands

Here’s how I think about the problem. There are two islands.

Island one is the IDE world. IntelliJ platform has deep code understanding – control flow graphs, cross-language refactorings, structural search, a debugger, Gradle integration, Spring Integration, and the long-tail more of the features. It’s an extraordinary amount of engineering. But it was all built for humans clicking menus. IntelliJ IDEs ship with a built-in MCP server since 2025.2, but it exposes a curated, fixed set of operations – file edits, run configurations, basic code actions. A start, but not the full picture.

Island two is the agentic world. AI agents that can reason, plan, iterate, and write code – but they’re stuck either running grep and sed, or limited to predefined tool menus, never touching the real depth of what the IDE already knows about the codebase.

MCP Steroid bridges them fully. An agent sends Kotlin through steroid_execute_code, and that code runs inside the IDE’s JVM with full access to everything IntelliJ knows. Not a curated subset. Not a fixed menu. The actual APIs that power the IDE’s own features. No abstractions skipped.

The Skill Factory

Here’s the workflow that changed how I use the plugin.

Phase one: research. The agent experiments with IntelliJ APIs via steroid_execute_code. It tries things, fails, iterates. This phase is messy – maybe 4-8 retries, a lot of tokens spent on compilation errors and wrong API assumptions – including JVM classloading quirks that trip up even experienced developers. That’s fine. The agent is learning.

At that phase Agent uses the 60+ resources that are already included into the MCP Steroid package. For really complex tasks, I also recommend adding the IntelliJ Community sources and the sources of your third-party plugins and ask the agent to conduct the research there as well.

Phase two: encapsulation. Once the agent figures out how to solve the problem, the working approach gets wrapped into a reusable skill – a Kotlin snippet stored as a markdown document. Now any agent can call it without re-discovering the API surface.

That’s the skill factory. Each solved problem becomes a skill. Skills accumulate. The agent that struggled for 8 retries to find deprecated methods with zero usages? Next time it takes one call.

The MCP Steroid repo ships with built-in articles that serve a dual purpose – they’re documentation for you, and reference material that agents read to create new skills. When your agent needs to figure out VFS or the debugger API, it reads these articles just like you would. Check the docs for the full set.

Why Skills, Not Plugin Code

Here’s what makes skills compelling: writing a skill is one markdown file with a Kotlin code snippet. Writing the same capability as traditional plugin code means a Gradle project, extension points, build infrastructure, and a full development cycle. Skills skip all of that – the agent handles compilation, threading, and iteration for you. You just need to point it in the right direction.

This also works well with sub-agent architectures. A parent agent can delegate a specific task to a sub-agent that reads only the relevant skill documentation from MCP resources. The sub-agent iterates until it works, and the parent’s context stays clean. This is how I run it in practice – the orchestrator picks the skill, the worker executes it.

Example: A Complete Skill

Here’s a working skill that finds all TODO comments in a project:

import com.intellij.psi.search.PsiSearchHelper
import com.intellij.psi.search.GlobalSearchScope

val todoItems = readAction {
    val searchHelper = PsiSearchHelper.getInstance(project)
    val result = mutableListOf<String>()
    searchHelper.processCommentsContainingIdentifier("TODO", GlobalSearchScope.projectScope(project)) { comment ->
        result.add("${comment.containingFile.virtualFile.path}: ${comment.text.trim()}")
        true
    }
    result
}
todoItems.forEach { println(it) }

An agent sends this through steroid_execute_code and gets back every TODO comment with its file path. No plugin development, no Gradle project, no build infrastructure. One snippet, one call.

This is the kind of thing that takes an agent 4-8 retries to discover the first time – PsiSearchHelper isn’t obvious, the GlobalSearchScope parameter is easy to miss, and readAction is required for PSI access. Once it’s a skill, every future agent gets it in one shot.

Enterprise: Your Own Skills

Even if you’re behind an enterprise firewall with proprietary IntelliJ plugins and internal APIs, you can create skills that wrap your own extensions. Your agent doesn’t need to know the internals of your company’s custom inspection plugin – it just calls the skill.

This is deliberately the same pattern. Open-source skills for the public IntelliJ APIs, private skills for your internal tooling. A team can build up a skill library for their specific codebase and workflows, and every agent on the team benefits.

What’s Next

The immediate focus is skill coverage. More documented API patterns, more worked examples, more pre-built skills. The goal is to shrink the research phase for common tasks until it’s nearly zero.

Longer term, I want to explore event-driven skills. IntelliJ already has APIs for subscribing to events – a commit happens, a test fails, an inspection fires. An agent that reacts to those events automatically, running the right skill in response, would be genuinely useful. The event APIs exist. We haven’t wired them into MCP Steroid yet.

And headless support – running the plugin in Docker containers, in CI – is an active investment. We already test MCP servers with real agents in Docker. Agents don’t always need a GUI, and we want MCP Steroid to work without one. That requires packaging work that JetBrains infrastructure makes possible.

Get Involved

The best way to contribute to MCP Steroid is to create a skill. Pick an IDE capability you use manually – navigate to declaration, find all usages of a deprecated API, list failing tests with their stack traces, whatever is useful in your workflow. Point your agent at it. Let it figure out the API. When it works, save the Kotlin as a skill file and open a pull request.

Star and fork the repository to get started: github.com/jonnyzzz/mcp-steroid (original source) and github.com/JetBrains/mcp-steroid (JetBrains fork). The docs have worked examples, and the Discord is where the community is building up.

You don’t need to be an IntelliJ platform expert. The agent does the API exploration. You need to know what IDE capability you want to expose – the rest is iteration.

Try It

According to the MCP Steroid strategy, we start from an explicit plugin for IntelliJ-based IDEs and Android Studio. The long-term target is a headless, self-contained runtime – the IDE for AI agents without the UI. But you can use it today.

You’ll need any IntelliJ-based IDE or Android Studio (version 2025.3+). Install the plugin from GitHub Releases – JetBrains Marketplace listing is coming soon. Once started, the plugin generates .idea/mcp-steroid.md in your project with instructions. Follow those to register the MCP Server with your agent. The server uses the Streamable HTTP protocol.

PoC Program

We’re opening a PoC program for companies that want MCP Steroid customized for their use cases – internal skills, proprietary API integrations, team-specific workflows. If that’s interesting, reach out to me on LinkedIn.

MCP Steroid Is Now Open Source

2026-04-07T00:00:00+00:00

MCP Steroid is now open source under the Apache 2.0 license. The source is at github.com/jonnyzzz/mcp-steroid, with the project transitioning under JetBrains at github.com/JetBrains/mcp-steroid.

The Bridge

AI Agents can think. They cannot always act. The gap between what agents can reason about and what they can actually do inside a codebase – that’s the bottleneck I’ve been working on.

I build products where the AI Agent is the user. No UI – APIs, CLIs, MCPs. People keep designing products for humans with AI bolted on. I’m doing the opposite: we make JetBrains tools available for AI agents, not for humans.

IntelliJ-based IDEs have shipped with a built-in MCP server since 2025.2 – curated tools for common operations like running configurations, file edits, and basic code actions. Useful, but fixed.

MCP Steroid is different. It gives AI Agents the ability to write and execute arbitrary Kotlin code against the full IntelliJ Platform API. Not a predefined menu of operations – the actual APIs that power the IDE’s own features: inspections, refactorings, the debugger, PSI trees, screenshots. It can access any plugins and third-party extensions too! AI Agents get the whole IDE, not a curated subset. On DPAI Arena benchmarks, agents with MCP Steroid are 20-54% faster on tasks requiring semantic understanding – 54% on rename-refactoring across 9 files, 20% on multi-layer generation across 15 files. Simple text replacements show no improvement, which is expected.

I wrote more about this framing in Agentic Experience and Tools and in the original MCP Steroid post.

How It Got Here

I started MCP Steroid in December 2025 as a free-time experiment – one engineer building a Bridge between AI Agents and IntelliJ’s APIs. It was built with AI agents. The project uses MCP Steroid itself plus a run-agent.sh swarm for development. The main effort went into evals and integration tests – making sure agents actually succeed at real tasks, not just compile. MCP Steroid plugin learned from its one development too.

The codebase has 84 prompt markdown files – 37% of production source by line count – that teach agents how to navigate IntelliJ APIs: the debugger, refactorings, inspections, test runners, VCS. Just like JetBrains IDEs make software developers more professional, these resources make AI agents more professional. There are integration tests for Claude Code, Codex, and Gemini, all running in Docker with full IDE containers.

We validated that AI Agents can write and call Kotlin code to solve specific tasks with the help of IntelliJ. This is quality work and a real experiment with 1,690 commits over four months, not a rough prototype – see the project assessment at 75 days for the earlier snapshot.

In March 2026, we agreed to move the project under JetBrains and start using it internally. The original source is at github.com/jonnyzzz/mcp-steroid, with the JetBrains fork at github.com/JetBrains/mcp-steroid, released under Apache 2.0. I’m still the main contributor.

Skills – a Tease

The real value isn’t individual API calls. It’s that solved problems accumulate into reusable skills. An agent struggles through IntelliJ’s API once, figures out the working approach, and that approach gets wrapped into a skill any agent can call without re-discovering the surface.

The skill prototyping process has become magnitude times cheaper – make an agent research the IntelliJ Community and figure out how to solve your task. Then, turn it as a skill which uses the MCP Steroid plugin. Eval it.

I’ve got a dedicated post about the skill factory coming next – with code examples, the two-phase workflow, and the enterprise angle. For now: think of it as the difference between giving an agent a tool and giving it a way to build its own tools.

Try It

According to our strategy, we start from an explicit plugin for IntelliJ-based IDEs (including any third-party IDEs, e.g. Android Studio). The long-term target is a headless self-contained runtime – available as SaaS and as an end-user product – the headless IDE for AI Agents. The project requires investment into packaging for headless environments, and that’s where JetBrains infrastructure matters.

To get started today: install the MCP Steroid plugin in any IntelliJ-based IDE or Android Studio (version 2025.3+). The plugin generates .idea/mcp-steroid.md in your project with instructions. Follow those instructions to register the MCP Server with your agent. The server uses the Streamable HTTP protocol.

Quick sanity check – ask your agent to run a Kotlin code like println(project.name) or ask it “What do I see in my IDE”

See it in action: YouTube playlist, and here’s Codex debugging an application in IntelliJ IDEA.

Get Involved

The project is open source, and the community is just getting started. If you’ve explored IntelliJ APIs, built agents, or solved IDE automation problems – that knowledge is useful here.

Star and fork the repository. The original source is at github.com/jonnyzzz/mcp-steroid and the JetBrains fork is at github.com/JetBrains/mcp-steroid. Fork it, experiment with it, write a skill, open an issue, improve the docs. Contributions of any kind are welcome.

You can just try the plugin, download it from the website or from JetBrains Marketplace (soon). Share what you build, and join the Discord.

What’s Next

With JetBrains infrastructure, support, and investment, I believe MCP Steroid will be delivered sooner and enable AI Agents of any kind with the best tools human developers love in IntelliJ-based products.

The skill factory post is coming tomorrow. And if you’re wondering what happens when the plugin ZIP exceeds 180 MB, the 413 post covers that. We’re also opening a proof-of-concept program for companies that want to use MCP Steroid for their specific workflows. If that’s interesting, reach out on LinkedIn or in the Discord.

Agentic Experience and Tools: My Program

2026-03-24T00:00:00+00:00

AI Agents can think. They cannot always act. I build the bridges between agent intelligence and the real-world tools that agents cannot reach.

I have spent twenty+ years at JetBrains making software developers more productive. I started IDE Services from zero, grew it to 500+ enterprise customers, and handed it to the team. I have given fifty-plus talks on developer tooling around the world. I am a founder – I create products, take them from inception to stable results, and move on to the next thing. That is what drives me.

In late 2025 I saw a shift. AI Agents crossed a threshold. They could read code, reason about architecture, propose changes, write tests, iterate on feedback, deploy services. The intelligence was there.

But agents live in a world of tokens and text. Our development infrastructure – IDEs, CI pipelines, code review systems, debuggers – lives in the human world. Agents cannot run your IDE’s thousand inspections. They cannot trigger your CI pipeline. They cannot start a debugger. They cannot navigate your code review system or debug your GUI app.

The gap between what agents can think and what they can do is the defining bottleneck of this era. I am building the bridges that close it.

I call this domain Agentic Experience & Tools. For me, I work in that domain and in the scope of exiting old products, where Agentic Experience and Tools are the most challenging to deliver.

The Mission: Agentic Experience & Tools

I make AI Agents more effective at solving problems on real-world projects by building the missing connections between agents and existing tools, processes, and infrastructure – including optimizing how agents work together, which models they use, and how they learn from their own runs.

The AI Agent is not an implementation detail. It is the user, and the product persona. The human is the stakeholder.

The biggest misconception I see: people keep designing products for humans with AI tools bolted on. I am doing the opposite. I build products intended directly for agentic usage. No UX, no UI in the traditional sense – APIs, CLIs, MCPs, and structured outputs that agents consume natively. Humans buy and install these tools to improve the performance metrics of their agents. Later, other AI Agents may do the buying too.

Only agents can validate what is actually better for agents. So I use an agentic learning process: agents define the evaluation, run it, and self-improve based on collected data. When I built the MCP Steroid debugger, one agent ran the debug task through IntelliJ while another reviewed the logs and rewrote the prompts. Multiple times. After iterations, the agent went from failing – falling back to screenshots just to see what was happening – to solving the debug task on the first attempt. That is the kind of improvement I am after: measurable, agent-validated, compounding.

I do not compete with AI Agents. I make every agent better. Whatever your team already uses – Claude, Codex, Gemini, Junie, Cursor, Augment, Kilo – my tools remove the walls between that agent and your development infrastructure. I integrate with all of them. I replace none of them. When there is no AI Agents in use, I enable them.

The Agentic Loop

Agents need real-world feedback: build the code, run the tests, deploy to staging. Once these loops are established, agents iterate on their own, improving quality with each pass.

The principle: agents follow the same processes as humans. No shortcuts. No special agent-only paths. That is what makes the output trustworthy. The human decides how much autonomy to grant, and signs off on the result.

What Is Still Broken

Agents cannot react to events yet. Today, a human kicks off agent runs. Agents should wake up automatically when a CI build fails, a code review gets comments, or a merge pipeline completes. I am looking for design partners to implement event-driven workflows.

Setup takes too long. Configuring the full stack is a 30-minute process. The goal is one Docker command to start.

Agents do not learn enough from failures. Every agent run generates telemetry. That data should feed back automatically – agents reporting problems to other agents that fix them.

What I Have Built

I have built a portfolio of tools that address different parts of the gap:

MCP Steroid gives agents access to the full IntelliJ IDE runtime – inspections, refactorings, debugger, screenshots. On DPAIA benchmarks, agents with MCP Steroid are 20-54% faster on tasks requiring semantic understanding and multi-file refactoring. It works with Claude, Codex, Gemini, Cursor, and any MCP client. See it in action: the demo playlist includes debugger integration, monorepo deep dives, and more. Try it on your IDE today.

run-agent.sh orchestrates agent swarms with full isolation and traceability – up to 16 agents in parallel, coordinating through an append-only message bus.

RLM decomposes tasks that exceed one context window into sub-agent work.

Dedicated posts about each are coming.

Find the Others

I am looking for the people who are actually doing this – not theorizing, not pitching, but deploying agents on real codebases and hitting real walls.

If your agents are stuck – they can generate code but cannot get it reviewed, tested, merged, or deployed – I want to hear about it. That is the exact gap I work on.

If you are building tools that agents use, I want to compare notes. What works, what breaks, what the models still cannot do.

Join the conversation and follow me on LinkedIn – that is where most of the discussion happens.

Andrej Karpathy on the No Priors podcast (March 2026):

Just I think everything, like so many things, even if they don’t work, I think to a large extent you feel like it’s a skill issue. It’s not that the capability is not there; it’s that you just haven’t found a way to string together what’s available. Like, I didn’t give good enough instructions to the agents.

The agents are capable.

The bridges are missing. I build them. Reach out on LinkedIn or X.

run-agent.sh v2.0: Hardened Runner with 115 Tests, Random Selection, and Agent Environment Contract

2026-03-17T00:00:00+00:00

I’ve been running AI Agents in parallel for weeks — Claude Code, Codex, Gemini — and the launcher script that ties them together kept accumulating rough edges. Stale PID files after crashes. No tests. No help output. And, as three AI reviewers independently discovered, a command injection vulnerability hiding in plain sight.

Today I’m releasing run-agent.sh v2.0 — a major rewrite that fixes all of that.

The script started as a quick 95-line wrapper. It now weighs in at 211 lines, backed by 115 acceptance tests, random agent selection, and a proper environment contract for every spawned agent.

What is run-agent.sh?

run-agent.sh enables you agents to start more agent processes for sub-tasks. That plays nice with Recursive Language Models (RLM.md), or THE_PROMPT_v5.md swarms, where you use more agents. In simple words, running multiple agents allows each agent to do fewer things at once via delegation, delivering better outcomes, while avoiding the context rot or overflow.

As an example, use the prompt like

<PUT YOUR TASK DESCRIPTION HERE>

In order to deliver on the task, you should use https://run-agent.jonnyzzz.com/run-agent.sh script
to start more tasks. You should follow the https://run-agent.jonnyzzz.com/THE_PROMPT_v5.md and
other files relative to it as the main process. Your purpose is to orchestrate and delegate
the work to other run-agent's which you start, you must not do the work yourself.
So create /loop when necessary to monitor the process. Never stop unless the work is completed.

All your promots should use the https://run-agent.jonnyzzz.com/MESSAGE-BUS.md as the key
communication principle. 

Make sure you download the files locally and use the full paths to the files below.

run-agent.sh is a unified shell script that launches AI coding agents in isolated sub-processes, with selected current directories. Each invocation creates a timestamped folder with the prompt copy, captured stdout/stderr, process metadata, and a copy of the runner itself — full traceability for every agent execution.

This is the tool for AI Agents to help consolidate and coupe with the work more effectively

./run-agent.sh claude ~/Work/project ./task-prompt.md

It powers the marinade agentic orchestration framework, where a root AI Agent spawns sub-agents in parallel.

Random agent selection

One thing I noticed while orchestrating multi-agent runs: I kept manually rotating between agents to diversify the results. That felt like a job for the script, not for me.

The default agent is now any — the script picks a random agent from the available pool:

./run-agent.sh any ~/Work/project ./prompt.md
# AGENT_SELECTED=gemini
# RUN_ID=run_20260317-134514-27961
# RUN_DIR=./runs/run_20260317-134514-27961

This is useful when you want to let agents compete or diversify across runs. When combined with RUN_AGENT_AGENTS, the random selection respects the restricted pool:

# Set at the environment level
export RUN_AGENT_AGENTS=claude,codex

# The actual call
./run-agent.sh any ~/Work/project ./prompt.md
# Never picks gemini

Agent availability control

A new environment variable RUN_AGENT_AGENTS controls which agents are available. Agents not in the list are rejected and hidden from --help:

# Only claude and codex are available
RUN_AGENT_AGENTS=claude,codex ./run-agent.sh gemini ...
# stderr: Unknown agent: gemini
# stderr: Known agents: claude,codex
# exit 2

Invalid names in the list are caught at startup:

RUN_AGENT_AGENTS=claude,fakename ./run-agent.sh claude ...
# stderr: RUN_AGENT_AGENTS: unknown agent 'fakename'. Built-in agents: codex,claude,gemini
# exit 2

Environment contract

Before this release, agents had to guess paths or rely on convention. Now every agent gets four exported environment variables — no guesswork:

Variable	Value
`RUNS_DIR`	Absolute path to the runs directory
`MESSAGE_BUS`	Absolute path to `MESSAGE-BUS.md` (now inside `RUNS_DIR`)
`RUN_ID`	Unique run identifier (e.g., `run_20260317-134514-27961`)
`PROMPT`	Absolute path to the copied prompt file

Every agent knows exactly where it is, where to write messages, and what run it belongs to.

Additionally, CLAUDECODE is explicitly unset before spawning — preventing nested Claude Code runtime context from leaking into sub-agents. I learned this the hard way: a Claude Code sub-agent was picking up its parent’s runtime state and behaving differently than when launched standalone.

115 acceptance tests, zero API keys

The test suite uses mock agent stubs — small bash scripts that simulate claude, codex, and gemini without making any API calls. The full suite runs in under 10 seconds:

$ bash tests/test-run-agent.sh
=== run-agent.sh Acceptance Tests ===
--- Test 1: Script structure ---
  PASS: run-agent.sh is executable
  PASS: run-agent.sh has bash shebang
  PASS: run-agent.sh uses set -euo pipefail
...
=== Test Results ===
  PASSED: 115
  FAILED: 0
RESULT: PASS (all 115 tests passed)

The tests cover what matters:

Prompt delivery: a mock agent that cats stdin, verifying prompt content reaches the agent
CLI arguments: a mock that echoes "$@", verifying --permission-mode, -C, etc.
CWD with spaces: creates a directory with spaces, runs an agent, checks pwd output
Injection rejection: passes $(echo pwned), foo;bar, ../etc as agent names — all exit 2
Environment exports: mock agents print $RUN_ID, $PROMPT, $MESSAGE_BUS — verified against expected values
CLAUDECODE sanitization: sets CLAUDECODE=should_be_removed, verifies agent sees it unset
cwd.txt correctness: checks not just key presence but actual values (absolute paths, numeric PID, matching RUN_ID)
Help side effects: verifies --help creates no run directories

The three-agent review also identified tests that were “vacuously true” — tests that would pass even if the behavior they claimed to test was broken. For example, test 15 originally grepped the script source for export MESSAGE_BUS instead of verifying the agent process actually received the variable. That is the kind of bug that hides in plain sight until someone (or some agent) asks the right question.

The exit code bug

This one was subtle. The original script had set -euo pipefail and then:

wait "$AGENT_PID"
EXIT_CODE=$?
rm -f "$PID_FILE"
echo "EXIT_CODE=$EXIT_CODE" >> "$CWD_FILE"

When an agent exited non-zero, set -e caused the script to bail at wait before cleaning up pid.txt or recording EXIT_CODE. Monitoring scripts that checked pid.txt would think the agent was still running. I spent more time than I’d like to admit debugging “zombie” agents that were actually long dead. The fix:

EXIT_CODE=0
wait "$AGENT_PID" || EXIT_CODE=$?
rm -f "$PID_FILE"
echo "EXIT_CODE=$EXIT_CODE" >> "$CWD_FILE"

The || EXIT_CODE=$? captures the non-zero exit code without triggering set -e. Standard bash idiom, but easy to miss when you write the happy path first.

CI/CD

Two GitHub Actions workflows keep the project honest:

Tests — runs all 115 acceptance tests on every push
Deploy — syncs static files, builds the site, deploys to GitHub Pages

Every push to main makes the latest run-agent.sh available at run-agent.jonnyzzz.com/run-agent.sh.

What’s next

The script is battle-tested for the orchestration use case, but I want to push it into real, established projects — not just greenfield AI experiments. That will likely surface new requirements and rough edges.

Concrete plans:

Integration tests with real agents — mock stubs catch regressions, but they cannot catch API-level breakage. I want a CI job that actually calls each agent with a trivial prompt and verifies end-to-end behavior.
Streaming output — right now stdout/stderr are captured to files. For long-running agents, tailing the output and progress would help to tell a suck agent from a thinking one.
More agents — the case statement makes it trivial to add new ones. If you use a different AI coding tool, open a PR.

There’s still so much more we can do. If you run multi-agent orchestration or have ideas for what the runner should handle, I would love to hear about it. Reach out on LinkedIn or Twitter/X.

The release is at github.com/jonnyzzz/run-agent/releases/tag/v2.0.0. The script is at run-agent.jonnyzzz.com.

From Voice Memos to Searchable Text with Local Whisper on macOS

2026-02-28T00:00:00+00:00

I record voice memos constantly – ideas during walks, meeting notes, random thoughts at 2 AM. The macOS and mainly watchOS Voice Memos app is perfect for capture, but terrible for retrieval. You can’t search recordings. You can’t grep audio. Those ideas just sit there, locked in .m4a files, slowly becoming irrelevant.

The obvious solution is transcription. Cloud services like Otter.ai or Whisper API do this well – but they cost money, require internet, and send your private voice recordings to someone else’s servers. For notes about work projects, product ideas, and personal reflections, that’s a non-starter.

So I built a pipeline that runs entirely on a MacBook. It pulls recordings from Voice Memos via AppleScript, transcribes them with Whisper running locally on Apple Silicon, and outputs searchable markdown files. No cloud. No API keys. No subscriptions.

Want to skip the explanation and just run it? The “Putting It All Together” section has a complete, copy-paste-and-uv run script. The production version with state management and CLI options lives in my internal repository.

Why LocaAI Transcription Matters

Before diving into the code, here’s why this matters beyond privacy:

No recurring cost. Cloud transcription services charge per minute of audio. A 30-minute daily voice memo habit costs $15–50/month. Local inference costs electricity.
Works offline. On planes, in tunnels, in countries with restricted internet – your transcription pipeline doesn’t care.
No data leaves your machine. Voice memos often contain sensitive content: product ideas, performance reviews, personal reflections. Local processing keeps it local.
Unlimited volume. No API rate limits, no monthly quotas. Transcribe your entire archive overnight.

The catch? You need an Apple Silicon Mac with enough RAM, and the first-time model download is ~1.6 GB. After that, everything runs locally.

System Requirements

Here’s what you need to run this pipeline. I’ve tested it on an M1 MacBook Air (16 GB) and an M4 Max MacBook Pro (128 GB):

Component	Requirement
Mac	Apple Silicon (M1, M2, M3, M4 – any variant)
RAM	16 GB, 32 GB+ recommended
Disk	~1.6 GB for the model + ~1 MB per hour of recordings
macOS	Sequoia 15.x (tested); Sonoma 14.x likely works
Python	3.11+
uv	Latest (astral.sh/uv)
ffmpeg	Required by mlx-whisper (`brew install ffmpeg`)
Accessibility	Terminal must have Accessibility permission

The Whisper large-v3-turbo model runs comfortably on an M1 with 16 GB. On an M4 Max, it transcribes roughly 10x faster than real-time – a 10-minute memo in about 60 seconds. On a base M1, expect roughly 1x real-time (1 minute of audio takes ~1 minute of processing).

The Architecture

The pipeline has two independent phases:

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Voice Memos    │     │  Export Audio    │     │  Transcribe      │
│  (macOS app)    │────▶│  (AppleScript    │────▶│  (mlx-whisper    │
│                 │     │   + clipboard)   │     │   or Ollama)     │
└─────────────────┘     └──────────────────┘     └──────────────────┘
                              │                         │
                              ▼                         ▼
                         .m4a files                .md transcripts

Phase 1: Fetch – AppleScript reads the Voice Memos sidebar, selects each recording, copies it via Cmd+C, and saves the M4A data from the clipboard to disk.

Phase 2: Transcribe – A local Whisper model converts each audio file to text. Two backends are supported: mlx-whisper (Apple Silicon native) and Ollama (more flexible, supports NVIDIA GPUs too).

Both phases are fully incremental – they skip recordings that have already been processed.

The Problem with Voice Memos (and What I Tried First)

Here’s the first challenge: macOS Voice Memos has no API. There’s no AppleScript dictionary, no command-line tool, no SQLite database you can query. Apple doesn’t expose the recordings through any documented interface.

My first attempt was to access the files directly. The recordings live under ~/Library/Group Containers/group.com.apple.VoiceMemos.shared/, in a CoreData/CloudKit-backed structure. I wrote a script that found .m4a files in there and copied them out. It worked – until iCloud sync kicked in.

My second attempt used NSSharingService through PyObjC to trigger the system share sheet. The share sheet requires user interaction for each recording. For 20+ memos, that’s 20+ clicks.

The approach that actually works is the most hacky one: UI automation via the Accessibility API. It’s ugly, it breaks when Apple changes the UI, and it requires your terminal to have Accessibility permission. But it reliably exports audio without corrupting sync state.

Before You Start

A quick checklist before running the scripts:

Grant Accessibility permission. System Settings > Privacy & Security > Accessibility – add your terminal app (Terminal.app, iTerm2, Warp, or whichever you use).
Open Voice Memos and select “All Recordings” in the sidebar.
Install prerequisites: brew install ffmpeg and install uv.
Verify Accessibility works with a test command:

osascript -e 'tell application "System Events" to get name of first process'

If this returns a process name, you’re good. If it errors, check your Accessibility settings.

Step 1: Listing Voice Memos

The first script reads the Voice Memos sidebar to discover all recordings. Voice Memos on macOS Sequoia nests its sidebar buttons 13 groups deep inside the window hierarchy. I discovered this number through trial and error with Accessibility Inspector done by AI Agent.

import subprocess


def run_applescript(script: str) -> str:
    """Run an AppleScript and return stdout."""
    proc = subprocess.run(
        ["osascript", "-"],
        input=script, text=True,
        capture_output=True, timeout=60,
    )
    if proc.returncode != 0:
        raise RuntimeError(f"osascript failed: {proc.stderr.strip()}")
    return proc.stdout.strip()


def list_voice_memos() -> list[dict]:
    # Voice Memos nests its sidebar 13 groups deep
    group_ref = "window 1"
    for _ in range(13):
        group_ref = f"group 1 of {group_ref}"

    script = f'''
tell application "VoiceMemos" to activate
delay 0.5
tell application "System Events"
    tell process "VoiceMemos"
        set theGroup to {group_ref}
        -- scroll to top so button 1 is the newest
        repeat 20 times
            perform action "AXScrollUpByPage" of theGroup
        end repeat
        delay 0.3

        set btnCount to count of buttons of theGroup
        set results to {{}}
        repeat with i from 1 to btnCount
            set btnRef to button i of theGroup
            set btnName to ""
            set btnDate to ""
            try
                set btnName to value of text field 1 of group 1 of btnRef
            end try
            try
                set btnDesc to description of btnRef
                if btnDesc contains ", " then
                    set AppleScript's text item delimiters to ", "
                    set descParts to text items of btnDesc
                    set AppleScript's text item delimiters to ""
                    if (count of descParts) > 1 then
                        set btnDate to item 2 of descParts
                    end if
                end if
            end try
            if btnName is not "" then
                copy (i as text) & tab & btnName & tab ¬
                    & btnDate to end of results
            end if
        end repeat
        set AppleScript's text item delimiters to linefeed
        return results as text
    end tell
end tell
'''
    items = []
    for line in run_applescript(script).splitlines():
        parts = line.strip().split("\t")
        if len(parts) >= 2:
            items.append({
                "position": int(parts[0]),
                "name": parts[1].strip(),
                "date": parts[2].strip() if len(parts) > 2 else "",
            })
    return items

A few things to note:

Scrolling to top first is essential. Without it, the button indices don’t correspond to the visible items, and you get stale data from offscreen elements.
The recording date comes from the button’s description attribute, not a separate text field. It’s embedded after the name, separated by a comma.
The 13-group depth is specific to macOS Sequoia (15.x). Earlier macOS versions may have different nesting depths. Use Accessibility Inspector (/Applications/Utilities/) to check.

Step 2: Exporting Audio via Clipboard

The next challenge: getting the audio data out. There’s no osascript command to save a Voice Memo to a file. But Cmd+C in Voice Memos copies the audio data to the clipboard – including the raw M4A bytes.

def select_and_copy(name: str, ui_delay: float = 0.5) -> None:
    """Find a recording by name, select it, and Cmd+C."""
    group_ref = "window 1"
    for _ in range(13):
        group_ref = f"group 1 of {group_ref}"

    escaped = name.replace("\\", "\\\\").replace('"', '\\"')
    script = f'''
tell application "VoiceMemos" to activate
delay {ui_delay}
tell application "System Events"
    tell process "VoiceMemos"
        set theGroup to {group_ref}
        set btnCount to count of buttons of theGroup
        repeat with i from 1 to btnCount
            set btnRef to button i of theGroup
            set btnName to ""
            try
                set btnName to value of text field 1 of group 1 of btnRef
            end try
            if btnName is "{escaped}" then
                perform action "AXPress" of btnRef
                delay {ui_delay * 2}
                keystroke "c" using command down
                delay {ui_delay}
                return "ok"
            end if
        end repeat
    end tell
end tell
return "not-found"
'''
    result = run_applescript(script)
    if result != "ok":
        raise RuntimeError(f"Recording not found: {name}")

Then save the clipboard audio data directly to an M4A file:

from pathlib import Path


def save_clipboard_audio(target_path: Path) -> int:
    """Save M4A audio data from clipboard to file. Returns bytes."""
    target_path.parent.mkdir(parents=True, exist_ok=True)
    escaped = str(target_path).replace('"', '\\"')

    script = f'''
set theData to the clipboard as «class M4A »
set thePath to POSIX file "{escaped}"
set theFile to open for access thePath with write permission
write theData to theFile
close access theFile
return "ok"
'''
    run_applescript(script)
    return target_path.stat().st_size

The magic here is the clipboard as «class M4A ». AppleScript’s clipboard can hold typed data, and Voice Memos puts the audio in the M4A class. The «class» syntax is AppleScript’s way of referencing four-character type codes. This avoids the Finder entirely – no drag-and-drop simulation, no save dialogs, just direct clipboard-to-file transfer.

Step 3: Transcription with mlx-whisper

Now for the AI part. mlx-whisper is a port of OpenAI’s Whisper to Apple’s MLX framework, which runs inference directly on the Apple Silicon GPU and Neural Engine. It’s significantly faster than running Whisper through PyTorch on the same hardware.

The script uses PEP 723 inline metadata, so uv run handles dependencies automatically – no virtual environment setup needed:

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "mlx-whisper>=0.4",
# ]
# ///

import sys
from pathlib import Path

# HuggingFace repo ID (auto-downloaded on first run, ~1.6 GB)
MODEL = "mlx-community/whisper-large-v3-turbo"


def transcribe(audio_file: Path, language: str | None = None) -> str:
    """Transcribe audio using mlx-whisper on Apple Silicon."""
    import mlx_whisper

    result = mlx_whisper.transcribe(
        str(audio_file),
        path_or_hf_repo=MODEL,
        language=language,
    )
    return result.get("text", "").strip()


if __name__ == "__main__":
    audio = Path(sys.argv[1])
    print(transcribe(audio))

Save this as transcribe.py and run:

uv run transcribe.py recording.m4a

On first run, uv creates an isolated environment, installs mlx-whisper and its dependencies, and downloads the model from HuggingFace. Subsequent runs reuse the cached environment and model. The PEP 723 # /// script block tells uv exactly which dependencies are needed – no requirements.txt, no pyproject.toml, just the script itself.

Why mlx-whisper?

Three reasons:

Speed. On an M4 Max, whisper-large-v3-turbo transcribes ~10x faster than real-time. A 10-minute memo takes under 60 seconds. On an M1, it’s roughly 1x real-time.
Memory efficiency. MLX uses unified memory, so the model loads directly into GPU-accessible RAM. No copying between CPU and GPU memory.
Zero configuration. No server to run. No Docker container. No GPU drivers. Import the library, call one function, get text.

The Model: whisper-large-v3-turbo

The whisper-large-v3-turbo model is a distilled version of Whisper large-v3 that’s ~4x faster with minimal quality loss. It supports 99 languages out of the box. The MLX-optimized version is hosted at mlx-community/whisper-large-v3-turbo on HuggingFace.

Property	Value
Model size	~1.6 GB (FP16)
Parameters	809M
Languages	99
Architecture	Encoder-decoder transformer (distilled)
Speed (M1)	~1x real-time
Speed (M4 Max)	~10x real-time

Alternative: Transcription with Ollama

If you prefer a server-based approach – or want to use an NVIDIA GPU – Ollama also supports Whisper models. This is useful if you already run Ollama for LLM inference and want a single tool for everything.

# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.32"]
# ///

import mimetypes
from pathlib import Path
import requests

OLLAMA_URL = "http://127.0.0.1:11434"
# Ollama uses short model names (no HuggingFace org prefix)
OLLAMA_MODEL = "whisper-large-v3-turbo"


def transcribe_with_ollama(
    audio_file: Path,
    model: str = OLLAMA_MODEL,
    language: str | None = None,
    timeout: int = 300,
) -> str:
    """Transcribe audio via local Ollama Whisper API."""
    mime = mimetypes.guess_type(audio_file.name)[0] \
        or "application/octet-stream"

    for endpoint in ["/v1/audio/transcriptions", "/api/transcribe"]:
        data = {"model": model}
        if language:
            data["language"] = language
        try:
            with audio_file.open("rb") as f:
                resp = requests.post(
                    f"{OLLAMA_URL}{endpoint}",
                    data=data,
                    files={"file": (audio_file.name, f, mime)},
                    timeout=timeout,
                )
            if resp.ok:
                text = resp.json().get("text", "").strip()
                if text:
                    return text
        except requests.RequestException:
            continue

    raise RuntimeError(f"Transcription failed for {audio_file}")

To set up Ollama for Whisper:

# Install Ollama (https://ollama.com)
ollama pull whisper-large-v3-turbo
ollama serve  # Starts on port 11434

The Ollama approach tries two API endpoints: the OpenAI-compatible /v1/audio/transcriptions and Ollama’s native /api/transcribe. Note that Whisper support in Ollama is relatively new and endpoint availability may vary between versions – I tested with Ollama 0.6.x. If one endpoint fails, the script falls back to the other.

It also supports a language fallback chain – try auto-detect first, then fall back to specific languages:

LANGUAGES = [None, "ru", "en"]  # auto -> Russian -> English

text = ""
for lang in LANGUAGES:
    try:
        text = transcribe_with_ollama(audio, language=lang)
        break
    except RuntimeError:
        continue

This is particularly useful for multilingual recordings. I record memos in both English and Russian, and the auto-detect works well for about 90% of cases. The fallback chain catches the rest.

mlx-whisper vs Ollama: When to Use Which

Factor	mlx-whisper	Ollama
Setup	`uv run` – zero config	Install Ollama + pull model
Platform	Apple Silicon only	macOS, Linux, Windows
GPU	Apple Neural Engine / GPU	Apple GPU, NVIDIA CUDA
Server required	No	Yes (ollama serve)
Speed (M4 Max)	~10x real-time	~6-8x real-time
Best for	MacBook-only pipelines	Multi-platform, existing Ollama

My recommendation: use mlx-whisper for a pure-Mac setup. Use Ollama if you already run it for LLM inference or need NVIDIA GPU support.

Putting It All Together

Here’s the complete pipeline as a single uv run-able script. It lists memos, exports audio, and transcribes – all in one pass:

#!/usr/bin/env python3
"""Voice memo transcription pipeline. Run: uv run pipeline.py"""

# /// script
# requires-python = ">=3.11"
# dependencies = ["mlx-whisper>=0.4"]
# ///

import subprocess
from pathlib import Path

OUTPUT_DIR = Path("voice-memos")
MODEL = "mlx-community/whisper-large-v3-turbo"


def run_applescript(script: str) -> str:
    proc = subprocess.run(
        ["osascript", "-"], input=script, text=True,
        capture_output=True, timeout=60,
    )
    if proc.returncode != 0:
        raise RuntimeError(proc.stderr.strip())
    return proc.stdout.strip()


def list_memos() -> list[dict]:
    group_ref = "window 1"
    for _ in range(13):
        group_ref = f"group 1 of {group_ref}"
    script = f'''
tell application "VoiceMemos" to activate
delay 0.5
tell application "System Events"
    tell process "VoiceMemos"
        set theGroup to {group_ref}
        repeat 20 times
            perform action "AXScrollUpByPage" of theGroup
        end repeat
        delay 0.3
        set btnCount to count of buttons of theGroup
        set results to {{}}
        repeat with i from 1 to btnCount
            set btnRef to button i of theGroup
            set btnName to ""
            try
                set btnName to value of text field 1 of ¬
                    group 1 of btnRef
            end try
            if btnName is not "" then
                copy (i as text) & tab & btnName to end of results
            end if
        end repeat
        set AppleScript's text item delimiters to linefeed
        return results as text
    end tell
end tell
'''
    return [
        {"position": int(p[0]), "name": p[1]}
        for line in run_applescript(script).splitlines()
        if (p := line.strip().split("\t")) and len(p) >= 2
    ]


def export_memo(name: str) -> Path:
    group_ref = "window 1"
    for _ in range(13):
        group_ref = f"group 1 of {group_ref}"
    escaped_name = name.replace('"', '\\"')

    run_applescript(f'''
tell application "VoiceMemos" to activate
delay 0.5
tell application "System Events"
    tell process "VoiceMemos"
        set theGroup to {group_ref}
        set btnCount to count of buttons of theGroup
        repeat with i from 1 to btnCount
            set btnRef to button i of theGroup
            try
                if value of text field 1 of group 1 of btnRef ¬
                    is "{escaped_name}" then
                    perform action "AXPress" of btnRef
                    delay 1
                    keystroke "c" using command down
                    delay 0.5
                    exit repeat
                end if
            end try
        end repeat
    end tell
end tell
''')

    output = OUTPUT_DIR / f"{name}.m4a"
    output.parent.mkdir(parents=True, exist_ok=True)
    escaped_path = str(output).replace('"', '\\"')
    run_applescript(f'''
set theData to the clipboard as \u00ABclass M4A \u00BB
set f to open for access (POSIX file "{escaped_path}") ¬
    with write permission
write theData to f
close access f
''')
    return output


def transcribe(audio: Path) -> str:
    import mlx_whisper
    result = mlx_whisper.transcribe(
        str(audio), path_or_hf_repo=MODEL
    )
    return result.get("text", "").strip()


def main():
    OUTPUT_DIR.mkdir(exist_ok=True)
    memos = list_memos()
    print(f"Found {len(memos)} voice memo(s)\n")

    for memo in memos:
        name = memo["name"]
        audio = OUTPUT_DIR / f"{name}.m4a"
        transcript = audio.with_suffix(".md")

        # Skip if already transcribed
        if transcript.exists():
            print(f"  Skip (exists): {name}")
            continue

        print(f"  Export: {name}")
        export_memo(name)

        print(f"  Transcribe: {name}")
        text = transcribe(audio)
        # Simple output; the production version adds YAML frontmatter
        transcript.write_text(f"# {name}\n\n{text}\n")
        print(f"  Done: {len(text):,} chars\n")


if __name__ == "__main__":
    main()

Run it:

uv run pipeline.py

First run downloads the Whisper model (~1.6 GB). After that, it processes your entire voice memo library incrementally – skipping recordings that already have transcripts.

Making It Incremental

The production version of this pipeline adds proper state management. A state.json file tracks which recordings have been fetched and transcribed, when, and with which model:

{
  "version": 4,
  "target_map": {
    "voice-memo-2026-02-13-recording-26": {
      "voice_memo_name": "Recording 26",
      "voice_memo_recording_date_iso": "2026-02-13",
      "target_audio": "voice-memo-2026-02-13.../Recording 26.m4a",
      "status": "success"
    }
  },
  "records": [
    {
      "kind": "transcribe",
      "audio": "voice-memo-2026.../Recording 26.m4a",
      "model": "whisper-large-v3-turbo",
      "language": "en",
      "status": "success",
      "transcript_chars": 8889
    }
  ]
}

This enables:

Skip-if-done – don’t re-transcribe recordings that haven’t changed.
Date cutoffs – only process recordings from the last N days or after a specific date.
Audit trail – see exactly when each recording was processed and with which model.
Model upgrades – when a better Whisper version comes out, force re-transcription with --force and compare results.

The Output: Searchable Markdown

Each transcript is saved as a markdown file with YAML frontmatter, compatible with Obsidian, Logseq, or any markdown-based knowledge system:

---
created: 2026-02-13
source: "[[Recording 26.m4a]]"
model: mlx-community/whisper-large-v3-turbo
tags:
  - voice-memo
  - transcript
---

# Recording 26

The transcript text appears here. Whisper adds punctuation
and capitalization automatically, which makes the output
surprisingly readable for raw speech-to-text.

Now you can grep your voice memos. Search for that product idea from three weeks ago. Find the meeting where someone mentioned that deadline. Your voice recordings become part of your searchable knowledge base.

Practical Tips

After running this pipeline on 20+ recordings, here are the things I learned:

UI Automation Is Fragile

AppleScript UI automation breaks when macOS updates change the accessibility tree. The 13-group depth for Voice Memos is specific to macOS Sequoia. Keep Accessibility Inspector handy for debugging – it shows the exact hierarchy.

Tip: Add configurable delays between UI actions. On slower machines or when the system is busy, the default 0.5-second delay isn’t enough. The production script uses --ui-delay to tune this.

When Things Go Wrong

A few failure modes I’ve encountered and how the production script handles them:

Clipboard contains text, not audio. If the memo selection fails, Cmd+C copies the name as text. The script checks whether the clipboard matches the expected memo name before saving. If it does, that means the audio wasn’t copied – retry.
Accessibility permission revoked. macOS occasionally resets Accessibility permissions after system updates. The script will fail with a cryptic AppleScript error. Check System Settings first.
Duplicate memo names. Voice Memos allows multiple recordings with the same name. The production script includes the recording date in the folder name (voice-memo-2026-02-13-recording-26/) to avoid collisions.
Model download fails. The first mlx-whisper run downloads ~1.6 GB from HuggingFace. If the download is interrupted, delete the HuggingFace cache (~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-turbo/) and try again.

Multi-Language Support

Whisper handles language detection automatically, but it’s not perfect. For recordings that mix languages (common if you’re multilingual), a fallback chain helps:

LANGUAGES = [None, "ru", "en"]  # auto -> Russian -> English

for lang in LANGUAGES:
    try:
        text = transcribe(audio, language=lang)
        if text:
            break
    except RuntimeError:
        continue

Try auto-detect first. If it fails or produces garbage, force a specific language. This catches about 95% of cases in my experience.

Run It Overnight

The first run through a large library takes time. Whisper large-v3-turbo on an M1 processes audio at roughly 1x real-time. If you have 10 hours of recordings, that’s 10 hours of processing. Queue it up before bed:

# The production script supports --since for date filtering:
uv run scripts/fetch_voice_memos.py --since 2025-01-01 2>&1 | tee transcription.log

Subsequent runs only process new recordings and finish in seconds.

Keep the Original Audio

Always keep the .m4a files alongside the transcripts. Whisper is good, but not perfect – especially for technical jargon, proper nouns, and domain-specific vocabulary. Having the original audio lets you spot-check and correct errors.

What This Enables

Once your voice memos are searchable text, interesting workflows emerge:

Daily review. I skim yesterday’s transcripts over morning coffee. Last week, I recovered a product architecture idea I’d completely forgotten about from a 3-minute walk recording.
Knowledge base. Import transcripts into Obsidian and link them to projects, people, ideas.
LLM summarization. Feed transcripts to a local LLM (via Ollama) for summaries, action items, or topic extraction. A 30-minute brainstorm session becomes a 10-line summary in seconds.
Semantic search. Index transcripts in a vector database (pgvector, Chroma) for similarity search across your entire recording history.

The pipeline from voice memo to searchable, AI-processable text is the starting point. What you build on top is where it gets interesting.

The Bigger Picture: Building a Personal Knowledge Base

This voice memo pipeline is one piece of a larger system I’m building – a fully local personal knowledge base. The transcripts land in an Obsidian vault alongside meeting notes, bookmarks, annotated PDFs, and research clippings. Multiple scripts and AI models work together to manage, update, and connect this growing collection.

The architecture behind it:

Voice memos get transcribed by Whisper (this post) and stored as markdown.
A RAG pipeline indexes all markdown files into a pgvector database – chunked, embedded, and searchable by semantic similarity. When I need to find “that idea about caching from last month,” I query the RAG system instead of grepping through hundreds of files.
Multiple AI scripts maintain the knowledge base: one summarizes long transcripts, another extracts action items, a third generates topic tags and cross-links between related notes.
Everything runs locally on the MacBook. For the broader knowledge base I use Ollama, which handles both Whisper transcription and LLM inference for summarization under one server. For the standalone voice memo pipeline in this article, mlx-whisper is the simpler choice. The vector database runs in a Docker container with pgvector.

The core insight: AI is most useful when it automates your personal routines, not just code generation. Transcription is a mundane task that took zero creativity but consumed real time. Now it runs in the background while I sleep. Summarization, tagging, and cross-linking happen automatically. The knowledge base grows and organizes itself.

That’s the kind of Local AI use case that justifies the hardware investment – not benchmarks, not leaderboards, but saving 30 minutes a day on something you actually do.

I’m planning to write more about this system. Next up: either the RAG pipeline with pgvector or the Obsidian integration and auto-tagging. If one of these interests you more – let me know. Ping me on LinkedIn or Twitter/X. Your questions genuinely help me prioritize what to write next.

References

OpenAI Whisper – the original speech recognition model
mlx-whisper on PyPI – Apple Silicon optimized Whisper
MLX framework – Apple’s machine learning framework for Apple Silicon
mlx-community/whisper-large-v3-turbo – the HuggingFace model
Ollama – local LLM and Whisper inference server
uv – fast Python package manager by Astral
PEP 723 – inline script metadata for self-contained Python scripts
Obsidian – markdown-based knowledge management

Have questions about running this on your hardware? Found a bug? Reach out on LinkedIn or Twitter/X.

MCP Steroid Project Assessment: 75 Days, 1300+ Commits, One Plugin

2026-02-23T00:00:00+00:00

I decided to take a step back and look at what has been built so far.

MCP Steroid started on December 10, 2025. It is an IntelliJ Platform plugin that exposes the full IDE JVM runtime to AI Agents via the Model Context Protocol. Instead of reading and writing files, agents can compile code, run inspections, trigger refactorings, use the debugger, and take screenshots – all through one MCP tool that executes Kotlin inside the IDE’s JVM – a much more flexible, powerful, and minimalistic API an AI Agent can use.

75 days later, the numbers tell an interesting story.

The numbers

Metric	Value
Total commits	1,306
Active development days	52 of 75 (69% utilization)
Avg commits per active day	~25
Production Kotlin LOC	27,505
Test Kotlin LOC	110,482
Test-to-production ratio	4:1
Gradle submodules	8
Releases	3 (0.87.0, 0.88.0, 0.89.0)

The 4:1 test-to-production ratio is not an accident. The Docker-based integration tests launch a full IntelliJ IDE in a container, connect real AI Agents (Claude Code, Codex, Gemini CLI), and verify end-to-end MCP workflows. Arena tests run curated project benchmarks comparing agent performance with and without the plugin.

Architecture highlights

The core execution pipeline follows a two-phase design: compile first with an external kotlinc process, then run the compiled code inside the IDE’s JVM with coroutine-based timeout enforcement. This separation means agents get compilation errors immediately without waiting for execution.

A few technical decisions that turned out well:

Modal dialog race detection – Kotlin select{} races script execution against IDE dialog appearance. If a dialog pops up mid-execution, the script cancels and a screenshot goes back to the agent.
External Kotlin compiler isolation – agent scripts cannot starve the IDE’s own Kotlin daemon. The plugin recovers automatically when the daemon dies.
Transport-agnostic MCP core – the JSON-RPC dispatcher has zero HTTP dependencies. The Ktor transport layer is pluggable.
Append-only execution storage – every script, compilation output, and result is stored as an immutable audit trail under .idea/mcp-steroid/.

Quality scorecard

Dimension	Score
Code Organization	9/10
Error Handling	9/10
Test Coverage	8.5/10
Architectural Sophistication	9/10
Coroutine Patterns	9.5/10
IntelliJ Platform Integration	9/10
Extensibility	9/10
Overall	8.8/10

Zero runBlocking() in production code. Proper readAction{}/writeAction{} threading. ProcessCanceledException always rethrown. IntelliJ service model used correctly throughout.

What makes this unique

MCP Steroid is the only product that gives AI Agents visual IDE access – screenshots with component trees, keyboard and mouse input dispatch, OCR integration. Agents operate at the same level of semantic understanding that the IDE itself uses: type-aware symbol search, real inspections, IDE-native refactorings, live test results.

The plugin works with Claude Code, OpenAI Codex, and Google Gemini CLI today. Human-in-the-loop review gates are configurable per project.

Where it is heading

Multi-IDE support is already underway (GoLand, WebStorm). The NPX proxy aggregates multiple IDE instances. The arena benchmarking framework measures agent quality across curated project scenarios. Enterprise deployment works via a custom plugin repository.

Update: v0.89.0 released

Three days after this assessment, version 0.89.0 shipped – 361 commits since 0.88.0.

Key highlights:

Codex agent output support – full NDJSON format handling for OpenAI Codex, including mcp_tool_call items, structured results, and reasoning blocks. Raw and decoded agent logs are saved per prompt run.
Prompt system overhaul – all prompt articles migrated to single-file .md format with auto-generated TOC and per-article read tests.
DPAIA arena testing – Docker-based A/B comparison framework that measures agent effectiveness with and without MCP Steroid on curated project scenarios.
Settings UI – new project settings page under Tools > MCP Steroid with copy buttons and structured connection info.
Claude Code 2.1.x compatibility – handles both old streaming and new structured event formats.
Stability fixes – resolved an 8-minute startup deadlock in Docker containers, fixed onboarding dialogs blocking test runs, and several NPE fixes.

Full release notes: v0.89.0 on the MCP Steroid site.

AI Agents can debug now

The debugger integration is what sets MCP Steroid apart from every other AI coding tool. No other product gives AI Agents access to breakpoints, step-over, variable inspection, and expression evaluation inside a real IDE debugger.

Here is Codex debugging an application in IntelliJ IDEA, powered by MCP Steroid:

And a shorter demo showing the debugger workflow – setting breakpoints, stepping through code, evaluating expressions:

Try MCP Steroid

If you are building with AI Agents and want to give them the full IDE – not just file access, but compilation, inspections, refactorings, debugging, and visual understanding – give MCP Steroid a try.

Get started:

Install the plugin – works with Claude Code, Codex, Gemini CLI, Cursor, and any MCP-compatible agent
Download v0.89.0 or add the custom plugin repository for automatic updates

Support the development:

Sponsor on GitHub – this project needs funding to continue development, testing, and infrastructure
Join the Slack community to discuss ideas and report issues
Star the GitHub repository

Read more:

Full project assessment with architecture analysis, commit theme breakdown, and competitive positioning

Testing Your MCP Server with Real AI Agents in Docker

2026-02-21T00:00:00+00:00

The only way to know your MCP server actually works is to test it with a real AI Agent.

Unit tests can tell you whether a JSON schema is valid. Mock tests can verify your handler returns the right bytes, and can deviate from the logic. But none of them tell you whether an AI Agent will actually discover your tool, call it correctly, and do something useful with the result.

The core insight that drove our testing approach:

Tests should be assertions about the agentic loop itself – not just about individual functions. A test that passes only when a real agent, starting from a cold container, successfully discovers and calls your tool is the only test that proves the contract is real.

We built this for mcp-steroid, an MCP server that gives AI Agents deep access to IntelliJ IDEA. The server has dozens of tools. Each agent CLI handles MCP registration, tool discovery, and streaming output differently. The only way to catch regressions was to test with real agents.

So we did.

The Architecture

The test setup has three moving parts:

The MCP server runs inside the IntelliJ test process on the host machine, listening on random port, say 0.0.0.0:17820
The AI Agent runs inside a Docker container
Docker networking connects them: host.docker.internal resolves to the host from inside any container

When the test starts, it binds the MCP server to all interfaces (not just localhost), so it is reachable from the Docker network. The container gets started with --add-host=host.docker.internal:host-gateway, which maps that hostname to the host gateway address. The test then translates the MCP URL from localhost:17820 to http://host.docker.internal:17820 before handing it to the agent.

┌──────────────────────────────────────────────────────┐
│  Host machine                                        │
│                                                      │
│  JVM test process                                    │
│  ┌──────────────────────────────────────────────┐    │
│  │  IntelliJ test framework                     │    │
│  │  MCP server: 0.0.0.0:17820                   │    │
│  └──────────────────────────────────────────────┘    │
│                              ▲                       │
│                              │ host.docker.internal  │
└──────────────────────────────┼───────────────────────┘
                               │
┌──────────────────────────────┼───────────────────────┐
│  Docker container            │                       │
│                              │ HTTP/SSE              │
│  AI Agent CLI ───────────────┘                       │
│  (Claude / Codex / Gemini)                           │
└──────────────────────────────────────────────────────┘

The test class wires this together before each test:

override fun setUp() {
    // Bind server to all interfaces, not just localhost
    System.setProperty("mcp.steroid.server.host", "0.0.0.0")
    System.setProperty("mcp.steroid.server.port", "17820")
    super.setUp()
}

private fun resolveDockerUrl(): String {
    val mcpUrl = SteroidsMcpServer.getInstance().getSseUrl()
    // Replace localhost with the Docker-accessible hostname
    return mcpUrl
        .replace("localhost", "host.docker.internal")
        .replace("127.0.0.1", "host.docker.internal")
}

Each agent session lives inside a Docker container. The container starts once, receives the MCP registration command, and then runs prompts via docker exec. The container is reused across calls within a single test.

Basically, each AI Agent container starts with sleep infinity command as the entrypoint, and we use docker exec commands to start various processes inside, even IntelliJ IDEA or Git.

API Keys

The agent containers need API keys to talk to their respective model providers. We pass them as environment variables when running commands inside the container. The test harness reads the key from the environment and creates environment variables internally – ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY. The key is injected only into the docker exec call, never stored in the image. We also redact the key from all log output so it doesn’t leak into CI logs.

Claude Code – `--verbose` or You Are Flying Blind

The Dockerfiles

All three containers follow the same structure: Node.js 20 base, install the agent CLI, non-root user. The only difference is the npm package name.

FROM debian:bookworm-slim

# ── Node.js 20 via NodeSource
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        curl ca-certificates gnupg && \
    mkdir -p /etc/apt/keyrings && \
    curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \
        gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
    echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] \
          https://deb.nodesource.com/node_20.x nodistro main" \
        > /etc/apt/sources.list.d/nodesource.list && \
    apt-get update && apt-get install -y nodejs && \
    rm -rf /var/lib/apt/lists/*

# ── Agent CLI -- swap this line per agent
RUN npm install -g @anthropic-ai/claude-code   # Claude Code
RUN npm install -g @openai/codex               # Codex
RUN npm install -g @google/gemini-cli          # Gemini

# ── Non-root user for isolation
RUN useradd -m -s /bin/bash agent
USER agent
WORKDIR /home/agent

# ── Keep the container alive; commands run via docker exec
CMD ["sleep", "infinity"]

The container starts with sleep infinity and stays alive. All commands run via docker exec – the container is never restarted between calls.

MCP Registration

Before running any prompt, we register the MCP server:

claude mcp add --transport http intellij http://host.docker.internal:17820

Running a Prompt

Claude Code has a non-interactive mode (-p) with streaming JSON output:

claude \
  --permission-mode bypassPermissions \
  --tools default \
  --input-format text \
  --output-format stream-json \
  --verbose \
  -p "List the MCP tools and call steroid_list_projects"

The --output-format stream-json --verbose flags are essential. Without them, Claude only emits the final text response after the agent finishes. We want to see if the Claude process is alive, and thus the verbose output with progress messages is very essential. With them, every event streams to stdout as NDJSON (one JSON object per line) in real time: assistant messages, tool calls, tool results, token usage. This is what makes debugging tests tractable – you see exactly what the agent did.

Parsing the JSON Output

Claude Code’s stream-json format is event-driven. Tool calls are nested inside assistant message events (in the current format), and the final result event carries cost and timing:

{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll list..."}]}}
{"type":"assistant","message":{"content":[{"type":"tool_use","name":"steroid_list_projects","input":{}}]}}
{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"...","content":"..."}]}}
{"type":"result","cost_usd":0.0042,"duration_ms":3200,"num_turns":2}

We parse this with a streaming NDJSON loop that routes on type. Tool calls render as >> steroid_list_projects, tool results as << steroid_list_projects, assistant text prints as-is, and cost appears at the end. We never buffer the full output – lines are processed as they arrive.

Codex – stderr Will Fool You

MCP Registration

codex mcp add intellij --url http://host.docker.internal:17820

Running a Prompt

Codex uses the exec subcommand for non-interactive batch mode:

codex exec \
  --dangerously-bypass-approvals-and-sandbox \
  --skip-git-repo-check \
  --json \
  "List the MCP tools and call steroid_list_projects"

The --json flag makes Codex emit NDJSON to stdout. Without it, you get the interactive terminal UI – not useful inside a test. The --dangerously-bypass-approvals-and-sandbox flag disables safety confirmation prompts so the agent can run without blocking on human input.

Parsing the JSON Output

Codex’s format uses item events:

{"type":"item.started","item":{"type":"mcp_tool_call","name":"steroid_list_projects"}}
{"type":"item.completed","item":{"type":"agent_message","text":"I found the following tools..."}}
{"type":"item.completed","item":{"type":"mcp_tool_call","name":"steroid_list_projects","output":"..."}}
{"type":"turn.completed","usage":{"input_tokens":400,"output_tokens":200}}

We route on item.type. The mcp_tool_call items show us tool invocations. The agent_message items (with a flat text field) give us the assistant’s text. turn.completed shows token usage.

One thing that burned us early: Codex writes to stderr in some modes and stdout in others. In --json mode, structured events go to stdout and plain diagnostic messages go to stderr. We spent a week thinking our output filter was broken before we realized we were reading the wrong stream. We now capture both streams separately and only parse stdout as NDJSON.

Gemini – Exit Code 137 Is Actually Fine

MCP Registration

Gemini’s registration syntax is the most verbose. It requires --type http, --scope user, and --trust to avoid interactive confirmation:

gemini mcp add intellij \
  --type http \
  http://host.docker.internal:17820 \
  --scope user \
  --trust

Running a Prompt

gemini \
  --screen-reader true \
  --sandbox-mode none \
  --approval-mode yolo \
  --output-format stream-json \
  --prompt "List the MCP tools and call steroid_list_projects"

The --approval-mode yolo disables tool-use confirmation prompts. The --screen-reader true flag suppresses ANSI terminal formatting.

Note: newer Gemini CLI versions replaced --sandbox-mode none with --sandbox false. We handle this with a simple retry – if the first attempt fails with unknown arguments: sandbox-mode, we retry with --sandbox false. This keeps the tests passing across CLI version bumps without needing to pin an exact version.

Parsing the JSON Output

Gemini’s format uses typed events with field names that differ from Claude’s:

{"type":"message","role":"assistant","content":"I'll start by listing...","delta":true}
{"type":"tool_use","tool_name":"steroid_list_projects","tool_id":"tool-1","parameters":{}}
{"type":"tool_result","tool_id":"tool-1","tool_name":"steroid_list_projects","status":"success","output":"..."}
{"type":"result","status":"success","stats":{"input_tokens":800,"output_tokens":400,"tool_calls":2,"duration_ms":1200}}

A few quirks worth knowing:

message.content is a plain string, not an array – unlike Claude’s format
Tool calls use tool_name and parameters, not name and input
The result stats have separate input_tokens and output_tokens, not a combined total

One more surprise: Gemini CLI occasionally exits with code 137 (SIGKILL) even after successfully completing a request. We detect this by checking the raw NDJSON for "status":"success" and treating exit code 137 as success when that signal is present. Without this guard, valid runs fail spuriously about 5% of the time.

The Gemini API also drops the socket mid-stream on transient errors (UND_ERR_SOCKET, terminated). We retry once when we see these patterns. Transient infrastructure failures shouldn’t count as test failures.

What a Passing Test Looks Like

The test prompts the agent with explicit instructions and then asserts on the output:

fun testDiscoversSteroidTools() = timeoutRunBlocking(300.seconds) {
    val result = session.runPrompt("""
        List all MCP tools starting with "steroid_" and print each as:
        TOOL: <name> - <description>

        Then call steroid_list_projects exactly once and print the result as:
        PROJECTS: <raw JSON>
    """)
    .assertExitCode(0, "prompt")
    .assertNoErrorsInOutput(message = "prompt")

    assertTrue(result.output.contains("PROJECTS:"))
    assertTrue(result.output.contains(project.name))
    assertTrue(result.output.contains(project.basePath.toString()))
}

The structured output format (TOOL:, PROJECTS:) makes assertions mechanical. The test fails if the agent hallucinates a tool call, misreads the MCP response, or doesn’t actually invoke the tool. That is precisely the contract we want to enforce.

We run all three agents against the same test cases. This has surfaced real differences: tools with ambiguous descriptions that Claude calls correctly but Gemini mis-calls, JSON response shapes that Codex handles but another rejects, and timeout boundaries that only appear under real container-to-host network latency.

The Development Loop

Before we had these tests, adding a new MCP tool meant:

Implement the tool handler
Start IntelliJ manually, open Claude Code, hope the tool showed up
Try a prompt and see if it worked
Debug output format issues in the UI
Repeat – usually four or five times

With integration tests, the loop is:

Implement the tool handler
Run ./gradlew :ij-plugin:test --tests "*CliClaudeIntegrationTest*"
Read the test output – the full NDJSON-filtered agent transcript is there
Fix what’s broken, re-run

Faster. Reproducible. And it runs in CI without any human in the loop. It runs inside Agentic loop too.

Having real end-to-end tests with real AI Agents is the fastest feedback loop we have found for MCP server development. The 60 seconds it takes to spin up a Docker container is cheaper than the 10 minutes of manual testing it replaces.

Container Lifecycle

One infrastructure detail worth mentioning: we use a lightweight reaper container to handle cleanup. When the test JVM exits or gets killed with SIGKILL, we need all agent containers cleaned up. The reaper registers containers via a simple TCP socket protocol (container=<id> messages) and kills them all when the connection drops.

This means test runs don’t leave orphaned Docker containers even when the process is forcibly terminated during development or in CI.

What This Enables

This approach enables the Agentic Loop, the way to make your coding agents receive instant feedback from the tests. My AI Agents broke these tests multiple times, and thanks to the tests, we were able to recover/rollaback, without breaking the real production. Integration tests, and the testing itself, is the vital building block, especially when AI Agents write the most of the code.

The test harness is part of mcp-steroid. If you want to build your own MCP server for IntelliJ, the same infrastructure is available. You can write a test that starts the real IDE, registers your server, and runs a real AI Agent against it – all from a single ./gradlew test command.

We’ve used this to test over 20 distinct tools across three agent CLIs, catching dozens of issues that would have been invisible in unit tests: tools with ambiguous descriptions that agents mis-call, JSON response shapes one CLI handles but another rejects, and timeout boundaries that only show up under real network latency between host and container.

While writing tests for every tool, we also noticed something else. Some tools were so simple that the agents could have called them just as well through a shell command. That observation turned into a broader question.

MCP Is One Way

MCP Server is not the only way to give AI Agents access to your tools.

In a recent post about CLI tools for AI Agents, I wrote about how well-designed command-line interfaces are often sufficient. Agents already know how to run shell commands, parse text output, and chain calls. If your tool has a good CLI, you may not need an MCP server at all.

For mcp-steroid, MCP made sense: we need structured tool calls, streaming data, and tight IDE integration that a CLI cannot provide. But for many tools – build systems, package managers, code search, deployment pipelines – a CLI is simpler to build, simpler to test, and works with every agent out of the box.

The question to ask is not “should I build an MCP server?” but “what interface does an AI Agent need to use this tool reliably?” Sometimes that is MCP. Sometimes it is a shell command. And sometimes it is both.

If you are building an MCP server and want to share how you tested it, I’d like to hear about it – reach out on LinkedIn or Twitter.

Eugene Petrenko

IntelliJ Plugin Hot-Reload: HTTP 413

The Investigation

First Idea: Another HTTP Server

Better Solution: Pass a Local Path

Why This Is Better

The Result

Takeaways

Building an IntelliJ Plugin That Works Across Multiple IDE Versions: 7 Approaches

Table of Contents

The Problem in Concrete Terms

The Kotlin Version Coupling

You Cannot Parametrize the Kotlin Compiler in Gradle

Bundled Libraries Change Between IJ Versions

IJ Platform APIs Change Without a Stability SLA

The Seven Approaches

Option 1: Symlinks + Multiple Gradle Subprojects

Option 2: Branch per IJ Version

Option 3: Reflection

Option 4: Shims / Typed Adapters

Option 5: Template Build Scripts

Option 6: Simplify IntelliJ’s API Surface (Long-term)

Option 7: Docker-based Build Compatibility Tests

The caching layer is what makes this practical

Why this fits mcp-steroid best

The Single-Invocation Approach: What JetBrains Uses Internally

One version per Gradle invocation

Source directory selection

How it compares to the multi-subproject PoC

Build-time Verification: ClassFile Reference Checking

Tier 1 — verifyClassRefs: erased-descriptor existence check

Tier 2 — verifyApiSignatures: generic signature comparison

Tier 3 — Plugin Verifier: full JLS binary compatibility

Comparison

Build Issues I Hit Along the Way

Scoring Summary

What JetBrains Could Do Better

Where to Start

What I Am Doing for MCP Steroid

Booting NVIDIA Jetson AGX Thor: Headless, from macOS, via Serial Console

The Hardware

Prerequisites

Step 1: Download the ISO

Step 2: Write the ISO to USB (macOS)

Step 3: Connect the Serial Console

Step 4: Boot from USB and Flash to NVMe

Step 5: The OOBE Trap

Step 6: SSH Setup

Step 7: Post-Install Configuration

UEFI and ISO Compatibility

What Came Out the Other Side

IntelliJ as a Skill Factory

Two Islands

The Skill Factory

Why Skills, Not Plugin Code

Example: A Complete Skill

Enterprise: Your Own Skills

What’s Next

Get Involved

Try It

PoC Program

MCP Steroid Is Now Open Source

The Bridge

How It Got Here

Skills – a Tease

Try It

Get Involved

What’s Next

Agentic Experience and Tools: My Program

The Mission: Agentic Experience & Tools

The Agentic Loop

What Is Still Broken

What I Have Built

Find the Others

run-agent.sh v2.0: Hardened Runner with 115 Tests, Random Selection, and Agent Environment Contract

What is run-agent.sh?

Random agent selection

Agent availability control

Environment contract

115 acceptance tests, zero API keys

Tier 1 — `verifyClassRefs`: erased-descriptor existence check

Tier 2 — `verifyApiSignatures`: generic signature comparison

Claude Code – `--verbose` or You Are Flying Blind