DEV Community: Naveen Gopalakrishna

Claude Desktop on Microsoft Foundry: Third-Party Inference Mode, Entra ID Sign-In, and What Claude Design Cannot Do

Naveen Gopalakrishna — Thu, 13 Aug 2026 14:04:57 +0000

After getting Claude Code onto Foundry
and then governing it with an APIM gateway,
the obvious next question is the GUI: can Claude Desktop use my own Foundry deployment too?

Short answer: yes, through a documented third-party inference mode — and it can point at the
same governed gateway. But it is an admin-deployed configuration, not something a developer
switches on, and one popular Claude feature is explicitly excluded.

Verified on 13 Aug 2026 against Claude Desktop 1.25927.0 on Windows.

What "out of the box" actually gives you

Install it and the first run is unambiguous:

winget install --id Anthropic.Claude

Sign-in offers Google or email — an Anthropic account. There is no "use my own endpoint" box,
and no Azure sign-in:

That is the default, and it is why people assume Desktop cannot do BYO-model. The capability
exists — it is just not reachable from the UI on a stock install.

Step 1 — Confirm your build supports third-party mode

Third-party inference landed in Desktop 1.2581.0. Before configuring anything, check the
shipping app actually carries the subsystem:

$asar = "$env:LOCALAPPDATA\AnthropicClaude\app-<version>\resources\app.asar"
$text = [System.Text.Encoding]::UTF8.GetString([IO.File]::ReadAllBytes($asar))
foreach ($k in @('inferenceProvider','inferenceFoundryResource','inferenceGatewayOidc')) {
    "{0,-28} {1}" -f $k, ([regex]::Matches($text, [regex]::Escape($k))).Count
}

On 1.25927.0 this returns matches for all of them. The provider enum is:

gateway | anthropic | bedrock | mantle | vertex | foundry

and the credential kinds are:

static | helper-script | interactive | vendor-profile | oauth | workforce

inferenceProvider is the master switch — the app's own description is "Selects the inference
backend. Setting this key activates third-party mode."

Step 2 — Register an Entra app for Desktop

Desktop signs the user in directly against Entra ID, so it needs its own app registration with
delegated access to the Cognitive Services data plane.

$app = az ad app create --display-name "Claude Desktop (Foundry)" `
    --is-fallback-public-client true `
    --public-client-redirect-uris "http://localhost" "ms-appx-web://microsoft.aad.brokerplugin/<client-id>" `
    | ConvertFrom-Json

# delegated user_impersonation on Azure Cognitive Services
az ad app permission add --id $app.appId `
    --api https://cognitiveservices.azure.com `
    --api-permissions <user_impersonation-scope-id>=Scope

az ad app permission admin-consent --id $app.appId

Note the redirect URI shape: ms-appx-web://microsoft.aad.brokerplugin/<client-id> is what the
broker flow needs on Windows. Use broker if you have Conditional Access policies that require
a compliant or managed device — it routes through Web Account Manager rather than a browser, so
the device claim is satisfied.

The admin-consent step needs a Privileged Role Administrator. If you are not one, this is where
you stop and open a ticket — it was where I stopped in my own tenant.

Step 3 — Push the configuration

This is the part that surprises people: 3P settings do not live in
claude_desktop_config.json. That file is for MCP servers and cosmetics. Inference
configuration is managed configuration, deployed the way an enterprise deploys policy.

Platform	Managed location
Windows	`HKLM\SOFTWARE\Policies\Claude` (machine) or `HKCU\SOFTWARE\Policies\Claude` (user), values as `REG_SZ`
macOS	`.mobileconfig` via MDM, domain `com.anthropic.claudefordesktop`
Linux	`/etc/claude-desktop/managed-settings.json`

The app keeps its own state separately under %LOCALAPPDATA%\Claude-3p\configLibrary\ — the
-3p suffix is literal, and its presence is a quick way to tell whether a machine has ever run
in third-party mode.

Pointing straight at Foundry

$k = "HKLM:\SOFTWARE\Policies\Claude"
New-Item -Path $k -Force | Out-Null

New-ItemProperty -Path $k -Name inferenceProvider        -Value "foundry"                    -PropertyType String -Force
New-ItemProperty -Path $k -Name inferenceFoundryResource -Value "<your-foundry-resource>"     -PropertyType String -Force
New-ItemProperty -Path $k -Name inferenceFoundryTenantId -Value "<tenant-id>"                 -PropertyType String -Force
New-ItemProperty -Path $k -Name inferenceFoundryClientId -Value "<app-registration-client-id>" -PropertyType String -Force
New-ItemProperty -Path $k -Name inferenceFoundryAuthFlow -Value "broker"                      -PropertyType String -Force
New-ItemProperty -Path $k -Name inferenceModels `
    -Value '[{"name":"claude-sonnet-5"},{"name":"claude-opus-5"}]' -PropertyType String -Force

inferenceFoundryResource is the bare resource name — the app builds
<resource>.services.ai.azure.com from it, exactly like Claude Code's
ANTHROPIC_FOUNDRY_RESOURCE.

inferenceFoundryAuthFlow accepts device-code (default), browser or broker.

Or point at your governed gateway

If you already run the APIM governance gateway,
Desktop can go through it and inherit the same per-developer budgets, tiering and chargeback:

inferenceProvider          = gateway
inferenceGatewayBaseUrl    = https://<your-apim>.azure-api.net/claude
inferenceCredentialKind    = oauth
inferenceGatewayOidcAuthFlow = broker
inferenceGatewayOidc       = {"clientId":"<app-id>",
                              "issuer":"https://login.microsoftonline.com/<tenant>/v2.0",
                              "bearerTokenType":"access_token",
                              "scopes":"https://cognitiveservices.azure.com/.default"}

inferenceGatewayAuthScheme defaults to bearer, which is what the gateway's
validate-azure-ad-token policy expects. This is the option I would pick for a team: one
enforcement point for both Claude Code and Claude Desktop.

If you cannot use registry policy

inferenceCredentialHelper points at an executable that prints a bearer token to stdout — the
same pattern as the token helper in the Claude Code setup:

New-ItemProperty -Path $k -Name inferenceCredentialHelper `
    -Value "C:\ProgramData\claude\get-foundry-token.cmd" -PropertyType String -Force

The app sets CLAUDE_HELPER_CONTEXT so the helper can tell an interactive start from a
mid-session refresh. That makes Key Vault, Windows Hello or az account get-access-token all
viable sources.

Step 4 — Verify

Once policy is applied and the app restarts, its diagnostics report:

Effective mode:          3P
inferenceProvider set:   yes
Provider:                foundry

If it still says 1P, the policy was not read. On a corporate-managed device that is the most
likely failure — see below.

The thing that will stop you on a managed laptop

On my own machine, both policy hives were locked by device management:

HKLM\SOFTWARE\Policies\Claude : Requested registry access is not allowed.
HKCU\SOFTWARE\Policies\Claude : Access to the registry key is denied.

That is not a bug — it is the point. SOFTWARE\Policies is reserved for administratively
deployed policy, and a managed device refuses hand-editing of it. Third-party mode is designed
to be pushed by Intune or Group Policy, not enabled by a developer.

Practically: package the keys as an Intune configuration profile (or a .mobileconfig on macOS)
and target the same Entra group you use to entitle Claude Code. Entitlement and configuration
then travel together.

Claude Design: the honest answer

Claude Design — Anthropic's visual design surface, launched April 2026 — cannot be pointed
at Foundry. It is explicitly excluded from third-party mode: Chat, Cowork and Code are supported
in 3P, and features that depend on Anthropic-hosted inference are not.

That is a product boundary, not a configuration gap. Its design-system ingestion, rendering
pipeline and Figma/Adobe integrations are Anthropic-side services, so there is nothing to
re-point. If you need design generation on your own deployment, you call the Claude models in
Foundry programmatically and build the surface yourself.

Worth knowing before someone promises it in a rollout plan.

What runs where, once you are done

Surface	Runs on your Foundry deployment?	Notes
Claude Code CLI	✅	`CLAUDE_CODE_USE_FOUNDRY=1`
Claude Code VS Code extension	✅	same settings file
Claude Desktop — Chat	✅	3P mode, admin-deployed
Claude Desktop — Cowork / Code	✅	3P mode
Claude Desktop — Design	❌	Anthropic-hosted only
claude.ai web	❌	Anthropic-hosted

The pattern underneath all three posts

Anthropic has converged on one idea across the product line: the model backend is a deployment
decision, not a product decision. Claude Code exposes it as environment variables, Desktop
exposes it as managed configuration, and both accept a gateway in the middle.

For a platform team that means you can put a single governed endpoint in front of everything, and
choose per surface whether it points at Foundry directly or through your gateway. The developer
experience does not change either way — which is exactly what you want from governance.

💻 Governance accelerator: https://github.com/naveenneog/claude-code-foundry-gateway
📘 Claude Code on Foundry: step-by-step
📗 Governing it with APIM: per-developer budgets and chargeback

Governing Claude Code with Azure API Management: Per-Developer Budgets, Tiering and Chargeback on Microsoft Foundry

Naveen Gopalakrishna — Thu, 13 Aug 2026 13:20:35 +0000

Running Claude Code on Foundry
solves the credential problem for one developer: az login and you're in, no API key anywhere.

Scaling that to a team surfaces a different problem. Going direct to Foundry means every
developer needs Cognitive Services User on the resource, and that gives you no rate limit, no
budget, no tiering, and usage data only at the resource level — you can see that $4,000 of tokens
were spent, but not by whom.

This post puts an Azure API Management AI gateway in front. Developers end up holding no
Foundry role at all.

Everything below was built and executed on 13 Aug 2026: APIM Basic v2, Claude Code
v2.1.223, claude-sonnet-5 and claude-opus-5 in East US 2.

Skip the manual steps: the whole thing is packaged as a one-command accelerator —
github.com/naveenneog/claude-code-foundry-gateway.
Steps 1–7 below are what it automates, and worth reading before you run it.

What you get

Control	Mechanism	Result
Who may use Claude Code	Entra ID group membership	403 with an actionable message
Tiered budgets	`llm-token-limit` per tier	standard vs premium
Per-developer rate limit	tokens/minute keyed on `oid`	429 + `Retry-After`
Per-developer daily budget	`token-quota` + period	403 until reset
Runaway-agent protection	`rate-limit-by-key`	request ceiling
Chargeback	`llm-emit-token-metric`	tokens per named person
No credential sprawl	gateway managed identity	nothing to leak or rotate

Why per-developer metering actually works here

This is the load-bearing detail, and I established it by intercepting real traffic rather than
assuming.

Claude Code's Foundry mode does not invent a credential. It calls the Azure SDK's
DefaultAzureCredential, so the request carries the developer's own Entra ID token:

{
  "aud": "https://cognitiveservices.azure.com",
  "oid": "43cc5304-...",
  "upn": "naveen.g@contoso.com",
  "appid": "04b07795-8ddb-461a-bbee-02f9e1bf7b46"
}

Three consequences:

Identity is unforgeable. oid is signed by Entra. A developer cannot spoof a colleague, and a shared credential cannot exist because there is no credential to share.
No client-side auth work. No app registration, no custom audience, no device-code flow.
Offboarding is free. Remove the person from the group and access stops. Nothing is revoked at the endpoint.

Claude Code also sends an x-claude-code-session-id header, which makes a useful metric
dimension.

Step 1 — Deploy the gateway

The SKU decision matters more than anything else in this post. APIM's llm-* policies parse
the Anthropic Messages API shape only on v2 tiers. On classic Developer/Basic/Standard/
Premium the policies apply happily and count zero tokens forever — budgets never trip and you
believe you are governed when you are not.

az apim create has no v2 support, so deploy with ARM/Bicep:

az deployment group create -g rg-claude-gateway `
    --template-file infra/main.bicep `
    --parameters foundryAccountName=<foundry> publisherEmail=<you@contoso.com>

Basic v2 provisions in about four minutes; classic tiers take 30–45.

The template enables a system-assigned managed identity — the identity that will reach
Foundry.

Step 2 — Let the gateway in, and nobody else

$apimMi = az apim show -n <apim> -g <rg> --query identity.principalId -o tsv
$scope  = az cognitiveservices account show -n <foundry> -g <rg> --query id -o tsv

az role assignment create `
    --assignee-object-id $apimMi --assignee-principal-type ServicePrincipal `
    --role "Cognitive Services User" --scope $scope

Then the step that actually closes the bypass:

az role assignment delete --assignee <developer-oid> `
    --role "Cognitive Services User" --scope $scope

Until developers lose that role they can point Claude Code straight at Foundry and skip every
control below. Leave it assigned only to the gateway.

Step 3 — Entitlement lives in Entra ID

az ad group create --display-name claude-code-standard --mail-nickname claude-code-standard
az ad group create --display-name claude-code-premium  --mail-nickname claude-code-premium

Entitlement belongs in Entra because that is where joiner/mover/leaver already runs. Adding
someone to claude-code-premium is an action your identity team can take, audit and review —
whereas an allowlist in a config file drifts and is nobody's job.

Step 4 — Import Foundry as an API

az apim api create -g <rg> --service-name <apim> `
    --api-id claude-foundry --path claude `
    --service-url "https://<foundry>.services.ai.azure.com/anthropic" `
    --protocols https --subscription-required false

az apim api operation create -g <rg> --service-name <apim> `
    --api-id claude-foundry --operation-id messages `
    --display-name "Create Message" --method POST --url-template "/v1/messages"

--subscription-required false is deliberate: authorization comes from the Entra token, not an
APIM subscription key. Claude Code has no reliable way to send a custom key header, and a shared
key would destroy per-person attribution anyway.

Step 5 — The policy

Limits live in named values so changing a budget is a config edit, not a redeployment:

tpm-standard=20000   quota-standard=500000
tpm-premium=80000    quota-premium=5000000
calls-per-minute=120

The policy itself, in order:

<validate-azure-ad-token tenant-id="{{tenant-id}}" output-token-variable-name="jwt"
                         failed-validation-httpcode="401">
    <audiences>
        <audience>https://cognitiveservices.azure.com</audience>
    </audiences>
</validate-azure-ad-token>

<set-variable name="userId" value="@(((Jwt)context.Variables["jwt"]).Claims.GetValueOrDefault("oid",""))" />

<set-variable name="tier" value="@{
    var oid = "," + (string)context.Variables["userId"] + ",";
    if (("{{allow-premium}}").Contains(oid))  { return "premium"; }
    if (("{{allow-standard}}").Contains(oid)) { return "standard"; }
    return "denied";
}" />

<llm-token-limit counter-key="@((string)context.Variables["userId"])"
                 tokens-per-minute="{{tpm-standard}}" estimate-prompt-tokens="false"
                 retry-after-header-name="Retry-After"
                 remaining-tokens-header-name="x-ratelimit-remaining-tokens"
                 tokens-consumed-header-name="x-tokens-consumed" />

<llm-emit-token-metric namespace="claudecode">
    <dimension name="User" value="@((string)context.Variables["userUpn"])" />
    <dimension name="Tier" value="@((string)context.Variables["tier"])" />
</llm-emit-token-metric>

<authentication-managed-identity resource="https://cognitiveservices.azure.com"
                                 output-token-variable-name="msi-token" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["msi-token"])</value>
</set-header>

Four things worth knowing:

The audience is https://cognitiveservices.azure.com — that is what Claude Code requests a token for, so that is what the gateway must accept. No app registration required.
estimate-prompt-tokens="false" bills actual usage from the response.
XML comments cannot contain --. APIM rejects the policy with an error that never mentions comments.
The developer's token is discarded, not forwarded. Foundry sees only the gateway identity.

Sentinel commas around each object id in the allowlists make contains() exact, so one id cannot
partially match another.

Step 6 — Sync group membership

The gateway cannot read group membership from the caller's token: the Cognitive Services audience
is a first-party Microsoft resource whose token has no configurable groups claim. Two options:

	How	Trade-off
Sync (default)	a script writes object ids into named values	no tenant admin needed; membership lags by one sync
Live Graph lookup	policy calls Graph per request, cached	no lag; needs admin consent for `GroupMember.Read.All`

I hit Authorization_RequestDenied on the Graph grant — it needs a Privileged Role Administrator
— so the accelerator ships the sync approach and documents the Graph upgrade.

./scripts/Sync-ClaudeAccess.ps1 -ApimName <apim> -ResourceGroup <rg>

Service principals in a group are invisible to a delegated token without Application.Read.All,
so CI identities are passed explicitly with -AdditionalPremiumOids.

Step 7 — Chargeback telemetry

Two settings, both of which fail silently if you miss them:

the APIM diagnostic needs metrics: true, or llm-emit-token-metric emits nothing and the metric namespace never appears
Application Insights needs CustomMetricsOptedInType: WithDimensions, or the metric arrives as a bare total with no User breakdown — exactly the part chargeback needs

Then:

naveen.g@contoso.com      831 tokens
service-principal         728 tokens

The Azure CLI's az monitor metrics list drops --namespace for custom namespaces and reports
"metric not found". Query the REST API instead.

Step 8 — Point Claude Code at the gateway

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://<apim>.azure-api.net/claude",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-5"
  },
  "availableModels": ["claude-sonnet-5", "claude-opus-5"],
  "enforceAvailableModels": true
}

ANTHROPIC_FOUNDRY_BASE_URL and ANTHROPIC_FOUNDRY_RESOURCE are mutually exclusive.
Setting both fails with baseURL and resource are mutually exclusive. Drop the resource
variable when you move to the gateway.

That one file covers the CLI and the VS Code extension. The panel opens straight into a usable
prompt — no sign-in step, because the Entra credential is already resolved — and streaming works
through the gateway unchanged:

To stop developers editing their own settings, push the same JSON as managed settings:
HKLM\SOFTWARE\Policies\ClaudeCode via Intune or Group Policy on Windows,
/Library/Application Support/ClaudeCode/managed-settings.json on macOS,
/etc/claude-code/managed-settings.json on Linux. Those also let you force availableModels and
block bypassPermissions.

Onboarding a developer, end to end

az ad group member add --group claude-code-standard `
    --member-id (az ad user show --id alice@contoso.com --query id -o tsv)

./scripts/Sync-ClaudeAccess.ps1 -ApimName <apim> -ResourceGroup <rg>

Alice then runs az login, drops in the settings file, and works. No key, no Foundry role, and
she appears in chargeback from her first request.

Guests: a B2B guest (a #EXT# UPN) must use az login --tenant <tenant-id>. A plain
az login lands them in their home tenant and the gateway returns 401. This caught me out
onboarding a colleague.

The accelerator

All of the above is packaged as a solution accelerator:

github.com/naveenneog/claude-code-foundry-gateway

git clone https://github.com/naveenneog/claude-code-foundry-gateway
cd claude-code-foundry-gateway
az login
./deploy.ps1

With no arguments it discovers a Foundry account that has Claude deployments, maps the
sonnet/opus/haiku aliases to deployments that actually exist, deploys APIM + Log Analytics +
Application Insights, creates the API and policy, grants the gateway identity its role, creates
the Entra groups, syncs membership, and writes the settings.json you hand to developers.

./deploy.ps1 -WhatIf previews without changing anything. There is a Deploy to Azure button
for the portal path, Show-Governance.ps1 to verify all four controls, and an inspector proxy
that shows exactly what Claude Code sends — that is how the identity model above was established
rather than assumed.

What it costs

Item	Approx
APIM Basic v2, 1 unit	~$250/month
Log Analytics + App Insights	ingestion-based, small at this volume
Claude tokens	Foundry CCU billing, unchanged by the gateway

Basic v2 is the cheapest tier that can enforce Anthropic token budgets at all. If that is too
much for a pilot, run direct-to-Foundry first and add the gateway when a second team joins.

The honest summary

The gateway buys you four things that direct access cannot: entitlement, budgets,
throttling and attribution. It costs you an APIM instance and one more hop.

For a single developer that trade is not worth it. For a team — especially one where "who spent
the $4,000?" is a question someone will eventually ask — it is the difference between a tool you
can roll out and a tool you have to keep explaining.

The part I did not expect: none of it required changing how developers work. They still run
az login and claude. The governance is entirely on the platform side.

💻 Accelerator: https://github.com/naveenneog/claude-code-foundry-gateway
📘 Getting Claude Code on Foundry first: step-by-step setup
📗 Microsoft Learn — APIM llm-token-limit: https://learn.microsoft.com/en-us/azure/api-management/llm-token-limit-policy
📗 Microsoft Learn — llm-emit-token-metric: https://learn.microsoft.com/en-us/azure/api-management/llm-emit-token-metric-policy

Run Claude Code on Microsoft Foundry: Step-by-Step Setup for VS Code and the CLI

Naveen Gopalakrishna — Thu, 13 Aug 2026 09:19:02 +0000

Claude Code can run against Claude models deployed in your own Microsoft Foundry resource,
authenticated with Microsoft Entra ID — az login on a workstation, managed identity on
Azure compute. No Anthropic account, no API key on disk, no proxy.

This is the procedure. Steps 1–3 are shared setup, Step 4 is the VS Code extension, Step 5
is the CLI, Step 6 verifies. Steps 4 and 5 are independent — do either or both.

Verified on 13 Aug 2026, Claude Code v2.1.223, against claude-sonnet-5 and
claude-opus-5 in East US 2.

Step 0 — Find your values (start here)

The whole setup needs five values. Here is what each one looks like, where it lives, and the
command that prints it. Examples below are real values from my own subscription with a few
characters masked.

Value	Example	Used for
Subscription ID	`e839ff0f-532b-4828-**-**19d85`	`az account set`
Resource group	`rg-cont****hub`	every `az ... -g` flag
Foundry resource name	`ai-contosohub****751908`	`ANTHROPIC_FOUNDRY_RESOURCE`
Region	`eastus2`	checking model availability
Deployment names	`claude-sonnet-5`, `claude-opus-5`	the three model aliases

Where they live in the Azure portal

Open portal.azure.com → search your Foundry resource by name →
Overview. Everything except the deployment names is on this one blade:

Read off:

Resource name — the page title. API Kind must say AIServices.
Resource group and Subscription / Subscription ID — in Essentials.
Location — the region, for Step 1.
Keys and Endpoint (left nav, under Resource Management) — the endpoint URLs.
Access control (IAM) (left nav) — where you add the role in Step 2.

Deployment names are not in the Azure portal. Click Go to Foundry portal at the top of
that blade, then View deployments on the project home — or just use the CLI below, which is
faster.

Or get everything from the CLI

az login

# subscription + tenant
az account show --query "{subscription:id, tenant:tenantId, user:user.name}" -o table

# every Foundry resource you can see, with its resource group and region
az cognitiveservices account list `
    --query "[?kind=='AIServices'].{name:name, rg:resourceGroup, region:location}" -o table

# the deployment names on one of them
az cognitiveservices account deployment list -n <resource> -g <rg> -o table

Or run Get-FoundryValues.ps1,
which finds every value, checks the RBAC role, and prints the exact config block to paste into
Steps 4 and 5. With no arguments it scans your subscription and picks a resource that actually
has Claude deployments. Add -Mask when screenshotting or pasting into a ticket:

.\Get-FoundryValues.ps1 -Mask

The last block is the config you need — copy it straight into Step 4.2 or 5.2.

Prerequisites

Requirement	Check
Foundry resource, kind `AIServices`	`az cognitiveservices account show -n <res> -g <rg> --query kind -o tsv`
Claude models deployed	Step 1
`Cognitive Services User` on the resource	Step 2
Azure CLI	`az --version`
Node.js 18+	`node --version`
VS Code 1.94+	`code --version`

If you don't yet know your resource name, resource group or deployment names, do Step 0 first.

Step 1 — Confirm your Claude deployments

az cognitiveservices account deployment list -n <resource> -g <rg> -o table

Note the deployment names in the output. These are the names you configure later — they are
yours, not Anthropic's catalogue names.

To create a deployment:

az cognitiveservices account deployment create `
    -n <resource> -g <rg> `
    --deployment-name claude-haiku-4-5 `
    --model-name claude-haiku-4-5 --model-version 2 --model-format Anthropic `
    --sku-name GlobalStandard --sku-capacity 1

To list what your region offers:

az cognitiveservices model list -l <region> -o json |
    ConvertFrom-Json |
    Where-Object { $_.model.format -eq 'Anthropic' } |
    ForEach-Object { $_.model.name } | Sort-Object -Unique

If deployment creation fails with a Marketplace error — Claude models bill through Azure
Marketplace. Internal, sandbox, CSP, student and sponsored-credit subscriptions are blocked
from creating them:
ERROR: Marketplace purchases are disabled for this subscription due to policy restrictions.
Existing deployments keep working. Map the missing alias to a deployment you do have (Step 4.2).

Step 2 — Grant data-plane access

Owner on the subscription is not sufficient — that is control plane. Inference needs the
data-plane role Cognitive Services User (a97b65f3-24c7-4388-baec-2e87135dc908).

$scope = az cognitiveservices account show -n <resource> -g <rg> --query id -o tsv

az role assignment create `
    --assignee "<upn-or-object-id>" `
    --role "Cognitive Services User" `
    --scope $scope

Verify:

az role assignment list --assignee "<you>" --scope $scope --include-inherited -o table

Step 3 — Sign in with Entra ID

Workstation:

az login
az account set --subscription <subscription-id>

Azure compute (VM, Container App, DevBox) — managed identity:

az login --identity                          # system-assigned
az login --identity --username <client-id>   # user-assigned

Assign the same role from Step 2 to the identity:

az role assignment create `
    --assignee-object-id <managed-identity-principal-id> `
    --assignee-principal-type ServicePrincipal `
    --role "Cognitive Services User" `
    --scope $scope

Confirm a token is obtainable:

az account get-access-token --resource https://cognitiveservices.azure.com --query expiresOn -o tsv

Both https://cognitiveservices.azure.com and https://ai.azure.com are accepted scopes.

Optional — prove the endpoint answers before involving Claude Code at all:

$t = az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv

Invoke-RestMethod -Method Post `
    -Uri "https://<resource>.services.ai.azure.com/anthropic/v1/messages" `
    -Headers @{ Authorization = "Bearer $t"; 'anthropic-version' = '2023-06-01' } `
    -ContentType 'application/json' `
    -Body '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"Reply with exactly: FOUNDRY-OK"}]}'

Step 4 — VS Code extension setup

4.1 Install the extension

code --install-extension anthropic.claude-code

Or: Ctrl+Shift+X → search Claude Code → Install (publisher: Anthropic).

The extension bundles its own engine. The npm CLI in Step 5 is not required for the panel to work.

4.2 Configure

Open Ctrl+Shift+P → Preferences: Open User Settings (JSON) and add:

{
  "claudeCode.environmentVariables": [
    { "name": "CLAUDE_CODE_USE_FOUNDRY",        "value": "1" },
    { "name": "ANTHROPIC_FOUNDRY_RESOURCE",     "value": "<your-resource-name>" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",   "value": "claude-opus-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",  "value": "claude-haiku-4-5" }
  ]
}

Rules:

ANTHROPIC_FOUNDRY_RESOURCE is the resource name, not a URL. Claude Code expands it to https://<resource>.services.ai.azure.com/anthropic.
Pin all three model aliases to deployment names that exist. Foundry mode does no start-up model check, so a wrong alias fails mid-task as DeploymentNotFound, not at launch. If claude-haiku-4-5 is not deployed, set the haiku alias to your Sonnet deployment.
Set no key. Leaving ANTHROPIC_FOUNDRY_API_KEY and ANTHROPIC_FOUNDRY_AUTH_TOKEN unset is what makes Claude Code fall through to DefaultAzureCredential.

If you also complete Step 5, ~/.claude/settings.json alone is sufficient for the extension and
this block is redundant — I tested that by deleting it and re-running. Either location works.

4.3 Reload and open the panel

Ctrl+Shift+P → Developer: Reload Window
Ctrl+Shift+P → Claude Code: Open in Side Bar

The panel opens straight into a usable prompt. There is no sign-in step — that absence is the
first signal Entra ID resolved.

4.4 Confirm it answers

Type any question about the open folder and send it. The panel calls its normal file tools and
answers from your Foundry deployment.

/status does not work in the panel — it returns "/status isn't available in this
environment." Use Step 5.3 to inspect the provider.

Step 5 — Claude Code CLI setup

5.1 Install

npm install -g @anthropic-ai/claude-code
claude --version

5.2 Configure

Create or edit %USERPROFILE%\.claude\settings.json (~/.claude/settings.json on macOS/Linux):

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "<your-resource-name>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Same three rules as 4.2. For a one-off session, use environment variables instead:

$env:CLAUDE_CODE_USE_FOUNDRY    = "1"
$env:ANTHROPIC_FOUNDRY_RESOURCE = "<your-resource-name>"
claude

5.3 Verify the provider

claude auth status

{ "loggedIn": true, "authMethod": "third_party", "apiProvider": "foundry" }

claude doctor

CLAUDE_CODE_USE_FOUNDRY is set, so this session is using Microsoft Foundry
- Not connected to the Anthropic API (api.anthropic.com)
- Not signed in to claude.ai

Then start an interactive session and run /status — it reports API provider: Microsoft
Foundry and the resource name (the screenshot at the top of this post).

claude

5.4 One headless check

claude -p "Reply with exactly: FOUNDRY-OK" --output-format json

Look for "provider":"foundry" and "canonicalModel":"claude-sonnet-5" in modelUsage.

Step 6 — Verify end to end

Run the seven-point check (Test-ClaudeFoundry.ps1):

.\Test-ClaudeFoundry.ps1 -Resource <resource> -ResourceGroup <rg>

#	Check
1	Azure CLI signed in
2	Entra ID data-plane token acquired
3	Claude deployments exist on the resource
4	`/anthropic/v1/messages` responds over Entra ID auth
5	Claude Code CLI installed
6	`claude auth status` reports `foundry`
7	A real Claude Code turn completes on Foundry

It exits non-zero on failure, so it drops into CI unchanged.

Confirm from the Azure side that traffic reached the resource:

$rid = az cognitiveservices account show -n <resource> -g <rg> --query id -o tsv
az monitor metrics list --resource $rid --metric TokenTransaction `
    --start-time (Get-Date).ToUniversalTime().AddHours(-1).ToString('yyyy-MM-ddTHH:mm:ssZ') `
    --interval PT5M --aggregation Total -o table

Reference

Endpoint

POST https://<resource>.services.ai.azure.com/anthropic/v1/messages
     Authorization: Bearer <entra-id-token>
     anthropic-version: 2023-06-01
     Content-Type: application/json

Foundry exposes Claude through the native Anthropic Messages API, which is why no proxy is
needed. Verified on a live resource:

Path	Result
`/anthropic/v1/messages`	200
`/anthropic/v1/messages/count_tokens`	200
`/openai/v1/chat/completions`	404 `api_not_supported`
`/models/chat/completions`	404 `api_not_supported`
`/openai/deployments/<name>/chat/completions`	404 `api_not_supported`
`/anthropic/v1/models`	404 `api_not_supported`

Streaming (SSE), tool use and count_tokens all work. ?api-version= is optional.

Environment variables

Variable	Purpose
`CLAUDE_CODE_USE_FOUNDRY`	`1` enables Foundry mode
`ANTHROPIC_FOUNDRY_RESOURCE`	Resource name; expands to the `services.ai.azure.com/anthropic` base URL
`ANTHROPIC_FOUNDRY_BASE_URL`	Full base URL override (gateways)
`ANTHROPIC_FOUNDRY_API_KEY`	Key auth instead of Entra ID
`ANTHROPIC_FOUNDRY_AUTH_TOKEN`	Pre-fetched bearer token; highest precedence
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Deployment behind the `sonnet` alias
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Deployment behind the `opus` alias
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Deployment behind `haiku` and background tasks

Auth precedence: ANTHROPIC_FOUNDRY_AUTH_TOKEN → ANTHROPIC_FOUNDRY_API_KEY →
DefaultAzureCredential.

CLAUDE_CODE_USE_AZURE does not exist. Scanning the v2.1.223 binary shows all five
*_FOUNDRY_* variables present and no CLAUDE_CODE_USE_AZURE.

Troubleshooting

Symptom	Cause → Fix
`DeploymentNotFound` mid-task	A model alias points at a deployment you do not have. Re-pin it (4.2 / 5.2).
HTTP 401 `invalid subscription key`	No usable `Authorization` header. Check Step 2 role and Step 3 sign-in. `Authorization: Bearer` wins when both it and `x-api-key` are sent.
HTTP 404 `api_not_supported`	OpenAI-shaped path. Claude deployments expose only `/anthropic/*`.
Extension prompts for Anthropic sign-in	Foundry variables not visible to it. Set them in `claudeCode.environmentVariables` or `~/.claude/settings.json`, then Developer: Reload Window. Shell exports do not reach the extension.
`/status` unavailable	Panel-only limitation. Use `claude auth status`, or `/status` in a terminal session.
Marketplace error on deployment create	Subscription is blocked from Marketplace purchases. Reuse existing deployments or use a pay-as-you-go subscription.
Windows: helper returns a WSL error as the "token"	In Git Bash a bare `az` resolves to the WSL shim. Use `az.cmd`. Note `command -v az.cmd` also fails (bash ignores `PATHEXT`), so run the candidate and validate the result starts with `eyJ`.

Scripts

Get-FoundryValues.ps1 — finds every value in Step 0 and prints the config block (-Mask to share safely)
Setup-ClaudeFoundry.ps1 — writes both config files, backs up what is already there
Test-ClaudeFoundry.ps1 — the seven checks in Step 6
get-foundry-token.sh — optional token helper for CI (Azure CLI, then IMDS)

Docs: Anthropic — Claude Code on Microsoft Foundry ·
Microsoft Learn — Deploy and use Claude models in Foundry

SpeechBridge: Near-Realtime Speech Translation on Azure — Keyless, One-Command, and Honest About Its Latency

Naveen Gopalakrishna — Mon, 10 Aug 2026 14:21:33 +0000

#AI4Good. I built a live interpreter: you speak, and the person across the table hears
you in their own language, roughly half a second later. Then I spent as much effort
documenting where it must not be used as I did making it fast.

Language is the quietest barrier there is. It decides who can ask a question in a meeting, who
can follow a lesson, who gets served first at a counter. Machine interpretation cannot fix
that — but a demo that puts a decent version of it in anyone's hands, free and open, is a
useful thing to be able to point at.

What it is

Two people who do not share a language sit at one laptop. Each speaks naturally; the other
hears it in their own language, in a natural neural voice. Live captions stream in both
languages while you are still talking.

16 languages, including English, Hindi, Kannada, Tamil, Telugu and Marathi alongside Spanish, French, German, Italian, Portuguese, Japanese, Korean, Chinese, Russian and Arabic.
Bidirectional. Hold the floor with 1 or 2, talk, press Esc. The other side hears the translation spoken aloud.
Right-to-left aware, so Arabic renders correctly rather than approximately.
It shows you the real numbers. Every turn displays three timings: time to caption, time to settled translation, and time until the other person actually heard it.

That last one is the part I care about most. "Realtime" is the easiest word in AI to say and
the hardest to mean. So the interface just tells you.

How it was built

The whole thing runs on Azure AI Speech, and the browser streams microphone audio
directly to Azure over a WebSocket. There's a small Express server, but audio never
touches it — putting a backend in that path would add a hop to every audio frame and quietly
destroy the latency budget. The server exists for exactly one job: minting credentials.

There are no API keys. There cannot be.

Every Azure Speech sample starts by pasting a subscription key. That was impossible here — the
tenant force-applies disableLocalAuth=true to every Cognitive Services account:

az cognitiveservices account keys list ...
→ ERROR: (BadRequest) Failed to list key. disableLocalAuth is set to be true

I created a brand-new resource to check whether it was a per-resource setting. It came back
key-disabled too. So this is Azure Policy, not configuration, and the entire sample corpus is
unusable.

That turned out to be a gift. The design that survives is strictly better:

The server holds a managed identity and gets a Microsoft Entra token.
It exchanges that for a Speech-scoped token that dies in ten minutes.
The browser receives only that token — never the Entra one, which every Cognitive Services resource in reach would happily accept.

The project charter enforces this mechanically: browser code is forbidden from importing
@azure/identity, and the build fails if it ever does. I grepped the shipped bundle to
confirm.

Two landmines, documented so nobody else loses an afternoon

Node's native WebSocket silently breaks the Speech SDK. Recognition died with
StatusCode: 1006 and no explanation, while text-to-speech on the same credential worked
perfectly — which sends you hunting through auth and RBAC for an hour. The cause: modern Node
exposes a global WebSocket that negotiates over HTTP/2, which the Speech endpoints reject.
delete globalThis.WebSocket fixes it instantly. Browsers are unaffected.

TranslationRecognizer has no echo cancellation. On open speakers, the app hears its own
translation, translates that, speaks it, and loops forever. My first fix — ignoring
recognition results during playback — was reviewed and found insufficient, because results are
filtered when they arrive, not when the audio was captured. Audio recorded during playback
can finalise after the cooldown and be believed. The real fix is to mute the microphone track
at the device.

Chasing the latency, and being wrong about it

Time-to-heard started at 1.2–2.4 seconds. The measurements said synthesis was 75–85% of it,
so the obvious move was switching to the recognizer's built-in fused synthesis. I benchmarked
it instead of assuming:

Strategy	Median to first audio
Chained synthesizer (cold)	2775 ms
Chained + pre-opened connection	2218 ms
Fused (architectural rewrite)	2032 ms

The middle row is the answer. Most of the cost wasn't the extra network round trip at all — it
was a cold TLS and WebSocket handshake, paid at the worst possible instant, right after the
speaker stops. Opening that connection while the user is still talking, when the wait is
free, recovered three quarters of the available win for a few lines of code, and no rewrite.

Time-to-heard is now 0.4–0.7 seconds.

One command to deploy

It ships as an Azure Solution Accelerator:

azd auth login && azd up

Bicep provisions the AI Services account, a managed identity with the Cognitive Services
User role, a container registry, Container Apps, and monitoring — then builds the image
remotely in ACR (so you don't need Docker installed), creates the Microsoft Entra app
registration, and turns on sign-in.

The bug that only a real deployment could find

That role is Cognitive Services User, and getting there cost me an hour.

I had assigned Cognitive Services Speech User — the obvious choice for a speech app, and
what every instinct says is correct least-privilege. The deployed app failed every single
token exchange:

HTTP 401 {"error":{"code":"PermissionDenied",
          "message":"Principal does not have access to API/Operation."}}

The role assignment existed. The client ID matched. The endpoint was right. It wasn't
propagation — I retried for forty minutes.

Listing the role's actual permissions explains it. Every data action Cognitive Services
Speech User grants sits beneath accounts/SpeechServices/…, CustomVoice, TTSPlayer.
Not one of them authorises /sts/v1.0/issueToken, which isn't under SpeechServices at
all. That's the endpoint my whole keyless design depends on.

And here's why it hid so well: locally, everything worked perfectly. Because locally I was
signed in as a subscription Owner, and inherited roles quietly supplied the permission the
explicitly-assigned one lacked. The managed identity had no such inheritance. It was the first
principal to ever exercise that role as actually written.

A permission model verified only by a subscription Owner proves almost nothing.

That's now the second bug on this project that survived template validation, unit tests and
careful reading, and died the moment something real ran. Both had the same shape: my
development environment was more privileged and more permissive than production.

I originally targeted App Service and it validated perfectly. Then I actually deployed it:

InternalSubscriptionIsOverQuotaForSku
Current Limit (Total VMs): 0

App Service isn't rate-limited in that subscription — it's zero, which is common in enterprise
and sponsored subscriptions. Deploying for real also surfaced two bugs no amount of template
validation could: the container couldn't pull its own image, and it bound to loopback inside
the container so every request timed out. Validate is not deploy.

Verified, not asserted

180 unit tests, and an end-to-end check that plays recorded speech into a real Chromium
microphone and fails unless the translation comes out in the right script — in both
directions. Proving one direction proves half a product. The design tokens are contrast-
tested too, so a colour that fails WCAG fails the build.

The good — and the honest limits

The upside is obvious: a free, open, self-hostable interpreter lowers a real barrier, and every
Indian language in the catalogue is one that machine translation demos usually skip.

But the most important file in the repository is docs/RESPONSIBLE_AI.md, and it is mostly a
list of places you should refuse to use this:

Medical consultations, diagnoses, consent, medication instructions
Legal proceedings, contracts, statements
Emergency and safety-critical communication
Immigration, asylum, or law-enforcement interviews

Those are precisely the settings where interpretation matters most — and precisely where this
fails worst. Machine translation is confidently wrong in ways humans are not. The interface
shows translations as flat statements with no confidence signal, so a wrong one looks exactly
like a right one. It guesses gender and formality when translating into languages that mark
them, and being misgendered is not a trivial error. It splits sentences on pauses and carries
no context between turns.

An AI4Good project that only lists its benefits isn't being good, it's being marketed. If you
deploy this: tell people they're being machine-translated before they speak, say plainly that
it's a machine, and provide a human alternative for anything that matters.

Try it

💻 Source: github.com/naveenneog/speechbridge
☁️ Deploy: azd up — keyless, authenticated, about two minutes
🖥️ Local: npm install && npm run dev, then az login. No API key required.
📖 The decisions: docs/adr/ — including the two landmines above, and every place a review found me wrong.

SpendLens: Private, On-Device Bank-Statement Analysis — No Login, No Cloud, No LLM

Naveen Gopalakrishna — Thu, 30 Jul 2026 07:13:08 +0000

Day 17 of #AI4Good. I used an AI coding agent to build a personal-finance app — and the single most important design decision was to keep AI, the cloud, and the network completely out of it. Your bank statement is read, parsed, and reconciled on your own device. Nothing is uploaded. Nothing is stored anywhere but your phone.

I'm Naveen Gopalakrishna — an AI Global Black Belt at Microsoft, a compulsive builder after hours. Most #AI4Good builds put AI in the product. SpendLens is the opposite, on purpose: the "good" here is financial privacy, so the intelligence lives in the parser, not in a model, and your money never leaves the device.

▶️ Try it in the browser (nothing retained): naveenneog.github.io/SpendLens
📦 Android APK: github.com/naveenneog/SpendLens/releases/latest
💻 Source: github.com/naveenneog/SpendLens

What it is

SpendLens reads a bank-statement PDF and turns it into an honest picture of where your money went — without a bank login, an OTP, a screen-scrape, or an upload.

Import a PDF through the native Android/iOS document picker (or drag one into the browser version). Password-protected statements are supported; the password is used in memory and never kept.
Reconciled summary — total spent, total received, opening and closing balance, and date range, in Indian digit grouping with tabular figures.
Spend by category, daily-spend trend, and largest spends, each with an accessible table/list equivalent and labels that never rely on colour alone.
Searchable, filterable transactions with editable categories. Correct a category once and SpendLens remembers the merchant rule for next time.
Saved statement history on-device, and a one-tap delete everything that really deletes everything.
Detection for 78 RBI scheduled retail banks — public-sector, private, small-finance, payments, and regional-rural — by official name, known aliases, and IFSC prefixes.

The cover image is the browser version analysing a fully synthetic Axis sample: an Axis Bank Ltd. statement, marked Verified, Active only in this tab, spend broken out by category, and a daily-spend chart — all rendered without a single network request leaving the page.

How it was built

The whole app is Flutter (Dart) with a thin layer of native platform code, and it was built with GitHub Copilot CLI in autopilot mode — the agent researched Indian statement formats, wrote the parser and tests, ran the builds, and drove an Android emulator smoke test end to end.

On-device PDF text extraction. Rather than ship a commercial PDF SDK, SpendLens calls the platform's own engine on a worker thread: PDFBox-Android (Kotlin) on Android and PDFKit (Swift) on iOS, over a method channel. Image-only / scanned PDFs are rejected explicitly (on-device OCR is a future module) instead of pretending they parsed.

A deterministic parser — no ML, no LLM. This is the heart of the trust model. The generic parser:

recovers multiline transaction descriptions and handles the common Indian date formats;
infers debit vs credit from the direction of consecutive running balances;
checks the opening + credits − debits = closing equation, and, when the statement declares its own debit/credit totals, validates those too — in the detected column order;
preserves DR, leading-minus, and zero-crossing overdraft balances;
and returns an explicit Verified, Needs review, or Incomplete verdict with the diagnostic attached.

It never converts a parse error into a success-shaped empty dashboard. If the numbers don't reconcile, the UI says so.

Money is integer paise, never floating point. Every amount is stored and summed as an integer so ₹0.01 rounding drift can't creep into a total.

Explainable categorization. Categories come from transparent keyword rules with token-boundary matching, so "Zuber" doesn't get filed under the ride brand "Uber," and your own merchant corrections always override the built-ins.

Local persistence. Statements, edited categories, merchant rules, and settings live in SQLite (analyses stored as JSON documents for schema agility). Category-rule updates and full data deletion are atomic transactions, and concurrent first-access is serialised through a single database-open future so startup can't race.

A custom native document picker. file_picker didn't compile cleanly against Flutter 3.44 / AGP 9, so SpendLens ships its own Storage Access Framework / UIDocumentPickerViewController picker — which also avoids asking for broad storage permissions.

A zero-retention web twin. The GitHub Pages version does the same parsing in the browser with self-hosted PDF.js and a Content-Security-Policy of connect-src 'none' — no cookies, local storage, IndexedDB, service worker, analytics, or upload endpoint. A static verify_web_privacy check runs in CI to keep it that way, and the analysis auto-clears after 15 minutes.

Verified before shipping. 40 automated tests (parser, bank registry, categorization, SQLite, controller, privacy, concurrency, widgets), a clean flutter analyze, the web-privacy verifier, and a scripted Android emulator smoke that imports a synthetic statement, checks reconciliation, and confirms that "delete everything" survives a relaunch.

The good

Most "see where your money goes" apps ask you to connect your bank — handing a third party your credentials, or trusting an aggregator to hold your transaction history. SpendLens is a bet that you shouldn't have to. Everything happens on the device you already trust with the statement. No account, no analytics SDK, no remote parser, no generative-AI dependency; Android backup/transfer is disabled and the iOS database is excluded from backups.

And it's built for Indian statements specifically — the date formats, the digit grouping, and coverage across 78 banks including the small-finance and regional-rural banks that mainstream tools ignore. When a layout is unfamiliar it degrades honestly to Needs review rather than inventing certainty.

The meta-point is the one I like most: an AI agent built a finance tool whose entire value proposition is that AI and the network never touch your money. That's a version of #AI4Good worth keeping in the toolkit — using the agent to ship privacy, not to harvest it.

Try it

▶️ Live (zero-retention browser analyzer): naveenneog.github.io/SpendLens
📦 Android APK: github.com/naveenneog/SpendLens/releases/latest
💻 Source: github.com/naveenneog/SpendLens

naveenneog / SpendLens

Privacy-first Flutter app that turns Indian bank-statement PDFs into on-device spending insights - no bank login, cloud upload, analytics, or LLMs.

SpendLens

SpendLens is a privacy-first Flutter app that turns Indian bank-statement PDFs into understandable spending summaries without bank logins, cloud uploads, or LLMs.

Version 0.2

On-device PDF text extraction and deterministic parsing
Detection registry for 78 RBI scheduled retail banks
Reconciliation and partial-parse diagnostics
Editable categories and remembered merchant rules
Category, daily-spend, and large-spend views
Searchable transactions and saved statement history
Adaptive Android/iOS layouts, light/dark themes, and accessible chart alternatives
Native Android and iOS document pickers with no broad storage permission
Password-protected PDF handling
Local SQLite persistence and complete data deletion
Zero-retention GitHub Pages analyzer in docs/
Self-hosted PDF.js with a CSP that forbids authored network connections
Explicit browser-memory clear and 15-minute inactivity clearing

Development

Flutter is installed at C:\Users\navg\flutter.

& "C:\Users\navg\flutter\bin\flutter.bat" pub get
& "C:\Users\navg\flutter\bin\flutter.bat" analyze
& "C:\Users\navg\flutter\bin\flutter.bat" test
& "C:\Users\navg\flutter\bin\flutter.bat" run

The current sideload artifact is:

artifacts\SpendLens-v0.2.0.apk

It follows…

View on GitHub

Part of the #AI4Good series — one build at a time, from a single laptop, with the "who does this help?" chosen first. GitHub · LinkedIn. #AI4Good

Overdrive: An Open-Source Skill That Makes Your Coding Agent Stop Settling for Correct

Naveen Gopalakrishna — Wed, 29 Jul 2026 08:51:47 +0000

Most of the gap between a mediocre answer and an exceptional one from the same model isn't capability. It's standards. Overdrive is the standards, written down and installed.

npx github:naveenneog/overdrive

I'm Naveen Gopalakrishna — an AI Global Black Belt at Microsoft, a compulsive builder after hours. This #AI4Good release is a tool rather than an app: an open-source agent skill that changes how hard your coding agent works.

💻 Source (MIT): github.com/naveenneog/overdrive
⚡ Install: npx github:naveenneog/overdrive
🤖 Works with: GitHub Copilot CLI · Claude Code

Where it came from

I'd collected a handful of those "show me the absolute ceiling of what you can do" prompts that get used to evaluate frontier models against each other. Five of them, in five completely unrelated domains:

Advanced web design
Real-time 3D
Motion graphics
A playable game
A private-wealth investment deck

A deck and a shader have nothing in common. But reading the five side by side, the shape of them was identical. Every one of them:

framed the ceiling, not the requirement — "the best thing you can produce", explicitly compared against other models, explicitly credited to you by name
told the model to decide and commit rather than ask which direction you'd prefer, and said the ambition of that choice was itself part of the score
named the boring, obvious, median answer up front so it could be ruled out
demanded research, not memory
offered a non-exhaustive buffet of advanced techniques and asked for several, integrated
held one dominant success criterion above everything else — fun in thirty seconds; timing; 60fps; taste; defensibility
required original assets rather than borrowed ones
ended with "QA it by actually using it"

That's not five prompts. That's one prompt wearing five costumes. So I extracted the skeleton and made it a skill.

What it actually is

Overdrive is a judgement layer, not a domain skill. It doesn't know how to build a game or write a deck. It changes how hard and how well the agent attacks whatever it was already going to do.

Ten rules override the agent's normal defaults when it's on. The two that change the most behaviour:

Decide and commit — never ask. Where the task leaves a choice open — concept, subject, genre, stack, angle — you choose. The ambition of that choice is part of the score. Asking "which would you like?" is a wasted turn.

QA by actually using it. Run it, play it, scroll it, watch it, read it end to end, stress it. An unrun deliverable is an unfinished deliverable.

The rest: frame the ceiling, name the median answer and refuse it, research instead of recalling, stack techniques rather than bolting one on, hold one dominant criterion, generate rather than borrow, survive inspection past the first screen, and red-team your own work then fix what the attack found.

Seven phases

The skill runs the work through: set the bar (write DOMAIN / CEILING / DOMINANT in three lines) → commit to a concept in one sentence → research → choose amplifiers → build with the dominant criterion in front → red-team → QA for real.

A rubric it has to report

Before declaring done, the agent scores itself 1–5 and shows you the scores:

Dimension	5 =
Ambition of the choice	The concept is impressive before a line is written
Dominant criterion	The one thing that matters is genuinely nailed
Technical depth	Multiple advanced techniques, composed — not bolted on
Craft / finish	Nothing default; deliberate typography, timing, naming, structure
Coherence	One clear point of view carried through every part
Originality	Assets, analysis and structure are yours, not borrowed
Robustness	Runs clean: no errors, no stutter, no overflow, no dead link
Honesty	Claims are sourced; estimates are labelled; limits are stated

Anything scoring ≤3 gets another pass. Scoring in the open is a forcing function — it's uncomfortable to hand someone a 3 you've written down yourself.

What's in the box

File	What it does
`SKILL.md`	The contract, the seven phases, the rubric, the failure modes, and when not to use it
`references/amplifiers.md`	Nine domain packs — web, real-time 3D, motion graphics, games, audio, research & decks, systems, data viz, writing. Each with its dominant criterion, technique buffet, library shortlist and QA moves
`references/red-team.md`	Five questions, an inversion pass, a contrast pass, how to delegate the red team to a sub-agent, and the bar for what must get fixed
`references/qa-protocol.md`	Per-domain "actually use it" QA, a browser harness, and the ship checklist
`references/research-protocol.md`	What always needs looking up, sourcing rules, and how to label an estimate as an estimate
`references/prompt-templates.md`	Paste-ready Overdrive prompts for when you are the one prompting a model
`scripts/qa_web.mjs`	Playwright harness — console/page errors, failed requests, horizontal overflow per viewport, FPS sampling, screenshots

Installing it

One command, zero runtime dependencies — the installer is plain Node and copies seven files:

# everywhere it finds an agent
npx github:naveenneog/overdrive

# or pick one
npx github:naveenneog/overdrive --claude
npx github:naveenneog/overdrive --copilot

# per-repo instead of your home directory
npx github:naveenneog/overdrive --project

# what's detected, what's already installed
npx github:naveenneog/overdrive --list

It lands in ~/.copilot/skills/overdrive and ~/.claude/skills/overdrive. There's --force, --dry-run, --dir <path> and --uninstall too.

Then start a new agent session and say "overdrive" — or "go all out", "show me the ceiling", "don't hold back", "make it a portfolio piece", "this is going public".

Does it actually do anything?

Fair question, and the honest answer is that a prompt-shaped tool is easy to fool yourself about. So here's the concrete case.

The ANTIKYTHERA title sequence — written up here — was built under Overdrive from a single prompt. A 29-second documentary title sequence in one self-contained HTML file: procedural bronze gear geometry at authentic Antikythera tooth counts, a hand-written post-processing chain, a fully synthesised Web Audio score, no assets of any kind.

But the output isn't the interesting part. Phase 7 is.

QA by actually using it is trivial for a human and structurally impossible for an agent — it can't watch a film. So it built itself an eye: installed Playwright, exposed a transport API from the piece, captured 90 frames across the runtime, assembled them into a contact sheet, and looked at the whole edit as one image.

That caught seven defects that reading the code never would have:

a wrapper div's z-index created a stacking context that isolated mix-blend-mode from the canvas — film grain rendered as raw grey static over everything
GSAP read a CSS translateY(112%) back as resolved pixels into its y cache, so the later yPercent tween animated a different axis and the title never appeared — while the tween reported progress: 1
the eclipsing moon's circles sat at SVG origin instead of the orrery centre, so totality never happened
the title wrapped onto two lines mid-animation
flash frames held 0.35s and read as an error rather than a cut
the corona quad's square edge was visible against the starfield
point-light intensities were in physical units on a renderer defaulting to legacy lighting, blowing an entire act to white

Every one of those is invisible in source and obvious in a screenshot. Without the "actually use it" clause, that piece ships broken and looks finished in the diff.

That's the mechanism. Not better code generation — better standards, and a refusal to declare done without evidence.

When not to use it

The skill says this itself, which I think matters more than the feature list. Overdrive costs time and tokens, and it explicitly tells the agent not to apply it to:

trivial mechanical edits — renames, version bumps, typos
anything you've said you want quick, minimal or throwaway
hotfixes under time pressure, where correctness and reversibility beat ambition
work with a hard external spec — an API contract, a compliance form — where invention is the enemy

A capability amplifier that fires on everything is just an expensive way to over-engineer a typo fix.

The good

Skills are the most underrated part of the current agent tooling, and they're just markdown in a folder. No SDK, no plugin API, no build. Which means the thing that separates a good agent session from a great one is largely writing down what "great" means — and that's a skill anyone can author, read, disagree with, and fork.

Overdrive is MIT. If your standards differ from mine, rewrite the rubric — that's the point. The interesting artifact isn't my eight dimensions. It's that eight dimensions written down at all beats infinite capability with no bar.

Try it

⚡ Install: npx github:naveenneog/overdrive
💻 Source (MIT): github.com/naveenneog/overdrive
🎬 Built with it: ANTIKYTHERA · the write-up

ANTIKYTHERA: A 29-Second Title Sequence in One HTML File — No Assets, No Build Step

Naveen Gopalakrishna — Sun, 26 Jul 2026 14:56:43 +0000

One prompt. No assets. No build step. No server. One index.html you can open by double-clicking it — and 29 seconds of motion design comes out.

I'm Naveen Gopalakrishna — an AI Global Black Belt at Microsoft, a compulsive builder after hours. This #AI4Good build is a little different from the app-a-day entries: it isn't an app at all. It's a film. And it's the most interesting capability test I've run at an AI coding agent so far.

▶️ Watch it: naveenneog.github.io/Antikythera
💻 Source (MIT): github.com/naveenneog/Antikythera

The prompt

This is the whole brief, verbatim. Nothing else was specified — not the subject, not the concept, not the look:

Build one motion graphics piece that demonstrates the absolute ceiling of your
motion design capability. You choose the subject and the concept. That decision
is part of what's being evaluated.

Context you should know: this is going into a video comparing you against other
frontier models, shown to a large audience, and your work will be credited to you
by name. Every model gets this exact prompt. So go nuts and show people what
you're actually capable of.

Requirements:

1. You pick it. A title sequence, a product spot, a data story, an explainer, a
   brand identity in motion, a piece of pure abstract choreography — anything.
   Decide and commit. The ambition of the choice is part of the score.

2. It plays automatically on load, runs roughly 15-30 seconds, and holds on a
   final frame. Add a replay control. It must read as a finished, edited piece —
   not a looping animation demo.

3. Choreography is the whole test. Pull from whatever best showcases you —
   including but not limited to: kinetic typography and per-character animation,
   variable font animation, staggered reveal systems, easing with real authored
   weight, overshoot and anticipation, masking and reveal wipes, SVG path drawing
   and morphing, shape transitions, mix-blend-mode compositing, particle and
   physics-driven motion, 3D layers and camera moves, depth and parallax,
   shader-based transitions, displacement and distortion, grain and optical
   treatment, match cuts between scenes, sound-design-driven timing.

4. You have free reign to look up how to use any of these, and to pull in open
   source animation libraries freely — GSAP, anime.js, Three.js, Lottie, shader
   libraries, anything on a CDN. Add any other technique you think demonstrates
   more. The list is a starting point, not a boundary.

5. Timing is what separates real motion design from animation. Beats should land
   with intent, moments should breathe, and the piece should build. If everything
   moves at the same speed with the same easing, it has failed.

6. Single self-contained index.html. Any library via CDN. No build step, no server,
   no API keys.

7. No hotlinked video or stock footage. Everything generated in-browser.

8. QA it by watching it. Play it start to finish several times. Check that beats
   don't collide, nothing pops in unstyled, timing reads, and it holds 60fps
   throughout.

Note requirement 1: the choice of subject is part of the score. That's the genuinely interesting part of the test. Anyone can animate a logo. Picking what deserves 29 seconds is a design judgement.

Why the Antikythera mechanism

Copilot picked the Antikythera mechanism — the bronze geared analog computer built around 150 BCE, lost in a shipwreck off the island of Antikythera around 60 BCE, and dredged up by sponge divers in 1901. It predicted eclipses, tracked the Metonic and Saros cycles, and modelled the motion of the sun and moon. Nothing of comparable mechanical complexity appears again in the archaeological record for over a thousand years.

The reasoning it gave for the choice is the bit I actually care about, because it's a motion design argument rather than a "cool topic" argument:

It hands you two opposing motion vocabularies to choreograph against each other.

Register	Behaviour	Where
Organic	slow, sine-driven drift, long eases, nothing ever stops hard	the sea floor
Mechanical	quantised, staccato, hard `expo` landings, overshoot and settle	the machine

The edit then cuts between those two registers. The subject isn't decoration — it generates the grammar of the piece. That's the difference between choosing a topic and choosing a concept.

The edit

Five acts, ~29 seconds, then it holds on the final frame.

t	Act	What happens
0.0s	The Dark	The frame closes to 2.39:1. Marine snow drifts through three parallax depth bands, light shafts sway, coordinates type on in the corner.
3.0s		A raking light travels across frame and uncovers a corroded bronze fragment — the light and the reveal mask are driven by the same value, so the light is physically the thing revealing the object.
5.55s	The Find	Hard cut. Register change to cold cyan. Corner reticles snap in with overshoot, data readouts stagger, a counter races to 82.
6.5s		A scan bar crosses the artifact and the gear line-art draws in exactly where the bar has already passed. Greek inscription glyphs flicker on around the rim in random order.
9.45s	The Machine	Hard cut. Eight bronze gears fly forward out of the dark and land hard. A beat of anticipation — a tiny backwards creep — and the train starts to turn.
11.2s		Four cycle cards cut over the mechanism: METONIC · SAROS · CALLIPPIC · EXELIGMOS, each with a different entrance, each with its number counting up.
15.7s		Everything accelerates, then slams to a dead stop with a prismatic radial smear.
16.5s	(silence)	Cut to black. 0.36 seconds of nothing.
16.85s	The Sky	The great gear's rim becomes the outer orbit. An orrery runs at real relative periods.
20.0s		The moon crosses the sun. Time decelerates. The light goes out, the stars come up — as they really do at totality.
22.0s		Totality. The piece stops moving for about a second.
23.85s	Title	The corona ring is squashed on one axis until it is the rule under the title. ANTIKYTHERA reveals per character.

Three match cuts carry the structure

This is the part I'd point at if someone asked what "editing" means in a piece with no footage.

The artifact becomes its own X-ray. Same SVG path, same position, same size — only the render register changes. The eye reads continuity, the brain reads a new way of seeing the same object.
The great gear's rim becomes the outer orbit. The camera lands at exactly z = 43.7 so the 223-tooth wheel's rim measures ~298px on screen; the outer orbit circle is 300px. For most of a second both are on screen at once while the machine dissolves out from under the circle. The machine doesn't cut to the sky — it becomes the sky.
The corona ring becomes the title rule. One property: scaleY → 0.0035. A circle with no height is a line. That line then slides down and is the rule under the title.

One circle, three meanings, across three acts.

How the graphics were made

Nothing is loaded. No image files, no video, no models, no HDRIs, no textures. Here's what that actually required.

Gear geometry from real tooth counts

The gears aren't decorative cog shapes. Each is a THREE.Shape whose outline is generated tooth by tooth, then extruded with THREE.ExtrudeGeometry and bevelled. The tooth counts are the real surviving Antikythera counts — 223 (the Saros wheel), 127 (Metonic), 64, 53, 48, 38, 32, 27 — laid out on a shared module, so every pitch radius is m · teeth / 2 and the gears genuinely mesh when placed tangentially:

const GEAR_SPEC = [
  {t:223, z: 0.00, abs:true, th:.46, arms:4},   // the great Saros wheel
  {t:127, z:-1.90, abs:true, th:.40, arms:3},   // Metonic, on a layer behind
  {t: 64, z: 0.98, p:0, ang: 58, th:.34, arms:3},
  {t: 53, z: 0.98, p:0, ang:  4, th:.34, arms:3},
  ...
];
// meshing distance is just the sum of the two pitch radii
const d = parent.rP + rP;
px = parent.mesh.userData.hx + Math.cos(a) * d;

Angular velocity is then ω · (223 / teeth) with alternating direction — so the train turns at true ratios. The little 27-tooth gear whirs; the great wheel barely creeps. You can feel the gearing without being told about it. Spoke cutouts are THREE.Path holes punched into the same shape, which is why you can see the Metonic wheel turning through the Saros wheel behind it.

The bronze surface, computed in JavaScript

There's no texture file, so the corrosion is a value-noise heightfield evaluated in JS at load:

An integer hash → smooth-interpolated value noise → 5-octave fBm heightfield.
Screen-space normals taken from the heightfield's neighbours.
A Lambert term against a fixed key direction, plus a tight specular power.
A second low-frequency noise field distributes verdigris patches (bronze → green patina).
A third, higher-frequency field carves pits, which also self-shadow — that's what sells the relief rather than making it look like printed noise.

It's rasterised once into three canvases and reused three ways: as an SVG <pattern> fill for the artifact, and as the map + roughnessMap + bumpMap on the gear material. One noise pass, one look, two rendering technologies.

An environment map with nothing to load

Metal needs reflections, and hotlinking an HDRI was off the table. So the environment is painted: a canvas gradient with a warm key blob and a cold cyan kicker, marked as an equirectangular texture and run through PMREMGenerator. That's where the bronze's specular life comes from.

A hand-written post-processing chain

No EffectComposer — the whole chain is written out, which keeps the cost controllable:

scene → half-float render target
      → bright pass (threshold 1.15)
      → two-scale separable gaussian bloom (¼ and 1/14 res, ping-pong)
      → one composite pass

That single composite pass does barrel distortion, prismatic radial smear, chromatic aberration, colour grade, ACES tonemap, sRGB encode and vignette. The expensive smear/aberration path — 8 taps × 3 channels — sits behind a uniform branch, so it costs nothing except on the two or three beats that actually use it (the slam, the cuts).

Optical treatment: grain and gate weave

Two details that do a disproportionate amount of work:

Film grain is eight pre-baked frames of gaussian noise (three uniforms averaged — flat Math.random() reads as video noise, not film) cycled at 24fps, not 60, with a randomised offset each swap, composited in mix-blend-mode: overlay.
Gate weave — sub-pixel translation and a fraction of a degree of rotation applied to the whole frame, because projected film never sits perfectly still. It's almost subliminal and the piece feels dead without it.

Three layers, one frame

#gl    <canvas>  Three.js — particles, gears, starfield, corona, post chain
#vec   <svg>     line art — artifact, X-ray gears, orbits, the title rule
#type  <div>     DOM      — all typography
       grain / scanlines / halation / vignette / flash / letterbox

Typography deliberately stays in the DOM: real font rendering, real variable-font axes, and it stays razor sharp regardless of the WebGL render scale. The title animates font-variation-settings from 'wght' 900 down to 420 as the letters land — the letterforms visibly cool from black to book weight while tracking in. That's a variable font doing something a static font simply cannot.

How the audio was made

Also no files. Every sound is synthesised with the Web Audio API at runtime.

Cue	How it's built
Sub drone (the bed)	Two detuned sawtooth oscillators at 40 / 40.35 Hz plus two sines, through a lowpass whose cutoff sweeps 110 → 340 → 150 Hz across the whole piece. A 0.09 Hz LFO on the gain gives it a slow tape-like breathing.
Impacts (the cuts)	A sine with a pitch envelope from 150 Hz down to 32 Hz in 0.34s, plus a band-passed noise transient for the click.
Gear ticks	50ms noise bursts through a narrow band-pass (Q = 9) at 2.4 kHz, pitch-scaled per gear so the eight gears landing sound like eight different pieces of metal.
Data blips	Short square-wave pings through a lowpass, one per readout row.
Riser (into the slam)	White noise through a band-pass sweeping 300 Hz → 7 kHz exponentially, doubled by a sawtooth sweeping 70 → 430 Hz.
Celestial pad (the sky)	Five sine partials on a minor voicing, each doubled and detuned by 0.4%, with a long 1.9s fade in.
Reverse swell (into the title)	Band-passed noise with an exponentially rising gain envelope, so it sounds like a reversed cymbal.

Reverb is a synthesised impulse response — 3.4 seconds of stereo noise shaped by an exponential decay curve, fed into a ConvolverNode. A plate reverb with no plate and no sample.

The important part isn't the synthesis, though. It's that every cue is fired from the same GSAP timeline that drives the picture:

tl.call(() => SND.hit(1.15), null, A3 - 0.050);   // the impact IS the cut
tl.call(() => SND.riser(0.95), null, A3 + 5.30);  // riser into the slam
GEARS.forEach((g, i) => {
  tl.call(() => SND.tick(0.55 + i*0.16, 0.20), null, at + 0.55);  // per gear landing
});

Sound and picture can't drift, because there's only one clock. Sound is off by default, and the piece says so rather than hiding it: a speaker icon sits in the corner from the first frame, reading turn on sound — headphones recommended. That click is the gesture that unlocks the AudioContext, so no autoplay policy is ever fought. Turn it on part-way through and the drone joins at the point in its envelope the picture has already reached, rather than restarting its five-second fade underneath Act III. The invitation steps back to a bare toggle after about eleven seconds, so it isn't sitting over the film for all 29 of them.

It's still designed to read perfectly silent — the sound is a layer on top of timing that already works.

Timing: the actual test

Requirement 5 said it plainly: if everything moves at the same speed with the same easing, it has failed.

So nothing in the piece uses a default ease. There are ten hand-authored CustomEase bezier curves, each with a job:

CE.create('cinema' ,'M0,0 C0.62,0 0.05,1 1,1');        // long filmic settle
CE.create('slam'   ,'M0,0 C0.04,0.92 0.09,1 1,1');      // hard mechanical stop
CE.create('settle' ,'M0,0 C0.12,0.86 0.18,1.045 1,1');  // land + micro overshoot
CE.create('punch'  ,'M0,0 C0.02,1.18 0.28,0.99 1,1');   // big overshoot
CE.create('antic'  ,'M0,0 C0.34,-0.30 0.18,1 1,1');     // pull back, then go
CE.create('choke'  ,'M0,0 C0.86,0.02 0.98,0.62 1,1');   // slow start, late rush

antic is the one I like best: it dips below zero before moving, so when the gear train starts turning it creeps backwards a few frames first. Classic animation anticipation, expressed as a bezier control point at y = -0.30.

And the single most effective beat in the whole piece costs nothing at all: after the mechanism slams to a stop, there is a hard cut to black and 0.36 seconds of absolutely nothing before the sky fades up. Silence and stillness, used as a beat. That's an editing decision, not an animation one.

Everything is placed on one gsap.timeline() at absolute times, so cut points are authored rather than accumulated. GSAP writes to a plain state object; the renderer only ever reads it. Picture logic and draw logic never touch each other.

How it was actually built — and what it says about capability

The whole thing was built in a single session with GitHub Copilot CLI in autopilot mode. The genuinely notable part wasn't the code generation. It was requirement 8: QA it by watching it.

An agent can't watch. So it built itself an eye:

Installed Playwright, exposed a small transport API (SEQ.seek(), SEQ.play()) from the piece.
Captured 90 frames across the runtime — every 0.5s, plus extra samples clustered on the cut points.
Assembled them into a contact sheet and looked at the whole edit as one image.
Measured frame pacing across a full real-time run (p50/p95/p99).

That loop caught seven real defects that reading the code would never have surfaced:

Bug	Why it mattered
A wrapper `div`'s `z-index` created a stacking context that isolated `mix-blend-mode` from the canvas — the film grain rendered as raw grey static over everything.	Structurally invisible in code. Obvious in one screenshot.
GSAP read a CSS `transform: translateY(112%)` back as resolved pixels into its `y` cache, so the later `yPercent` tween animated a different axis — the title never appeared at all.	The tween existed, was correctly positioned, and reported `progress: 1`. Only the picture showed it was wrong.
The eclipsing moon's circles sat at SVG origin instead of the orrery centre — it flew off-screen and totality never happened.
The title wrapped onto two lines mid-track-in.
Flash frames held ~0.35s — read as an error, not a cut. Now 2–3 frames.
The corona quad's square edge was visible against the starfield.
Point-light intensities were in physical units on a renderer defaulting to legacy lighting — the entire third act blew out to white.

Two of those were in the QA harness rather than the piece, which is its own lesson: waitForFunction's rAF polling stalls under a software rasterizer, and GSAP's seek() suppresses onUpdate by default, so scrub-based screenshots silently missed every onUpdate-driven write. Both were diagnosed by instrumenting rather than guessing.

Then, because the environment had no GPU at all (a software rasterizer — 15fps), it added adaptive resolution: if rolling frame time exceeds 21.5ms the render scale steps down, at most three times, never changing composition, timing or colour. That doubled throughput on the bad machine and stays at full resolution on real hardware.

That's the capability worth pointing at. Not "it wrote some Three.js." It made a design decision with a defensible rationale, built its own verification instrument when the requirement demanded one it didn't have, believed the evidence over its own code, and fixed things it could not have known were broken without looking.

The good

Two things, honestly.

The first is access. A 29-second title sequence of this kind is normally After Effects, Cinema 4D, a plugin stack, licences, and a render farm's worth of patience. This is one text file, three CDN links, and a browser. A student anywhere can open it, read every line, change the tooth counts, and watch what happens. There's no pipeline standing between curiosity and the thing.

The second is the subject. The Antikythera mechanism is a reminder that the ancient world was not simple, and that knowledge is genuinely fragile — this machine existed, worked, and then the entire idea of it vanished for a millennium. If a few thousand people watch 29 seconds and go and read about the Saros cycle afterwards, that's a good use of a title sequence.

Try it

▶️ Watch it: naveenneog.github.io/Antikythera — plays on load, ~29s; click the speaker to turn the score on (headphones recommended)
💻 Source (MIT, one file): github.com/naveenneog/Antikythera
🛠 Built with: Three.js r149 · GSAP + CustomEase · Web Audio API · Bodoni Moda / Archivo / JetBrains Mono · GitHub Copilot CLI

One note if you go poking: it pins Three.js r149 on purpose. r149 is the last release that ships a real UMD build/three.min.js. Everything after it is ES-module only, and module CORS blocks file:// — which would have quietly broken the "no build step, no server" constraint the moment anyone double-clicked the file.

Cast in Bidri Metal: Four Ancient Karnataka Board Games, Reborn in 3D

Naveen Gopalakrishna — Tue, 21 Jul 2026 17:27:06 +0000

Before Ludo, before Snakes & Ladders left the subcontinent and came back Anglicised, our grandmothers drew boards in rice-flour on the courtyard floor and played games older than most kingdoms. This is an attempt to give four of Karnataka's own games a home that honours where they came from — and looks good enough to keep on your phone.

I'm Naveen Gopalakrishna — an AI Global Black Belt at Microsoft, a compulsive builder after hours. This #AI4Good build is four games shipped together, each its own free web app and Android APK:

Game	What it is	Play	Get the APK
ಸಾಲು ಮನೆ ಆಟ · Saalu Mane Ata	Nine Men's Morris — align three, break one	play	APK
ಆಡು ಹುಲಿ · Aadu Huli	Goats & Tigers — the asymmetric hunt	play	APK
ಚೌಕಾ ಬಾರಾ · Chowka Bara	The cowrie-and-tokens race	play	APK
ಅಳಗುಳಿ ಮನೆ · Alaguli Mane	Pallanguzhi — the sowing & counting game	play	APK

The games, and where they come from

None of these are inventions. They're games with centuries — sometimes millennia — of continuous play across South India.

Saalu Mane Ata (Nine Men's Morris) is a mill game — three nested squares, nine seeds a side. Form a connected line of three ("a mill") and you break a rival seed. Pure strategy, no dice: the same family of game scratched into the stone floors of temples at Aihole. A game of foresight.
Aadu Huli (Goats & Tigers) is an asymmetric hunt on a triangular board — a few tigers leap to capture goats, while a herd of goats tries to hem the tigers in until they cannot move. The South Indian cousin of Bagh-Chal.
Chowka Bara (Ashta Chamma) is a race game played with cowrie shells for dice on a cross-and-circle board, with safe squares. The ancestor Ludo forgot.
Alaguli Mane (Pallanguzhi) is a mancala — two rows of pits, seeds sown counter-clockwise, pits of four captured. No luck, just counting ahead. The carved wooden board is a genuine heirloom in Kannada and Tamil homes.

Each game ships with multiple "worlds" — a Realistic heritage board, an Original glowing-3D reading, a Modern interpretation, sometimes a Fable world — and the one this post is really about.

The Bidri world — the reason this build exists

The spark for the whole project was a single question: what would these games look like if a master craftsman of Bidar made them?

Bidriware is a 14th-century metal craft from Bidar, Karnataka. A zinc-and-copper alloy is cast, engraved with floral and geometric tarkashi patterns, inlaid with pure silver wire, then blackened with a special soil from the Bidar fort — a soil that darkens the alloy to deep matte black but leaves the silver brilliant. The result is unmistakable: jet-black metal, glowing silver inlay. A GI-tagged craft, and one of the most striking in the world.

So every game got a bespoke Bidri board — not a generic skin, but a mat whose inlay is designed around that game's geometry:

How we matched real artisan work

Getting AI-generated art to actually read as Bidri — and not as "generic ornate black-and-gold" — took a tight loop:

Study first. Real Bidri is matte black, not glossy, the inlay is silver, not gold, the motifs are floral tarkashi and geometric bands, and the craft lives in the contrast. Those became hard constraints.
Prompt to the constraints. Every render was pushed toward "near-black blackened-brass ground, brilliant pure-silver inlay, delicate floral tarkashi engraving, museum-quality metalwork, soft studio light with rich reflections" using Azure gpt-image-2. Gold only as a thin rim highlight.
Align the board to the mat. The generated ornament had to sit around the playable geometry — central design centred on the board, surrounding tarkashi filling the field, the way a craftsman composes a real tray. The mat and a seamless table tile were rendered as a set.
Iterate on light & reflection. Several passes went purely into how the silver catches light and how the black holds shadow, until each board looked photographed, not textured.

The same pipeline produced each game's app icon — this game's own board, cast in Bidri. The Bidri work was distilled into a reusable "Bidri style" skill so the look stays consistent across future builds.

How it was built

The whole suite is deliberately boring where it counts so it can live forever for free:

Pure static, mobile-first, Kannada-first. No backend, no accounts, no tracking. Each game is a folder of HTML/JS/assets on GitHub Pages. Kannada is the first language, English second.
3D in the browser. A shared Three.js core (game3d) renders boards, pieces and worlds, tuned for a mid-range phone. Each game is a thin ruleset on top.
Four games, one drift-locked core. ~36 shared modules stay byte-identical across all four, enforced by a custom rc-gate that fails the build on any drift and runs the full unit-test matrix (668 tests: AH 206 · AM 161 · CB 152 · SMA 149), i18n coverage, JSON-schema contracts, language/voice-pack freshness, and an asset budget.
Six languages, packaged. Kannada + English core; four more ship as downloadable text & voice packs (an "asset diet" with a default-core build that fetches optional packs on demand).
Narration via Azure Speech neural voices, later repacked to cut size.
APKs from the same web build. Capacitor wraps each web/ folder; GitHub Actions builds a debug APK on every release (JDK 21, cap add android, gradlew assembleDebug) and attaches it automatically. Push to main → Pages redeploys; publish a release → the APK builds itself.
Art & icons: Azure gpt-image-2. Everything is open source.

What I learned

Constraints make AI art authentic. "Ornate Indian" gets you tourist-shop clip-art. "Matte-black blackened alloy, pure-silver tarkashi, no gold except a rim highlight" gets you something a Bidar artisan would recognise. Research the craft, then encode it as non-negotiables.
A drift gate is worth more than a test suite alone when shipping four near-identical apps. The most valuable script in the repo is the one that refuses to let the four codebases diverge silently.
Ship the culture first, the translation second. Kannada-first (not "English with a toggle") changed how the whole UI reads.
Static + Capacitor is a superpower for heritage software. One web/ folder becomes a free website and an installable app, zero servers — exactly right for something meant to outlast any hosting bill.
A tiny asset budget forces good decisions. Packing optional languages/voices and fetching on demand kept the base app small without cutting features.

Try it

Free, offline, no account, open source:

Saalu Mane Ata — play · APK · source
Aadu Huli — play · APK · source
Chowka Bara — play · APK · source
Alaguli Mane — play · APK · source

If you have grandparents who played these on a courtyard floor, show them the Bidri board. That reaction is the whole point.

cordless v0.8: Tab Groups, Custom Launchers & Bring-Your-Own Copilot

Naveen Gopalakrishna — Mon, 13 Jul 2026 14:51:24 +0000

TL;DR — cordless is a CLI-first tool that manages your remote terminal / coding-agent sessions and puts them on your phone. v0.8 is about organising the swarm: Chrome-mobile-style tab groups, custom launchers (bring any command as a profile), a built-in GitHub Copilot CLI profile, renameable tabs, and persisted scrollback history so a reopened session after a reboot shows what it was doing. There's also a proper cordless setup installer. Six features, each on its own branch — designed with GPT-5.6 Sol, built with GitHub Copilot CLI.

v0.7 taught cordless to tell me which of my eight agent sessions needs me. v0.8 is the next problem: once you're running that many, they stop fitting on the screen. You need to organise them — like browser tabs, because that was the whole metaphor from day one. So this release is six features that make a big session swarm manageable.

Tab groups

The headline. Sessions can now live in named, colored groups — think "API migration", "Website", "Flaky tests" — exactly like Chrome mobile's tab groups.

In the terminal dashboard, groups render as collapsible headers with a live per-group waiting/session count:

── Sessions (6) ──
▼ API migration          2 waiting · 3 sessions
  ! claude   build pipeline            waiting
  ● codex    api tests                 working
  ○ shell    api ~/src/api             idle
▶ Website                              2 sessions
▼ Ungrouped                            1 session
    ○ copilot scratch                  idle

Press g for the group menu (new / assign / ungroup / collapse / rename / delete), and f to cycle a smart-view filter — All · Attention · Claude · Codex · Copilot · Shell. Those filters are views, not groups; collapse state is per-device. On the phone you get the same idea as a chip strip above the tabs (All · Unread · one chip per group, with counts and color dots) plus rename/move in the details sheet.

The design decision I kept going back and forth on — and where Sol was firm — was manual groups over continuous auto-grouping. Auto-sorting your tabs by directory sounds clever until a session changes cwd and silently jumps groups. So groups are something you choose; deleting one never kills its sessions, it just ungroups them.

Custom launchers (and a built-in Copilot)

Until now cordless had three profiles: shell, claude, codex. v0.8 makes profiles yours. Drop this in ~/.cordless/config.json:

"profiles": {
  "api": { "command": "pwsh", "args": ["-NoLogo"], "cwd": "C:/src/api" },
  "notes": { "command": "nvim", "args": ["~/notes.md"] }
}

…and cordless new api spawns it directly (resolved against the daemon's PATH, not a shell string — no sh -c injection surface). A missing executable doesn't crash anything; it shows as unavailable with a reason, and cordless profiles lists every launcher with its source and availability.

And because the agent world moved, v0.8 ships a built-in copilot profile — the standalone GitHub Copilot CLI — right next to claude and codex. The nice part: attention detection is now preset-driven, so copilot (and any custom profile you tag attentionPreset: "agent") gets the same waiting / finished heuristics the other agents get, for free.

Rename tabs

Small feature, big daily quality-of-life. cordless rename <id> "API migration", or the dashboard e key, or a long-press on the phone. Titles are Unicode-normalized, control-stripped and length-capped, an empty title restores the generated default, and the change broadcasts live to every connected client (with a monotonic revision so a stale update can't clobber a newer one).

Persisted history — survive the reboot

This is the one that turned into a proper engineering story. A cordless session already survives a daemon restart (it reopens the same shell in the same directory). But it came back blank — you lost the scrollback. v0.8 fixes that: the daemon persists a capped, plain-text copy of each session's scrollback (2000 lines / 512 KB, gzipped, user-only) and, on restore, shows it as frozen context above the reopened session with a ── session reopened after system restart ── banner.

A couple of decisions worth calling out:

Normalized text, not raw bytes. Sol talked me out of persisting a truncated ANSI stream (it can start mid-escape-sequence and depends on terminal state you've discarded). We store logical lines from the headless terminal buffer instead.
Don't write it into the fresh terminal. My first version injected the old scrollback into the reopened shell — which promptly wiped it, because a shell like PowerShell clears its own screen on startup. So restored history is kept beside the live session and rendered above it.
Save periodically, not just on shutdown. A reboot doesn't send you a polite shutdown signal, so history is flushed every few seconds while the session runs.

The bug that only failed on Linux

Here's the part I'm glad CI caught. My persisted-history tests were green on Windows and I shipped v0.8.0. The Linux and macOS CLI builds went red on the exact same test.

The cause is a lovely cross-platform trap. On a graceful stop, the daemon catches SIGTERM and runs shutdown(): it saves each session's history, then kills the PTYs. Killing a PTY fires its exit handler — and that handler deleted the just-saved history and rewrote the "reopen these on restart" manifest without the now-exited session. So on Linux the session came back with no history; on macOS it didn't come back at all.

Why did Windows pass? Because on Windows SIGTERM from another process is an uncatchable hard-kill — shutdown() never runs, the exit handler never fires, and the periodically-flushed history file just… survives. The platform that "worked" only worked by accident.

The fix is a _shuttingDown flag so the exit handler preserves history and the manifest during a graceful stop. What I like about it: I reproduced the Linux-only failure on Windows by driving shutdown() directly in a unit test (the harness's SIGTERM can't), so the regression is now locked shut on every platform. Re-tagged, rebuilt, and v0.8.0 went out clean with the full asset set.

How it was built

Same loop, tightened further: me on GitHub Copilot CLI, GPT-5.6 Sol as the design partner — and this time with a rule I'm keeping for good: every feature on its own branch, merged --no-ff, with clean well-documented code. The v0.8 program was six branches (feature/persisted-history, feature/custom-profiles, feature/copilot-profile, feature/session-rename, feature/session-groups, feature/group-ui-phone) plus a fix/history-shutdown. The daemon's test harness grew to 24 suites — the pure profile/attention/render checks, live rename + groups over the WebSocket, the dashboard-driven resume regression, and persisted-history across a real restart — and CI runs all of it on Windows, Linux and macOS before building and smoke-testing the self-contained binary.

The good

The feeling I was chasing: open cordless with a dozen agents running and not feel underwater. The waiting ones surface (v0.7); the rest are filed into groups you named, launched from profiles you defined, titled how you think about them — and if the box reboots overnight, each one comes back with its history intact. It's the browser-tabs promise, finally delivered for a swarm of terminals.

Try it

▶️ Live / docs: naveenneog.github.io/cordless
💻 cordless CLI (Windows / Linux, no Node needed): github.com/naveenneog/cordless/releases/latest — then cordless setup
📦 Android APK: github.com/naveenneog/cordless/releases/latest
🧑‍💻 Source: github.com/naveenneog/cordless

Part of the #AI4Good series. Built one day at a time. — @naveenneog

cordless v0.7: Attention State — Know Which of Your 8 Agent Sessions Needs You

Naveen Gopalakrishna — Sat, 11 Jul 2026 18:26:03 +0000

TL;DR — cordless is a CLI-first tool that manages your remote terminal / coding-agent sessions and puts them on your phone. v0.7 adds the thing that actually matters when you're juggling many agents: per-session attention state. The daemon watches each session's output and infers whether it's working, idle, or waiting for you — then badges it, sorts attention-first, and can push a notification (ntfy / webhook) so you get pinged instead of babysitting. Also new: scrollback search, copy last output, and named workspaces. Designed with GPT-5.6 Sol, built with GitHub Copilot CLI.

Here's the real problem with running eight coding agents at once: they keep stopping to ask you things. "Apply these edits? (y/n)". "Run the tests?". One finishes; another hits an error; a third is still churning. You can't watch eight terminals. So you tab through them, and half the time you're staring at a session that's happily working while another has been blocked on a yes/no for four minutes.

v0.7 is my answer to that.

Attention state

cordless now tracks, for every session, two things:

activity — working, idle, or exited
attention — waiting (a prompt), bell, finished, or nothing

The daemon infers this purely from the session's PTY output — no shell integration, no hooks required. In the dashboard, sessions are badged and sorted attention-first, so the one that needs you floats to the top with a !:

── Sessions (3) ──  1 need attention
▸ ! claude  review PR #1284            waiting
      Apply these edits to src/api? (y/n):
  ○ codex   codex ~/src/api            idle
  ○ shell   tests ~/src/app            idle

Press c to mark it handled; sending input clears it automatically (answering is handling it). On the phone you get the same badges. cordless sessions --attention lists just the ones asking for you.

The hard part: what counts as "waiting"?

This is where I leaned on Sol the most, because naive detection is a false-positive machine. A silent build looks "stuck". A shell sitting at its prompt looks "ready" but isn't asking anything. vim and htop repaint constantly. The rules we landed on are deliberately conservative:

A trailing shell prompt ($, #, >, ❯) is readiness, not attention. Never notify on it.
A silent session is idle, not waiting — a paused agent, a long build, and a sleeping process all look the same, so we don't guess.
We only raise waiting on high-confidence confirmation/agent prompts — (y/n), "Continue?", "Do you want me to…?", "Enter your password:" — matched against the last non-empty line after a short quiet window.
Alternate-screen apps (vim/htop/less) suppress prompt heuristics entirely — better to miss a full-screen prompt than to cry wolf.
BEL (^G) is an explicit signal, so it's trusted — but ignored during a session's first few seconds and right after a keypress (startup and invalid-key beeps).
finished is heuristic and scoped to claude/codex: back at a shell prompt after real activity. It's labelled low-confidence and can be turned off.

The whole classifier is a pure, unit-tested module — 41 fixture checks across shells, pagers, and Claude/Codex-style prompts. And QA earned its keep: I caught a bug where a prompt appearing within two seconds of a keypress was silently dropped (the input-grace guard also skipped the whole quiet cycle). A cross-platform live test now locks that path shut.

Get pinged — without any cloud

Badges are great when you're looking. When you're not, v0.7 can notify you. Point it at an ntfy topic (the ntfy phone app pushes it) or a generic webhook (Slack/Discord/automation) in config.json, and cordless POSTs when a session transitions to waiting / bell / finished. cordless notify test validates it.

cordless owns no cloud for this, and the anti-spam is strict (Sol was insistent): one notification per state revision, a 60-second per-session cooldown, a 5-per-minute global cap, optional quiet hours, and no terminal output in the payload by default (it can contain code or secrets). Topic and webhook URLs are treated as secrets and never logged. Delivery is async with a short timeout — a broken webhook can never stall your terminal.

Three more coder niceties

Copy last output: cordless output <id> --lines 50 --copy grabs a session's recent output to your clipboard (cross-platform).
Scrollback search: cordless search <id> "TypeError" scans a session's retained buffer.
Workspaces: cordless workspace save api-feature snapshots your running sessions (profile + cwd + title); cordless workspace open api-feature relaunches the whole layout — "Claude on api, Codex on web, a tests shell" — in one command.

How it was built

Same loop, sharpened: me on GitHub Copilot CLI, Sol as the design partner — and this sprint I kept it honest about version control. Each feature was built on its own branch (feature/attention-state, feature/notifications, feature/output-search, feature/workspaces), tested, and merged as a unit. The daemon's test harness grew to 16 suites — pure attention heuristics, live prompt/idle detection, notifier anti-spam + delivery (injected fetch, no network), scrollback, workspaces, plus the existing protocol/security/restore coverage — and CI runs all of it on Windows and Linux, then builds and smoke-tests the self-contained binary.

The good

The feeling I was after: glance at cordless (in the terminal or on my phone) and instantly know which agent needs me — not by tabbing through eight sessions, but because the one waiting is at the top with a ! and, if I've wandered off, my phone buzzed. Everything else — search, copy, workspaces — is in service of the same thing: running a lot of agents without drowning in them.

Try it

▶️ Live / docs: naveenneog.github.io/cordless
💻 cordless CLI (Windows / Linux, no Node needed): github.com/naveenneog/cordless/releases/latest
📦 Android APK: github.com/naveenneog/cordless/releases/latest
🧑‍💻 Source: github.com/naveenneog/cordless

Part of the #AI4Good series. Built one day at a time. — @naveenneog

cordless v0.6: Going CLI-First — Run It, Scan the QR, You're Paired

Naveen Gopalakrishna — Sat, 11 Jul 2026 17:17:06 +0000

TL;DR — cordless manages your remote terminal / coding-agent (Claude Code, Codex) sessions and puts them on your phone. v0.6 makes it CLI-first: run cordless and it opens a full-screen terminal dashboard whose starting screen shows a live pairing QR — scan it, done. No separate cordless pair, no GUI to babysit. And it now ships as one self-contained binary (its own Node runtime and node-pty baked in), so there's nothing to install first. Designed in a running debate with GPT-5.6 Sol, built with GitHub Copilot CLI.

Every version so far treated cordless as "a daemon plus a phone app." Then the owner said something that reframed the whole thing:

"cordless should be a **CLI first. Look at the design of a terminal app and get the features from that. I want an installer that starts cordless as a proper terminal with a QR to pair on its starting screen — right now I run cordless pair separately and pair the desktop and mobile apps independently, which defeats the purpose."

That's a redesign, not a tweak. So I opened a long debate with Sol and rebuilt the front door.

cordless is the terminal now

Run cordless with no arguments and you get the screen on that card: a brand banner, daemon + Tailscale status, your session list, and — front and center — a single-use pairing QR with a countdown. Scan it with the phone app and you're paired. Press p for a fresh code. No second command, no separate terminal.

Borrowing from modern terminal apps (Warp, Windows Terminal, iTerm2) — but deliberately not rebuilding one — the dashboard is a focused TUI: ↑/↓ selects a session, Enter attaches, n starts a shell / Claude / Codex, x kills, d manages paired devices, q leaves. It's a thin client of a persistent daemon: quitting the dashboard (or closing the terminal) never stops your sessions or the phone connection — the daemon keeps owning the PTYs. Sol was firm on that boundary, and it's the right one.

Attach right there in your terminal

Enter (or cordless attach <id>) streams a session straight into your host terminal — no xterm.js, no second renderer. Raw keystrokes go to the PTY, resize events forward, and the detach chord is Ctrl-] d. It's a tiny tmux-like attach that reuses the exact replay/snapshot protocol the phone uses. The host terminal is the renderer; cordless just pipes bytes.

Pairing is daemon-owned now

The old cordless pair minted a secret by writing a file directly. Sol flagged that: two processes minting into the same store invites races and inconsistent limits. So in v0.6 there's one authenticated pairing.create over the WebSocket, and it can only be called by a loopback-scoped credential from a real loopback socket — the local machine's owner, never a remote phone. It's single-use, 256-bit, five-minute TTL, rate-limited, and capped. Both the dashboard and cordless pair call the same path. A stolen phone token can't enroll new devices; only you, at the machine, can.

One binary, no Node required

The biggest ask hiding in "an installer that just works" is: don't make me install Node first. So v0.6 ships a self-contained executable built with Node's Single Executable Application support:

esbuild bundles the whole CLI into one file (with node-pty marked external).
Node generates a SEA blob from that bundle.
The blob is injected into a copy of the Node runtime → cordless.exe.
node-pty and the built web client ship beside the exe under resources/, and a small loader resolves the native module from there.

The trick that made it painless: node-pty ships node-api prebuilds, which are ABI-stable across Node versions — so there's no fragile per-version native rebuild. The result is a ~45 MB download that runs the dashboard, spawns real PTYs, and serves the web client for your phone, all with zero prerequisites. CI builds and smoke-tests it (start → spawn a PTY → stop) on Windows and Linux; macOS is built the same way but still has a runner-specific node-pty spawn quirk I'm chasing, so it's flagged as pending for now.

How it was built

The same loop as the whole project — me on GitHub Copilot CLI, Sol as the design partner — but this time the pivot leaned hard on Sol's judgment: run the daemon in-process or as a persistent service? (service). How interactive should the TUI be for v0.6? (dashboard + minimal attach, not a pane framework). pkg or Node SEA? (SEA, with node-pty external). Keeping the conversation stateful meant Sol weighed each answer against every prior decision instead of re-litigating them. Ten test suites — protocol E2E, security headers, loopback-scope enforcement, daemon-owned pairing, the CLI client, dashboard rendering, and restore-across-restart — stay green on every push.

The good

The onboarding is finally one motion: install cordless, run it, scan the QR. No Node, no npm install -g, no separate pairing step, no GUI to keep open. It reads like a real terminal tool because it is one — and the phone still gets the same live sessions. Turning a "daemon + app" into "a command you run" is exactly the kind of course-correction that only lands when you actually live with the thing.

Try it

▶️ Live / docs: naveenneog.github.io/cordless
💻 cordless CLI (Windows / Linux, no Node needed): github.com/naveenneog/cordless/releases/latest
📦 Android APK: github.com/naveenneog/cordless/releases/latest
🧑‍💻 Source: github.com/naveenneog/cordless

Part of the #AI4Good series. Built one day at a time. — @naveenneog

cordless v0.5: A Desktop App, a >_< Logo, and QR-First Security

Naveen Gopalakrishna — Sat, 11 Jul 2026 09:14:05 +0000

TL;DR — cordless manages many remote terminal / coding-agent (Claude Code, Codex) sessions like browser tabs, with sessions that survive disconnects. v0.5 adds a hardened Electron desktop app (Windows .exe, macOS .dmg, Linux .AppImage/.deb), a proper >_< brand logo made with gpt-image-2, and a security course-correction: QR pairing stays the only default way in, and the desktop's one-click "Connect to this computer" uses a loopback-only credential that a Tailscale or LAN address is rejected for. As always — designed with GPT-5.6 Sol, driven with GitHub Copilot CLI.

_< logo">

I shipped cordless, then made it livable in v0.4 — seamless resume, an in-app QR scanner, no more truncation. v0.5 is about the two things a "real" tool needs that a phone app alone can't give you: a proper desktop experience, and an identity. And it's where a security instinct paid off.

A face for the project: the `>_<` logo

cordless needed a mark. I generated one with gpt-image-2 on my Azure AI Foundry deployment — a small Python script (tooling/gen_logo.py) that POSTs a prompt and writes back the base64 PNG. After iterating on a few concepts, the winner was almost too obvious: >_< — a shell prompt >_ that doubles as a happy little face — set in a blue→violet gradient inside a terminal-window frame.

One gotcha worth remembering: gpt-image-2 won't render a transparent background (you get an HTTP 400 if you ask). So I generated the mark on a dark background and luminance-keyed it transparent with Pillow (tooling/apply_logo.py) — the same script then resizes it into every size the project needs: PWA icons (icon-192/512, a maskable variant, apple-touch, favicons), the landing-page hero, and the full set of Android launcher / adaptive-icon / splash assets.

A subtle bug fell out of this: the repo's .gitignore had a blanket *.png rule (to keep Playwright screenshots out), and it was silently swallowing the new app icons. The APK and PWA would have shipped with missing icons. Two lines fixed it — !client/public/*.png, !desktop/build/*.png — a good reminder to always check git status after adding binary assets.

The desktop app — a hardened Electron shell

The headline feature. When you're at your dev box (or remoted into it), a phone is the wrong tool — you want a real window with a real keyboard. So v0.5 ships a desktop app for Windows, macOS, and Linux.

I designed the architecture in my running conversation with Sol, and we landed on the pragmatic choice: the Electron window loads the daemon's own served page at http://127.0.0.1:<port>. Because it's same-origin to the daemon, there are zero CORS/CSP changes — it's the exact same UI, sessions, tabs, and replay you already have, just in a window.

The interesting part is the security hardening, straight from Sol's review:

contextIsolation: true, nodeIntegration: false, sandbox: true, webSecurity: true.
Navigation is pinned to the trusted loopback origin — will-navigate and setWindowOpenHandler reject anything else; all new windows, <webview>s, and permission requests (camera, mic, geolocation…) are denied.
The renderer gets a tiny preload bridge and nothing else: { platform, getLocalCredential, startDaemon, retry }. No fs, no shell, no openExternal.
Every IPC call validates that the sender is one of our own trusted pages. startDaemon accepts no path, command, or argument from the page — it resolves the installed CLI itself.
If the daemon isn't running, the app shows a Start daemon / Retry screen instead of a blank window.
The port is resolved with a strict precedence — the credential's server, then the daemon config, then 7443 — and every candidate is validated to be loopback http (no https, no userinfo, no path, no localhost name ambiguity).

That last bit of parsing is security-critical, so I pulled it into a pure module (desktop/lib/resolve.js) and wrote 24 unit tests for it. It runs in CI on every push.

QR-first security — the course-correction that mattered

Here's the moment I'm most glad about. While wiring the desktop app, I built a convenient "auto-connect on localhost" path. It worked. It was also wrong — it quietly bypassed pairing. The rule for cordless is: QR / pairing-code is the one true way in.

So I tore the auto-connect out and rebuilt it as an explicit, opt-in button. The daemon now writes a desktop-credential.json (mode 0600; it stores only the token's hash) tied to a device with scope: "loopback". The authenticate() path accepts that token only when the socket peer is 127.0.0.1 / ::1 — checked against the real socket address, never a spoofable header. A Tailscale 100.x or LAN address is rejected outright. In the UI, the 🖥️ Connect to this computer button only appears when the Electron bridge actually hands over a credential; open the same page in a plain browser and you see QR/code only.

I verified it with a test that asserts exactly this: loopback IPs authenticate, and 100.64.x.x (Tailscale's range) does not. It's a local convenience that is structurally incapable of being a remote bypass.

ok    ip=127.0.0.1        authed=true   (expected true)
ok    ip=::1              authed=true   (expected true)
ok    ip=203.0.113.5      authed=false  (expected false)
ok    ip=100.64.1.2       authed=false  (expected false)   <- Tailscale, still rejected
=== LOOPBACK-SCOPE ENFORCEMENT PASS ===

Prerequisites & Tailscale, documented properly

A fair complaint about the earlier docs: the prerequisites and Tailscale setup weren't written down clearly. Fixed. The README and landing page now spell out, with Sol's help:

Prerequisites — Node.js 22, the platform build tools node-pty needs, Tailscale, and (on Windows) PowerShell 7, with download links.
Tailscale setup — tailscale up / status / ip -4, an optional device tag, a copy-pasteable tailnet ACL that locks TCP 7443 to your own identity, and a Windows Firewall rule that only opens 7443 on the Tailscale adapter (100.64.0.0/10).
Resume your sessions — cordless install once, then open the desktop app or http://localhost:7443; your tabs reattach, and after a reboot the daemon reopens them from its restore manifest.

How it was built

Same loop as the whole project: me on GitHub Copilot CLI, Sol as the design partner and reviewer — and this time I kept the conversation stateful, so Sol remembered every prior decision instead of re-litigating them. The desktop architecture, the Electron hardening checklist, and the loopback-credential rules all came out of that back-and-forth. CI does the heavy lifting: pushing a v* tag builds the Android APK and the three desktop installers on native GitHub runners and attaches them to the release. And npm test is now a self-contained harness that boots an isolated daemon and runs every suite — protocol E2E, security headers, the new desktop-credential + loopback-scope checks, and session-restore across a daemon restart. Seven suites, green.

The good

v0.5 is the version where cordless stopped feeling like a phone experiment and started feeling like a product: it has a name and a face, it runs as a real desktop app, and — the part I care about most — the convenience features were built without weakening the security model. The one-click local connect is genuinely handy, and it cannot be turned into a remote hole. That's the bar.

Try it

▶️ Live / install the PWA: naveenneog.github.io/cordless
🖥️ Desktop app (Win/macOS/Linux): github.com/naveenneog/cordless/releases/latest
📦 Android APK: github.com/naveenneog/cordless/releases/latest
💻 Source: github.com/naveenneog/cordless

Part of the #AI4Good series. Built one day at a time. — @naveenneog