Note: This post focuses only on OTP generation — how we take a shared secret and turn it into those familiar 6-digit codes. How we store secrets securely (PBKDF2, AES-GCM, the accounts.json file) is a story for the next post.

Why Do We Even Need a "Second Factor"?

Passwords alone are fundamentally brittle. They get reused, phished, leaked in data breaches, and brute-forced. The core idea behind two-factor authentication (2FA) is to combine something you know (your password) with something you have (your phone/authenticator app).

Even if an attacker steals your password, they'd also need physical access to your device to get the current OTP. And because the OTP changes every 30 seconds, a stolen code becomes useless almost immediately.

The beauty of TOTP-based 2FA is that it works offline — your authenticator app doesn't need to call any server. Both your app and the server independently compute the same code from a shared secret and the current time. No SMS, no push notification, no network dependency. Just math.

Starting from the Foundation: HOTP

Before we can understand TOTP, we need to understand HOTP — HMAC-based One-Time Password, defined in RFC 4226.

HOTP is conceptually simple: you have a shared secret and a counter. You feed both into an HMAC function, then extract a human-friendly number from the result.

The HOTP Algorithm Step-by-Step

Here's the formula:

HOTP(K, C) = Truncate(HMAC-SHA1(K, C)) mod 10^d

Where:

• K = the shared secret key (a byte array)

• C = an 8-byte counter value (big-endian)

• d = the number of digits in the output (usually 6)

Let's break each step down.

Step 1: Counter to Bytes

The counter is a 64-bit integer. We convert it to an 8-byte array in big-endian order. So counter 5 becomes:

[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x05]

Step 2: HMAC-SHA1

We compute HMAC using the shared secret as the key and the counter bytes as the message. HMAC-SHA1 produces a 20-byte (160-bit) hash.

HMAC itself is defined as:

HMAC(K, text) = H((K' ⊕ opad) || H((K' ⊕ ipad) || text))

Where ipad = 0x36 repeated, opad = 0x5c repeated, and K' is the key padded to the hash's block size (64 bytes for SHA-1). Don't worry if this looks intimidating — in practice, every crypto library handles this for you.

Step 3: Dynamic Truncation

Here's where it gets clever. We have a 20-byte HMAC result, but we need a 6-digit number. RFC 4226 defines a dynamic truncation algorithm:

1. Take the last byte of the HMAC and look at its lowest 4 bits. This gives you an offset (0–15).

2. Starting at that offset, extract 4 consecutive bytes.

3. Mask off the most significant bit (to avoid sign issues), giving you a 31-bit unsigned integer.

offset = hmac[19] & 0x0F

code = ((hmac[offset]     & 0x7F) << 24)
     | ((hmac[offset + 1] & 0xFF) << 16)
     | ((hmac[offset + 2] & 0xFF) << 8)
     |  (hmac[offset + 3] & 0xFF)

Step 4: Modulo

Finally, take that 31-bit integer modulo 10^digits and pad with leading zeros:

otp = code % 1000000  →  "038314"

Visualizing the HOTP Flow

HOTP's Limitation: The Counter Sync Problem

With HOTP, both the client and server maintain a synchronized counter. Every time you generate a code, the counter increments. But what if you generate a code and don't use it? Your counter advances, but the server's doesn't. Now they're out of sync.

Servers deal with this by checking a "look-ahead window" — they'll try counter values C, C+1, C+2, ... up to some limit. But it's fragile. And a stolen HOTP code remains valid indefinitely until it's used or the counter advances past it.

This is exactly the problem TOTP solves.

Enter TOTP: Time as the Counter

TOTP (RFC 6238) is HOTP, but with one elegant twist: instead of maintaining a counter, we derive the counter from the current time.

T = floor((CurrentUnixTime - T0) / TimeStep)

Where:

• CurrentUnixTime = seconds since the Unix epoch (1970-01-01 00:00:00 UTC)

• T0 = the reference time (usually 0, i.e., the epoch itself)

• TimeStep = how often the code changes (usually 30 seconds)

Then we simply call HOTP with T as the counter:

TOTP(K, T) = HOTP(K, T)

That's it. The entire TOTP algorithm is just "replace the counter with a time-derived value."

Why 30 Seconds?

The 30-second window is a balance between security and usability. Shorter windows (like 10 seconds) would be more secure but give users barely enough time to read and type the code. Longer windows (like 60 seconds) give attackers more time to use a stolen code. 30 seconds is the sweet spot recommended by RFC 6238.

Clock Drift Tolerance

What if the user's phone clock is slightly off? Servers typically accept OTPs from the previous, current, and next time windows — effectively creating a 90-second acceptance window. This is enough to handle minor clock drift without meaningfully reducing security.

TOTP Supports More Hash Algorithms

While HOTP (RFC 4226) was specified with SHA-1 only, TOTP (RFC 6238) explicitly supports:

The dynamic truncation algorithm works the same regardless of hash output size — it always uses the last byte to find the offset, then extracts 4 bytes. The only difference is the range of possible offsets (0–15 for SHA-1 with 20 bytes, 0–15 for SHA-256 with 32 bytes, 0–15 for SHA-512 with 64 bytes — the offset is always 4 bits, so always 0–15).

In practice, the overwhelming majority of services use SHA-1. But some security-conscious services (like some crypto exchanges) use SHA-256 or SHA-512 for a larger HMAC output.

How TOTP Provisioning Works: QR Codes and otpauth:// URIs

When you enable 2FA on a website, this is what happens under the hood:

Anatomy of an otpauth:// URI

The QR code encodes a URI in the otpauth:// format, formalized in the IETF draft draft-linuxgemini-otpauth-uri:

otpauth://totp/GitHub:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub&algorithm=SHA1&digits=6&period=30

Let's break it down:

The secret parameter is the star of the show — it's the shared secret that both the server and your authenticator app use to independently generate matching codes. It's Base32-encoded because Base32 uses only uppercase letters and digits 2–7, making it easy to display and manually type if QR scanning fails.

How Do Other Authenticator Apps Store Secrets?

I found it really interesting to research how different authenticator apps handle OTP secret storage and backup. There's a huge range — from "barely encrypted" to "enterprise-grade security":

Google Authenticator

Google Authenticator originally stored secrets in a plaintext SQLite database on Android — no encryption at all. If your device was rooted, anyone could read all your 2FA secrets directly. Their cloud sync feature (added in 2023) initially transferred secrets without end-to-end encryption, meaning Google's servers could theoretically read them. They've since added E2EE to cloud sync, but the local storage on Android still relies on the OS-level sandboxing rather than application-level encryption.

Microsoft Authenticator

Microsoft Authenticator takes security more seriously. On iOS, secrets are stored in the Keychain, and on Android they use encrypted shared preferences. Cloud backups are encrypted — iCloud backups are protected by Keychain, and Android backups go to Microsoft's servers with account-based encryption.

Authy (Twilio)

Authy was one of the first authenticator apps to offer cloud backup. They encrypt secrets using a user-provided "backups password" (processed via PBKDF2 or similar KDF) before uploading. The downside? The app is proprietary and was sunset in 2024, with users urged to migrate. Also, in 2024, Twilio disclosed a breach where phone numbers associated with Authy accounts were leaked (though not the secrets themselves).

1Password & Bitwarden

Both 1Password and Bitwarden store TOTP secrets as part of their broader encrypted vault. They use AES-256-GCM with keys derived from your master password via PBKDF2 (Bitwarden) or Argon2 (1Password). The secrets are just another encrypted field in your vault item. Both have been independently audited and are open-source (Bitwarden fully, 1Password's crypto components partially).

2FAS

2FAS is fully open-source and stores secrets encrypted on the device. They use a user-provided password to derive an encryption key. Backups are encrypted files that you control — no mandatory cloud. Their source code is available on GitHub, which is a huge plus for auditability.

Ente Auth

Ente Auth is another open-source contender. They use end-to-end encryption with XChaCha20-Poly1305 for their cloud sync, with keys derived from the user's password via Argon2. Their code is fully open-source and has been independently audited.

Summary Table

Diving Into Our Codebase

Now that we understand the theory, let's look at how TwoFac implements all of this. All the OTP logic lives in our sharedLib module — the pure Kotlin Multiplatform library that powers every platform (Android, iOS, Desktop, Web, CLI, Wear OS).

The Crypto Layer: cryptography-kotlin

We use cryptography-kotlin by whyoleg — specifically dev.whyoleg.cryptography v0.5.0 — for all our cryptographic primitives. The beauty of this library is that it wraps platform-native crypto providers:

This means we're not shipping a custom crypto implementation — on each platform, we're delegating to the battle-tested, OS-level crypto that's already there. Here's how the dependencies are configured in sharedLib/build.gradle.kts:

// commonMain
implementation(libs.crypto.kt.core)       // Core API

// jvmMain
implementation(libs.crypto.kt.jdk)        // → java.security / javax.crypto

// nativeMain (iOS, macOS, Linux)
implementation(libs.crypto.kt.openssl)    // → OpenSSL 3

// wasmJsMain (Web, Browser Extension)
implementation(libs.crypto.kt.web)        // → Web Crypto API

The CryptoTools Interface

All cryptographic operations are abstracted behind a CryptoTools interface:

interface CryptoTools {
    enum class Algo { SHA1, SHA256, SHA512 }

    suspend fun hmacSha(algorithm: Algo, key: ByteString, data: ByteString): ByteString
    suspend fun createSigningKey(passKey: String, salt: ByteString? = null): SigningKey
    suspend fun encrypt(key: ByteString, secret: ByteString): ByteString
    suspend fun decrypt(encryptedData: ByteString, key: ByteString): ByteString
}

Notice everything is a suspend fun — this isn't just a Kotlin convention. On some platforms (especially WebCrypto), cryptographic operations are inherently asynchronous. By making the interface suspend-based, we can use the native async crypto APIs without blocking.

The DefaultCryptoTools implementation wires everything to cryptography-kotlin:

class DefaultCryptoTools(val cryptoProvider: CryptographyProvider) : CryptoTools {

    val hmac = cryptoProvider.get(HMAC)

    override suspend fun hmacSha(
        algorithm: CryptoTools.Algo,
        key: ByteString,
        data: ByteString
    ): ByteString {
        val keyDecoder = when (algorithm) {
            CryptoTools.Algo.SHA1 -> hmac.keyDecoder(SHA1)
            CryptoTools.Algo.SHA256 -> hmac.keyDecoder(SHA256)
            CryptoTools.Algo.SHA512 -> hmac.keyDecoder(SHA512)
        }
        val hmacKey = keyDecoder.decodeFromByteString(HMAC.Key.Format.RAW, key)
        val signature = hmacKey.signatureGenerator().generateSignature(data.toByteArray())
        return ByteString(signature)
    }
}

The OTP Interface

Both HOTP and TOTP implement a common OTP interface:

interface OTP {
    val digits: Int                      // 6 or 8
    val algorithm: CryptoTools.Algo      // SHA1, SHA256, SHA512
    val secret: String                   // Base32-encoded
    val accountName: String              // e.g. "alice@example.com"
    val issuer: String?                  // e.g. "GitHub"

    suspend fun generateOTP(counter: Long): String
    suspend fun validateOTP(otp: String, counter: Long): Boolean
}

Our HOTP Implementation

The HOTP class is a direct implementation of RFC 4226:

class HOTP(
    override val digits: Int = 6,
    override val algorithm: CryptoTools.Algo = CryptoTools.Algo.SHA1,
    override val secret: String,
    override val accountName: String,
    override val issuer: String?,
) : OTP {

    private val cryptoTools = DefaultCryptoTools(CryptographyProvider.Default)

    override suspend fun generateOTP(counter: Long): String {
        // 1. Counter → 8 bytes (big-endian)
        val counterBytes = ByteArray(8) { i ->
            ((counter shr ((7 - i) * 8)) and 0xFF).toByte()
        }

        // 2. Decode the Base32 secret
        val secretBytes = Encoding.decodeBase32(secret)

        // 3. HMAC
        val hmac = cryptoTools.hmacSha(
            algorithm,
            ByteString(secretBytes),
            ByteString(counterBytes)
        )

        // 4. Dynamic Truncation
        val fourBytes = dynamicTruncate(hmac)

        // 5. Modulo → pad with zeros
        val otp = fourBytes % 10.0.pow(digits.toDouble()).toInt()
        return otp.toString().padStart(digits, '0')
    }
}

The dynamic truncation method follows the RFC exactly:

internal fun dynamicTruncate(hmac: ByteString): Int {
    // Last byte's lowest 4 bits = offset (0-15)
    val offset = (hmac.get(hmac.size - 1) and 0x0F).toInt()

    // Extract 4 bytes, mask the MSB for a 31-bit unsigned int
    return ((hmac.get(offset).toInt() and 0x7F) shl 24) or
           ((hmac.get(offset + 1).toInt() and 0xFF) shl 16) or
           ((hmac.get(offset + 2).toInt() and 0xFF) shl 8) or
            (hmac.get(offset + 3).toInt() and 0xFF)
}

One thing I want to highlight: our dynamicTruncate uses hmac.size - 1 instead of hardcoding 19 (like you'd see in SHA-1-only implementations). This makes it work correctly with SHA-256 (32 bytes) and SHA-512 (64 bytes) too.

Our TOTP Implementation

The TOTP class is remarkably simple because it just wraps HOTP:

class TOTP(
    override val digits: Int = 6,
    override val algorithm: CryptoTools.Algo = CryptoTools.Algo.SHA1,
    override val secret: String,
    override val accountName: String,
    override val issuer: String?,
    private val baseTime: Long = 0,    // Unix epoch
    val timeInterval: Long = 30        // 30 seconds
) : OTP {

    // Reuse HOTP internally!
    private val hotp = HOTP(digits, algorithm, secret, accountName, issuer)

    private fun timeToCounter(currentTime: Long): Long {
        return (currentTime - baseTime) / timeInterval
    }

    override suspend fun generateOTP(currentTime: Long): String {
        val counter = timeToCounter(currentTime)
        return hotp.generateOTP(counter)
    }

    override suspend fun validateOTP(otp: String, currentTime: Long): Boolean {
        val counter = timeToCounter(currentTime)
        // Check previous, current, and next windows (±1)
        return hotp.validateOTP(otp, counter - 1) ||
               hotp.validateOTP(otp, counter) ||
               hotp.validateOTP(otp, counter + 1)
    }
}

This is one of my favorite parts of the codebase. The TOTP class doesn't duplicate any crypto logic — it just converts time into a counter and delegates to HOTP. The validateOTP method checks ±1 time windows (the standard tolerance for clock drift).

Parsing otpauth:// URIs

When you scan a QR code, we need to parse the otpauth:// URI and create the right OTP object. This is handled by OtpAuthURI:

object OtpAuthURI {
    fun parse(uri: String): OTP {
        require(uri.startsWith("otpauth://"))

        // Extract type: "totp" or "hotp"
        val typeStr = uri.substring(10, uri.indexOf("/", 10))

        // Extract label: "GitHub:alice@example.com"
        val label = uri.substring(uri.indexOf("/", 10) + 1, uri.indexOf("?"))
        val labelIssuer = label.substringBefore(":", "")
        val accountName = label.substringAfter(":", label).trim()

        // Parse query parameters
        val params = paramsStr.split("&").associate { /* ... */ }

        val secret = params["secret"]!!
        val algorithm = when (params["algorithm"]?.uppercase()) {
            "SHA256" -> CryptoTools.Algo.SHA256
            "SHA512" -> CryptoTools.Algo.SHA512
            else -> CryptoTools.Algo.SHA1  // Default
        }

        return when (type) {
            Type.TOTP -> TOTP(
                digits = params["digits"]?.toIntOrNull() ?: 6,
                algorithm = algorithm,
                secret = secret,
                timeInterval = params["period"]?.toLongOrNull() ?: 30L,
                accountName = accountName,
                issuer = issuer
            )
            Type.HOTP -> HOTP(/* ... */)
        }
    }
}

The parser also has a Builder that works in reverse — given an OTP object, it constructs the otpauth:// URI. This is used when exporting or backing up accounts.

Base32 Encoding

OTP secrets in the otpauth:// URI are Base32-encoded per RFC 4648. We implement our own Base32 encoder/decoder in Encoding.kt:

object Encoding {
    const val ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"

    fun decodeBase32(base32: String): ByteArray {
        val cleanInput = base32.replace("=", "").uppercase()
        // Each Base32 character represents 5 bits
        // We accumulate bits in a buffer and emit bytes when we have 8+
        var buffer = 0
        var bitsLeft = 0
        /* ... */
    }
}

Why Base32 instead of Base64? Base32 uses only uppercase letters and digits 2–7, so there's no ambiguity between 0/O, 1/l/I, or +//. This matters because users might need to manually type the secret if QR scanning fails.

How We Store OTP Accounts

Each OTP account is stored as a StoredAccount:

@Serializable
data class StoredAccount(
    val accountID: Uuid,          // Unique identifier
    val accountLabel: String,     // Display name (e.g. "GitHub - alice")
    val salt: String,             // Salt for key derivation
    val encryptedURI: String,     // The otpauth:// URI, encrypted with AES-GCM
)

Notice that we store the encrypted otpauth:// URI, not the raw secret. The entire URI (which contains the secret, algorithm, issuer, etc.) is encrypted with AES-256-GCM using a key derived from the user's password via PBKDF2. Each account gets its own salt.

This means even if someone gets access to the storage file, they can't read any OTP secrets without the user's password. But that's a topic for the next post — where we'll dive deep into PBKDF2, AES-GCM, and the accounts.json storage format.

Verifying Against the RFCs

One thing I'm particularly proud of is that our test suite validates against the official RFC test vectors. Here's a snippet from our HOTP tests:

// Secret: "12345678901234567890" (ASCII)
// Base32: "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ"
val expectedOTPs = listOf(
    "755224", // Counter = 0
    "287082", // Counter = 1
    "359152", // Counter = 2
    "969429", // Counter = 3
    "338314", // Counter = 4
    "254676", // Counter = 5
    "287922", // Counter = 6
    "162583", // Counter = 7
    "399871", // Counter = 8
    "520489"  // Counter = 9
)

These are the exact test vectors from RFC 4226 Appendix D. Our TOTP tests go even further, validating against RFC 6238's test vectors with all three hash algorithms:

// RFC 6238 test vectors with 8-digit codes
RFC6238TestVector(59, "1970-01-01 00:00:59", key_sha1, SHA1, "94287082"),
RFC6238TestVector(59, "1970-01-01 00:00:59", key_sha256, SHA256, "46119246"),
RFC6238TestVector(59, "1970-01-01 00:00:59", key_sha512, SHA512, "90693936"),
// ... and more timestamps across decades

If our implementation matches the RFC test vectors on every platform (JVM, Native, Wasm), we can be confident we're computing OTPs correctly.

The Full Picture

Here's how everything fits together in TwoFac — from scanning a QR code to displaying the 6-digit code on your screen:

What's Next?

In this post we covered the generation side of things — how a shared secret and the current time produce those familiar 6-digit codes. But generation is only half the story.

In the next post, we'll explore the storage side: how TwoFac protects your secrets at rest using PBKDF2 for key derivation and AES-256-GCM for authenticated encryption. We'll walk through the accounts.json format, why we chose the iteration counts we did, and how the encryption pipeline works across all platforms.

Links and References

• TwoFac GitHub Repository

• RFC 4226 — HOTP: An HMAC-Based One-Time Password Algorithm

• RFC 6238 — TOTP: Time-Based One-Time Password Algorithm

• RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

• RFC 4648 — Base Encodings (Base32)

• draft-linuxgemini-otpauth-uri — The otpauth URI Format

• Google Authenticator Key URI Format

• cryptography-kotlin by whyoleg

• NIST SP 800-38D — AES-GCM

When I started sketching out the project, I knew I wanted it to run on everything from my Android phone and Apple Watch to my Linux terminal and Chrome browser. But as usually happens during such "yak shaving sessions," I spent a good chunk of time just thinking about the architecture. How do you share code between a SwiftUI Watch app, a Wasm-based browser extension, and a native Linux CLI without losing your mind?

Today, I want to walk you through the technical decisions and the module structure that makes TwoFac possible.

The Core Philosophy: Logic as a Library

A mistake I see often in cross-platform development is trying to force a single UI framework onto every device. While Compose Multiplatform is amazing (and we use it!), sometimes you just want a native experience—like on the tiny circular screen of a watch.

I decided that the "brain" of TwoFac—the part that handles TOTP/HOTP generation, otpauth:// parsing, and encryption—should be a pure, logic-only library. It shouldn't know or care about buttons, screens, or viewmodels.

This became our sharedLib module.

How the Platforms Connect to the Core

Because sharedLib is pure Kotlin Multiplatform, it gets exported in formats native to every ecosystem we target. But how do the actual applications consume it? This is where the module structure gets interesting.

The composeApp Bridge: Most of our visual applications—Android, Desktop, and Web—reside in the composeApp module. This module depends directly on sharedLib as a standard Kotlin library. It acts as the shared UI layer, using Compose Multiplatform to draw the screens.

• Desktop: The composeApp can be compiled into native desktop GUI applications, packaged as standard installers (.dmg for macOS, .msi for Windows, .deb for Linux).

• Web (WasmJS): For the web, composeApp uses the new wasmJs target. This allows us to deploy the app as a downloadable Progressive Web App (PWA) running via an index.html. Incredibly, we use the exact same compiled Wasm binary to power the popup.html and sidepanel.html of our Chrome and Firefox browser extensions!

Thin Wrappers for Mobile: If composeApp holds the UI, how do the mobile apps work? We have very thin androidApp and iosApp modules that essentially just "boot up" the shared UI.

• For Android, androidApp just contains the MainActivity that calls the Compose content. With the recent Android Gradle Plugin (AGP) 9.0 updates, keeping the Android application plugin (com.android.application) separate from the Kotlin Multiplatform plugin (org.jetbrains.kotlin.multiplatform) is actually mandated, making this thin wrapper pattern not just good architecture, but a requirement.

• Similarly, iosApp is just a standard Xcode project with a Swift entry point that delegates to the shared Compose UI framework.

The Pure Native CLI (cliApp):

Our CLI tool is completely separate from composeApp. It depends directly on sharedLib. But here is the cool part: cliApp uses Kotlin/Native to compile into a pure native binary for Mac, Windows, and Linux. There is zero JVM involved when you run 2fac in your terminal; it links against sharedLib as a native klib, making it incredibly fast.

Why the Watches Stand Alone: You might notice we have separate watchApp (Android Wear) and iOS watch modules. Why not use composeApp? A full-blown Compose Multiplatform UI is heavy, and on a tiny circular screen, the UI needs are fundamentally different. I didn't want the watch apps to inherit the bloat of the main application. Instead, they are designed to be thin clients that simply display synced accounts. Therefore, they bypass composeApp entirely and depend directly on sharedLib to handle the decryption and TOTP generation locally, using native UI frameworks (like SwiftUI for the Apple Watch) for the best possible performance and look.

Desktop and CLI Applications

Our desktop and command-line interfaces are tailored for each major operating system. The CLI links directly to the sharedLib for instant native execution, while the graphical desktop apps use composeApp to render the UI.

Mobile and Watch Applications

For mobile devices, composeApp acts as the shared UI layer wrapped by very thin native application projects. However, the watch apps bypass the shared UI layer entirely, directly consuming sharedLib and using platform-native UIs (Compose for WearOS and SwiftUI for Apple Watch).

Web App and Browser Extensions

Leveraging the power of Wasm, the exact same composeApp output is used to generate our Progressive Web App as well as our browser extensions, ensuring complete feature parity across the web ecosystem.

The "Terminal First" Experience

I use CLI tools extensively (lately, I've been living in tools like Claude Code), and I wanted TwoFac to feel like a native citizen of the terminal.

Since sharedLib can compile to native binaries, our cliApp is a lightning-fast tool with zero JVM overhead. I'm using Clikt for command parsing and Mordant for those pretty terminal colors we all love.

When I run 2fac generate github, I don't want to wait for a runtime to boot up. I want my code, and I want it now.

Managing the Chaos with Version Catalogs

If you've followed my blog for a while, you know I'm a big fan of Gradle Version Catalogs. With 10+ targets and multiple modules, trying to keep versions in sync manually would be a nightmare.

Every single dependency in TwoFac is managed in gradle/libs.versions.toml. Whether it's the Kotlin version or a specific crypto provider, it's defined once.

[versions]
kotlin = "2.3.10"
kstore = "2.0.4"
crypto-kt = "0.5.0"

[libraries]
kstore-core = { module = "tech.arnav:kstore", version.ref = "kstore" }
crypto-core = { module = "dev.whyoleg.cryptography:cryptography-core", version.ref = "crypto-kt" }

Data Persistence: Enter KStore

One problem I faced early on was how to handle data storage. A browser extension uses localStorage, a mobile app uses files (or DataStore), and a CLI tool might use a hidden folder in $HOME.

I absolutely love KStore for this. It provides a unified, coroutine-based API for storage across all platforms. In TwoFac, we use it to save our accounts.json—the encrypted store for all your 2FA secrets—regardless of whether we're on a watch, a phone, or a server.

Finding the "Right" Directory with AppDirs

But where exactly should accounts.json live? On Windows, it should be in AppData/Roaming. On macOS, it's Library/Application Support. On Linux, it's usually $HOME/.local/share.

To handle this, I used the Kotlin Multiplatform AppDirs library. It's a KMP rewrite of the classic Java AppDirs library that helps you find these platform-specific directories without writing a single line of expect/actual code.

A Fork for the Modern Age

You might notice in our libs.versions.toml that we're using my own fork of KStore (tech.arnav:kstore).

While the original xxfast/KStore is excellent, it hadn't been updated to use the latest Kotlin Multiplatform Hierarchy Template. This new internal structure in Kotlin 1.9.20+ makes it much easier to share code between intermediate targets (like appleMain or nativeMain). I forked it to ensure TwoFac could benefit from the most modern Gradle setups and to add support for the wasmJs targets we need for our browser extensions.

What's Next?

By keeping the core logic decoupled from the UI, we've built an architecture that is both flexible and robust. The same security audits that apply to the CLI tool automatically apply to the Apple Watch app, because they are running the exact same code.

In the next post, I'll dive into the Cryptography side of things—how we use cryptography-kotlin to keep your secrets safe while making them accessible across all your devices.

Links and References

• TwoFac GitHub Repository

• Compose Multiplatform Documentation

• Kotlin Multiplatform Official Guide

This raises a practical question: what is actually inside an “agent,” and how is it different from ChatGPT (a chat UI over a model) or coding tools like Claude Code (an agentic coding surface)? Gas Town’s README frames it as a “multi‑agent orchestration system for Claude Code with persistent work tracking” — i.e., an orchestration layer on top of existing coding agents, not a new model class. Likewise, Claude Code’s docs describe it as an “agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools” — a powerful agent shell, not the core model itself.

In this article I’ll walk through each layer, show TypeScript code snippets, and then assemble a minimal reference implementation, using public docs as anchors. The goal is to make “agent” a concrete stack you can build and reason about, rather than a black box.

1) The bare-metal LLM call

Everything starts with a plain text-in, text-out call. OpenAI’s Responses API is the recommended entry point. The SDK example below is the minimum viable “agent brain” — it just generates text.

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.responses.create({
  model: "gpt-5.2",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

sequenceDiagram
  participant App
  participant OpenAI
  App->>OpenAI: POST /responses (model, input)
  OpenAI-->>App: response.items
  App->>App: extract output_text

References:

• OpenAI Text generation guide: https://platform.openai.com/docs/guides/text
• OpenAI TypeScript SDK: https://github.com/openai/openai-node

2) Turning completion into chat (the for-loop)

Chat is not a separate API concept. It is just a loop that keeps appending history. The API is stateless unless you pass context. This for-loop is the whole trick.

const history = [
  { role: "developer", content: "You are a concise coding assistant." },
];

for (const userInput of turns) {
  history.push({ role: "user", content: userInput });
  const response = await client.responses.create({
    model: "gpt-5.2",
    input: history,
  });
  history.push({ role: "assistant", content: response.output_text ?? "" });
}

flowchart TB
  U[User turn] --> H[Append to history]
  H --> R["responses.create(input=history)"]
  R --> A[Assistant turn]
  A --> H
  H -. alternative .-> P[previous_response_id chain]
  P -.-> R

At this stage the model is only using its internal knowledge plus what you send. It does not search. It does not execute. It is still a “completion engine”. For example, at this stage if you ask the model about recent events (after its training cutoff date), it will not be able to tell you. The initial release of ChatGPT, before any search capabilities, was just this.

References:

• OpenAI Conversation state: https://platform.openai.com/docs/guides/conversation-state

3) Tool calling: the model asks, your code executes

Tool calling is where agents become agents. The model can request a tool; your application executes it and sends the output back. OpenAI’s docs describe the flow explicitly: “Execute code on the application side with input from the tool call,” and “When the model calls a function, you must execute it and return the result.”

const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get the current weather for a location.",
    parameters: {
      type: "object",
      properties: {
        location: { type: "string" },
        units: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["location", "units"],
      additionalProperties: false,
    },
  },
];

const input = [{ role: "user", content: "What's the weather in Paris?" }];

const response = await client.responses.create({
  model: "gpt-5.2",
  tools,
  input,
});

for (const item of response.output) {
  if (item.type !== "function_call" || item.name !== "get_weather") continue;
  const result = getWeather(JSON.parse(item.arguments));
  input.push({
    type: "function_call_output",
    call_id: item.call_id,
    output: JSON.stringify(result),
  });
}

sequenceDiagram
  participant App
  participant Model
  participant Tool
  App->>Model: prompt + tools
  loop while tool calls
    Model-->>App: function_call(name, args, call_id)
    App->>Tool: execute(args)
    Tool-->>App: result
    App->>Model: function_call_output(call_id, result)
  end
  Model-->>App: final response

The Responses API is described as “agentic by default,” because it supports multiple tool calls inside a single request.

References:

• OpenAI Function calling guide: https://platform.openai.com/docs/guides/function-calling
• OpenAI Responses API benefits: https://platform.openai.com/docs/guides/migrate-to-responses

4) Writing agents and coding agents

Once tool calling works, specialization is just tool design. A writing agent needs search and citations. A coding agent needs shell access, tests, and documentation. Both are the same loop, different tools.

Writing agent (search + citations)

const tools = [
  {
    type: "function",
    name: "web_search",
    description: "Search the web for sources to cite.",
    parameters: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"],
      additionalProperties: false,
    },
  },
];

const input = [
  { role: "developer", content: "You are a writing agent. Cite sources with inline links." },
  { role: "user", content: "Write two paragraphs about the history of Markdown." },
];

Example trace (writing agent, simplified):

[
  {"role":"user","content":"Write two paragraphs about Markdown with citations."},
  {"type":"function_call","name":"web_search","arguments":"{\"query\":\"Markdown history original announcement\"}"},
  {"type":"function_call_output","name":"web_search","output":"[{\"title\":\"Daring Fireball: Markdown\",\"url\":\"https://daringfireball.net/projects/markdown/\",\"snippet\":\"Markdown is a text-to-HTML conversion tool...\"}]"},
  {"role":"assistant","content":"Markdown was introduced by John Gruber as a text-to-HTML conversion tool... ([source](https://daringfireball.net/projects/markdown/))."}
]

Coding agent (shell + tests)

const tools = [
  {
    type: "function",
    name: "shell",
    description: "Run a shell command in the repo.",
    parameters: {
      type: "object",
      properties: { command: { type: "string" } },
      required: ["command"],
      additionalProperties: false,
    },
  },
];

const input = [
  { role: "developer", content: "You are a coding agent. Use shell to run tests and inspect files." },
  { role: "user", content: "Tests are failing. Find the failure and suggest a patch." },
];

Example trace (coding agent, simplified):

[
  {"role":"user","content":"Tests are failing. Find the failure and suggest a patch."},
  {"type":"function_call","name":"shell","arguments":"{\"command\":\"npm test -- --runInBand\"}"},
  {"type":"function_call_output","name":"shell","output":"{\"exitCode\":1,\"stdout\":\"FAIL src/math.test.ts\",\"stderr\":\"Expected 3, received 4\"}"},
  {"type":"function_call","name":"shell","arguments":"{\"command\":\"sed -n '1,120p' src/math.ts\"}"},
  {"type":"function_call_output","name":"shell","output":"{\"exitCode\":0,\"stdout\":\"export const add = (a,b)=>a+b+1;\"}"},
  {"role":"assistant","content":"Bug in add(): remove the +1. Suggested patch: export const add = (a,b)=>a+b;"}
]

flowchart TB
  U[User task] --> P[Agent prompt + policy]
  P --> M[Model turn]
  M --> D{Tool needed?}
  D -->|No| OUT[Final draft / patch]
  D -->|Yes| R[Orchestrator / tool router]
  R --> W[Writer stack<br/>web_search + cite formatter]
  R --> C[Coder stack<br/>shell + tests + file inspector]
  W --> O1[Tool outputs]
  C --> O2[Tool outputs]
  O1 --> F[Normalize + append to context]
  O2 --> F
  F --> M

References:

• OpenAI tool calling flow: https://platform.openai.com/docs/guides/function-calling
• OpenAI practical guide to building agents: https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/

5) Context limits, compaction, and memory

Every agent hits the context window. This creates three issues: rising cost, forgotten instructions, and session loss. The fixes are standard:

• Compaction: OpenAI provides server-side compaction and a standalone /responses/compact endpoint that returns a compacted context window.
• Memory: store long-term context in a database (vector store or logs) and retrieve it when needed. Lilian Weng’s survey describes this as short-term memory (context window) vs. long-term memory (external retrieval).
• Session boundaries: a new session has no idea about prior runs unless you explicitly pass memory or chain responses.

flowchart TB
  subgraph ContextWindow[Context window]
    Prompt[Current turn + recent history] --> Model[LLM]
    Model --> Output[Response]
  end
  Output -->|store| Memory[Long-term memory]
  Memory -->|retrieve relevant| Prompt
  Output -->|compact| Compact[Compacted context item]
  Compact --> Prompt

References:

• OpenAI Compaction guide: https://platform.openai.com/docs/guides/compaction
• OpenAI Conversation state: https://platform.openai.com/docs/guides/conversation-state
• Lilian Weng, LLM Powered Autonomous Agents: https://lilianweng.github.io/posts/2023-06-23-agent/

6) Orchestrators and multi-agent fan-out

Orchestrators are what make OpenClaw-style systems feel “real.” One agent delegates to many specialists, then merges the result. OpenAI’s agent guide describes two patterns: a manager agent (agents-as-tools) and a decentralized handoff model. Both are graph execution with tool calls at the edges.

A key implementation detail: if the model emits multiple tool calls, the orchestration layer decides whether to execute them sequentially or in parallel. OpenAI’s Agents SDK docs explicitly expose this switch (parallel_tool_calls) and also describe code-first orchestration with parallel execution primitives (for example, asyncio.gather). In a shell-centric harness, the same rule applies: independent tool calls can be dispatched in separate subprocesses (for example, separate bash/command workers) and then fan-in their outputs; dependent calls should stay serialized.

flowchart LR
  Manager[Manager agent] -->|fan-out| R1[Research agent]
  Manager -->|fan-out| R2[Writing agent]
  Manager -->|fan-out| R3[Coding agent]
  R1 --> Merge[Fan-in merge]
  R2 --> Merge
  R3 --> Merge
  Merge --> Manager
  Manager --> Final[Final response]

Example fan-out trace (simplified JSON):

[
  {"role":"user","content":"Draft a 1-page brief on vector databases with citations and a code sample."},
  {"role":"assistant","content":"I will delegate research, citations, and code sample."},
  {"type":"tool_call","name":"agent_research","arguments":"{\"task\":\"Background + key concepts\"}"},
  {"type":"tool_call","name":"agent_citations","arguments":"{\"task\":\"Find authoritative sources\"}"},
  {"type":"tool_call","name":"agent_code","arguments":"{\"task\":\"Minimal TS example with a vector store API\"}"},
  {"type":"tool_result","name":"agent_research","output":"Key concepts: embeddings, ANN search, HNSW..."},
  {"type":"tool_result","name":"agent_citations","output":"Sources: openai docs, Weng survey, FAISS paper..."},
  {"type":"tool_result","name":"agent_code","output":"Code sample: embed + upsert + query"},
  {"role":"assistant","content":"Merged brief with citations and code sample."}
]

References:

• OpenAI practical guide to building agents: https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/
• OpenAI Agents guide: https://platform.openai.com/docs/guides/agents
• OpenAI Agents SDK orchestration patterns: https://openai.github.io/openai-agents-python/multi_agent/
• OpenAI Agents SDK model settings (parallel_tool_calls): https://openai.github.io/openai-agents-python/ref/model_settings/
• OpenAI cookbook parallel agents example: https://developers.openai.com/cookbook/examples/agents_sdk/parallel_agents
• Node.js child processes (spawn/exec for separate subprocesses): https://nodejs.org/api/child_process.html

7) Skills, MCP, and capability expansion

Tools are the base layer, but two concepts make agent systems feel modular: Skills and MCP. OpenAI defines Skills as “versioned bundles of files” with a SKILL.md manifest, designed to codify reusable processes. You can mount them in hosted or local shell environments so the model can invoke them as needed. Skills are powerful precisely because they can package both instructions and code.

Example: mounting a skill in a hosted shell (TypeScript):

const response = await client.responses.create({
  model: "gpt-5.2",
  tools: [
    {
      type: "shell",
      environment: {
        type: "container_auto",
        skills: [{ type: "skill_reference", skill_id: "skill_basic_math" }],
      },
    },
  ],
  input: "Use the basic-math skill to add 144 and 377.",
});

MCP (Model Context Protocol) is the other half of the expansion story. It’s an open standard for connecting models to external systems. OpenAI’s connector/MCP tooling exposes this directly in the Responses API: “You can give models new capabilities using connectors and remote MCP servers.” These tools can be gated by explicit approval, and the docs emphasize the risk surface: “A malicious server can exfiltrate sensitive data from anything that enters the model’s context.”

Example: MCP tool setup (remote server) with approval gating:

const response = await client.responses.create({
  model: "gpt-5.2",
  tools: [
    {
      type: "mcp",
      server_label: "github",
      server_url: "https://mcp.github.example/sse",
      require_approval: "always",
      allowed_tools: ["list_prs", "get_commit", "merge_pr"],
    },
  ],
  input: "Summarize open PRs for repo foo/bar.",
});

Typical layout (Skills, MCP servers, and integrations):

agent-system/                     <--- repo root for the agent harness
  skills/                         <--- reusable skill bundles
    basic-math/ 
      SKILL.md   <--- skill manifest + instructions
      scripts/         
        add.py   <--- executable to do deterministic logic 
  mcp-servers/                    <--- MCP server implementations
    github/                       
      package.json           <--- server deps + metadata
      src/ 
        server.ts         <--- MCP server entrypoint (can be expressjs)
        tools/ 
          list_prs.ts     <--- uses github GraphQL api to return PRs
          get_commit.ts   <--- find commit details
          merge_pr.ts     <--- makes POST request to merge a PR
  integrations/                    <--- local connector implementations
    connectors/  
      dropbox.ts       <--- Dropbox connector (handles auth etc)
      gmail.ts         <--- Gmail connector

MCP servers usually expose a list of tools (their input schemas and names). The model sees those tools and can call them like any other tool call; your harness still owns approvals and can restrict which tools are exposed.

Example: a GitHub MCP server in action (hypothetical trace):

[
  {"role":"user","content":"Show me open PRs in foo/bar and merge the top one if checks are green."},
  {"type":"mcp_list_tools","server_label":"github","tools":["list_prs","get_pr","merge_pr"]},
  {"type":"tool_call","name":"list_prs","arguments":"{\"repo\":\"foo/bar\",\"state\":\"open\"}"},
  {"type":"tool_result","name":"list_prs","output":"[{\"number\":42,\"title\":\"Fix build\",\"checks\":\"green\"}]"},
  {"type":"mcp_approval_request","name":"merge_pr","arguments":"{\"repo\":\"foo/bar\",\"number\":42}"},
  {"type":"mcp_approval_response","approve":true},
  {"type":"tool_call","name":"merge_pr","arguments":"{\"repo\":\"foo/bar\",\"number\":42}"},
  {"type":"tool_result","name":"merge_pr","output":"merged"},
  {"role":"assistant","content":"Merged PR #42 after checks passed."}
]

Permissions and approvals are the key guardrail. The MCP guide notes: “By default, OpenAI will request your approval before any data is shared with a connector or remote MCP server.” You can relax these approvals once trust is established, but the default is permissioned by design.

References:

• OpenAI Skills guide: https://platform.openai.com/docs/guides/tools-skills
• OpenAI Connectors and MCP servers: https://platform.openai.com/docs/guides/tools-connectors-mcp
• MCP overview: https://modelcontextprotocol.io/docs/getting-started/intro

8) Harnessed tools, permissions, and shell-centric agents

Tool calls are requests, not execution. The harness (your app) is responsible for enforcing permissions, sandboxing, and actually running commands. The OpenAI shell guide is blunt: “Running arbitrary shell commands can be dangerous. Always sandbox execution, apply allowlists or denylists where possible, and log tool activity for auditing.” It also clarifies how the control loop works: the model emits shell_call items, your runtime executes them, then you send back shell_call_output.

This is why shell‑centric agents are so powerful. Tools like Codex CLI, or lightweight local harnesses, treat the model as a planner and the shell as the executor. Minimal harnesses (think “single file shell agent”) can already support build/test/fix loops. Stack a scheduler, memory, and orchestration on top, and you are now halfway to systems like OpenClaw.

References:

• OpenAI Shell tool: https://platform.openai.com/docs/guides/tools-shell
• OpenAI Local shell tool: https://platform.openai.com/docs/guides/tools-local-shell
• OpenAI Connectors/MCP approvals: https://platform.openai.com/docs/guides/tools-connectors-mcp

9) A minimal OpenClaw-style reference implementation

Here’s the smallest possible control plane, expanded with a more OpenClaw‑like shape. OpenClaw’s docs describe a Gateway: a single long‑lived daemon that owns messaging surfaces, exposes a WebSocket API, and emits system events like cron and heartbeat. The Gateway runs on a host continuously, and its periodic cron ticks are the trigger to poll queues, check health, and schedule work. When new tasks arrive from chat or clients, the Gateway creates jobs in a queue, spawns agent runs (often in separate worker processes or runtimes), streams progress back to clients, and finally persists results into memory.

In other words: the “cron tick” is not just a timer, it is the heartbeat of the control plane. It’s where the Gateway decides which jobs to claim, which agents to spawn, and how to advance long‑running work. It also decides when a job is complete (all sub‑agents have returned, or exit criteria met) and sends a final status back to the original chat thread.

flowchart LR
  Chat[Chat providers] -->|ingest| Gateway((Gateway daemon))
  Clients[CLI/Web/Admin] <--> |WebSocket| Gateway
  Nodes[Devices/Tools] <--> |WebSocket| Gateway
  Gateway --> Cron[cron tick]
  Cron --> Queue[Job queue]
  Queue --> Workers[Agent workers]
  Workers --> Results[Results + logs]
  Results --> Gateway
  Gateway --> Memory[Global memory/store]
  Gateway --> Updates[Thread updates]

type Job = {
  id: string;
  source: "chat" | "client";
  threadId: string;
  prompt: string;
  status: "queued" | "running" | "done" | "failed";
};

async function onIncomingChat(threadId: string, prompt: string) {
  // Chat/client message becomes a queued job.
  await enqueueJob({
    id: `job_${Date.now()}`,
    source: "chat",
    threadId,
    prompt,
    status: "queued",
  });
}

async function cronTick() {
  // Claim a small batch so multiple workers can share the queue.
  const jobs = await claimQueuedJobs({ limit: 5 });

  for (const job of jobs) {
    // Update status and notify the originating thread.
    await updateJob(job.id, "running");
    await notifyThread(job.threadId, "started", { jobId: job.id });

    // Pull relevant memory before delegating work.
    const memory = await searchMemory(job.prompt);

    // Fan out to specialist agents in parallel.
    const [research, citations] = await Promise.all([
      runAgent("research", `Research background: ${job.prompt}`),
      runAgent("citations", `Find sources for: ${job.prompt}`),
    ]);

    // Fan-in: assemble a final draft with memory + sources.
    const draft = await runAgent(
      "writer",
      `Draft answer for: ${job.prompt}\n\nContext:\n${memory}\n\nSources:\n${citations}`
    );

    // Persist result and close out the job.
    await writeMemory(`Job ${job.id} summary:\n${draft}`);
    await updateJob(job.id, "done");
    await notifyThread(job.threadId, "completed", { jobId: job.id, draft });
  }
}

That is the full stack: LLM call, loop, tools, memory, orchestration. Everything else is engineering around reliability, safety, cost, and UX.

References:

• OpenHands repo: https://github.com/OpenHands/OpenHands
• OpenClaw Gateway architecture: https://docs.openclaw.ai/concepts/architecture
• ReAct paper (Reasoning + Acting): https://arxiv.org/abs/2210.03629

Closing

If you strip away the hype, modern agent frameworks are just well‑engineered loops: deterministic code around probabilistic models. The wins come from tool design, memory strategy, and orchestration discipline, not from “prompt magic.”

If you want to build this out further, a few practical next steps make the biggest difference:

1) Add guardrails: tool approvals, allowlists/denylists, and sandboxing. The OpenAI shell tool docs stress that executing arbitrary commands is dangerous and should be sandboxed and logged. https://platform.openai.com/docs/guides/tools-shell 2) Make tools modular: Skills and MCP servers let you package capabilities and expose them safely. See OpenAI’s Skills guide and Connectors/MCP docs. https://platform.openai.com/docs/guides/tools-skills https://platform.openai.com/docs/guides/tools-connectors-mcp 3) Scale orchestration: if you want many agents, study systems like Gas Town (multi‑agent orchestration with persistent work tracking) and OpenClaw’s Gateway architecture for long‑lived control planes. https://github.com/steveyegge/gastown https://docs.openclaw.ai/concepts/architecture 4) Harden memory: learn how compaction, conversation state, and retrieval are handled in production. https://platform.openai.com/docs/guides/compaction https://platform.openai.com/docs/guides/conversation-state 5) Learn from coding agents: Claude Code is a concrete example of an “agentic coding tool” that reads codebases, edits files, and runs commands. https://code.claude.com/docs/en/overview

Start tiny: one LLM call, one loop, one tool. Then scale the loop into a harness, and scale the harness into a system.

Further reading

• OpenAI Agents guide: https://platform.openai.com/docs/guides/agents
• OpenAI Function calling guide: https://platform.openai.com/docs/guides/function-calling
• OpenAI Compaction guide: https://platform.openai.com/docs/guides/compaction
• OpenAI Skills guide (building and using skills): https://platform.openai.com/docs/guides/tools-skills
• OpenAI Connectors and MCP servers: https://platform.openai.com/docs/guides/tools-connectors-mcp
• OpenAI guide to adding remote MCP servers as tools: https://platform.openai.com/docs/guides/tools-connectors-mcp
• MCP overview: https://modelcontextprotocol.io/docs/getting-started/intro
• Gas Town (Steve Yegge): https://github.com/steveyegge/gastown
• OpenClaw Gateway architecture: https://docs.openclaw.ai/concepts/architecture

The moment you generate a Google Maps API key on one machine, you have started a countdown. Eventually, you will need that key on the other two machines. Usually, this involves the shameful act of Slacking a secret to yourself or the tedious ritual of digging through a password manager. I just wanted the keys to exist everywhere, as if by magic.

So I build env.sync.local - go check it out and install from my Github.

The Problem: The Copy-Paste Tax

We have been conditioned to accept the "Manual Copy-Paste" tax as a cost of doing business. When you work across three different operating systems, syncing a .env file usually involves a game of telephone with insecure intermediaries.

I needed to scratch a few very specific itches. First, no master server. I didn't want to maintain a "secrets vault" or a central authority. If any two of my machines are online, they should be able to talk without a middleman. Second, zero configuration. If I buy a new machine, I should be able to run an install script and have it automatically discover the rest of the mesh. Finally, security at rest. Secrets should not sit in plaintext on my disk, even if the disk is encrypted.

Architecture: Discovery and Transport

The first hurdle was discovery. Static IP addresses are a relic of the past in a home network context. I leaned on mDNS (Bonjour/Avahi). It is a beautiful protocol that allows machines to shout "I am here" into the local void. By registering an _envsync._tcp service, any node can find its peers without a config file. No more hardcoding IP addresses like it is 1998.

For the transport layer, I started with a simple HTTP server fallback, but SCP (over SSH) is the real winner here. It provides authenticated, encrypted pipes out of the box. If I can already SSH into my MiniPC, env-sync can just piggyback on that existing trust to move files. It is pragmatic, it uses existing infrastructure, and it works.

The Crypto: AGE and Multi-Recipient Encryption

Initially, the project was just moving plaintext files. That felt wrong. If someone stole my Beelink, they would have the keys to my entire kingdom. I moved to AGE (Actually Good Encryption) for at-rest security.

The challenge with a decentralized system is key management. If there is no central server to manage a shared secret, how does a new machine join the party? I implemented a multi-recipient model. Every machine generates its own X25519 key pair. When you add a new machine, it broadcasts its public key. The existing machines discover this new key and re-encrypt their secrets to include the new recipient.

I added a "remote trigger" feature to solve the bootstrap problem. A new machine can SSH into an existing peer and say: "Here is my public key, re-encrypt everything for me and let me sync." This makes it zero-config for the existing nodes and provides instant gratification for the new one.

Evolution: From Bash to Go

The project started as a collection of Bash scripts. Bash is the ultimate glue. It allowed me to build the MVP in a single weekend. But Bash has very low ceilings. Once you start managing background daemons, parsing JSON from mDNS tools, and fighting with cross-platform pathing on WSL2, you are in for a world of pain. Shell quoting is a dark art that I would rather not practice daily.

I migrated the entire core to Go for a few specific reasons. First, the single binary. I wanted a statically linked artifact that I could drop onto any machine without worrying about dependencies. Second, native AGE. Using the filippo.io/age library meant I didn't need the age binary installed on the host. Finally, concurrency. Go's select loops and goroutines made managing the mDNS listener and the sync cron significantly more robust.

The result is a system that feels invisible. I add a key on one machine, and by the time I have walked over to my other desk and opened a terminal, the key has already propagated. It is eventually consistent, decentralized, and stays out of my way.

The Nerd Stats

For those who want the technical specs:

• Discovery: mDNS via _envsync._tcp on port 5739.
• Transport: SCP/SSH (Default) or HTTP (Fallback).
• Encryption: AGE (X25519).
• Conflict Resolution: Per-key timestamps (latest write wins).
• Distribution: Peer-to-peer gossip-adjacent sync.

We spend so much time automating our CI/CD pipelines for production, yet we often leave our local development environments in the stone age. env-sync is my attempt to bring a little bit of that automation home. If it saves me from one more "where is that API key?" hunt, it has already paid for itself.

Here's how to get llama.cpp running with Vulkan support on AMD AI Max 395 (Strix Halo) based devices. I tried it on a Beelink GTR 9 Pro, but should work for Framework Ddesktop too.

Installing a few Prerequisites

sudo apt install amd-smi rocminfo glslc  libvulkan-dev vulkan-tools   mesa-vulkan-drivers   clinfo

Download and build llama.cpp

Get it from github

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

Build it for Vulkan support

cmake -B build \
  -DGGML_VULKAN=ON \
  -DCMAKE_BUILD_TYPE=Release

cmake --build build -j$(nproc)

Run a local LLM model

Once it is built, we can run a model

./build/bin/llama-cli \
  -m ~/.lmstudio/models/lmstudio-community/GLM-4.7-Flash-GGUF/GLM-4.7-Flash-Q4_K_M.gguf \
  -ngl 999 \
  -c 4096 \
  -t $(nproc) \
  --color on \
  -p "Explain how Vulkan helps LLM inference on AMD GPUs."

I built sharetime.zone because I found myself in this loop way too often. Whether it was catching up with friends or consulting with clients in different locations, I needed a way to just say, "Here is the time," without the mental math.

The Idea: Simplicity First

The core idea is dead simple. I wanted to be able to share a link that instantly communicates a specific time in a specific timezone, converted to the viewer's local time.

Instead of opening a timezone converter app, selecting cities, and copying a long generated link, I wanted something I could type out manually if I had to.

So, sharetime.zone works like this:

sharetime.zone/IST/1700

That's it. You click that link, and it tells you exactly what 5:00 PM Indian Standard Time is in your local timezone. No friction, no confusion.

For the Developers: It Works in cURL

Since I spend most of my time in the terminal, I didn't want to leave the command line just to check a time. I figured, why not make it work with curl?

I added support for cURL user agents, so you can literally fetch the time from your terminal:

curl sharetime.zone/IST/1700

And it returns a plain text response with the converted time.

Why Edge Functions?

You might wonder, "Why not just a standard serverless function?" or "Why does this need special handling?"

In a browser-based app (like the Vue frontend of this site), determining your local timezone is trivial. The JavaScript running in your browser can simply ask the browser: "Hey, what timezone are we in?" (usually via Intl.DateTimeFormat().resolvedOptions().timeZone).

But curl is different. When you make a request from your terminal, you aren't sending your timezone information. You're just sending a raw HTTP request. Without that context, the server has no idea if you are in Tokyo or Toronto.

This is where Netlify Edge Functions shine. Because they run at the "edge"—on servers distributed globally and closest to the user—they have immediate access to the request context, including the user's IP-based geolocation.

I can access the user's timezone directly from the request context:

// netlify/edge-functions/curl-response.ts
export default async (request: Request, context: Context) => {
  const clientTZ = context.geo.timezone;
  // ... logic to convert time to clientTZ
}

This allows the tool to provide a personalized answer ("5 PM IST is 7:30 AM in your timezone") without you ever having to tell it where you are.

Deployed on Netlify

Deploying this was surprisingly straightforward. I defined the edge function in my netlify.toml:

[[edge_functions]]
    function = "curl-response"
    path = "/*"

This tells Netlify to intercept every request to the site with this function. Inside the function, I check if the User-Agent contains curl. If it does, I hijack the response and send back the text output. If not, I let the request pass through to the standard Vue app.

Performance at the Edge

Another huge benefit is speed. "What time is it?" is a query that doesn't need a centralized database or a server sitting in a data center in Virginia. It's a calculation that can happen anywhere.

By using Edge Functions, the logic runs on a server physically close to you.

1. Low Latency: The request travels a shorter distance.
2. No Central Bottleneck: There's no single server coordinating everyone's time queries.
3. Deno Runtime: Netlify Edge Functions use Deno, which starts up incredibly fast compared to cold-booting a Node.js container.

What I Learnt Building This

While the app looks simple on the surface, timezones are notoriously tricky. Here are a few things I picked up along the way:

1. Deno is Different

Since Netlify Edge Functions run on Deno, I couldn't just drop in my usual Node.js code. I had to adapt to the Deno runtime environment, using URL imports for dependencies (like https://deno.land/x/ptera) instead of npm install. It was a fun challenge to step outside the node_modules comfort zone.

2. Timezones with Luxon

For the frontend, I leaned heavily on the Luxon library. Handling timezones "correctly" is a rabbit hole of edge cases—Daylight Saving Time (DST) shifts, ambiguous abbreviations (is "CST" Central Standard Time or China Standard Time?), and historical changes.

Luxon made this manageable, but it also taught me that you can't just assume a timezone offset is constant. You have to calculate it for the specific instant in time you're talking about.

Wrapping Up

This was a fun weekend project that solved a real itch for me. It’s open source, so feel free to poke around the code or fork it if you want to add support for your favorite obscure timezone.

Give it a try next time you're setting up a meeting: sharetime.zone

It’s messy, but if you get the setup right, you get better performance for a fraction of the cost.

Here is how I break down the current state of AI coding going into 2026, and how to navigate the choices between mainstream giants (Cursor, Claude) and the new wave of open models (Minimax M2, Qwen3, Kimi K2).

NOTE: Parts of this article are written using Gemini 3 based on some of my rough notes on this topic.

The Breakdown: The 3 Layers

Just like we separate our frontend from our backend, the AI stack is now decoupled:

1. The Provider: Who runs the GPU? (AWS, Cerebras, your own Mac Studio).

2. The Model: The brain. (GPT-5.1, Claude Opus, Qwen3).

3. The Tool: Where you type. (IDE, CLI, or a background agent).

Not only are there multiple mix-and-match combinations possible, I have even been using different setups during different sessions/stages working on the same project too.

Let’s dive into each.

Layer 1: The Provider

This is purely about who runs the model. You have six options, ranging from "easy but pricey" to "DIY hardware."

1. Proprietary Labs: You go straight to the source (OpenAI, Anthropic, Google). Tokens are expensive, which is why we now see "Max" plans with flat fees to cap the bleeding.

2. The Big Clouds: AWS Bedrock, GCP Vertex, Azure. This is mostly for enterprises that want the billing on their existing cloud contract. It’s safe, but rarely the fastest or cheapest. But that said, apart from Google’s models only available on their TPUs, other SOTA models are available via the big 3 clouds mostly.

3. The Chinese Labs: Alibaba (Qwen), DeepSeek, Moonshot serve their models directly too. They are fairly cheap and performant, but you have to deal with the censorship. Asking about Tiananmen Square might flag you, but for React components, they are beasts. Creating new account on Alibaba Cloud is not exactly pleasant UX either.

4. Infra-as-a-Service (Resellers): Providers like DeepInfra, Parasail, and Novitas rent massive GPU clusters and resell access by the token. They are significantly cheaper than the labs, but there is a catch: they often aggressively quantize models (lowering precision) to save VRAM, so you might lose some "smartness" on edge cases. There are now some exacto models to counter this problem.

5. Dedicated LLM Chips: This is where the speed is. Cerebras and Groq don't use standard GPUs; they use wafer-scale engines or LPUs.

   • Real numbers: Cerebras is clocking ~3,000 tokens per second on Llama 3.1 70B.1 That is not reading speed; that is "blink and it's done" speed.

   • I’d highly recommend trying out gpt-oss-120b on groq/cerebras and seeing the speed. Once code starts appearing immediately after you hit enter, it can change your mind about the importance of tok/s numbers.

6. Self-Hosting (Local): Hardware has finally caught up.

   • Apple: A Mac Studio with an M2/M4 Ultra chip and 128GB+ RAM.

   • AMD: The new Strix Halo (Ryzen AI Max+ 395) APUs support up to 128GB of LPDDR5X RAM.

   • The Result: You can run gpt-oss-120b or GLM-4.5-Air locally with zero API costs and total privacy.

Layer 2: The Model

In the unbundled stack, the "Model" is the fungible component. Developers no longer ask "Is Copilot good?" but rather "Which model is best for refactoring legacy C++ vs. writing new React components?" The market has segmented into three distinct categories: The Classic Trio (High Intelligence), Chinese Open Models (High Value), and Fast/Vibe Models (High Velocity).

The Classic Trio: The Gold Medals

These models represent the current state-of-the-art (SOTA) for high-complexity tasks. They are generally too expensive for autocomplete but essential for architectural planning, complex debugging, and tasks requiring deep "System 2" reasoning.

1. GPT-5.1 Codex Max (OpenAI):

This is the gold standard for agentic coding. It is built for long-running, detailed work.

• Capability: It shows a remarkable aptitude for sustaining long-horizon coding tasks. Benchmarks place it at the top of SWE-Bench Verified with a score of 77.9% (for "xhigh" thinking level)

• Mechanism: Its key innovation is compaction, allowing it to work over millions of tokens by summarizing past interactions. This unlocks "project-scale refactors" where the model must understand the implications of a change across hundreds of files

• Use Case: Deep debugging sessions, multi-hour agent loops, and massive refactors.

2. Claude Opus 4.5 (Anthropic):

Anthropic's flagship model excels in nuance and "human-like" reasoning.

• Capability: It is described as "dynamic rather than overthinking," capable of interpreting ambiguous requirements and reasoning over architectural tradeoffs.8 It scores 80.9% on SWE-Bench, slightly edging out competitors in certain evaluations

• Mechanism: Opus 4.5 preserves "thinking blocks" from previous turns in the model context, allowing it to maintain a coherent chain of thought throughout a conversation

• Use Case: Architectural planning, complex system design, and tasks where "understanding the intent" is more important than raw speed.

3. Gemini 3 Pro (Google):

The multimodal beast.

• Capability: With a 1 Million token context window as standard, Gemini 3 Pro is the premier model for "whole repo" understanding. It outperforms competitors in multimodal tasks—reading screenshots of UIs alongside code—and boasts a GPQA Diamond score of 91.9%, indicating PhD-level scientific reasoning

• Mechanism: It uses a "thinking process" that allows it to reason deeply before generating a response, similar to Chain-of-Thought prompting but baked into the model architecture

• Use Case: Large-scale codebase understanding, multimodal UI debugging, and scientific/mathematical coding tasks.

The Chinese Open Models: The Commoditizers

The gap between proprietary SOTA and open weights has collapsed. Models from Chinese labs offer 90-95% of the performance of the "Classic Trio" at nearly zero marginal cost for local users or significantly reduced API costs.

Qwen3 Coder (Alibaba):

Qwen3 Coder is an open-source marvel supporting 119 languages.

• Innovation: It features a "Hybrid Thinking Mode" that intelligently switches between deep reasoning (slow) and fast response based on the complexity of the query.34 This adaptability makes it an incredibly versatile tool for polyglot developers.

• Performance: It rivals Claude Sonnet 4 in coding benchmarks, making it a viable free alternative for local hosting

DeepSeek V3 / R1:

Known for its "Deep Thinking" capabilities, DeepSeek R1 forces the model to verify its own logic steps before outputting code.

• Innovation: The R1 model utilizes reinforcement learning strategies to "self-correct" during the generation process. This significantly reduces logic errors in complex algorithms, making it widely considered the best price-to-performance model on the market

• Economics: Its ultra-low cost (due to efficient MoE architecture) allows developers to use it for "brute force" tasks—generating 100 variations of a function to find the best one—without breaking the bank.

Moonshot Kimi K2:

Kimi K2 is a "Thinking Agent" model.

• Innovation: It is meticulously optimized for agentic capabilities, specifically tool use. Unlike models that struggle with multi-step instructions, Kimi K2 is trained to execute 200-300 sequential tool calls (search, file read, file write) without losing the thread of the task

• Performance: It scores 71.3% on SWE-Bench Verified, placing it in the upper echelon of coding models

The Velocity Models: "Fast" & "Vibe"

A new category of model has emerged focused purely on latency. These are used for "Vibe Coding"—where the developer iterates rapidly in natural language, expecting near-instant visual feedback.

Grok Code Fast (xAI):

Grok Code Fast is optimized for sheer speed in agentic workflows.

• Philosophy: xAI recognized that agentic loops (Reasoning -> Tool Call -> Observation -> Reasoning) are often bottlenecked by the model's latency. Grok Code Fast is designed to be "blazing fast," allowing it to call dozens of tools before the user has even finished reading the first paragraph of the thinking trace

• Specs: It supports a 256k context window and is particularly adept at TypeScript, Python, and Rust

GLM-4.5 Air (Zhipu AI):

A lightweight powerhouse.

• Efficiency: GLM-4.5 Air requires only 32-64GB of VRAM to run locally. This makes it the most powerful model that can comfortably fit on a high-end consumer workstation (like a dual 3090 setup or a Mac Studio) while maintaining strong instruction following capabilities.39

• Adoption: It has become a favorite for local "vibe coding" setups where users want privacy without sacrificing too much intelligence. Even Windsurf and Cursor have built their “own” models by basically fine-tuning this.

gpt-oss-120b:

The gpt-oss-120b represents the community's effort to run massive models on dedicated silicon like the Strix Halo Running a 120B model locally at acceptable speeds transforms the development experience, offering near-SOTA capabilities without the latency or cost of the cloud. But if run on a cloud like Cerebras or Groq, it can also give almost 1000+ tokens/second of speedy outputs.

Layer 3: The Coding Interface

The tool layer is where the developer lives. In the bundled era, this was VS Code with a proprietary plugin. In the unbundled era, the tool is a flexible chassis that accepts any provider and any model. The market has segmented into Agentic IDEs, Open Source tools, CLIs, and Vibe Coding Platforms.

The Agentic IDEs: Cursor, Windsurf, Copilot

These are forks or heavily modified versions of VS Code designed to integrate AI natively into the editor's core loop, rather than bolting it on as a sidebar.

Cursor:

Cursor is the pioneer of the unbundled IDE space.

• Features: It allows users to "tab" through code generation and features "Composer," a multi-file editing agent. Crucially, Cursor allows users to input their own API keys (BYOK) for models like Claude Opus or GPT-4o, giving them control over costs and capabilities

• Philosophy: Cursor treats the AI as a pair programmer that "lives" in the editor, capable of seeing the cursor position, diffs, and terminal output.

Windsurf:

Windsurf focuses on "Flow" states.

• Features: It utilizes deep context awareness of the codebase ("Cascade") to predict the developer's next move. By indexing the codebase locally, it allows for "context-aware" completions that understand the broader architecture of the project.

GitHub Copilot (Evolution):

Even the progenitor of the bundled model has had to adapt. Copilot has evolved to support multiple models (Anthropic, Gemini, OpenAI) within its interface, acknowledging the unbundling trend. However, it still largely operates as a "subscription" service rather than a pure BYOK platform.

The Open Source & "Bring Your Own Key" (BYOK) Tools

For developers who reject vendor lock-in or telemetry, a new class of open-source editors and extensions has risen.

Roo Code (formerly Cline):

Roo Code is a VS Code extension that transforms the editor into an autonomous agent.

• Features: It explicitly supports OpenRouter, Anthropic, DeepSeek, and Gemini APIs. It features "Modes" (Code, Architect, Ask, Debug) to tailor the AI's behavior and system prompts to the specific task

• Control: Roo Code gives the developer absolute control. You can approve every tool call, set budget limits, and switch providers on the fly. It is the tool of choice for the "sovereign developer."

Kilo Code:

Kilo Code offers a transparent "pay for what you use" model.

• Features: It integrates with local models (via Ollama) or cloud APIs. It focuses on "Agentic Engineering," providing a team of AI agents that work together to build software

The CLI Renaissance

A surprising trend in 2024-25 is the return to the Command Line Interface (CLI). As agents become more capable, the graphical overhead of an IDE becomes unnecessary for many tasks.

Claude Code:

Anthropic's CLI tool allows developers to manage complex refactors directly from the terminal.

• Workflow: Users can issue natural language commands like "refactor the auth module to use JWTs," and the CLI manages the file reads, edits, and git commits autonomously.46 It creates a "headless" coding experience where the human acts as the manager.

Gemini CLI & OpenCode:

Google's Gemini CLI brings the power of Gemini 3 Pro/Flash to the terminal OpenCode provides an open-source, vendor-neutral alternative, popular among Vim/Neovim users who prefer lightweight, keyboard-driven workflows. These tools appeal to "vim lovers" and power users who want to script their AI interactions.

Vibe Coding Platforms

"Vibe Coding" refers to a development style where the user provides natural language intent ("Make it pop," "Add a dark mode toggle"), and the AI handles the implementation details entirely. The user validates the "vibe" (the outcome) rather than the code.

Lovable.dev:

Lovable is a platform that generates full-stack web apps from text.

• Capabilities: It integrates with backends like Supabase and handles deployment. It effectively replaces the junior dev + DevOps loop for prototypes.48 Users can describe a "CRM for a dog walking business," and Lovable spins up the database, authentication, and frontend UI in minutes.

Bolt.new:

Bolt is a browser-based full-stack builder.

• Capabilities: It creates a containerized environment where the AI can write and execute code, allowing for instant preview and iteration.49 It is the ultimate "low-floor" tool for Vibe Coding, allowing anyone with an idea to build a functional app without setting up a local dev environment.

Jules (Google), Copilot, Cursor Agents:

Jules and the Background Agents by existing IDE heavyweights represents the "asynchronous" future of vibe coding.

• Workflow: Unlike an IDE assistant, these works on GitHub PRs. You assign it a task ("Upgrade all dependencies and fix breaking changes"), and it creates a Pull Request hours later.51 It is "fire and forget" software development, where the AI acts as a remote contractor.

The Fungible Future

The "Copilot Era" of 2023-2024 was defined by convenience and bundling. The "Unbundled Era" of 2026 is defined by control, specialization, and arbitrage.

The three layers of the stack—Provider, Model, and Tool—have become fully fungible. A developer today might write code in Cursor (Tool), routed via DeepInfra (Provider) to DeepSeek V3 (Model) for drafting, while using Claude Code (Tool) with Opus 4.5 (Model) for architectural review.

This unbundling has three profound implications:

1. Price Deflation: The competition at the Provider and Model layers (driven by Chinese labs and open weights) ensures that the cost of intelligence trends toward zero for standard tasks.

2. Tool Innovation: Freed from the burden of training models, tool builders (Roo, Cursor, Bolt) are innovating rapidly on UX, creating new paradigms like "Vibe Coding" where the interface is the product, not the model.

3. Sovereignty: The ability to self-host or choose vendor-neutral protocols (MCP) protects developers from platform capture. The stack is no longer a monolith; it is a set of Lego blocks.

As we look toward late 2026, the distinction between "writing code" and "managing agents" will continue to blur. The unbundled stack provides the necessary infrastructure for this transition, allowing developers to assemble the exact cognitive supply chain required to build the future.

The Microchip Revolution: From Labs to Laptops

The Transformation Pattern

The microchip revolution followed a clear democratization arc. In the 1960s and early 1970s, computing existed primarily in corporate mainframes and university research centers. These room-sized machines required specialized knowledge and institutional access—individual programmers couldn't become computer experts without affiliation to top laboratories or universities.^1

The introduction of microprocessors changed everything. Intel's 4004 in 1971 and the more powerful 8008 in 1972 made it possible to build computers that could sit on office desks. By the late 1970s and early 1980s, personal computers became mass-market products, with the IBM PC in 1981 establishing the dominant standard. This shift enabled anyone with a personal computer to start writing software and experimenting with code.^3^5

Job Displacement and Creation

The computer revolution eliminated traditional roles like secretaries who took dictation and typists, but created vastly more opportunities. According to McKinsey Global Institute research, while approximately 3.5 million jobs were destroyed in the US between 1980 and the present due to personal computing and the Internet, over 19 million new jobs were created—a net gain of 15.8 million positions. This represents about 10% of today's civilian labor force working in occupations that exist directly because of computer technology.^6

The new jobs spanned multiple categories: hardware manufacturing, software development, system administration, and entirely new industries like call centers that couldn't exist without computer terminals to access customer information.^6

The Cloud Computing Wave: From Server Rooms to Services

The Transformation Pattern

The cloud revolution followed a similar democratization model. In the 1990s and early 2000s, every tech company providing internet services needed to run their own physical servers. Becoming a system administrator, database administrator, or Linux engineer required working at companies with substantial infrastructure investments.^7

The introduction of Infrastructure-as-a-Service platforms in 2006, led by Amazon Web Services, radically changed how businesses manage computing resources. Instead of massive upfront capital expenditures for servers, companies could provision computing power with just a few clicks, transforming capital expenses into operational expenses. This shift significantly lowered the barrier to entry for starting software companies and created an economic boom that continues today.^9

Job Evolution in the Cloud Era

Cloud computing didn't simply eliminate traditional IT roles—it transformed them. Traditional database administrators saw their responsibilities shift from hardware installation and maintenance to database customization, query optimization, and security management. System administrators evolved into DevOps engineers and cloud architects, focusing on orchestrating distributed systems rather than managing physical hardware.^8

The cloud era created infinitely more opportunities than it displaced, with backend and web developer jobs exploding as the barrier to building consumer products dropped dramatically. Companies could now focus on application logic rather than infrastructure management, enabling rapid innovation in web and mobile applications.^11

The AI Wave: From GPU Clusters to Universal Access

Current Access Barriers

Today's AI landscape mirrors the early stages of both previous revolutions. Access to powerful AI capabilities has been limited to organizations with massive GPU clusters. Training sophisticated AI models requires enormous computational power—GPT-4 training alone required around 30 megawatts of power, while high-end GPUs can consume 400-700 watts per chip, similar to a microwave.^13^15

Normal software engineers struggle to become ML experts or create AI applications without exposure to these expensive, specialized computing resources. The barriers are substantial: AI data centers require exponentially more electricity than traditional facilities, and GPU clusters can cost millions of dollars to establish and operate.^16^18

Democratization Through Multiple Vectors

The democratization of AI is happening through several converging trends:

Enterprise Token Access: Companies are increasingly providing employees with unlimited or generous AI token allowances, with enterprise AI spending growing 75% year-over-year. Organizations investing in AI access for employees are seeing an average 41% return on investment, with 75% of knowledge workers now using AI at work.^19^21

Open Source Models: The proliferation of open-source AI models is reducing dependency on proprietary systems. Powerful models can now run locally on consumer hardware, with Apple's M-series chips particularly well-suited for AI workloads. Local AI implementations on Mac Silicon can run sophisticated models like Llama and Qwen without cloud dependencies.^22

Improved Local Compute: Apple's M4 chips enable users to run some of the most advanced open-source large language models locally, while techniques like "Mixture of Experts" architectures are improving training efficiency. This allows individual developers and small organizations to experiment with AI without massive infrastructure investments.^23^24

Productivity Gains and Job Creation Patterns

Early evidence suggests AI follows the same job displacement/creation pattern as previous waves. Research shows AI can improve highly skilled worker performance by nearly 40% when used within its capabilities, while enterprise studies indicate AI helps workers save time (90%), focus on important work (85%), and be more creative (84%).^25

Like previous technological revolutions, AI is eliminating some routine tasks while creating demand for new skills. The economic potential of generative AI could enable labor productivity growth of 0.1 to 0.6 percent annually through 2040, with work automation potentially adding 0.5 to 3.4 percentage points annually to productivity growth.^26

The Investment Opportunity: Learning from History

Early Adopter Advantages

Companies that invested early in previous technological waves captured disproportionate returns. Organizations that provided employees with laptops during the PC revolution gained competitive advantages through improved mobility and productivity. Similarly, early cloud adopters reduced infrastructure costs while enabling faster innovation cycles.^12

The same pattern is emerging with AI. Companies like Spotify are investing heavily in AI-powered features, using artificial intelligence to drive deeper personalization and user engagement. Early enterprise AI adopters report seeing ROI within months of implementation, with 92% of organizations already seeing returns on their AI investments.^27

Strategic Implications

The historical pattern suggests that companies providing generous enterprise AI access and unlimited tokens will see the most significant gains from this technological wave. Just as cloud adoption enabled the creation of new business models and reduced barriers to innovation, universal AI access within organizations is likely to unlock new forms of productivity and creativity.^12

The key insight from both the microchip and cloud revolutions is that democratization—making powerful capabilities accessible to more people—creates exponentially more value than it destroys. The companies that recognize this pattern and invest accordingly will be positioned to capture the greatest benefits as AI transforms every aspect of business operations.

The AI wave represents not just another technological shift, but the continuation of a decades-long trend toward democratizing computational power. Organizations that embrace this democratization—by providing their teams with unlimited AI access and encouraging experimentation—will write the next chapter in the ongoing story of technology-driven economic growth.

And then, the email landed. Twilio announced they were sunsetting the Authy desktop app.

Initially, the end-of-life was set for August 2024, which was disappointing but manageable. But then, in a move that felt like a slap in the face to its most loyal users, the date was abruptly pulled forward to March 19, 2024.1 The developer community's reaction was, to put it mildly, not positive. One user summed it up perfectly: "This is an excellent way to piss off thousands of developers and make sure we never touch any of your products again".1

The real salt in the wound, however, wasn't just the loss of the app. It was the realization of the digital cage we'd been living in. Authy provided no way to export your 2FA secrets.1 The only way to migrate to a new authenticator was to painstakingly go through every single one of your accounts, disable 2FA, and then re-enable it with a new app. For anyone with more than a handful of accounts, this was a nightmare.

This experience was a catalyst. It crystallized a problem that had been nagging at me for a while: our reliance on proprietary, centrally-controlled services for our most critical security functions. The moment a company decides to change its strategy, pivot, or simply cut costs, we, the users, are left stranded. This project, therefore, is more than just an attempt to build a replacement for a defunct app. It’s a philosophical stance. It's about reclaiming our digital sovereignty and building a tool based on principles of openness, user control, and data ownership. It’s about building the authenticator I, and many others, always wanted.

NOTE: Many parts of this article is paraphrased using Google Gemini Deep Research based on my rough notes for this project.

Surveying the Landscape: A Crowded Field with Room for One More

Before diving into a new project, it’s always wise to survey the existing landscape. I’m not the first person to have this idea, and there are some truly excellent open-source authenticator apps out there. The goal isn't to reinvent the wheel, but to see if there's a specific niche—my niche—that isn't being perfectly served.

The Contenders: 2FAS and Ente

Two projects immediately stand out: 2FAS and Ente Auth.

2FAS is fantastic and has a massive following for good reason. It's fully open-source, doesn't require an account to use, has a beautiful and simple user interface, and even provides browser extensions for one-tap authentication.4 It hits many of the right notes on privacy and usability. However, it falls short of my personal "be everywhere" requirement. It lacks official desktop clients, and while there are browser extensions, it's not the same as a native application. Furthermore, there's no support for wearables like the Apple Watch, a feature some users have explicitly wished for.5

Ente Auth gets even closer to my ideal. It is also open-source and has been praised by the likes of Linus Tech Tips. Crucially, it offers a full suite of native clients for Android, iOS, Windows, macOS, and Linux, plus a web app.9 This is a huge win for cross-platform users. It provides end-to-end encrypted cloud backup and sync, which is a great feature for most people.

But here’s the rub. Ente's sync is tied to their cloud service.8 While it is end-to-end encrypted and the company has a strong privacy focus, it doesn't satisfy the power-user desire for complete and total control over the backup location. What if I want to store my encrypted secrets in my own S3 bucket? Or on my personal Google Drive? Or sync them to a local server via anrsync endpoint? This is where I see the gap.

My project aims to fill the niche for the user who wants the comprehensive, multi-platform presence of Ente but with the absolute data sovereignty of being able to choose their own backup provider. It's for the developer who demands a first-class, scriptable Command-Line Interface (CLI) not just as an afterthought, but as a core part of the experience.

The Vision: A Manifesto for the Perfect Authenticator

This project is guided by a set of core principles that address the shortcomings of existing solutions and embody the spirit of user empowerment.

1. Platform Ubiquity: The app must be available and feel native on every platform I use: iOS, Android, watchOS, Wear OS, Windows, macOS, Linux, the Web (as a PWA and browser extension), and the command line.

2. User Sovereignty: Your secrets are yours. Period. The application will never require you to use a hosted cloud service. Backups will be fully under your control.

3. Interoperability: The core logic should be a self-contained, distributable library that other developers can use in their own projects.

4. Openness: Everything, from the cryptographic core to the UI, will be open-source, auditable, and community-driven.

5. Intelligence: The app should do more than just display six-digit codes. It should provide context and act as a security advisor to help users make smarter decisions.

Feature Breakdown

With those principles in mind, here is the planned feature set:

• Baseline Requirements (v1.0):

  • Support for TOTP (Time-based) and HOTP (HMAC-based) one-time passwords.

  • Ability to add accounts by scanning a QR code or manually entering the secret string.

  • GUI apps for iOS, Android, watchOS, and Wear OS.

  • GUI apps for desktop: Windows, macOS, and Linux.

  • A fully-featured web app (PWA) and browser extensions for Chrome and Firefox.

  • A first-class, scriptable CLI for power users and automation.

  • Ability to create encrypted backups locally, without involving any cloud service.

• Future Features (v2.0 and beyond):

  • A simple, secure password manager for storing private passwords alongside 2FA secrets.

  • Multiple backup "providers," allowing you to "bring your own cloud." This includes options like a personal S3-compatible bucket, a Google Drive or Apple iCloud folder, or even an rsync-compatible endpoint.

To make the vision clearer, here’s how my proposed app (let's tentatively call it AuthZen) stacks up against the competition:

This table shows the clear value proposition. AuthZen is designed for the user who wants it all: every platform, complete control over their data, and a powerful CLI, all wrapped in an open-source package.

The Architectural Blueprint: Kotlin, One Codebase to Rule Them All

So, how is it possible for a solo developer to build and maintain an application across such a vast array of platforms? The answer lies in a carefully chosen, modern tech stack that maximizes code reuse without sacrificing performance or the native feel of each platform. The cornerstone of this entire project is Kotlin.

Why Kotlin Multiplatform is the Only Sane Choice

Building native apps for iOS (Swift/SwiftUI), Android (Kotlin/Compose), and Desktop (C++/Qt, C#/WPF, Electron/JS, etc.) would require three or more separate codebases. This is simply not feasible. This is where Kotlin Multiplatform (KMP) comes in. KMP is a technology from JetBrains that allows you to share code between different platforms while retaining full access to native APIs.12

This isn't like older cross-platform frameworks that give you a one-size-fits-none solution. With KMP, you decide what to share. For this project, the plan is to share almost everything: the business logic, the data models, the network code, and even the UI. The fact that Google now officially supports KMP for its Jetpack libraries gives this approach immense credibility and ensures its longevity.14

The Core Engine: lib2fa

The heart of the application will be a shared Kotlin module, tentatively named lib2fa. This library will contain all the critical, non-UI logic:

• The implementation of the TOTP and HOTP algorithms.

• Logic for parsing otpauth:// URIs.

• Encryption and decryption routines for backups.

• State management for the list of accounts.

• (In v2.0) The integration logic for the various backup providers (S3, Google Drive, etc.).

The beauty of KMP is how this single library can be compiled for different targets:

• For JVM Targets (Android, Desktop): The lib2fa code will be compiled into a standard Java .jar file, which can be easily consumed by the Android and Desktop JVM applications.12

• For Native Targets (iOS, CLI): Using Kotlin/Native, the exact same Kotlin code is compiled down to native machine code.15 For iOS and watchOS, this produces a

  .xcframework that can be imported directly into an Xcode project. For the desktop and CLI apps, it produces standalone executables or shared libraries (.so on Linux, .dll on Windows).15 This directly fulfills the goal of having a core engine that is truly interoperable.

Painting the Pixels with Compose Multiplatform

For all the graphical user interfaces, I'll be using Compose Multiplatform. This is a declarative UI framework from JetBrains, based on Android's popular Jetpack Compose, that allows you to share your UI code across Android, iOS, desktop, and even the web.13

This means I can write the UI for a feature once in Kotlin, and it will run everywhere.

• On Desktop, Compose uses the powerful Skia 2D graphics library for rendering, giving it native performance.17

• On Android, it's the native Jetpack Compose framework.

• On iOS, it renders its UI into a native UIViewController, allowing for seamless integration with the rest of the iOS ecosystem.18

• On the Web, it compiles to WebAssembly (WASM), offering near-native performance in the browser.20

This unification of logic and UI is the project's strategic enabler. When I add the v2.0 password manager feature, I'll add the logic to lib2fa and the UI screens to the shared Compose module. With one push, that feature will be available consistently and simultaneously across every single platform. This is a massive advantage in development speed and ensures a cohesive user experience that many cross-platform projects lack.

The CLI: A Purely Native Experience

The Command-Line Interface won't be a second-class citizen. It will be a dedicated Kotlin/Native application that depends directly on the native-compiled lib2fa. I'll use a robust library like kotlinx-cli to build a powerful and user-friendly interface with commands, subcommands, and flags, making it perfect for scripting and automation.22

Here’s a clear breakdown of the architecture:

The Road Ahead: Open Source, Open for Contribution

This is an ambitious project, but it's one I'm incredibly passionate about. The entire codebase, from lib2fa to every UI component, will be open-source under a permissive license. Trust is paramount for a security tool, and the only way to earn it is through transparency.

This is just the beginning of the journey. I'm starting this project not just for myself, but for everyone who felt the sting of the Authy shutdown and wished for a better, more open alternative. I'll be setting up a GitHub repository soon where you can follow the progress, star the project, contribute ideas, and eventually, submit code.

Let's build the tool we all deserve.

Works Referenced

1. Twilio reminds users that Authy Desktop apps die in March – not in August - The Register, accessed on June 21, 2025, https://www.theregister.com/2024/02/15/twilio_authy_eol/

2. Topic: Authy for Desktop End of Life (EOL) @ AskWoody, accessed on June 21, 2025, https://www.askwoody.com/forums/topic/authy-for-desktop-end-of-life-eol/

3. help.twilio.com, accessed on June 21, 2025, https://help.twilio.com/articles/22771146070299-User-guide-End-of-Life-EOL-for-Twilio-Authy-Desktop-app

4. 2FA Authenticator (2FAS) on the App Store, accessed on June 21, 2025, https://apps.apple.com/us/app/2fa-authenticator-2fas/id1217793794

5. 2FAS Review - PCMag, accessed on June 21, 2025, https://www.pcmag.com/reviews/2fas

6. 2FAS - 2FA Authentication App Reviews (2025) - Product Hunt, accessed on June 21, 2025, https://www.producthunt.com/products/2fas-2fa-authentication-app/reviews

7. Ente Auth - 2FA Authenticator – Apps on Google Play, accessed on June 21, 2025, https://play.google.com/store/apps/details/ente_Authenticator?id=io.ente.auth&hl=en_AU

8. What is Ente Auth? - WorkOS, accessed on June 21, 2025, https://workos.com/blog/what-is-ente-auth

9. Ente Auth - 2FA Authenticator - Apps on Google Play, accessed on June 21, 2025, https://play.google.com/store/apps/details?id=io.ente.auth

10. Ente Auth - Open source 2FA authenticator, with E2EE backups, accessed on June 21, 2025, https://ente.io/auth/

11. Ente Auth - 2FA Authenticator on the App Store, accessed on June 21, 2025, https://apps.apple.com/us/app/ente-auth-2fa-authenticator/id6444121398

12. Kotlin Multiplatform Development: A Comprehensive Guide - Riseup Labs, accessed on June 21, 2025, https://riseuplabs.com/kotlin-multiplatform-development-comprehensive-guide/

13. Kotlin Multiplatform – Build Cross-Platform Apps - JetBrains, accessed on June 21, 2025, https://www.jetbrains.com/kotlin-multiplatform/

14. Kotlin Multiplatform Overview - Android Developers, accessed on June 21, 2025, https://developer.android.com/kotlin/multiplatform

15. Kotlin/Native | Kotlin Documentation, accessed on June 21, 2025, https://kotlinlang.org/docs/native-overview.html

16. Kotlin Multiplatform | Kotlin Documentation, accessed on June 21, 2025, https://kotlinlang.org/docs/multiplatform.html

17. Compose Multiplatform – Beautiful UIs Everywhere - JetBrains, accessed on June 21, 2025, https://www.jetbrains.com/compose-multiplatform/

18. Has anyone used Compose Multiplatform? : r/FlutterDev - Reddit, accessed on June 21, 2025, https://www.reddit.com/r/FlutterDev/comments/1afeo2r/has_anyone_used_compose_multiplatform/

19. Building a subscription tracker Desktop and iOS app with compose multiplatform - Setup, accessed on June 21, 2025, https://dev.to/kuroski/building-a-subscription-tracker-desktop-and-ios-app-with-compose-multiplatform-5feg

20. Create your Compose Multiplatform app - JetBrains, accessed on June 21, 2025, https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-create-first-app.html

21. Compose Multiplatform, a modern UI framework for Kotlin that makes building performant and beautiful user interfaces easy and enjoyable. - GitHub, accessed on June 21, 2025, https://github.com/JetBrains/compose-multiplatform

22. Kotlin/kotlinx-cli: Pure Kotlin implementation of a generic CLI parser. - GitHub, accessed on June 21, 2025, https://github.com/Kotlin/kotlinx-cli

I actually even made a whole game to place people on urinal stalls using various code-generating tools like bolt.new to have fun with this

The Prompt

Anyway, that led me to wonder, how would today’s (that is Jan 2025) state of the art LLM models fare on solving a LeetCode-style puzzle of optimally placing people in a row of urinal stalls which are already partially occupied.

So I tried my best to come up with a prompt that’s worded like typical LeetCode questions

There are 8 urinal stalls and some people are already using some of them. We have to place one new person in that stall. The current state of the urinal stalls is represented by a 8 digit number like 01100110 which means there are people occupying stalls 2, 3,6 and 7 After the new person is placed at a position, the final "comfort" score is calculated. We go from one end to another, and for every person (i.e. a '1') we do the following

• add +1 for empty slot on either left or right (+2 if both empty)

• add another +1 for 2 empty slots on either left or right (+2 if on both sides)

For the following existing urinal stall configurations, give the answer that in which position should the new person be added, and what will be the total comfort score of that configurations. If there are more than one positions where the highest comfort score can be achieved, any of those positions is a correct answer. (stalls are counted 1-indexed, starting from left).

Question Inputs

1. 01101010

2. 11010101

3. 11001011

4. 00111100

5. 01001010

6. 11001110

7. 10000110

8. 11000110

This particular question is something I just conjured up 30 min ago, so obviously this exact question would not be in the training data. But the way this question is framed with the particular format of input and output, is fairly common from LeetCode to events like Advent of Code, so the LLMs are definitely trained on tons of data of this particular format.

The Answers

Let’s see how different LLM models fare with this prompt. These are all 1st-attempt answers, on a fresh chat without any previous context, conversation history or “memory”.

Claude 3.5 Sonnet

I'll help solve this urinal placement optimization problem. Let me solve it step by step for each configuration.

1. For 01101010:
Let me check each possible position and calculate scores.
The best position is stall 8 (rightmost), giving a final configuration of 01101011.
Final score calculation:
- Position 2: +1 (right empty)
- Position 3: +1 (right empty)
- Position 6: +2 (both sides empty)
- Position 7: +1 (right empty)
- Position 8: +1 (left empty)
Total comfort score: 6

2. For 11010101:
Only positions 4 and 6 are available.
Best position is 4, giving 11011101.
Final score calculation:
- Position 1: +1 (right empty)
- Position 2: +1 (right empty)
- Position 4: +2 (initially both empty)
- Position 6: +1 (right empty)
- Position 8: +1 (left empty)
Total comfort score: 6

3. For 11001011:
Position 5 is the best choice, giving 11001111.
Final score calculation:
- Position 1: +1 (right empty)
- Position 2: +1 (right empty)
- Position 5: +0 (no empty adjacent)
- Position 6: +0 (no empty adjacent)
- Position 7: +0 (no empty adjacent)
- Position 8: +1 (left empty)
Total comfort score: 3

4. For 00111100:
Position 1 is optimal, giving 10111100.
Final score calculation:
- Position 1: +1 (right empty)
- Position 3: +0 (no empty adjacent)
- Position 4: +0 (no empty adjacent)
- Position 5: +0 (no empty adjacent)
- Position 6: +1 (right empty)
Total comfort score: 2

5. For 01001010:
Position 8 is optimal, giving 01001011.
Final score calculation:
- Position 2: +2 (both sides empty)
- Position 5: +2 (both sides empty)
- Position 7: +1 (right empty)
- Position 8: +1 (left empty)
Total comfort score: 6

6. For 11001110:
Position 5 is optimal, giving 11001110.
Final score calculation:
- Position 1: +1 (right empty)
- Position 2: +1 (right empty)
- Position 5: +0 (no empty adjacent)
- Position 6: +1 (right empty)
- Position 7: +1 (right empty)
Total comfort score: 4

7. For 10000110:
Position 4 is optimal, giving 10001110.
Final score calculation:
- Position 1: +2 (right empty + double right empty)
- Position 4: +2 (both sides empty)
- Position 6: +1 (right empty)
- Position 7: +1 (right empty)
Total comfort score: 6

8. For 11000110:
Position 4 is optimal, giving 11001110.
Final score calculation:
- Position 1: +1 (right empty)
- Position 2: +1 (right empty)
- Position 4: +1 (right empty)
- Position 6: +1 (right empty)
- Position 7: +1 (right empty)
Total comfort score: 5

Summary of answers:
1. Position 8, Score 6
2. Position 4, Score 6
3. Position 5, Score 3
4. Position 1, Score 2
5. Position 8, Score 6
6. Position 5, Score 4
7. Position 4, Score 6
8. Position 4, Score 5

Gemini 1.5 Pro

**Understanding the Scoring**

* **Proximity:** Each occupied stall (1) gets points for adjacent empty stalls (0).  One point for each side with an empty stall, up to two points per side.
* **Total Score:** The sum of the proximity points for all occupied stalls.

**Analyzing the Inputs**

To find the best position for the new person, we'll consider each possible placement and calculate the resulting comfort score.

**1. 01101010**

* **Best Position:** 5 (0110**1**1010)
* **Score:** 10 
    * (Stall 2: 2 points) + (Stall 3: 2 points) + (Stall 5: 2 points) + (Stall 7: 2 points) + (Stall 8: 2 points) = 10

**2. 11010101**

* **Best Position:** 3 (11**1**10101) 
* **Score:** 6
    * (Stall 1: 1 point) + (Stall 2: 1 point) + (Stall 3: 2 points) + (Stall 4: 1 point) + (Stall 6: 1 point) + (Stall 8: 0 points) = 6

**3. 11001011**

* **Best Position:**  3 (11**1**01011)
* **Score:** 8
    * (Stall 1: 1 point) + (Stall 2: 1 point) + (Stall 3: 2 points) + (Stall 5: 2 points) + (Stall 7: 1 point) + (Stall 8: 1 point) = 8

**4. 00111100**

* **Best Positions:** 1 or 8 (**1**0111100 or 0011110**1**)
* **Score:** 8
    * (Stall 1/8: 2 points) + (Stall 3: 2 points) + (Stall 4: 2 points) + (Stall 5: 2 points) = 8

**5. 01001010**

* **Best Position:** 3 (01**1**01010)
* **Score:** 10
    * (Stall 2: 2 points) + (Stall 3: 2 points) + (Stall 5: 2 points) + (Stall 7: 2 points) + (Stall 8: 2 points) = 10

**6. 11001110**

* **Best Position:** 3 (11**1**01110)
* **Score:** 6
    * (Stall 1: 1 point) + (Stall 2: 1 point) + (Stall 3: 2 points) + (Stall 5: 1 point) + (Stall 6: 1 point) + (Stall 7: 0 points) = 6

**7. 10000110**

* **Best Position:** 4 (100**1**0110)
* **Score:** 10
    * (Stall 1: 2 points) + (Stall 4: 4 points) + (Stall 6: 2 points) + (Stall 7: 2 points) = 10

**8. 11000110**

* **Best Position:**  4 (110**1**0110)
* **Score:** 8
    * (Stall 1: 1 point) + (Stall 2: 1 point) + (Stall 4: 4 points) + (Stall 6: 1 point) + (Stall 7: 1 point) = 8

Gemini 2.0 Flash Experimental

Here's the breakdown of optimal placement and comfort scores for each urinal configuration:

**Understanding the Scoring**

It's crucial to understand the scoring system. For each occupied stall (1), we check the adjacent empty stalls (0s).

*   **+1 for each adjacent empty stall:** Up to +2 per occupied stall.
*   **+1 for each pair of adjacent empty stalls:** Up to +2 per occupied stall.

**Calculations**

Here's the analysis for each configuration:

**1. 01101010**

*   Placing at index 0: 11101010. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 3: 01111010. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 5: 01101110. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 7: 01101011. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   **Optimal Placement:** 0, 3, 5, or 7.
*   **Comfort Score:** 8

**2. 11010101**

*   Placing at index 2: 11110101. Score: (0+1)+(1+1)+(1+1)+(1+1) = 6
*   Placing at index 4: 11011101. Score: (1+1)+(1+1)+(1+1)+(0+1) = 6
*   Placing at index 6: 11010111. Score: (1+1)+(1+1)+(0+1)+(1+1) = 6
*   **Optimal Placement:** 2, 4, or 6.
*   **Comfort Score:** 6

**3. 11001011**

*   Placing at index 2: 11101011. Score: (0+1)+(1+2)+(1+1)+(1+1) = 7
*   Placing at index 3: 11011011. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 5: 11001111. Score: (1+1)+(1+1)+(0+1)+(1+1) = 6
*   **Optimal Placement:** 3
*   **Comfort Score:** 8

**4. 00111100**

*   Placing at index 0: 10111100. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 1: 01111100. Score: (1+0)+(0+1)+(1+1)+(1+1) = 6
*   Placing at index 6: 00111110. Score: (1+1)+(1+1)+(1+0)+(0+1) = 6
*   Placing at index 7: 00111101. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   **Optimal Placement:** 0 or 7
*   **Comfort Score:** 8

**5. 01001010**

*   Placing at index 0: 11001010. Score: (0+2)+(1+1)+(1+1)+(1+1) = 7
*   Placing at index 2: 01101010. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 3: 01011010. Score: (1+1)+(0+2)+(1+1)+(1+1) = 7
*   Placing at index 5: 01001110. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   Placing at index 7: 01001011. Score: (1+1)+(1+1)+(1+1)+(1+1) = 8
*   **Optimal Placement:** 2, 5, or 7
*   **Comfort Score:** 8

**6. 11001110**

*   Placing at index 2: 11101110. Score: (0+1)+(1+2)+(0+1)+(0+1) = 5
*   Placing at index 3: 11011110. Score: (1+1)+(1+1)+(0+1)+(0+1) = 6
*   **Optimal Placement:** 3
*   **Comfort Score:** 6

**7. 10000110**

*   Placing at index 1: 11000110. Score: (0+1)+(2+1)+(1+1) = 6
*   Placing at index 2: 10100110. Score: (1+1)+(1+1)+(1+1) = 6
*   Placing at index 3: 10010110. Score: (1+1)+(1+1)+(1+1) = 6
*   Placing at index 4: 10001110. Score: (1+1)+(0+1)+(0+1) = 4
*   **Optimal Placement:** 1, 2, or 3
*   **Comfort Score:** 6

**8. 11000110**

*   Placing at index 2: 11100110. Score: (0+1)+(2+1)+(1+1) = 6
*   Placing at index 3: 11010110. Score: (1+1)+(1+1)+(1+1) = 6
*   Placing at index 4: 11001110. Score: (1+1)+(0+1)+(0+1) = 4
*   **Optimal Placement:** 2 or 3
*   **Comfort Score:** 6

Gemini 2.0 Experimental Advanced

Okay, I understand the problem. Let's analyze each configuration and determine the best position for the new person and the resulting comfort score.

**How the Comfort Score is Calculated**

For each person (1) in the urinal row:

*   **+1 point:**  If there's an empty slot (0) to their immediate left or right.
*   **+1 point (additional):** If there are two empty slots (00) to their immediate left or right.

**Analysis of Each Configuration**

Here's the breakdown for each input:

**1. 01101010**

*   **Possible new person positions:** 1, 4, 6, 8
*   **Analysis:**
    *   **Position 1:** `11101010` -> Comfort: 0 + 1 + 2 + 0 + 1 + 0 + 1 + 0 = 5
    *   **Position 4:** `01111010` -> Comfort: 0 + 1 + 2 + 2 + 2 + 0 + 1 + 0 = 8
    *   **Position 6:** `01101110` -> Comfort: 0 + 1 + 1 + 0 + 1 + 2 + 2 + 0 = 7
    *   **Position 8:** `01101011` -> Comfort: 0 + 1 + 1 + 0 + 1 + 0 + 1 + 1 = 5
*   **Best position:** 4
*   **Comfort score:** 8

**2. 11010101**

*   **Possible new person positions:** 3, 5, 7
*   **Analysis:**
    *   **Position 3:** `11110101` -> Comfort: 1 + 2 + 2 + 2 + 0 + 1 + 0 + 1 = 9
    *   **Position 5:** `11011101` -> Comfort: 1 + 1 + 0 + 1 + 2 + 2 + 0 + 1 = 8
    *   **Position 7:** `11010111` -> Comfort: 1 + 1 + 0 + 1 + 0 + 1 + 2 + 2 = 8
*   **Best position:** 3
*   **Comfort score:** 9

**3. 11001011**

*   **Possible new person positions:** 3, 4, 6
*   **Analysis:**
    *   **Position 3:** `11101011` -> Comfort: 1 + 2 + 1 + 0 + 1 + 0 + 2 + 1 = 8
    *   **Position 4:** `11011011` -> Comfort: 1 + 1 + 0 + 2 + 2 + 0 + 2 + 1 = 9
    *   **Position 6:** `11001111` -> Comfort: 1 + 1 + 0 + 0 + 1 + 2 + 2 + 2 = 9
*   **Best positions:** 4, 6
*   **Comfort score:** 9

**4. 00111100**

*   **Possible new person positions:** 1, 2, 7, 8
*   **Analysis:**
    *   **Position 1:** `10111100` -> Comfort: 1 + 0 + 2 + 2 + 2 + 1 + 0 + 0 = 8
    *   **Position 2:** `01111100` -> Comfort: 0 + 1 + 2 + 2 + 2 + 1 + 0 + 0 = 8
    *   **Position 7:** `00111110` -> Comfort: 0 + 0 + 1 + 2 + 2 + 2 + 1 + 0 = 8
    *   **Position 8:** `00111101` -> Comfort: 0 + 0 + 1 + 2 + 2 + 1 + 0 + 1 = 7
*   **Best positions:** 1, 2, 7
*   **Comfort score:** 8

**5. 01001010**

*   **Possible new person positions:** 1, 3, 4, 6, 8
*   **Analysis:**
    *   **Position 1:** `11001010` -> Comfort: 1 + 2 + 0 + 0 + 1 + 0 + 1 + 0 = 5
    *   **Position 3:** `01101010` -> Comfort: 0 + 1 + 2 + 0 + 1 + 0 + 1 + 0 = 5
    *   **Position 4:** `01011010` -> Comfort: 0 + 1 + 0 + 2 + 2 + 0 + 1 + 0 = 6
    *   **Position 6:** `01001110` -> Comfort: 0 + 1 + 0 + 0 + 1 + 2 + 2 + 0 = 6
    *   **Position 8:** `01001011` -> Comfort: 0 + 1 + 0 + 0 + 1 + 0 + 1 + 1 = 4
*   **Best positions:** 4, 6
*   **Comfort score:** 6

**6. 11001110**

*   **Possible new person positions:** 3, 4, 8
*   **Analysis:**
    *   **Position 3:** `11101110` -> Comfort: 1 + 2 + 1 + 0 + 2 + 2 + 2 + 0 = 10
    *   **Position 4:** `11011110` -> Comfort: 1 + 1 + 0 + 2 + 2 + 2 + 2 + 0 = 10
    *   **Position 8:** `11001111` -> Comfort: 1 + 1 + 0 + 0 + 1 + 2 + 2 + 2 = 9
*   **Best positions:** 3, 4
*   **Comfort score:** 10

**7. 10000110**

*   **Possible new person positions:** 2, 3, 4, 5, 8
*   **Analysis:**
    *   **Position 2:** `11000110` -> Comfort: 1 + 2 + 0 + 0 + 0 + 2 + 1 + 0 = 6
    *   **Position 3:** `10100110` -> Comfort: 1 + 0 + 2 + 0 + 0 + 2 + 1 + 0 = 6
    *   **Position 4:** `10010110` -> Comfort: 1 + 0 + 0 + 2 + 0 + 2 + 1 + 0 = 6
    *   **Position 5:** `10001110` -> Comfort: 1 + 0 + 0 + 0 + 2 + 2 + 2 + 0 = 7
    *   **Position 8:** `10000111` -> Comfort: 1 + 0 + 0 + 0 + 0 + 1 + 2 + 2 = 6
*   **Best position:** 5
*   **Comfort score:** 7

**8. 11000110**

*   **Possible new person positions:** 3, 4, 5, 8
*   **Analysis:**
    *   **Position 3:** `11100110` -> Comfort: 1 + 2 + 1 + 0 + 0 + 2 + 1 + 0 = 7
    *   **Position 4:** `11010110` -> Comfort: 1 + 1 + 0 + 2 + 0 + 2 + 1 + 0 = 7
    *   **Position 5:** `11001110` -> Comfort: 1 + 1 + 0 + 0 + 2 + 2 + 2 + 0 = 8
    *   **Position 8:** `11000111` -> Comfort: 1 + 1 + 0 + 0 + 0 + 1 + 2 + 2 = 7
*   **Best position:** 5
*   **Comfort score:** 8

**Summary Table**

| Input      | Best Position(s) | Comfort Score |
| :--------- | :--------------- | :------------ |
| 01101010   | 4                | 8             |
| 11010101   | 3                | 9             |
| 11001011   | 4, 6             | 9             |
| 00111100   | 1, 2, 7          | 8             |
| 01001010   | 4, 6             | 6             |
| 11001110   | 3, 4             | 10            |
| 10000110   | 5                | 7             |
| 11000110   | 5                | 8             |

Chat GPT 4o

To solve this problem, we'll compute the total "comfort" score for each valid position where the new person can be placed and find the position that yields the highest comfort score. Here's the solution for each input configuration:

---

### **1. Input: `01101010`**
- Valid positions: 1, 5, 8.
- Comfort scores:
  - Place at position **1**: Final state `11101010`. Score = 8.
  - Place at position **5**: Final state `01101110`. Score = 8.
  - Place at position **8**: Final state `01101011`. Score = 8.
- **Answer**: Position 1 (or 5 or 8), **Comfort score: 8**.

---

### **2. Input: `11010101`**
- Valid positions: 3, 6.
- Comfort scores:
  - Place at position **3**: Final state `11110101`. Score = 7.
  - Place at position **6**: Final state `11011101`. Score = 7.
- **Answer**: Position 3 (or 6), **Comfort score: 7**.

---

### **3. Input: `11001011`**
- Valid positions: 4, 5.
- Comfort scores:
  - Place at position **4**: Final state `11011011`. Score = 8.
  - Place at position **5**: Final state `11001111`. Score = 8.
- **Answer**: Position 4 (or 5), **Comfort score: 8**.

---

### **4. Input: `00111100`**
- Valid positions: 1, 2, 7, 8.
- Comfort scores:
  - Place at position **1**: Final state `10111100`. Score = 4.
  - Place at position **2**: Final state `01111100`. Score = 4.
  - Place at position **7**: Final state `00111110`. Score = 4.
  - Place at position **8**: Final state `00111101`. Score = 4.
- **Answer**: Position 1 (or 2, 7, 8), **Comfort score: 4**.

---

### **5. Input: `01001010`**
- Valid positions: 1, 3, 5, 7, 8.
- Comfort scores:
  - Place at position **1**: Final state `11001010`. Score = 10.
  - Place at position **3**: Final state `01101010`. Score = 9.
  - Place at position **5**: Final state `01011010`. Score = 9.
  - Place at position **7**: Final state `01001110`. Score = 9.
  - Place at position **8**: Final state `01001011`. Score = 9.
- **Answer**: Position 1, **Comfort score: 10**.

---

### **6. Input: `11001110`**
- Valid positions: 5.
- Comfort scores:
  - Place at position **5**: Final state `11011110`. Score = 7.
- **Answer**: Position 5, **Comfort score: 7**.

---

### **7. Input: `10000110`**
- Valid positions: 2, 3, 4, 5.
- Comfort scores:
  - Place at position **2**: Final state `11000110`. Score = 10.
  - Place at position **3**: Final state `10100110`. Score = 9.
  - Place at position **4**: Final state `10010110`. Score = 9.
  - Place at position **5**: Final state `10001110`. Score = 9.
- **Answer**: Position 2, **Comfort score: 10**.

---

### **8. Input: `11000110`**
- Valid positions: 4, 5.
- Comfort scores:
  - Place at position **4**: Final state `11010110`. Score = 8.
  - Place at position **5**: Final state `11001110`. Score = 7.
- **Answer**: Position 4, **Comfort score: 8**.

---

### **Summary of Results**
1. **01101010** → Position 1 (or 5, 8), Score = 8.  
2. **11010101** → Position 3 (or 6), Score = 7.  
3. **11001011** → Position 4 (or 5), Score = 8.  
4. **00111100** → Position 1 (or 2, 7, 8), Score = 4.  
5. **01001010** → Position 1, Score = 10.  
6. **11001110** → Position 5, Score = 7.  
7. **10000110** → Position 2, Score = 10.  
8. **11000110** → Position 4, Score = 8.

GPT o1 Preview

Finally it is time for our “thinking” model to have a go at it. It thought for close to 3 minutes for this.

To solve this problem, for each urinal stall configuration we considered all vacant positions (positions where the value is '0') and calculated the comfort score after placing a new person in that position. The comfort score is determined by the sum of comfort levels of all occupied stalls after the new person is placed, where the comfort for each person is calculated based on adjacent empty stalls as per the given rules.

For each configuration, we compared the total comfort scores for all possible placements of the new person and selected the position that resulted in the highest comfort score. If multiple positions yield the same highest score, any one of those positions can be the answer.

Here are the answers for the given configurations:

1. **Position:** 7, **Comfort Score:** 6
2. **Position:** 3, **Comfort Score:** 4
3. **Position:** 6, **Comfort Score:** 4
4. **Position:** 1, **Comfort Score:** 2
5. **Position:** 1, **Comfort Score:** 7
6. **Position:** 8, **Comfort Score:** 4
7. **Position:** 3, **Comfort Score:** 7
8. **Position:** 3, **Comfort Score:** 5

istration of the new person should be in the following stalls with the corresponding comfort scores.

**Answers:**

1. 7 6
2. 3 4
3. 6 4
4. 1 2
5. 1 7
6. 8 4
7. 3 7
8. 3 5

DeepSeek R1 671B

The entire chain of thought is pasted here - https://gist.github.com/championswimmer/361e91a8ead97c2afa85502d07bbf8fa. It “thought” for 4+ minutes, and generated 700+ lines of thoughts before giving the answer.

**Answers**

1. **Input: 01101010**  
   **Position:** 1  
   **Comfort Score:** 6  

2. **Input: 11010101**  
   **Position:** 3 (or 5 or 7)  
   **Comfort Score:** 5  

3. **Input: 11001011**  
   **Position:** 5  
   **Comfort Score:** 7  

4. **Input: 00111100**  
   **Position:** 1 or 8  
   **Comfort Score:** 14  

5. **Input: 01001010**  
   **Position:** 7  
   **Comfort Score:** 7  

6. **Input: 11001110**  
   **Position:** 8  
   **Comfort Score:** 8  

7. **Input: 10000110**  
   **Position:** 3  
   **Comfort Score:** 9  

8. **Input: 11000110**  
   **Position:** 7  
   **Comfort Score:** 7  

Each answer selects an optimal position (1-indexed) and the resulting maximum comfort score. If multiple positions yield the same score, any can be chosen.

Result Summary

I don’t know about the “AGI” hype of o1, but it definitely marks itself a rank above the others, when faced with a net-new question, which it never faced in training data. If the chain-of-thought was published, it would definitely be intriguing to look at, but at least on the board it scores a 7:1 win, when the closest anyone else could do (Claude 3.5 Sonnet) was a 1:7 loss.

If you try this prompt out with any open models like DeepSeek R1, LLaMa, Mistral etc, let me know in comments how did it go and did any of them solve it.

Bonus - 8 minutes of “thinking”

Just for run, here is DeepSeek R1 Distilled Llama 7b thinking for a whole 8 minutes

As is evident, just “CoT”ing your way out of incapable models does not really work. I don’t think a model can start reasoning just by forcing it to generate <think> blocks in its intermediate output and aligning it with reinforcement learning. Sure, it improves certain things, but it also opens you up to the jailbreak scenario where the thoughts spiral out of control, growing larger than the context, and thus pushing the original prompt out of the window, and the final answer having no relation to the actual prompt.

Tests should be independent, and ideally not block each other. Jest is designed to not make test file execution order deterministic, nor sequential, and there's a reason for that. one.spec.ts and two.spec.ts should be completely independent set of tests that can run from start to end without interacting with each other. There's a reason unit tests are called unit tests.

That said, let me describe where I wanted to do something like this. Below is a simplified diagram of some systems that we use, and the kind of tests we want to do.

The flow of the system

• home page - a list of categories (from content service)

• categories - a list of contents (from content service)

• contents - contain a content id with which further data is to be fetched from playback service

• player - gets playback URLs and runs the correct rendition* of content based on network conditions / device capability etc.

A 'rendition' means different formats like 4K, 1080p, with or without Dolby audio etc.

The test files and what they do

content.tests.ts

Tests that home page data can be fetched, and further data of all the contents inside it can be fetched. This is not a typical unit test, this is a periodic test that runs every hour, and we want it to fail if the API is not sending the correct data. (Think of this as more of an API monitoring test)

playback.tests.ts

This gets a content id, and based on that fetches content metadata and playback URLs from the playback service. It tests that playback URLs for all content ids are actually available, and the playback URLs contain valid playable video content / streams.

Why we want tests to be dependent on each other?

When content.tests.ts runs, it already fetches all the content ids (N categories, avg M contents in each - so M x N content ids)

We wish to run playback.tests.ts on all of those M x N content ids. Instead of repeating the work of fetching them inside playback.tests.ts we want to simply use the contents fetched inside content.tests.ts

Hacking up a basic global 'observable' inside Jest tests

content.tests.ts

So here's what we do. We make a global object contentList in content.tests.ts that will be imported in playback.tests.ts and we make a promise contentListReady that resolves when the content is downloaded (or times out at 6 seconds)

export const contentList: Content[] = []
// internal variable to be set true when all assets are downloaded
let _contentsReady = false

// hack to wait for all assets to be downloaded so that they can be used in `playback.tests.ts`
export const contentListReady: Promise<Boolean> = new Promise((resolve, reject) => {
     // Poll every second to check if asset list is ready
     // If asset list is ready, resolve the promise
     // If asset list is not ready after 6 seconds, reject the promise
     // Either way, clear the interval and the timeout
    const looper = setInterval(() => {
        if (_assetListReady && assetList.length > 0) {
            clearTimeout(waiter)
            clearInterval(looper)
            resolve(true)
        }
    }, 1000)
    const waiter = setTimeout(() => {
        clearInterval(looper)
        clearTimeout(waiter)
        reject("Asset List not ready")
    }, 6000)
})

describe('content', () => {
    test('get home', async () => { /* ... */ })
    test('get categories', async () => { /* ... */ })
    test('get contents', async () => { 
        // contents are available here 
        contents.forEach( content => contentList.push(content) )
        _contentsReady = true
    })
})

In the due course of running all iterations of content tests, the `contentList` will get populated. When all the contents are fetched, we will set _contentsReady to true.

playback.tests.ts

In the beforeAll hook we wait for content list to be ready

describe('playback', () => {
    beforeAll(async () => {
        info("Waiting for asset list to be ready...")
        if (await assetListReady) info("Asset list is ready")
        else error("Asset timed out")

    })

    test('playback sample', () => {
        expect(true).toBeTruthy()
    })
})

Thus even when jest actually starts all your tests in parallel, playback.tests.ts won't actually start executing its tests, till content.tests.ts either resolves or rejects the contentListReady promise.

Do remember to clear the timeout as well as the interval in that contentListReady promise, or else Jest will warn you about open handles at the end of the tests.

NOTE: I encountered this while working on the 1px.li project. You can find the source code of that here. It is hosted on Railway. You can find the hosting configuration and what all services it uses on Railway here.

For most things on http://1px.li so far I want to have a clean Dockerfile and docker-compose - and have a setup that replicates well on localhost as well as on Railway. So far Postgres was a charm. Clickhouse is not an officially supported "database" on Railway though.

But searching for Clickhouse does turn up a community-maintained image from marketplace, made by Greg Scheir, a Railway employee. It is basically straight up clickhouse/clickhouse-server:23.3.8.21 docker image only, which is great for my "whatever works on localhost, works same on Railway" principle.

Since the docker image takes variables CLICKHOUSE_USER, CLICKHOUSE_PASSWORD and CLICKHOUSE_DB by default, it is really easy to configure those things when deploying to Railway - just set those variables.

The challenge really comes in connecting to this database from other Railway services. So what happens for a databases like Postgres is that Railway sets up a TCP proxy for you - so that you can connect with the database's native driver that talks over raw TCP. Some databases (including Clickhouse) do allow connecting over HTTP(S) as well - but typically that is inefficient and unnecessary if your servers are inside a VPC already. While the docs at Railway.app do seem to say that TCP proxying is available for any service, at least when I launched the Clickhouse template I found there is no way to set up TCP proxy, but only use the HTTP connection.

Using Clickhouse over HTTP is something that'll take slight bit of digging to figure out all the pieces of the puzzle.

The official drivers seems to be made only for native connections, but actually it does support HTTP mode as well. It is said to be "experimental" though - I believe some types of data might fail while escaping it to be able to pass through HTTP bodies. (I haven't faced any problem so far)

But, I was not interested in using the raw driver. I am already using Gorm, and wanted to use Gorm for Clickhouse as well. But the gorm driver doesn't quite clearly mention that you can connect over HTTP too just by passing http:// as the schema instead of clickhouse://

The gorm clickhouse driver has moved to v2 of the clickhouse golang library, and thus, it can automatically use HTTP mode when the URL is HTTP protocol. Had to take to look through the source code to figure out that they handle it, before I could use it. Now to actually connect to this service on Railway, the best is to formulate 2 URLs, one for private and one for public access.

Private Access:

• you can use http, not https (within your cloud)

• server is exposed on the port of that service (default: 8123)

Public Access

• use https (Railway will handle TLS for you)

• server is exposed on 443, not the internal port, so don't specify port in this URL

The public URL is what you can connect to from your laptop. The private URL is what you should use from your server hosted inside Railway to access this.

One issue that has been plaguing me recently was that the cursor position was jittery, and when moving the mouse, the cursor was jumping around a bit.

I noticed that it happened a lot more if I was having an additional external monitor attached.

Just to note it down properly, here are the things I am using

• Macbook Pro 16" - 2021 Model (M1 Max)

• MacOS 12.1

• MX Master 3 Mouse

• Logi Options+ 1.60.xxx

So what solved the problem was a weird set of steps (I do not know why this solved the problem).

1. I turned down the Mouse tracking speed in system settings to really low

   

2. Inside Logi Options+ I increased the pointer speed to much higher to compensate for that.

   

If I have to hazard a guess, this way the actual hardware interface tracks the mouse much slower (hence less jumps) and the Logi Options+ driver translates that to bigger movements at the software layer. I do not know this for sure, and thus I do not know exactly why this set of steps fixes this problem, but that it does.

Anyway, documenting this mainly for myself to find this solution back again few years later when I update my Macbook to M4 Max or something and face this issue again, I guess. If you faced the same and this solved for you, do leave a comment. Thanks :)

So let me start by saying that I come from the world of Java (originally an Android developer, before branching out to do all the other stuff). Which means there's a very rigid idea about how test files are structured back in my world.

Recently I started working on a Golang sample project ¹ and I was told that in Go, typically you keep test files beside your source files. Makes sense, Go's understanding of modules is different from Java's understanding of packages. In Java, when building the test package, the code from main and test are merged semantically keeping the test and the source beside each other in runtime.

Fair enough. Some Javascript projects do the same too - and I am ok doing this.

My Problem with Project Structure

What I do not like though is this type of project structure (file explorer view) by default

- resources
- docs
- src 
    - users 
        - user_controller.go
        - user_controller_test.go
    - articles
        - article_data.go
        - article_data_tests.go
        - article_handler.go
        - article_handler_tests.go

What I would much rather prefer is - at first glance just see all my code.

- resources
- docs
- src 
    - users 
        - user_controller.go
    - articles
        - article_data.go
        - article_handler.go

and then, if I want to look at tests as well, I can expand them and see that as well

Collapsing Test Files

I'll keep it short - you can do this on Jetbrains (Intellij IDEA, Goland etc) as well as Visual Studio Code. I am sure other IDEs have it too - I don't use them - so not my concern for now.

Jetbrains

On JetBrains IDEs the concerned feature we are looking for is called File Nesting

Search for that in the actions bar,

You'll get into this little modal

There is a simple pattern to map there.

If you want all files of type xyz_test.go to be nested under xyz.go then just add this

As you can see, some other patterns, like _string.go and _easyjson.go are already there. These are common Go libraries for JSON parsing and String i18n/l10n which generate such files. I added the _test.go into it.

Now, this is how my src folder looks like by default when I open it

And the tests can be expanded if I want to see them

Visual Studio Code

The same thing can be done for Visual Studio Code. The feature over there is also called File Nesting - we need to go to Settings and enable it first (it is disabled by default).

The file pattern is slightly different here. I have added 2 rules there - one for nesting go.sum file under the go.mod file (I like that Jetbrains Goland does this out of the box). For the other case I write

*.go : ${basename}_test.go

The description in VS Code for that setting (in my above screenshot as well) should be self-explanatory.

And voila, the same thing works on VS Code for now.

References

• [1] https://github.com/championswimmer/onepixel_backend

The problem though lies that most developers starting out are not coached properly for it.

How UI is represented ?

Let's try to understand the problem here.

Classically how UI is represented and how it triggers logic is a bit like this

UI interacts with some "controller" like layer which in turn interacts with local DBs or APIs.

That's pretty much the basic 'structure' of this model.

As UIs keep updating, more and more complexities take place.

More UI elements are 'interactive' - clicking, toggling, typing, and scrolling them trigger different functions on the controllers, they fetch/save more stuff to the DB/API, and more things in UI updates.

Over time as the complexity grows and grows, problems arise. What if when the user is not logged in, someone scrolls the feed? We want only 2 folds of info for guest users or else trigger login.

Ok after login when they come back to this screen how to handle that?

That's just one example, but what keeps happening is that these different UI elements which trigger logic in different 'controller' like places need to have co-dependency on each other. Sometimes cyclic dependencies hit your performance with a ton of bricks.

Eventually, some of your senior developers - the ones that keep a copy of SICP under their pillow, and keep uttering "monad" and "closure" with an expression like food bloggers do when reviewing European dishes - want 'state management' to become 'declarative'.

Time to unpack.

Understanding State

So to understand what 'state' is, and get the essence of the rest of what I'll be saying, it might serve well to go for a quick trip to a state visualiser, like say - XState.

Here go play around with the visualiser here (you can add more states)

https://stately.ai/viz

Attaching here a few framework diagrams that you might have encountered in your life which try to sell the idea of 'one way flow of state' or some similar idea (in different words).

Recognise any? (read the alts, if you can't)

This is typically held in contrast to 'bad', 'older' state management philosophies like "2-way data binding" or "MVC"

The OG guys who promulgated that was Microsoft & Angular

I think the simple theory - "these have more arrows, i.e. must be bad" holds good collective wisdom 😂

A better way to work with state ?

What are the wise, senior, developers who have spent a lot of years wrangling with the basic problem of "users do something on UI, some logic runs, the UI changes to something else" saying though?

And why is the utopia they are showing still not lead to performant UIs?

What they (or 'we', I am part of this group) are saying is

"whatever you see on the UI is a representation of state"

Everything. Buttons being disabled or enabled, to the data the user fills in the input boxes, to what shows up on the Twitter app's feed - it is all state.

Now if we can make this little magic box, which, regardless of whatever weirdass complexities we bring into the 'business logic' of your program, can just chuck a "state" into, and it chucks out the "UI" that should represent that state, we are golden!

Never will the UI chuck something back into the magic box though. And never will the state change because the magic box said so. The magic box has but one function.

Take the 'state' in a machine-readable format (JSON, XML, objects, whatever) and turn it into user interface.

But there is a problem with this approach

See the thing is user interfaces are not like frames of a movie. We do not (and should not) generate the whole damn frame every time something changes

You clicked like on this tweet? Cool just update the ♡ to ❤️, not the whole page!

The utopia of declarative UI lies in aligning "view hierarchy" with "information hierarchy".

This is something that is visualised by nothing better than 2 images from VueJS's official docs.

If you look at the UI (grey, left) do you immediately see the code I have written?

The key to understanding why the 2 hierarchies must align (in the minds of those who are creating this) is because of the aforemention problem - clicking the like button shouldn't 'redraw' my whole screen.

For example, refreshing the articles should do this

Or more precisely, if I clicked like on a particular post, even more specific set of things to update.

Caveats and Dragons Beware

Apart from the 'creators' of this product - which include the designers of the UI to a degree, and not only the engineers of the UI but those 'generating' the objects that constitute state (which could be happening partly on the backend) - aligning on this hierarchy which itself is not the easiest thing to happen (when a group of 20 people are building technically complex things, everyone visualising the exact same hierarchy is not that easy), there also are certain things we need from that 'magical box' we talked about.

The magic box must be smart enough to actually see which parts of the information tree actually changed, and accordingly, on the UI actually change only those parts of the view tree (for eg. highlighted in pink)

Some frameworks put the onus of the 'smartness' on devs, some don't

Putting the onus of the smartness on the devs has it's downsides of coaching the devs about this whole thing (so far I have been talking in this thread) - they need to be made cognizant of the 'cost of drawing' elements, and 'lifting up the state' term starts to appear soon.

Being able to untangle a thread of state from a mess of highly co-dependent variables in the memory, 6 screens deep in the flow of an app with 50 screens, is not exactly easy to wrangle for new developers, especially after parachuting into an already complex project.

Frameworks like Flutter put the onus on the developers, and all online articles which cover "improving performance on Flutter" will always start with the question "are you updating more stateful widgets than you need?"

Some others do some smartness on your behalf, like React+Redux where there are magical "dom diffing" operations under the hood which will diff the new state with old state to figure out which elements need drawing again, or Jetpack Compose where Compose internally does this.

The framework doing the smartness for you has 2 downsides.

1. you still need to architect the information hierarchy properly. if the object tree itself gets updated right from the root (or is undiffable), framework cannot do any magic

2. more magic == less debugability. simple

Thought I will try it out myself as well.

The cover image is generated using AlphaCTR.com

The Prompt

So the idea is simple. I want to make a GUI wrapper for yt-dlp - a tool I frequently use to download videos (or parts thereof) from YouTube.

I asked ChatGPT (GPT4) to build this app for me.

So here was my prompt. (It is fairly detailed).

I want to make a Flutter app that downloads videos using the 'yt-dlp' tool. 

Assume the following 
1. I do not need to setup yt-dlp, it exists on my PC already. 
2. Do not help me with Flutter installation and plugin adding steps. 
3. Only show the code for the lib/main.dart file 

The app's UI will have the following 

1. Title bar: "YouTube Downloader GUI" 
2. Input Box [id: ytUrl, placeholder: "youtube video url"]
3. A row of 3 checkboxes 
  a. "Video" [id: dlVid, default: checked]
  b. "Audio" [id: dlAud, default: unchecked] 
  c. "Thumbnail" [id: dlThumb, default: unchecked]
4. Two input boxes for start and end time 
  a. "Start time" [id: timeStart] 
  b. "End Time" [id: timeEnd] 
5. Two dropdown boxes to select quality of audio and video 
  a. id: qualVid, choices: [480p, 720p, 1080p, 2K, 4K], default: 1080p 
  b.  id: qualAud, choices: [64k, 128k, 192k, 256k, 320k] default: 192k 


The logic for downloading should be this. 

1. If dlAud = true, download audio separately 
2. If dlThumb = true, download thumbnail too 
3. If start and end time are given, download only that portion of the video 
4. If ytUrl is not provided or doesn't contain 'youtube.com' in it show a Dialog "Enter valid YouTube URL"
5. Factor in the qualVid and qualAud when downloading audio and video. 
6. Download videos in mp4 form and audio in mp3 form

Highlighting a few things here

1. I explicitly asked only to generate the lib/main.dart code for me because otherwise ChatGPT by default provides all the info required to setup a Flutter project and install dependencies. Since I am well versed with Flutter at a basic level to do these things myself, I asked it to avoid it for faster output

2. I am building a Flutter app (and not say, React Native Desktop) especially because this is a platform I am slightly familiar with and I can debug the final output

The Initial Output

So here is the code that ChatGPT generated for me

import 'package:flutter/material.dart';
import 'package:process_run/cmd_run.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'YouTube Downloader GUI',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key key}) : super(key: key);

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  String ytUrl;
  bool dlVid = true;
  bool dlAud = false;
  bool dlThumb = false;
  TimeOfDay timeStart;
  TimeOfDay timeEnd;
  String qualVid = '1080p';
  String qualAud = '192k';

  List<String> qualVidOptions = ['480p', '720p', '1080p', '2K', '4K'];
  List<String> qualAudOptions = ['64k', '128k', '192k', '256k', '320k'];

  void download() async {
    if (ytUrl == null || !ytUrl.contains('youtube.com')) {
      showDialog(
        context: context,
        builder: (context) => AlertDialog(
          content: Text('Enter valid YouTube URL'),
        ),
      );
      return;
    }

    String command = 'yt-dlp -f \'bestvideo[height<=${qualVid.replaceAll('p', '')}]'
        '+bestaudio/best[height<=${qualVid.replaceAll('p', '')}]\' $ytUrl';
    if (dlAud) command += ' -x --audio-format mp3 --audio-quality ${qualAud}';
    if (dlThumb) command += ' --write-thumbnail';
    if (timeStart != null && timeEnd != null)
      command +=
          ' --postprocessor-args "-ss ${timeStart.format(context)} -to ${timeEnd.format(context)}"';

    await runCmd(ProcessCmd(command.split(' ')[0], command.split(' ').sublist(1)));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('YouTube Downloader GUI'),
      ),
      body: Padding(
        padding: EdgeInsets.all(16.0),
        child: Column(
          children: <Widget>[
            TextField(
              onChanged: (value) => ytUrl = value,
              decoration: InputDecoration(
                labelText: 'YouTube Video URL',
              ),
            ),
            Row(
              children: <Widget>[
                Checkbox(
                  value: dlVid,
                  onChanged: (bool value) {
                    setState(() {
                      dlVid = value;
                    });
                  },
                ),
                Text('Video'),
                Checkbox(
                  value: dlAud,
                  onChanged: (bool value) {
                    setState(() {
                      dlAud = value;
                    });
                  },
                ),
                Text('Audio'),
                Checkbox(
                  value: dlThumb,
                  onChanged: (bool value) {
                    setState(() {
                      dlThumb = value;
                    });
                  },
                ),
                Text('Thumbnail'),
              ],
            ),
            Row(
              children: [
                Expanded(
                  child: TextField(
                    onTap: () async {
                      TimeOfDay time = await showTimePicker(
                        context: context,
                        initialTime: TimeOfDay.now(),
                      );
                      if (time != null) setState(() => timeStart = time);
                    },
                    readOnly: true,
                    decoration: InputDecoration(
                      labelText: 'Start Time',
                      hintText: timeStart?.format(context) ?? '',
                    ),
                  ),
                ),
                SizedBox(width: 16),
                Expanded(
                  child: TextField(
                    onTap: () async {
                      TimeOfDay time = await showTimePicker(
                        context: context,
                        initialTime: TimeOfDay.now(),
                      );
                      if (time != null) setState(() => timeEnd = time);
                    },
                    readOnly: true,
                    decoration: InputDecoration(
                      labelText: 'End Time',
                      hintText: timeEnd?.format(context) ?? '',
                    ),
                  ),
                ),
              ],
            ),
            DropdownButton(
              value: qualVid,
              items: qualVidOptions
                  .map((value) => DropdownMenuItem(
                        child: Text(value),
                        value: value,
                      ))
                  .toList(),
              onChanged: (String value) {
                setState(() {
                  qualVid = value;
                });
              },
            ),
            DropdownButton(
              value: qualAud,
              items: qualAudOptions
                  .map((value) => DropdownMenuItem(
                        child: Text(value),
                        value: value,
                      ))
                  .toList(),
              onChanged: (String value) {
                setState(() {
                  qualAud = value;
                });
              },
            ),
            ElevatedButton(
              onPressed: download,
              child: Text('Download'),
            ),
          ],
        ),
      ),
    );
  }
}

It does also mention that this might not cover all corner cases and be mindful of YouTube policies

Trying to use it

Let's see what happens when I try to use it. I am not sure if this code will work straight out of the box or not!

So it didn't work out of the box, and the main reason for that is that ChatGPT's knowledge cutoff date is Sept 2021, which means most things in Flutter and Dart that have evolved since then wouldn't have found its way into ChatGPT's codex. One particular thing that affects is that ChatGPT-generated Flutter code doesn't use const constructors. Because it would not have been trained on much code with const

Here is a full diff of the changes I had to do to get it just working.

https://github.com/championswimmer/yt_dlp_ui/commit/8a1fe9ba3a2bb33120779138b66222c804a25859

Some highlights

1. ofcourse, lots of const additions

1. not understanding 2023-era Dart null safety

1. using some older APIs of the process_run library

Getting it to work

Had to make one final change (which ChatGPT already had warned me about) - to disable MacOS sandbox mode, to be able to run shelle commands

Basically go to macos/Runner/DebugProfile.entitlements and

    <key>com.apple.security.app-sandbox</key>
    <false/>

Mostly after these changes, it basically works!

• The start/end time input boxes are timepickers, which we need to fix!

• I stopped the download midway that's why it didn't finish

• Will need to fix how the video/audio quality is translated in the shell command

Conclusion

I think this is pretty good. Obviously the way this will get weaponised won't be us talking to a damn chatbot and asking it to code. There will be better ways this will integrate into the coding workflow.

I will next try to achieve the same using smol-dev-js which is based on smol.ai and I'll probably write up about that when I do.

Till then, this is fairly promising. And I will finally turn the Small App Ideas.md page from by Obsidian into actual apps maybe!

The interesting thing is, it is made using Kotlin Multiplatform, which means it can be compiled to the following formats

• Native Windows .exe executable (via mingw)

• Native MacOS executable

• Native Linux binary

• .jar file for running on JVM

• .js file that can be run using NodeJS

And they way I have set it up on Github, on every tag, it releases all these binaries.

So how does that work, you'll ask? Here's how.

Compilation Steps

1. JavaScript

jobs:
  build_js:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'microsoft'
      - name: Build with Gradle
        uses: gradle/gradle-build-action@v2
        with:
          gradle-version: current
          arguments: compileProductionExecutableKotlinJs
      - name: Tar Artifact
        run: tar -czf ParkingLot-LLD-Kotlin-MPP.nodejs.tgz build/js/packages/ParkingLot-LLD-Kotlin-MPP
      - name: Upload JS Build
        uses: actions/upload-artifact@v2
        with:
          name: js-build
          path: ParkingLot-LLD-Kotlin-MPP.nodejs.tgz

2. JVM

  build_jvm:
    ...
    steps:
      ...
      - name: Build with Gradle
        with:
          arguments: assembleDist # java distribution
      - name: Upload JVM Build
        uses: actions/upload-artifact@v2
        with:
          name: jvm-build
          path: build/distributions/ParkingLot-LLD-Kotlin-MPP-*.zip # this is the path where it is created

3. MacOS

  build_macos:
    runs-on: macos-latest # build this on a Mac
    steps:
      ...
      - name: Build with Gradle
        with:
          arguments: macosX64Binaries # to build mac binary
      - name: Upload MacOS Build
        uses: actions/upload-artifact@v2
        with:
          name: macos-build
          path: build/bin/macosX64/releaseExecutable/ParkingLot-LLD-Kotlin-MPP.kexe

Similarly Windows and Linux are done too. You can check the entire workflow here

I use Github Actions extensively, mainly for my opensource projects as Github gives you unlimited free tier build minutes for OSS repos. And I prefer having a full end-to-end CI setup on my projects so it makes it easier for me to review and merge PRs.

Anyway, one problem I used to face is absence of validation of the workflow.yml files when working on IDEs. Visual Studio code does seem to have some plugins which can validate Github Workflow files, but on Jetbrains IDEs (IntelliJ IDEA, Webstorm, GoLand etc) there isn't something like that.

But SchemaStore does have JSON Schema definitions for Github Actions. Which we can use to validate our workflow files. Here's how-

Add JSON Schema for Github Workflow in IDE Settings

Go here in Preferences

• Preferences

  • Languages & Frameworks

    • JSON Schema Mappings

Add a new JSON Schema Mapping.

Give it a name, like github-workflow

Add this as the path to the JSON Schema https://json.schemastore.org/github-workflow.json (you can click the 🌍 globe icon and search "Github Workflow" in the SchemaStore list too).

Now we need to add a file pattern, to tell the IDE which files to be validated with this JSON Schema. Add this file pattern

.github/workflows/*.yml

And voila.... schema validation shoud start working

You'll also get auto-complete and descriptions of the keys when you edit Github Workflow files now.

Yesterday after a long long time I was coding in darkness and wanted to switch to a dark theme. I don't remember, in the past which themes I have mostly used for Dark Mode, and I was really yearning for a theme that would be similar to Quiet Light in terms of the color palette. While I did find this one extension claiming to implement dark version of Quiet Light, it didn't actually quite live up to the expectation.

As usually happens during such yak shaving sessions, I started off with trying to edit that theme's json file, and finally ended up considering publishing my own theme to the VS Code Marketplace. So here are the steps to make your own theme and publish them.

Create a VS Code Extension Package

VS Code team have made a yeoman generator for creating VS Code extensions. Start from there.

❯ npm install -g yo generator-code
❯ yo code

This is what the structure of the newly created project look like

.
├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── icon.png          # add an icon for marketplace listing
├── package.json
├── quieter-dark-color-theme-0.0.1.vsix
├── screenshot.png    # add a screenshot for marketplace
├── themes
│   └── Quieter Dark-color-theme.json
└── vsc-extension-quickstart.md

Make sure the theme file ends with -color-theme.json and then VS Code will give you code completion help when editing it.

There are two main things inside a theme, colors and tokenColors

• colors define background, foreground colors for elements of the UI of VS Code itself, including sidebars, status bars, editor panes, tooltips etc

• tokenColors define syntax highlighting, like classes, functions, keywords etc.

Once you have created the theme as per your liking, you can move it (or symlink it) into ~/.vscode/extensions/ to have it installed to your local IDE and try it out. Once you are satisfied, you can move on to publishing it.

You'll find more detailed documentation on creating color themes in the official docs
https://code.visualstudio.com/api/extension-guides/color-them

Publishing a Visual Studio Code Color Theme to the Marketplace

Before we go to the further steps, keep vsce (the VS Code Extension manager CLI) installed.

npm install -g @vscode/vsce

Before you can publish, you need to ensure a few steps.

1. Create a Azure Devops organisation if you do not have one. (Go here)

2. Get a Personal Access Token inside that organisation. This PAT must have Marketplace > Manage scope in it.

   

   

3. Save this personal access token somewhere. I prefer having it saved in my ~/.profile file as VSC_MARKET_PAT=xxxxxxxxx so I can use the env variable $VSC_MARKET_PAT wherever I need it.

4. Create a VS Code Marketplace publisher. Note this is important to remember what publisher name you make here as you need to add it to your package.json too. (Go here to make this)

5. Check that the publisher you made is working by doing vsce login <publisher name> in your terminal, and making sure the login works.

Make sure you add a name and a publisher to your package.json before proceeding.

To publish your extension run

vsce publish

You can also specify a version of your extension, when making changes and updating it

vsce publish 0.0.1 
# or 
vsce publish minor # 0.1.0 increment 
# or 
vsce publish major # 1.0.0 increment

You'll get more detailed information including how to disable your extension or deprecate it, and get analytics data of it in the official docs
https://code.visualstudio.com/api/working-with-extensions/publishing-extension

Links and References

• https://github.com/championswimmer/vscode-theme-quieter-dark
  source code of the extension I made

  https://github.com/championswimmer/vscode-theme-quieter-dark

• https://marketplace.visualstudio.com/items?itemName=championswimmer.quieter-dark-color-theme
  published link of the extension

  https://marketplace.visualstudio.com/items?itemName=championswimmer.quieter-dark-color-theme

The most common way people have been coping with that was using buildSrc, but the problem with that is buildSrc changes cause cache invalidations across your build and increases build times.

There obviously now calls to action to move from buildSrc to includeBuild

If you have other custom build logic, and build plugins, it ofcourse makes sense to move to the includeBuild mechanism, but if you needed buildSrc only for version management of dependencies, there is a better way - gradle version catalogs

Elaborate explanations of how it works is available in the previous link, I will quickly cover the basic set of steps

Add versions and libraries to settings.gradle(.kts)

NOTE: All my examples are in kts because buildscripts in kotlin have better DX (autocomplete, linting etc)

This is for example what I added in my settings.gradle.kts (expanding on the lines afterwards)

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }

    versionCatalogs {
        create("libs") {
            version("androidx.navigation", "2.4.1")
            version("android.material", "1.7.0-alpha01")
            version("moshi", "1.13.0")
            version("retrofit", "2.9.0")
            version("moshi", "1.13.0")

            library("android.material", "com.google.android.material", "material").versionRef("android.material")
            library("androidx.navigation.fragment", "androidx.navigation", "navigation-fragment-ktx").versionRef("androidx.navigation")
            library("androidx.navigation.ui", "androidx.navigation", "navigation-ui-ktx").versionRef("androidx.navigation")
            library("androidx.core", "androidx.core:core-ktx:1.7.0")
            library("androidx.appcompat", "androidx.appcompat:appcompat:1.4.1")
            library("okhttp", "com.squareup.okhttp3:okhttp:5.0.0-alpha.6")
            library("retrofit", "com.squareup.retrofit2", "retrofit").versionRef("retrofit")
            library("retrofit.converter.moshi", "com.squareup.retrofit2", "converter-moshi").versionRef("retrofit")
            library("moshi", "com.squareup.moshi", "moshi-kotlin").versionRef("moshi")
            library("moshi.compiler", "com.squareup.moshi", "moshi-kotlin-codegen").versionRef("moshi")

            bundle("androidx.appcompat", listOf("androidx.core", "androidx.appcompat"))
            bundle("androidx.navigation", listOf("androidx.navigation.fragment", "androidx.navigation.ui"))
            bundle("retrofit", listOf("retrofit", "retrofit.converter.moshi"))
        }
    }
}

1. Creating 'libs' block

dependencyResolutionManagement {
  versionCatalogs {
    create("libs") {...}
  }
}

2. Add version constants

version("android.material", "1.7.0-alpha01")
version("moshi", "1.13.0")
version("retrofit", "2.9.0")

3. Add each dependency

You can refer versions constants via versionRef()

library("android.material", "com.google.android.material", "material").versionRef("android.material")

4. Create 'bundles' if there are a set of libraries that get used together

bundle("androidx.appcompat", listOf("androidx.core", "androidx.appcompat"))

Using version catalog libraries in build.gradle(.kts) files

The way to use these in your module(s)' build.gradle is as follows

dependencies {

    implementation(libs.bundles.androidx.appcompat)
    implementation(libs.android.material)
    implementation("androidx.constraintlayout:constraintlayout:2.1.3")
    implementation(libs.bundles.androidx.navigation)
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.3")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
}

Normal libraries are used like this

    implementation(libs.android.material)

While an entire bundle can be added like this

    implementation(libs.android.material)

What does not work ?

There are a few caveats (as of April 2022, most I expect to improve)

Gradle 7.4+

If you are using Gradle 7.3 or below, then version catalogs are unstable/experimental API and you need to mark that as so. From 7.4 they are default enabled

Android Studio Support of Version Management

Dependencies inside version catalogs do not show up in Project Structure options of Android Studio nor does studio remind you to update the dependencies that are out-of-date.

As you can see below there is a warning regarding version catalogs, and the version catalog dependencies do not show up

Autocomplete works with Kotlin only

If you use build.gradle (groovy) instead of build.gradle.kts (kotlinscript), then the libs.x.y dependencies will not have autocomplete or type-checking

Below is autocomplete working only inside .kts files.