DEV Community: Adem İşler

How RunOnMine Puts a Local Policy Boundary Between AI Agents and Your Machine

Adem İşler — Sun, 09 Aug 2026 17:29:57 +0000

AI agents have a boundary problem that becomes more visible as soon as they can touch a real machine.

Keep the model inside a chat box and the boundary is simple, but the workflow is limited.

Give the model access to files, a terminal, a browser and desktop automation and the workflow becomes much more useful — but a raw shell or broad credential can turn the entire operating-system account into one permission.

That creates a practical trade-off:

capability or control.

I wanted to see whether machine access could stay useful without making account-level authority the default interface.

That became RunOnMine, an open-source, local-first MCP security gateway for controlled AI access to files, terminals, browsers and desktop apps.

Repository: https://github.com/ademisler/RunOnMine

The first public beta is available for macOS, Windows and Linux.

This article is about the architecture behind the boundary, the failure modes I wanted to avoid, and why I do not describe RunOnMine as a sandbox.

The product boundary

RunOnMine is not a collection of MCP tools with a permission dialog added later.

The permission boundary is the product.

A request should not become executable just because an authenticated client knows the name of a tool.

The system needs to answer several questions together:

Which connector delivered the request?
Which requester is behind that connector?
Which tool is being called?
Which resource is being targeted?
What does the machine owner's local policy say?
Does this exact action require approval?

The simplified flow is:

AI request
    |
    v
requester + connector identity
    |
    v
local resource policy
    |
    +---- allow ----> execute
    |
    +---- ask ------> local approval ----> execute / deny
    |
    +---- deny --------------------------> stop

The important detail is where the decision happens.

It happens on the machine being controlled.

Remote authentication can narrow authority, but it does not get to expand local policy.

A tool name is not an authorization decision

Consider a filesystem write.

fs_write tells us what class of operation is requested. It does not tell us whether the request should be allowed.

The authorization decision also depends on the path, the requester, the connector and the exact action.

The same is true for shell execution.

git status inside one selected repository and a destructive command from a remote connector should not collapse into the same boolean permission just because both use shell_exec.

This is why RunOnMine separates tool capability from local authorization.

Selected roots instead of account-wide filesystem access

A coding agent usually does not need my entire home directory.

It may need one repository.

RunOnMine asks the owner to select filesystem roots and keeps file operations inside those roots. The implementation uses capability-oriented, descriptor-relative operations and rejects paths that escape the configured boundary.

This changes the failure surface.

A prompt mistake or prompt injection inside one project should not automatically turn into visibility over unrelated repositories, SSH material, browser state and personal documents simply because the process happens to run as the same OS user.

The rule I wanted was simple:

grant the project, not the account.

Approval should be about the action, not the button

Human-in-the-loop security becomes weak if approval means "trust this tool forever".

An owner needs to understand what is about to happen.

RunOnMine binds approval to the requester and the concrete action context. If the meaningful action changes, the previous approval should not silently become permission for the new one.

Approval is also local-only.

There is no MCP tool called approve_my_request that a remote agent can invoke after asking for something dangerous.

That sounds obvious when written down, but keeping the approval authority outside the remote tool surface is an important part of the design.

Shell execution is not a sandbox

This is the limitation I care most about stating clearly.

If a shell command is permitted, it runs with the authority of the RunOnMine operating-system account.

RunOnMine can decide whether a request reaches execution. It can scope the working directory, bind the decision to the requester, require approval, bound retained output and terminate a process tree on timeout.

It cannot turn an arbitrary permitted command into harmless code.

That is why the project calls itself a security gateway and approval system rather than a sandbox.

The optional privileged helper is a separate installation boundary. It is not installed by normal setup, and remote connectors do not receive administrator execution through the standard policy profiles.

Browser control adds a network boundary

A separate browser profile is useful, but it is not the whole browser security problem.

If a remotely driven browser can freely reach localhost or private networks, the browser itself can become a bridge to services the external requester could not otherwise reach.

RunOnMine's protected browser path therefore treats destination access as part of the policy boundary.

The browser uses an isolated profile and protected network behavior. The implementation checks destinations and uses a controlled proxy path for protected automation rather than assuming profile isolation solves private-network access.

This is also why attaching to an arbitrary existing browser through CDP is a different trust decision: launch-time protections cannot be retroactively applied to a process that was started outside that boundary.

Remote access without a raw public MCP listener

I did not want "use this remotely" to mean "bind the MCP server to 0.0.0.0".

RunOnMine keeps its HTTP MCP listener on loopback.

Remote connectivity is carried outward through supported connector/tunnel models. The current beta supports local stdio, opt-in authenticated loopback HTTP, Cloudflare connector modes and OpenAI Secure MCP Tunnel integration.

The network transport still does not become the policy authority.

Remote callers remain subject to local policy. Dangerous remote actions cannot approve themselves, and remote administrator execution is denied by the safety ceiling.

Emergency Lock is different from uninstall

A system that can perform real machine actions needs a cheap revocation path.

The owner should not have to delete configuration or dismantle the installation to say "stop now".

RunOnMine has an Emergency Lock operation for that purpose.

It stops the active agent/connectors, rejects pending approvals, removes temporary grants, revokes relevant OAuth state and invalidates temporary credentials used by supported connector paths.

The local configuration remains, so the owner can inspect and recover deliberately later.

That distinction matters:

revocation is a runtime operation, not an uninstall workflow.

Audit should not become a second secret store

Machine automation needs an audit trail.

But logging everything naively can create a new security problem.

Raw command payloads, credentials, URLs and machine paths can contain sensitive data. A debug bundle that simply archives an application state directory is easy to create and difficult to trust.

RunOnMine keeps a tamper-evident audit chain while avoiding raw secret storage in audit records. Support material is built from bounded, redacted diagnostics instead of blindly copying internal state.

The audit trail is not meant to make a compromised user account tamper-proof. It is meant to make normal machine actions and unsophisticated modification visible without turning observability into another credential leak.

Release engineering is part of the boundary

Security claims are difficult to reason about when the tested source and the downloadable artifact are ambiguous.

For the public beta I wanted release evidence tied to an exact candidate.

The repository records the frozen source candidate and release gates in machine-readable files. Platform acceptance evidence names the source revision and artifact hashes. The release also includes SHA-256 checksums and target-specific CycloneDX SBOMs.

That does not replace code signing or an external review.

It makes the beta evidence inspectable.

What the beta does not claim

RunOnMine is prerelease software.

The current beta has intentionally visible limitations:

macOS is ad-hoc signed, not Developer ID signed/notarized
the Windows installer is not Authenticode signed
an independent external security review is still pending

Those gaps are documented because a security-oriented tool should not hide its own distribution trust limitations.

Public beta

RunOnMine v0.1.0-beta.1 is available for macOS, Windows and Linux.

It is written in Rust and licensed under Apache-2.0.

GitHub: https://github.com/ademisler/RunOnMine

Website: https://runonmine.github.io/

The main lesson from building it is that giving an agent more tools is the easy part.

The harder question is deciding where automation ends and owner authority begins.

For people building or using MCP agents: which machine actions would you allow automatically, and which would you never allow without an exact local approval?

How Myna Player Generates Context-Aware Subtitles Ahead of Playback

Adem İşler — Sat, 01 Aug 2026 23:44:40 +0000

Subtitles have a timing problem that becomes more visible when AI translation enters the pipeline.

Translate every tiny fragment immediately and the text may arrive on time, but important context disappears. Wait for a longer passage and the translation becomes more coherent, but the subtitle may appear after the dialogue has already passed.

That creates a practical tradeoff:

speed or context.

I wanted to see whether a media player could avoid making that choice at playback time.

That became Myna Player, an open-source, local-first AI video player that processes audio ahead of the current playback position, transcribes it locally, translates finalized subtitle cues with surrounding context, and renders them against the native player clock.

Myna Player is currently a public alpha. The core macOS application works, Windows code and packaging are under active verification, and the first stable public release has not been published yet.

This article explains the architecture, the subtitle timing contract, and why processing ahead of playback changes the problem.

The product boundary

Myna Player is not a general-purpose transcription editor with a video preview attached.

It is a media player with a just-in-time subtitle pipeline.

That distinction affects the architecture.

The system must keep several things true at the same time:

playback remains responsive;
transcription stays ahead of the viewer;
seeking does not corrupt old work;
completed subtitle work can resume later;
translation receives enough context;
translated cues keep the original timing;
local media and audio remain on the device;
the renderer never waits for an AI request.

The simplified flow is:

native player clock
        |
        v
persistent priority scheduler
        |
        v
FFmpeg audio windows
        |
        v
local Whisper worker + VAD
        |
        v
timed source subtitle cues
        |
        +--------------------+
        |                    |
        v                    v
local source cache     optional translation workers
        |                    |
        +----------+---------+
                   |
                   v
       synchronized subtitle renderer

The key idea is that the expensive work happens outside the playback loop.

Why listening to system audio would be the wrong abstraction

A live-caption application often listens to whatever audio is currently being played.

That is useful when the source is unknown or truly live.

Myna Player works with local media files. It can read the source directly.

That means it does not need to wait for sound to leave the speakers before analyzing it. It can extract audio from later sections of the file and prepare subtitles before playback reaches them.

Direct file access provides several advantages:

deterministic time ranges;
repeatable extraction;
precise stream selection;
the ability to jump ahead;
resumable cached work;
no dependency on system-audio capture permissions;
no feedback from notification sounds or other applications.

The media file itself becomes the source of truth.

The processing unit is a canonical time window

Myna Player schedules deterministic, non-overlapping audio windows.

The current design uses canonical 30-second ranges.

Conceptually:

00:00–00:30
00:30–01:00
01:00–01:30
01:30–02:00
...

Canonical windows are important because they give the cache stable identities.

If the same video is reopened, the application can determine exactly which regions were completed. If the user seeks, already finished windows do not have to be transcribed again.

The scheduler assigns priority according to playback position:

the first required window is urgent;
roughly the next 90 seconds are promoted;
later windows remain background work.

The result is not simply “transcribe the entire file as fast as possible.”

It is:

Keep the region the viewer is about to reach prepared, while using spare capacity to extend the cache farther into the video.

Media fingerprints and pipeline keys

A file path alone is not a safe cache key.

The media may change. The selected audio stream may change. The speech model, language mode, VAD model, chunk size, or cue-segmentation rules may change.

Myna Player creates a media fingerprint and combines it with a pipeline key that includes inputs such as:

selected audio stream;
Whisper runtime and model hash;
transcription language mode;
VAD model;
chunk and extraction parameters;
cue-segmentation version.

Only checkpoints with an exactly matching key are restored.

This prevents a subtle class of bugs where old subtitle data appears valid even though it was produced by a different pipeline configuration.

A cache should not merely remember that work happened. It should remember which work happened under which assumptions.

Seeking requires generations, not only cancellation

A viewer may seek from minute 3 to minute 48 while transcription is processing minute 4.

The current worker needs to stop, but cancellation alone is not sufficient.

A slow process may still return after the seek. If its result is accepted blindly, stale cues from the previous playback region can overwrite or pollute the new session.

Myna Player increments a processing generation when the active region changes.

The seek flow is conceptually:

cancel the active ASR and translation connection;
increment the generation;
preserve completed cache entries;
promote the newly requested region;
reject late results from older generations.

Generations turn cancellation into a verifiable contract.

The system does not have to assume that every subprocess stopped instantly. It can recognize that an old result belongs to an obsolete plan.

Extracting audio with context

Each canonical window is expanded slightly during extraction.

Myna Player reads approximately two seconds of neighboring audio context around the canonical range and converts it to:

mono
16 kHz
signed 16-bit PCM

The context helps speech recognition around boundaries, but the persisted output still belongs to the canonical time range.

This is a common pattern in stream processing:

read overlapping input for better local decisions;
write non-overlapping canonical output for deterministic storage.

Without boundary context, words split across windows can be lost or duplicated. Without canonical output boundaries, overlapping windows can produce conflicting cues.

A long-lived local Whisper worker

Starting a speech-recognition process for every 30-second segment would add significant overhead.

Myna Player uses a long-lived local whisper.cpp worker.

The worker:

binds only to a random 127.0.0.1 port;
loads the selected model once;
accepts extracted audio windows;
can apply Silero voice activity detection;
returns word-level timestamps;
is terminated on cancellation or application shutdown.

Word timestamps are essential because the language model should not invent the subtitle timing.

The transcription layer produces timed words. A deterministic segmentation stage then converts those words into readable, non-overlapping subtitle cues.

That separation lets the system improve visual subtitle grouping without asking the translation provider to decide when a cue should appear.

Voice activity detection reduces wasted work

A 30-second media window may contain music, silence, or non-speech sound.

Optional Silero VAD identifies speech regions before transcription.

That can reduce unnecessary inference and avoid producing unstable text from silence or background audio.

VAD is part of the pipeline fingerprint because changing the speech-region detector can change the resulting transcript and cue boundaries.

Again, the cache key must represent the actual computation, not only the source file.

Persisting source cues transactionally

After a source window is transcribed and segmented, Myna Player stores the source cues and marks the checkpoint complete in the same SQLite transaction.

This prevents a failure state such as:

checkpoint says complete;
subtitle rows were only partially written.

Or the reverse:

subtitle rows exist;
checkpoint still says incomplete;
the application repeats the work and creates overlap.

The storage layer uses SQLite with WAL mode and versioned migrations.

The database contains local information such as:

media fingerprints;
playback position;
processing checkpoints;
source transcript segments;
provider-specific translations;
model metadata;
user corrections.

Persistent storage is what turns the look-ahead pipeline from a temporary live effect into resumable product behavior.

Transcription and translation are separate workers

Translation should not block source transcription.

Myna Player runs ASR and cloud translation as independent scheduling lanes.

The source pipeline can continue preparing timed cues while the translation worker processes bounded groups of completed cues.

This matters because cloud providers have variable latency. A slow translation response should not stop the application from building the source-language cache.

It also means a user can switch translation providers or target languages without retranscribing the media.

Source text and provider-specific translations are stored separately.

The structure is conceptually:

source cue
  ├── DeepL / French
  ├── Gemini / Turkish
  ├── OpenAI / English
  └── MiniMax / German

The source timing remains the shared foundation.

The translation contract: context may change words, not time

This is the central rule of the translation layer.

A translation provider receives:

a bounded batch of finalized cues;
stable cue IDs;
limited previous-dialogue context;
the requested target language;
instructions to return every requested cue exactly once.

The provider may improve wording using context.

It may not:

merge cue IDs;
split one cue into new IDs;
reorder cues;
omit cues;
duplicate cues;
invent timestamps;
change the source timing.

Responses are validated before persistence.

Missing, duplicate, unknown, or reordered IDs are rejected.

This creates a useful division of responsibility:

Layer	Responsibility
ASR	Recognize words and timestamps
Cue segmentation	Create readable timed source units
Translation	Produce context-aware text for those units
Player clock	Decide which cue is visible now

The language model handles language. Deterministic code handles time.

Why surrounding context still matters

A subtitle cue is often too small to translate correctly in isolation.

Pronouns, formality, verb tense, gender, idioms, and ambiguous words may depend on previous dialogue.

Sending the entire film for every request would be expensive, slow, and unnecessary.

Myna Player sends bounded prior dialogue context with the active batch.

The contextual text helps the provider interpret the current lines, but only the requested cue IDs are accepted as output.

This separates context for understanding from scope for mutation.

The provider can read more than it is allowed to rewrite.

That is a useful pattern beyond subtitles. AI systems often benefit from broad context while still needing narrow, validated output boundaries.

Source edits invalidate translations

Users can correct subtitle text and timing.

When the source text of a cue changes, every provider translation derived from the old text becomes stale.

Myna Player invalidates those translations rather than silently continuing to display them.

Source and translated data therefore have an explicit dependency relationship.

A correction is not just a visual edit. It changes the input to downstream language processing.

Incremental updates over Tauri Channels

The UI does not reload the entire subtitle set every time a worker finishes a window.

The backend sends:

one full initial snapshot;
ordered incremental cue patches.

These updates travel through Tauri Channels.

Ordering matters because source cues, translations, corrections, and invalidations may arrive from different workers.

The frontend applies a known sequence of patches instead of trying to reconstruct state from unordered events.

This keeps the WebView focused on presentation while the native backend owns persistence and pipeline state.

Rendering against a native player clock

The subtitle renderer does not call Whisper or a translation API.

It reads already cached cues and compares them to a player clock updated at roughly 100 ms intervals.

Cue lookup uses binary search rather than scanning every subtitle on every tick.

This provides a strict runtime rule:

Playback rendering must remain deterministic even when background AI work is slow, offline, or failing.

If the next translated cue is not ready, the system can display source text or wait according to the selected mode. It does not freeze playback while waiting for a model.

Native video below a transparent WebView

Myna Player uses Tauri 2 and a Leptos interface compiled to WebAssembly, but video rendering is native.

On macOS, libVLC renders into an application-owned NSView positioned below the transparent Tauri WebView.

The web layer owns controls and generated subtitles. AppKit owns the video surface geometry and updates it during resize and fullscreen transitions.

On Windows, the application creates a child HWND below WebView2 and binds libVLC to that surface.

This composition avoids forcing decoded video frames through the web interface.

It also creates a clear boundary:

native layer: playback, clock, surfaces, media tracks;
web UI: controls, settings, subtitles, progress state;
Rust backend: scheduling, storage, processing, providers.

Unsafe libVLC interaction remains isolated inside a limited player crate.

The Rust workspace follows product boundaries

The repository is split into focused crates:

myna-player-core       domain models and scheduling
myna-player-media      FFprobe and FFmpeg integration
myna-player-player     native libVLC engine
myna-player-jobs       persistent priorities, retry, resume
myna-player-storage    SQLite/WAL and media fingerprints
myna-player-pipeline   ASR, VAD, translation, cue processing
myna-player-providers  provider registry and credentials
src-tauri              desktop composition and IPC
myna-player-ui         Leptos/WASM interface

The separation is not only organizational.

It helps keep several risky concerns from leaking into each other:

shell process execution stays in media and pipeline boundaries;
unsafe player calls stay in the player layer;
credentials stay behind the provider boundary;
persistent scheduling stays independent from UI state;
serializable domain types remain usable in tests.

Local-first privacy

The following operations run on the user's computer:

FFprobe media inspection;
FFmpeg audio extraction;
voice activity detection;
whisper.cpp speech recognition;
subtitle timing and segmentation;
playback;
editing and export;
caching and checkpoint management.

Cloud translation is opt-in.

When enabled, the provider receives finalized transcript text and limited neighboring context. It does not receive the video file or extracted audio.

Provider credentials are stored through the operating system credential store and are never returned to the web UI.

The local Whisper worker binds only to localhost, and diagnostic logs are bounded and redact home-directory paths.

Local-first does not mean every optional feature is offline. It means the user can understand and control which data crosses the device boundary.

Per-video deletion

Generated data is grouped under the media fingerprint.

SQLite foreign keys use cascading deletion so a video can be reset atomically from the application's point of view.

Reset this video:

cancels the active ASR and translation generation;
pauses playback and seeks to the beginning;
deletes checkpoints, transcripts, translations, cache, and remembered position;
recreates only the open-media identity;
leaves global settings, installed models, and credentials intact.

This is another place where product wording matters.

“Clear cache” is too vague. A user should know whether a reset deletes subtitle history, corrections, translations, or provider credentials.

Packaging AI runtimes is part of the application

A local-first desktop AI product is not complete when it builds on the developer's machine.

Myna Player needs native runtimes and models such as:

VLC and plugins;
FFmpeg and FFprobe;
whisper.cpp;
optional Silero VAD data;
Whisper model files.

The packaging scripts download or build pinned components, verify SHA-256 checksums, stage required licenses, and create native bundles.

Models are activated only after expected size and checksum verification.

The release workflow is designed to:

build on clean macOS and Windows runners;
verify packaged runtimes;
exercise native playback smoke tests;
sign nested binaries;
notarize macOS artifacts;
verify Windows signatures;
publish checksums.

The project is not marked release-verified until those workflows pass with the required signing configuration.

That conservative status is intentional. A successful development build is not the same as a trustworthy public installer.

Export and interoperability

Myna Player can export:

source subtitles;
translated subtitles;
dual-language subtitles;
SRT;
VTT.

The generated subtitles are not trapped inside the application.

Export is useful for users, but it is also a debugging tool. A persisted subtitle file makes it easier to inspect cue boundaries, timing drift, translation consistency, and corrections outside the player.

What I learned

1. Processing ahead changes the latency budget

The system does not need every AI operation to be faster than human speech. It needs the prepared region to remain ahead of the playback clock.

That turns the problem from instantaneous inference into scheduling.

2. Context and timing should belong to different layers

Translation needs surrounding dialogue. Timing should remain deterministic. Stable cue IDs create the boundary between them.

3. Cancellation needs versioned state

Generation numbers make late worker results rejectable. Without them, a seek can create subtle stale-data races.

4. Cache validity depends on the complete pipeline

A transcript produced with another model, language mode, VAD configuration, or segmentation version is not necessarily reusable.

5. AI must not enter the render loop

The player should remain responsive even when models are slow, credentials are missing, or the network is unavailable.

6. Packaging is an engineering domain of its own

Bundling VLC, FFmpeg, Whisper, models, licenses, signatures, and platform-specific surfaces required as much architectural attention as the subtitle pipeline.

7. Local-first is a data-flow promise

It is not enough to say “privacy focused.” The product must document which operations are local, what optional text leaves the device, where credentials live, and how generated data can be deleted.

Current status

Myna Player is open source under GPL-3.0-or-later and remains in public alpha.

The core macOS experience is integrated. Windows playback and packaging code exists and is being verified through clean-runner workflows. Signed public alpha artifacts and broader clean-machine smoke tests remain release milestones.

The repository includes architecture, privacy, security, contribution, packaging, release, and third-party licensing documentation.

ademisler / Myna-Player

Open-source, local-first AI video player for ahead-of-playback transcription, contextual translation, and precisely timed subtitles.

Myna Player

Watch in any language.

A local-first, open-source AI video player that transcribes ahead, translates with context, and displays each subtitle at the right moment

Website · Architecture · Roadmap · Contributing · Security

Project status

Myna Player is a public alpha. The core macOS application works, Windows code and packaging are under active verification, and the first stable public release has not been published yet. Expect interface, storage, and packaging changes before 1.0.

The repository is open for review and contribution. Please read CONTRIBUTING.md before proposing substantial changes.

Why Myna Player exists

Live subtitle systems often choose between speed and coherence. Translating tiny fragments quickly loses context; translating long blocks makes subtitles arrive late. Myna Player separates those concerns:

it processes audio ahead of playback;
Whisper produces word-level timing locally;
natural subtitle cues are derived from those timestamps;
translation sees surrounding context but may not rewrite cue…

View on GitHub

I would especially value feedback on these areas:

How far ahead of playback should a subtitle pipeline normally process?
Which subtitle segmentation rules produce the best balance between readability and faithful timing?
Should contextual translation include only previous dialogue, or a limited amount of future dialogue as well?
What should a player display when source subtitles are ready but translation is still pending?
Which clean-machine tests would make you trust an alpha desktop AI application?

This is the fifth and final article in this first series documenting the products I have built—from a browser toolbox to local AI desktop systems.

Building a Local-First Quota Monitor and Account Switcher for Codex

Adem İşler — Sat, 01 Aug 2026 23:42:39 +0000

Codex account management looks simple until several accounts have different quota windows, different reset times, and different local session states.

At that point, two questions become surprisingly difficult:

Which account is actually usable right now?
Which account is the local Codex installation currently using?

I originally wanted a small menu-bar utility that could answer those questions without opening dashboards, estimating usage from local activity, or manually replacing authentication files.

That became CodexControl: an open-source, local-first quota monitor and account switcher for Codex on macOS and Windows.

The product intentionally does only two things:

read live Codex quota state;
switch the active local Codex account.

Keeping the scope narrow made the interface simple. The implementation, especially cross-platform switching, was less simple than it first appeared.

Why a quota monitor needs live data

A usage estimate can be useful when an API exposes no authoritative quota information.

Codex already has account state that can be read through the authenticated local session, so I did not want to infer remaining capacity from token counts, request logs, or time spent working.

CodexControl uses each saved account's local authentication state to request live quota information directly.

That matters because an estimate can drift in several ways:

usage may happen from another computer;
background activity may not be visible locally;
different models or operations may consume capacity differently;
the server may adjust or normalize quota state;
cached responses may remain visible after the real window changes.

The app treats the provider response as the source of truth instead of trying to reconstruct it indirectly.

Quota is not a single percentage

A Codex account may expose more than one usage window.

The two windows most important to the app are:

a shorter five-hour window;
a longer seven-day window.

These windows can have very different states.

An account may still have weekly capacity while the short-term window is exhausted. Another account may have a nearly full short-term window but little weekly capacity remaining.

Collapsing both into one number would hide the operational decision the user needs to make.

CodexControl therefore keeps each window independent and shows its own:

remaining or used capacity;
reset time;
current availability;
normalized presentation state.

The app also preserves exact reset timestamps rather than displaying only a vague label such as “resets later.”

Accuracy became a first-order requirement

A quota monitor loses its value quickly if the numbers cannot be trusted.

I added several safeguards around live reads:

cache-bypassing network sessions;
repeated reads with equivalence checks;
rejection of inconsistent responses;
per-window normalization without merging independent values;
clearing stale snapshots after failed refreshes;
token refresh before retrying when required.

The most important principle was this:

A missing value is better than a confident but stale value.

If a refresh fails, continuing to show an old quota without a clear stale state can lead the user to switch to an account that is no longer usable.

The app prefers to expose the failure and request another refresh.

The account list is sorted for action, not decoration

A raw account list sorted alphabetically does not answer the main question.

The user is usually trying to decide which account to activate next.

CodexControl sorts accounts by practical usefulness so that currently usable accounts remain easier to reach. Presentation logic considers live window state, authentication health, and whether the account is active.

The list also supports local management actions:

add an account;
refresh quota;
reauthenticate;
relabel;
remove;
open the account directory;
switch the ambient Codex identity.

Periodic refresh runs every few minutes, but manual refresh remains available when the user needs an immediate answer.

Local accounts are stored as separate Codex homes

Each managed account has its own local Codex home and authentication state.

The ambient ~/.codex directory represents the account currently used by the normal Codex CLI and desktop workflow.

A simplified model is:

managed account A home ─┐
managed account B home ─┼─> CodexControl
managed account C home ─┘
                             |
                             v
                      ambient ~/.codex

Switching means making the selected managed account become the ambient identity.

The exact work required depends on the platform and the current Codex Desktop implementation.

macOS: a native menu-bar workflow

The macOS application is built with SwiftUI and AppKit and lives in the menu bar.

That form factor matches the task:

glance at quota;
choose an account;
switch;
return to work.

There is no need for a large always-open dashboard.

On macOS, the app reads local Codex homes, refreshes account tokens when needed, fetches live quota, replaces the ambient session during a switch, and restarts Codex Desktop so the new identity is applied.

The project includes packaging, signing, notarization, and Homebrew cask support so the utility can behave like a normal desktop application rather than a script collection.

Windows revealed that switching is not one file copy

The first Windows implementation switched accounts by replacing only:

~/.codex/auth.json

That was not enough for current Codex Desktop builds.

The CLI identity could change while the desktop application continued to show a login screen or a stale session.

The reason was that identity existed in multiple state layers.

Layer 1: CLI and global Codex state

The local Codex directory included:

auth.json
.codex-global-state.json
.codex-global-state.json.bak

The global-state files could retain a previous creator_id even after the authentication file changed.

The switch flow therefore needed to rewrite the previous provider account ID with the target account ID in both global-state files.

Layer 2: Codex Desktop MSIX session state

The Windows desktop app also maintained browser and application session state inside its MSIX package cache:

%LOCALAPPDATA%\Packages\OpenAI.Codex_*\LocalCache\Roaming\Codex

Updating the CLI files did not automatically replace this desktop session layer.

The visible symptoms were confusing:

the switch appeared to complete, but the desktop app still displayed the previous identity;
the desktop app reopened at a login screen;
the app terminated but failed to relaunch after a copy error;
a target account had valid CLI authentication but no matching desktop session yet.

Backing up desktop session state per account

The Windows restart flow now treats desktop session state as account-specific data.

During a switch it can:

stop Codex Desktop;
back up the current desktop session into the managed home of the account being left;
update auth.json and global identity state;
restore the target account's saved desktop session when available;
relaunch Codex Desktop.

The backup and restore process operates per entry with logging rather than failing the entire switch on the first copy problem.

There is also an important first-use case.

A target account may not yet have a saved desktop-session snapshot. On the first switch, Codex Desktop may need to reconcile that account's state itself. Once the account has been active and its session has been backed up, later switches can restore it more consistently.

This was the clearest engineering lesson in the project:

Authentication state and application session state are related, but they are not the same thing.

Account identity cannot rely on email alone

Another subtle issue appeared when accounts shared identifying fields.

Using only email or authentication subject as the account key can collapse distinct provider accounts into one row.

CodexControl prefers the provider account ID and uses other fields only as fallbacks.

This matters when:

multiple accounts use the same email address;
an organization changes account metadata;
authentication records are rotated;
old and new managed homes coexist temporarily.

Stable identity should come from the most provider-specific identifier available.

Removed accounts should stay removed

The app discovers managed Codex homes from disk.

That creates a lifecycle problem: deleting an account from the visible list is not enough if an old duplicate home is rediscovered at the next startup.

The removal flow therefore needs to:

record the removed identity;
filter later discovery against removed identities;
remove duplicate managed homes for the same provider account;
avoid recreating an account from stale authentication data.

Deletion is a state-management feature, not merely a UI action.

Recovering from rotated refresh tokens

A user may have multiple local auth homes for the same account, and older homes may contain stale refresh tokens.

A failed refresh does not always mean the account itself is invalid. A newer matching home may contain the current credentials.

The recovery path can search matching local identities and use fresher authentication state before declaring that reauthentication is required.

This avoids forcing the user through login again when valid local credentials already exist.

At the same time, the app stops automatic retry loops for accounts already known to require reauthentication. Manual refresh and reauthentication remain explicit actions.

Cross-platform implementation without pretending the platforms are identical

The project uses different native approaches on each platform:

Platform	Implementation
macOS	SwiftUI and AppKit menu-bar application
Windows	Python tray-first desktop application

It would have been possible to force both platforms into one cross-platform UI framework.

I chose not to make shared UI code a goal by itself.

The shared product behavior is more important:

account discovery;
identity normalization;
live quota reads;
token refresh;
sorting and presentation rules;
switching semantics;
synthetic demo data;
repository hygiene.

Platform-specific session handling remains platform-specific.

This is especially important on Windows, where MSIX package state and restart behavior require code that has no meaningful macOS equivalent.

Local-first does not mean offline

CodexControl is local-first, but it still contacts OpenAI to refresh authenticated quota information.

The distinction is about ownership and storage:

account files stay on the user's computer;
the app reads existing local Codex authentication state;
there is no CodexControl cloud account database;
screenshots and public examples use synthetic identities;
live tokens, snapshots, and desktop sessions are never intended for the repository.

The application stores its own local state under the normal platform application-data directories.

Credentials and session data deserve more careful treatment than ordinary preferences. The repository security policy explicitly tells users not to include auth.json, tokens, snapshots, private paths, or real account screenshots in public reports.

Synthetic demo data is part of security design

A quota dashboard naturally displays account names, emails, plan details, reset times, and usage values.

Real screenshots can leak more than expected.

The repository therefore uses synthetic accounts and snapshots for documentation and product images.

This is not just a marketing concern. Safe demo modes make it possible to:

reproduce UI states;
test sorting and warning behavior;
capture screenshots consistently;
review the project publicly;
avoid manually redacting every image.

A reliable synthetic-data path is often safer than asking contributors to “be careful” each time they take a screenshot.

Release engineering

CodexControl includes a tag-driven release workflow for both platforms.

The macOS path can:

import a Developer ID certificate when configured;
build the app;
sign the bundle;
notarize artifacts;
publish a ZIP and checksum.

The Windows path builds a standalone package and publishes its archive and checksum to the same GitHub release.

The project also includes:

a static product website;
direct release downloads;
a Homebrew cask;
a changelog;
platform-specific build and install scripts;
automated tests for account management and presentation behavior.

Distribution work is part of the product. A quota switcher that only runs from a development checkout would solve a much smaller problem.

What I learned

1. A narrow product can still require deep systems work

The interface answers two questions, but doing so reliably required authentication handling, live network reads, local state discovery, process restarts, Windows package caches, and release automation.

2. Accuracy is a user-experience feature

Repeated reads, stale-state clearing, and independent quota windows are not backend details. They determine whether the user trusts the next account-selection decision.

3. Account switching is distributed state synchronization

The active identity may exist in authentication files, global state, desktop caches, and running processes. Updating one layer does not guarantee the product has switched.

4. Cross-platform does not require identical implementations

A shared product contract can be more valuable than a shared UI framework. Native platform behavior should remain explicit where the operating systems differ.

5. Removal and recovery paths deserve first-class design

Adding an account is the easy path. Duplicate discovery, stale refresh tokens, deleted identities, failed restarts, and first-time desktop sessions are where the product becomes dependable.

Current scope

CodexControl remains intentionally Codex-specific.

It is not a general multi-provider dashboard, billing platform, or browser-based account manager.

It is for people who actively use multiple Codex accounts and need a fast local answer to:

which account has usable capacity;
when its quota resets;
which account is currently active;
how to switch without manually repairing local state.

The project is open source and supports macOS and Windows.

ademisler / codexcontrol

Local-first Codex quota tracker and multi-account switcher for macOS and Windows

CodexControl

Local-first Codex quota tracking and account switching for macOS and Windows.

Website · GitHub · Releases · Security

CodexControl is a focused desktop app for people who actively manage multiple OpenAI Codex accounts.

It does two things well:

shows live quota directly from OpenAI
switches the active Codex account used by the local CLI

Install

Homebrew

brew install --cask ademisler/tap/codexcontrol

Direct Download

macOS and Windows release: Latest GitHub release
Homebrew tap: ademisler/homebrew-tap

Why CodexControl

Most tools around this workflow fall into one of these categories:

multi-provider dashboards with too much surface area
browser-driven quota trackers with extra runtime overhead
scripts that estimate usage instead of reading the live account state
switchers that do not tell you which account is actually usable right now

CodexControl is intentionally narrower:

Codex-only
local-first
fast to scan
built around real quota windows and active-account control

Core Capabilities

Capability	What it does
Live quota reads

…

View on GitHub

I would be interested in feedback on a few areas:

Which quota signals are most useful when choosing between accounts?
How should the UI represent partial availability across short and long windows?
Have you encountered other desktop apps where authentication and browser-session state diverge?
Which local-first account-management workflows deserve better tooling?

This is the fourth article in my series documenting the products I have built. The next one covers Myna Player and the problem of generating context-aware subtitles without letting them arrive late.

Why I Built a Mailbox Instead of Injecting Messages Into a Running AI Agent

Adem İşler — Sat, 01 Aug 2026 23:38:01 +0000

The most obvious way to send new guidance to a running AI coding agent is to inject another message into its active conversation.

I deliberately chose not to do that.

When an agent is already implementing, testing, or reasoning through a task, active steering can be useful—but it also changes the conversational state immediately. A late instruction can interrupt a coherent plan, arrive in the middle of a tool operation, or blur the line between the task the agent accepted and the new context being introduced.

I wanted a different interaction model:

Leave guidance now. Let the agent read it at the next safe checkpoint.

That idea became CodexPigeon, an open-source desktop app and CLI that gives each Codex worktree a small, repository-local mailbox.

The human writes to an inbox. The agent reads it when control returns to a reasonable checkpoint, acknowledges the message, and can write a reply or receipt. The app observes Codex state, but it never starts, interrupts, steers, or injects into an active turn.

This article explains why I chose a mailbox protocol, how the ownership boundaries work, and what I learned while designing asynchronous human-agent communication.

The problem: useful context often arrives late

Long-running software tasks rarely remain perfectly static.

While an agent is working, a human may notice that:

one module must not be changed;
a test environment has become unavailable;
a release gate should be checked before publishing;
a requirement was misunderstood;
another developer changed a related file;
a destructive operation needs explicit approval;
the final answer should include a particular validation result.

The information is relevant, but the timing is awkward.

Interrupting immediately is not always necessary. Waiting until the current turn ends may be too late.

The product question became:

Can a human update the working context without treating the active chat stream as the only communication channel?

Why I rejected active-turn injection

Codex exposes methods that could conceptually be used to start, steer, interrupt, or inject items into conversations.

CodexPigeon explicitly refuses to use them.

The read-only App Server allowlist contains only:

initialize
thread/list
thread/read
thread/loaded/list
hooks/list

Methods such as these are rejected by design:

turn/steer
turn/start
turn/interrupt
thread/inject_items

This is not because active steering is universally wrong. It is because CodexPigeon has a narrower contract.

The product is a mailbox companion, not a second chat client.

A narrow contract makes the behavior easier to reason about:

the app cannot silently alter an active conversation;
the user can inspect the exact message written to disk;
the agent decides when it is safe to consume the message;
guidance remains attached to the repository and worktree;
communication state is visible outside the chat UI;
the security review can focus on a small set of file and read-only process boundaries.

The core rule: one thread, one worktree, one mailbox

Each active worktree receives a .codex-mailbox directory:

.codex-mailbox/
  INBOX.md
  OUTBOX.md
  RECEIPTS.md
  STATE.json
  HOOK_STATE.json
  README.md
  .gitignore

The operating rule is:

1 thread = 1 worktree = 1 .codex-mailbox/

This prevents guidance for one task from leaking into another task that happens to share the same repository.

Git worktrees are a useful boundary because they already represent separate working copies, branches, and task contexts. The mailbox follows that boundary instead of inventing a global message bus with complicated routing rules.

File ownership is the security model

The protocol separates files by writer:

File	Writer	Purpose
`INBOX.md`	CodexPigeon app or CLI	Human guidance for the agent
`OUTBOX.md`	Codex agent	Human-readable replies
`RECEIPTS.md`	Codex agent	Acknowledgement and action status
`STATE.json`	CodexPigeon app or CLI	Technical state and optional repeats
`HOOK_STATE.json`	Hook runtime	Reminder throttling and runtime state

The app must never write to OUTBOX.md or RECEIPTS.md.

The agent must never write to INBOX.md.

This avoids two processes editing the same logical record and makes provenance visible. When a line appears in the inbox, it came from the human-side tool. When a receipt appears, it came from the agent-side workflow.

The boundary is simple enough to explain in one table, which is usually a good sign for a protocol.

A message is plain Markdown

I chose Markdown rather than a hidden database protocol because the mailbox should remain inspectable with normal tools.

An inbox message looks like this:

## msg_20260520T153000_01HY4YF9F0Q2A3N4B5C6D7E8F9

from: human
created_at: 2026-05-20T15:30:00.000Z
priority: normal
status: unread
scope: current_task

Message:
Do not touch the auth module during the billing refactor.
If auth changes are needed, ask in OUTBOX.md first.

The ID combines a readable timestamp with a ULID-style suffix. That gives messages a useful chronological hint while avoiding collisions during rapid writes.

Messages are append-only. The app does not later rewrite status: unread inside the original inbox block.

Instead, current status is derived from agent receipts.

Receipts are more useful than mutating the inbox

A receipt can say whether the agent accepted, rejected, deferred, applied, or was blocked from applying a message.

Example:

## receipt_20260520T153245_01HY4YJ4Q8E2GHK2Z6MBWR6A1R

message_id: msg_20260520T153000_01HY4YF9F0Q2A3N4B5C6D7E8F9
seen_at: 2026-05-20T15:32:45.000Z
decision: accepted
action_status: applied
summary: Updated the current plan to avoid auth module changes.

The UI derives message state from these receipts:

no receipt → unseen;
accepted → accepted;
rejected → rejected;
deferred → deferred;
needs confirmation → needs confirmation;
applied → applied;
blocked → blocked.

This has two advantages.

First, the original human message remains immutable.

Second, acknowledgement and execution are separate concepts. An agent may understand an instruction but be unable to apply it, or it may defer the instruction until a later stage.

A single “read” flag would lose that distinction.

OUTBOX is intentionally separate

The agent can also write a human-readable reply:

## reply_20260520T153250_01HY4YJ9W9A2F33H4Y9N7DR5F0

from: agent
to: msg_20260520T153000_01HY4YF9F0Q2A3N4B5C6D7E8F9
created_at: 2026-05-20T15:32:50.000Z

Understood. I will avoid auth and ask here first if that changes.

Receipts are structured status. OUTBOX is conversation-like feedback.

Keeping them separate prevents the UI from having to infer operational state from free-form prose.

Safe checkpoints instead of immediate delivery

The mailbox only works if the agent checks it at useful moments.

CodexPigeon installs a managed section into AGENTS.md that asks the agent to inspect the inbox:

before a major architectural decision;
after a meaningful implementation step;
after tests or a long shell command;
before the final response.

It also installs project-local hooks:

SessionStart
PostToolUse
Stop

The hooks can create missing mailbox files, detect unread messages, and remind the agent to perform a final check.

But hooks are not treated as a hard security boundary. They are reminder infrastructure.

The primary contract remains:

repository instructions tell the agent how to behave;
ownership rules say which side writes each file;
App Server methods remain read-only;
the agent consumes mailbox content as human guidance, not executable shell input.

Preserving existing repository instructions

Installing a tool into a real repository should not overwrite the project's existing operating rules.

CodexPigeon updates only a managed block inside AGENTS.md:

<!-- CODEXPIGEON_MAILBOX_START -->
...
<!-- CODEXPIGEON_MAILBOX_END -->

Everything outside that block is preserved.

The same principle applies to .codex/hooks.json. Existing non-CodexPigeon hook groups remain in place, while only the managed CodexPigeon groups are replaced or updated.

This was an important implementation detail. A tool that helps coordinate an agent should not destroy the instructions that define how that agent works.

The desktop app has two integration planes

The architecture separates two different responsibilities.

1. Mailbox integration

The app and CLI can:

install the mailbox into a workspace;
validate messages;
append inbox entries;
parse inbox, outbox, and receipt Markdown;
watch files for changes;
derive message status;
manage optional repeated sends;
inspect whether hooks and instructions are installed correctly.

2. Read-only Codex integration

The App Server client can:

discover threads;
read thread metadata;
observe loaded threads;
inspect hooks;
enrich the UI with activity status.

These planes meet in the interface, but they do not share mutation powers.

The desktop app can help a user choose the correct worktree and observe the related Codex task. It still writes guidance only through the mailbox.

Package boundaries

The project is a TypeScript monorepo with several focused packages.

`packages/mailbox-core`

This is the protocol implementation:

Markdown parsing and serialization;
message ID generation;
path normalization;
append locking;
file watching;
installer behavior;
message validation;
repeated-message state.

`packages/codex-app-server`

This is the read-only JSON-RPC client. It enforces the method allowlist at runtime rather than relying only on developer discipline.

`packages/cli`

The CLI exposes commands such as:

send
watch
install
snapshot
doctor
automation list
automation stop
automation run-due

`packages/hooks`

This contains the managed AGENTS.md block, hook configuration, Python hook runtime, mailbox README, and ignore templates.

`apps/desktop`

The Electron application owns native dialogs, filesystem watching, IPC, and the React interface.

The renderer does not receive unrestricted Node access. A narrow preload bridge exposes the operations the UI needs.

Why parsing Markdown still required discipline

Human-readable files do not remove the need for a real parser.

The mailbox uses a Markdown syntax tree rather than splitting strings on headings or blank lines.

The parser treats each H2 heading as a new message, reads initial key: value metadata, and then captures the body.

Malformed blocks are skipped instead of being automatically rewritten.

That matters because mailbox files are both machine-readable and human-editable. A defensive parser should tolerate partial mistakes without corrupting the rest of the history.

Cross-process appends and race conditions

The app and CLI may both be active.

Repeated-message scheduling may also attempt to append while a human sends a manual message.

Inbox writes therefore use a cross-process lock. Missing files are created before append, and both manual and repeated messages use the same validation and write path.

Separate file ownership removes the largest race condition: the human-side tools and agent never append to the same file.

Optional repeated messages

CodexPigeon can repeat guidance at an interval while the desktop app or an explicit CLI runner remains active.

A repeat is stored in STATE.json with fields such as:

next run time;
last send time;
interval;
source message ID;
send count;
status;
whether warnings were explicitly allowed.

When due, the scheduler appends a new normal inbox message. It does not use a hidden channel and does not mutate the original message.

Repeated sending is disabled by default and has a minimum interval to prevent accidental hot loops.

The intended use is reminders such as:

Re-check the deployment gate before finalizing.

It is not intended for continuously pushing destructive commands into a task.

Message validation

Mailbox content is prompt-like input. It can still ask the agent to do something unsafe.

CodexPigeon warns on messages that appear to contain:

secrets;
destructive operations;
risky production actions;
credential-related instructions;
unusually large content.

Warnings block sending by default.

The CLI requires an explicit override, and the UI requires a deliberate “send anyway” action.

This is a user-safety layer, not a perfect secret scanner. The project still tells users not to paste credentials into mailbox messages.

Important limitations

The mailbox model has honest constraints.

An agent cannot read while trapped inside a blocking tool call

If a shell command runs for twenty minutes without returning control, the agent cannot inspect new mailbox messages during those twenty minutes.

That is a consequence of safe-checkpoint delivery rather than active interruption.

Markdown is not a transactional database

The files should remain reasonably small and append-only. The design favors transparency and local inspectability over high-throughput messaging.

Worktree handoffs can lose ignored runtime files

Mailbox runtime files are intentionally ignored by Git because they may contain private working context. Some worktree or repository handoff patterns therefore will not carry them automatically.

The app and hooks recreate missing files when needed, but the runtime history is local by design.

Hooks require a trusted project

If Codex does not trust the repository, project-local hook layers may be ignored. The UI and doctor command need to make that situation visible.

What I learned

1. Not every human-agent interaction belongs in chat

A repository task has state outside the conversation: files, plans, test results, worktrees, and constraints. A repo-local mailbox can be a better place for durable working guidance.

2. Refusing capabilities can strengthen a product

CodexPigeon would be more powerful if it could directly steer or interrupt turns. It would also be a different and harder-to-reason-about product.

The explicit refusal to use mutation APIs created a clearer identity.

3. Ownership tables are powerful design tools

The rule “the app writes inbox, the agent writes outbox and receipts” removed entire classes of ambiguity and write races.

4. Acknowledgement is not the same as execution

Structured receipts made it possible to distinguish seen, accepted, deferred, applied, blocked, and rejected states.

5. Transparent protocols are easier to debug

When something goes wrong, the user can open a Markdown file and inspect what was sent, what the agent acknowledged, and which side owns the next action.

Current status

CodexPigeon is a working MVP for local macOS and Linux development.

It includes:

an Electron and React desktop application;
a CLI;
a mailbox parser and installer;
read-only Codex thread discovery;
project-local hooks;
diagnostics and doctor commands;
automated tests for protocol, installer, hooks, and App Server boundaries.

Signed desktop packages and a Windows packaging path remain future work.

ademisler / codexpigeon

Non-interrupting mailbox companion for Codex worktrees on macOS and Linux, with repo-local inbox files, read-only App Server discovery, and safe checkpoint reminders.

CodexPigeon

Non-interrupting mailbox companion for Codex worktrees

Built by Adem Isler · MIT licensed · macOS and Linux development builds

What This Is

CodexPigeon lets a human leave repo-local guidance for a Codex task without injecting into the active chat turn.

It gives each selected repo/worktree a .codex-mailbox/ folder. The app and CLI append human messages to INBOX.md; the Codex agent reads those messages at safe checkpoints through installed project instructions and hooks, then writes status back to agent-owned files.

The product invariant is strict:

no active chat steering
no chat message injection
no turn interruption or turn start APIs
no App Server write APIs
no app writes to agent-owned OUTBOX.md or RECEIPTS.md

Open Source

This repository is intended to be inspectable. The mailbox protocol is plain Markdown, runtime files are repo-local, and all Codex App Server access is restricted to read/status/discovery methods.

The current release is a working…

View on GitHub

I would particularly value feedback on these questions:

Which safe checkpoints make sense during a long coding task?
Is plain Markdown the right tradeoff for human-agent working state?
Which receipt states would be useful beyond accepted, deferred, applied, and blocked?
Where should the boundary sit between asynchronous guidance and active steering?

This is the third article in my series documenting the products I have built, moving from browser utilities toward AI-native developer tools and local desktop systems.

How I Ran Custom Model Providers in Separate Codex Desktop Apps

Adem İşler — Sat, 01 Aug 2026 23:36:19 +0000

After building Toolboard, I started exploring a different kind of product problem: how to use a custom model provider inside Codex Desktop without turning the main installation into an experimental environment.

The obvious approach was to edit the existing configuration and point it at another endpoint.

I did not want to do that.

My normal Codex setup already had its own sessions, configuration, automations, icon, launcher, and authentication state. A custom provider should not overwrite any of it. It should behave like a separate application that can live beside the original.

That requirement became Codex Desktop Custom Models: an open-source starter kit for creating isolated Codex Desktop apps on macOS and Linux.

The reference implementation is Codex MiniMax, a separately branded Codex Desktop app that uses MiniMax through a local compatibility bridge.

This article explains the architecture behind it, the API mismatch that required a bridge, and why isolation turned out to be the most important product decision.

The real problem was not changing the model

Changing a model name is easy.

Creating a second desktop application that does not interfere with the first one is a larger systems problem.

A custom Codex app needs its own:

application name and icon;
bundle or desktop application identity;
launcher and executable path;
webview port;
CODEX_HOME directory;
provider configuration;
API credentials;
sessions and local state;
bridge process;
automation definitions and runner state.

If even one of those boundaries is shared accidentally, the two apps can collide in subtle ways.

They may open with the wrong icon, share session history, overwrite configuration, reuse the same webview port, or make it unclear which provider is active.

So I made isolation the primary invariant:

A custom Codex app should feel familiar, but it should not share identity, state, ports, or provider configuration with the primary installation.

What the isolated setup looks like

A normal installation and a custom profile can exist side by side:

Original Codex	Custom Codex app
Default application identity	Unique app name, icon, and app ID
Main `~/.codex` directory	Separate directory such as `~/.codex-minimax`
Default provider configuration	Custom provider configuration
Existing sessions and state	Independent sessions and state
Existing automations	Separate local automation layer

For the MiniMax reference profile, the resulting flow is:

Codex MiniMax Desktop
        |
        v
custom launcher and application identity
        |
        v
CODEX_HOME=~/.codex-minimax
        |
        v
local bridge at 127.0.0.1:4007/v1/responses
        |
        v
MiniMax OpenAI-compatible /chat/completions endpoint

The original Codex installation is left untouched.

On macOS, the installer creates a separate app bundle under ~/Applications, command wrappers under ~/.local/bin, an isolated home directory, and a LaunchAgent for the bridge process.

On Linux, it creates a side-by-side desktop shell under the user's local application directories and reuses large runtime assets where practical.

Why a local bridge was necessary

The model provider was not the only compatibility layer.

Codex Desktop communicates with a provider using the Responses API shape. Many third-party providers expose an OpenAI-compatible Chat Completions API instead.

Those APIs overlap, but they are not interchangeable.

The bridge has to translate:

Responses input items into chat messages;
developer instructions into the correct upstream role;
assistant messages and output text;
function calls and function-call outputs;
namespaced tools;
tool-choice behavior;
streaming and non-streaming output;
provider-specific model names;
errors and health checks.

The basic path is:

POST /v1/responses
        |
        v
normalize Codex input and tools
        |
        v
POST <provider>/chat/completions
        |
        v
convert assistant text and tool calls
        |
        v
Responses-compatible output for Codex

Text-only requests are the easy case.

Tool calls are where the design becomes more interesting.

Translating namespaced tools

Codex can represent tools inside namespaces. A Chat Completions provider usually expects a flat function name.

For example, a conceptual Codex tool might look like:

namespace: github
function: fetch_file

The bridge flattens that into a provider-safe function name such as:

github__fetch_file

It keeps an internal map so that when the provider returns a tool call, the original namespace and function name can be restored before the result goes back to Codex.

This sounds like a small transformation, but it is essential. Without a reversible mapping, the model may call a function successfully while Codex cannot route the result to the correct tool.

The bridge also sanitizes names because provider function-name rules can be stricter than the identifiers used by the source tool system.

Why I used a local HTTP service

The bridge runs only on 127.0.0.1.

That decision provided a few useful properties:

Codex can treat it like a normal provider endpoint;
the upstream API key stays in the custom profile environment;
provider-specific translation logic remains outside the desktop application bundle;
health checks and test requests are easy to run;
the bridge can be restarted independently;
another OpenAI-compatible provider can reuse the same architecture.

The custom configuration points Codex to the local Responses endpoint, while the bridge points to the actual provider's Chat Completions endpoint.

The reference profile uses MiniMax, but the architecture is deliberately generic. A different provider mostly requires changing:

the upstream base URL;
the default model name;
the supported model list;
the API-key environment variable;
any provider-specific response normalization.

Application isolation on macOS

macOS application identity is more than a folder name.

A side-by-side application needs a unique bundle identifier, display name, icon, helper identity, launcher behavior, and webview port. Copying the base .app bundle gives the custom profile a controlled place to patch those values.

The installer then creates wrappers such as:

codex-minimax
codex-minimax-desktop
codex-minimax-proxy

Each wrapper has one narrow responsibility:

invoke the Codex CLI with the isolated home;
launch the custom desktop bundle;
manage, test, and inspect the bridge process.

The bridge is registered through a LaunchAgent so it can survive beyond the shell session that created it.

This matters because a desktop app should not depend on the user remembering to keep a terminal command running.

Application isolation on Linux

The Linux path has a different set of constraints.

Many large runtime files can be reused, but identity-sensitive files should be copied rather than linked.

The custom app keeps independent versions of things such as:

the launcher script;
executable identity;
branding assets;
desktop entry metadata;
the application directory structure.

Large internal runtime assets can be linked where doing so does not create shared writable state.

The rule is not “copy everything” or “symlink everything.” The rule is:

Copy the files that define application identity, and reuse only the files that are effectively immutable runtime dependencies.

That avoids unnecessary duplication without creating Dock, taskbar, icon, or profile collisions.

Separate `CODEX_HOME` is the real boundary

The most important directory is not the app bundle. It is the custom CODEX_HOME.

A profile such as ~/.codex-minimax contains the custom app's:

config.toml;
provider environment files;
bridge scripts;
automation definitions;
session and application state;
local logs and SQLite files.

The launcher exports this directory before invoking Codex.

That means the custom app does not need to mutate ~/.codex, and removing the custom application does not require deleting the user's main Codex state.

The uninstall process intentionally keeps the custom home by default. Removing the app and deleting its history are separate decisions.

That distinction is valuable in any desktop tool: uninstalling executable files should not silently destroy user data.

Automations required a second compatibility layer

A custom Codex profile does not automatically inherit automation tools supplied by the host environment.

So the project includes a small local MCP server and runner.

The MCP server exposes an automation update tool and stores definitions under the isolated custom home. It also mirrors enough metadata into local SQLite state for the app to display those automations.

The runner polls for due jobs and supports two patterns:

background or inbox-style tasks;
same-thread follow-ups.

Same-thread delivery was the important detail.

Creating a scheduled record is not the same as making the result appear in the conversation where the user requested it.

For same-thread reminders, the automation stores the target thread ID and later runs a command conceptually equivalent to:

codex exec resume <thread-id> ...

That allows the follow-up to return to the original thread instead of creating disconnected output elsewhere.

The scheduler is intentionally limited to common minutely, hourly, and daily patterns. It is not trying to replace a full calendar system.

Safety and repository hygiene

A project that works with custom model providers and local Codex state has an obvious publishing risk: accidentally committing credentials or private session data.

The repository includes a verification command that checks syntax and scans for patterns such as:

API keys;
personal home-directory paths;
local project names;
private state files;
provider environment files.

The public starter kit contains templates and examples, not a copy of a real Codex profile.

The files that must remain private include provider keys, session indexes, shell snapshots, logs, and application state databases.

This is also why I prefer isolated profiles to modifying the primary installation. Isolation makes the security boundary easier to understand and easier to audit.

What I learned

1. Compatibility is broader than API syntax

The request and response formats were only one layer. A real desktop integration also needed process management, state isolation, app identity, ports, icons, launchers, and automation behavior.

2. Side-by-side products need explicit identity

A renamed folder is not a separate application. Operating systems use bundle IDs, executable paths, helper identities, and desktop metadata to decide how apps are grouped and launched.

3. Tool calling makes provider bridges significantly harder

Text can often be mapped directly. Namespaces, function-call IDs, tool outputs, and provider naming restrictions require reversible and carefully validated transformations.

4. Local bridges are useful architectural seams

Keeping provider adaptation in a small localhost service allowed the desktop shell, Codex configuration, and upstream provider logic to remain independently understandable.

5. Isolation is a product feature

The strongest benefit is not that the project can connect to MiniMax. It is that a user can experiment without destabilizing the setup they already rely on.

Who this project is for

Codex Desktop Custom Models is not a one-click consumer application.

It is an operator-friendly starter kit for developers who:

already have Codex Desktop working;
understand that upstream internals may change;
want a separate app for an OpenAI-compatible provider;
prefer inspectable scripts over modifying their primary environment;
are comfortable testing integrations after Codex updates.

It is unofficial and is not an OpenAI, MiniMax, or Ollama project.

The repository

The repository includes the provider bridge, macOS and Linux installers, configuration templates, automation MCP and runner, diagrams, screenshots, troubleshooting notes, and a publishing checklist.

ademisler / codex-desktop-custom-models

Open-source starter kit for isolated Codex Desktop apps for custom model providers on macOS and Linux, with provider bridges, custom icons, and local automations.

Codex Desktop Custom Models

Create isolated Codex Desktop apps for custom model providers on macOS and Linux, with separate icons, state, provider bridges, and automations

An open-source project by Adem İşler Released under the MIT License.

What This Is

Codex Desktop Custom Models is a starter kit for people who already have Codex Desktop installed and want a second, independent Codex app for a custom model provider.

The reference app is Codex MiniMax: a red-icon Codex Desktop profile that uses MiniMax M2.7 through a local OpenAI-compatible bridge.

It does not modify your original Codex app. Your normal Codex install keeps its own config, data, sessions, provider, icon, and launcher.

Open Source

This project is released under the MIT License. You can use it, fork it, adapt it for other providers, and contribute fixes through pull requests.

What You Get

Part	Purpose
Isolated app clone	Creates a side-by-side Codex

…

View on GitHub

I am interested in feedback on a few areas:

Which other OpenAI-compatible providers would be useful as documented examples?
Should provider adapters remain configuration-driven, or should complex providers get separate bridge modules?
Which parts of desktop-app isolation have caused the most trouble in your own tooling?

This is the second article in my series documenting the products I have built, moving from browser utilities toward AI-native developer tools and desktop systems.

How I Turned a Cluttered Browser Workflow Into a Chrome Extension With 83 Tools

Adem İşler — Sat, 01 Aug 2026 23:28:39 +0000

As I started documenting the products I have built over time, I decided to begin with one of the earliest: Toolboard.

Browser workflows rarely become frustrating because one important feature is missing. They become frustrating because useful actions are scattered across separate extensions, websites, menus, and tabs.

I had one extension for screenshots, another for colors, another for fonts, separate websites for data conversion, and a growing set of small utilities I repeatedly searched for. Each tool solved a real problem. Together, they created a fragmented workflow.

So I built one place for them.

Toolboard is a Manifest V3 Chrome extension that brings 83 browser tools into a single searchable interface. It covers inspection, capture, browsing enhancements, general utilities, format conversion, structured-data previewing, and AI-assisted workflows.

This post is less about listing 83 features and more about the product and engineering decisions required to stop 83 features from becoming a mess.

The product boundary

The initial idea was simple:

Put the small browser tools I use regularly behind one consistent interface.

That boundary mattered. Toolboard was not meant to become a second browser or a giant automation platform. It was meant to reduce the friction between noticing a task and completing it.

Examples include:

inspecting a color, font, element, or link on the current page;
capturing a screenshot, page text, media, PDF, QR code, or tab recording;
adding sticky notes, highlights, reading mode, bookmarks, or dark mode;
converting units, currencies, time zones, colors, timestamps, encodings, data formats, images, and subtitles;
previewing JSON, CSV/TSV, Markdown, XML, PDFs, images, OpenGraph metadata, schema data, and links;
summarizing, translating, analyzing, or discussing page content with AI.

As the project grew, the tools settled into seven categories:

Category	Examples
Inspect	Color Picker, Element Picker, Font Finder, Link Picker
Capture	Screenshot Picker, Media Download, Text Picker, PDF Generator, QR Generator, Video Recorder
Enhance	Sticky Notes, Reading Mode, Text Highlighter, Bookmark Manager, Dark Mode
Utilities	Site Info, Color Palette Generator, Copy History, Macro Recorder
Converters	Units, currency, time zones, Base64, URLs, UUIDs, hashes, JWTs, JSON/YAML, CSV/JSON, XML/JSON, images, media, subtitles, and more
Previewers	JSON, CSV/TSV, Markdown, XML, PDF, image, OpenGraph, schema, and link previews
AI	Summarizer, Translator, Content Detector, Email Generator, SEO Analyzer, AI Chat

The breadth is useful, but breadth immediately creates a second problem: discoverability.

Adding tools was not the hard part

The difficult part was not writing another converter or picker. The difficult part was keeping dozens of tools understandable, searchable, testable, and consistent.

Toolboard uses a central tool manifest as its product registry. Every tool declares information such as:

{
  "id": "color-picker",
  "name": "Color Picker",
  "category": "inspect",
  "module": "inspect/colorPicker.js",
  "icon": "color",
  "tags": ["color", "design", "palette"],
  "keywords": ["hex", "rgb", "hsl", "eyedropper"],
  "permissions": ["activeTab"]
}

This manifest became the source of truth for the interface and release process.

It lets the extension:

build categories without hard-coding every card;
search by names, tags, and related keywords;
keep ordering predictable;
connect tools to icons and localization keys;
associate functionality with the permissions it needs;
detect missing modules or inconsistent registrations before release.

That structure was more important than any individual feature. Without it, every new tool would have increased the amount of manual UI code and made future changes more fragile.

Designing for 83 choices

A grid containing 83 equally weighted options is not a productivity interface. It is a directory.

I added several layers to reduce that cognitive load:

Search

Users can search by tool name as well as related terms. Someone looking for “hex,” “eyedropper,” or “palette” should still reach the Color Picker.

Favorites and usage-based ordering

Frequently used tools can be marked as favorites. Favorites rise to the top, and usage frequency helps order tools within that group.

The goal is for Toolboard to become smaller for each user over time. The extension may contain 83 tools, but a person should mostly see the subset relevant to their own workflow.

Hidden tools

Not every feature is useful to every person. Tools can be hidden instead of forcing everyone to navigate the full catalog forever.

Consistent interaction patterns

Dozens of tools should not feel like dozens of unrelated mini-apps. Buttons, panels, previews, loading states, copy actions, downloads, and completion feedback need to behave consistently.

I even added small multilingual coffee-themed messages after successful operations. It is a minor detail, but consistency in small feedback moments helps a broad utility suite feel like one product rather than a folder of scripts.

The permission model is part of the product

A multi-tool browser extension naturally needs a wider permission surface than a single-purpose extension.

Toolboard uses permissions such as:

activeTab and scripting for page inspection and tool activation;
storage for preferences, favorites, notes, bookmarks, highlights, and local history;
clipboardRead and clipboardWrite for copy-related workflows;
downloads for generated or captured files;
tabCapture for the video recorder;
tabs where tab metadata is needed.

The extension also needs to operate across normal HTTP and HTTPS pages so the tools are available where the user needs them.

This makes transparency essential. A permission list should not be treated as a technical footnote. Users should be able to understand which capability needs each permission and what happens to their data.

Most Toolboard state stays in chrome.storage.local, including:

favorites and hidden tools;
per-site sticky notes and highlights;
bookmarks and copy history;
theme and onboarding preferences;
tool usage data used for sorting.

There is no analytics or crash telemetry built into the extension.

AI features are different because they need a model endpoint. They use the user's own Gemini API key, and the relevant selected text or page content is sent to Gemini only when the user invokes an AI tool. API keys are encrypted locally before storage. A small number of converter features also use task-specific external services, such as exchange-rate or label-rendering APIs.

The lesson for me was simple: privacy is not a badge added to a README. It is a product surface that needs explicit controls, explanations, and boundaries.

AI as a tool category, not the entire product

Toolboard includes an AI Summarizer, Translator, Content Detector, Email Generator, SEO Analyzer, and a page-aware chat interface.

But I did not want every utility to become a chat prompt.

A color picker should still pick colors. A JWT decoder should still decode a token. A CSV previewer should still show a table immediately.

AI is useful where interpretation is required:

condensing a long page;
translating selected or full-page text;
generating a structured email;
reviewing SEO signals;
discussing the current page with context.

It is less useful when a deterministic local operation can provide an immediate and reliable result.

Keeping AI as one category among seven helped preserve that distinction.

Release gates for a large extension

Feature count creates maintenance risk. A small change to the registry, icons, translations, or activation path can break tools that appear unrelated.

The release process therefore checks more than whether the JavaScript parses.

Automated tests validate areas such as:

tool IDs being unique and consistently formatted;
registered modules existing and exporting the expected shape;
localization keys being present across English, Turkish, and French;
every tool having a registered icon;
the manifest and displayed tool count staying aligned;
shared completion-message coverage remaining complete.

There is also a manual release checklist for preview rendering, repeated tool execution, fullscreen behavior, overlay closing, light/dark contrast, localization, and permission consistency.

This is one of the biggest lessons I took from Toolboard:

Shipping many small features does not reduce the need for engineering discipline. It multiplies it.

What I learned

1. Feature breadth changes the core problem

At first, the problem was building useful tools. Later, the problem became helping people find and trust the right tool quickly.

2. A registry-driven architecture scales better than manual UI wiring

The manifest gave the project a stable vocabulary for tools, categories, keywords, icons, localization, and permissions.

3. Consistency matters more as individual features become smaller

When each action is brief, inconsistent buttons, feedback, previews, or output handling become disproportionately noticeable.

4. Browser permissions require product communication

Technical justification is not enough. Permission use has to be understandable from the user's point of view.

5. AI should be applied selectively

AI added value to interpretation-heavy workflows, but many browser tasks remained better as fast, local, deterministic utilities.

Where the project stands

Toolboard is currently at version 3.0.1 and remains open source under the MIT License.

The repository includes the extension source, privacy documentation, tests, and release checklist:

ademisler / toolboard

A Chrome extension with 80+ productivity tools for inspection, capture, conversion, and AI-assisted workflows.

Toolboard

A comprehensive Chrome extension with 83 web productivity tools, including AI-powered features, a smart favorite system, converter suite, and coffee toast messages.

🚀 Features

AI-Powered Tools

AI Summarizer - Intelligent text summarization with multiple length options
AI Translator - Real-time translation with in-place page translation
AI Content Detector - Detect AI-generated content with detailed analysis
AI Email Generator - Professional email generation with customizable tone and type
AI SEO Analyzer - Comprehensive SEO analysis with AI-powered scoring
AI Chat - Intelligent conversational interface with persistent page context awareness

Inspection Tools

Color Picker - Extract colors from any webpage element
Element Picker - Inspect DOM elements and their properties
Font Picker - Analyze fonts used on web pages
Link Picker - Validate and analyze links

Capture Tools

Screenshot Picker - Capture full page or selected area screenshots
Text Picker - Extract text from web pages
Media Picker - Extract images…

View on GitHub

I am especially interested in feedback on three areas:

Does the category structure match how you think about browser tools?
Which permissions or privacy boundaries need clearer explanations?
Should a broad tool such as this remain one extension, or should some categories eventually become focused standalone products?

This is the first article in a series documenting the products I have built—from browser utilities to newer AI-native developer tools and desktop systems.