Skip to content
judellPublic

About

No description, website, or topics provided.

Resources

Security policy

Stars

66 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

2,716 Commits

Folders and files

Repository files navigation

Bram

What is it?

Agentic software development on human terms: legible, orderly, transparent, accountable, and collaborative.

Why the name?

Bram runs agents mindfully.

Who is it for?

Anyone who uses Claude Code, Codex, OpenCode and/or Antigravity.

Bram demo video: a six-minute tour of Bram tackling and completing a GitHub issue. Click to watch on the Bram homepage.

How does it work?

Terminal (optional)

A terminal where you run claude, codex, opencode or agy (Antigravity). It starts closed, in favor of the agent pane's Worklist, Transcript, and Queue views. The terminal button in the toolbar opens and closes it for the current session; to have it open every time Bram launches, turn on Terminal open at startup in the Settings tab's UI section.

Agent pane

  • Header: Switches between agents and adjusts font size.

  • Worklist: Where you decide what happens to your repo. Each row carries an icon for where it stands β€” not started, nothing to commit, or has changes you can commit β€” plus its plan, the files it alters as work happens, and your feedback history. Items that share a file with another started item show up together in a Shared files table. The most recent conversation exchange stays in view.

  • Transcript: Shows your terminal session in a more readable form.

  • Issues: Tracks and searches GitHub issues for the repo Bram runs in.

  • Commits: Tracks and searches your commits.

  • Queue: Parks editable messages while the agent works and sends each one only when you choose.

  • Sessions: Lists your sessions; rename, delete, or switch between them.

  • History: Lists and searches your Worklist items.

  • Log: Under More, tells what Bram did around your work (Start, Commit and Push, your searches, queued messages, session switches, a kept selection after a pane reload, demo instances) over the last five hours and across relaunches. Entries expand and link to History, Commits and the Transcript.

  • Tasks: Under More, lists the commands your agents keep re-typing across sessions, ranked, each with a suggested name. A measurement for now; it doesn't save or run anything yet.

  • Settings: Shows and changes global (repo-independent) settings.

  • Footer: Shows agent status and the current session, and lets you message the agent.

Workflow

On the Worklist tab, create Worklist items in conversation ("Hey agent, let's do x") or with the + New item button, which can also cite an open issue. Either way the agent proposes an item: a short plan with Before and After notes, naming the files it expects to alter.

To act, tick one or more items and use the buttons above the message box. One action, and one message, covers every item you selected. Buttons dim rather than disappear as you tick items, so the row of actions holds still β€” a dimmed button means it doesn't apply to the current selection, not that it's gone.

  • Start accepts a proposal and authorizes the agent to alter files.

  • Commit commits an item's altered files to git.

  • Drop retires items you don't want. A dropped item isn't lost: you can resurrect it from the History tab, or ask the agent to file an issue first so the idea survives in GitHub.

When two started items both touch the same file, a Shared files table lists the shared path, what's on disk, and which items claim it.

On the Issues tab, use + New issue to ask Bram to file a GitHub issue.

On the Queue tab, park thoughts that arrive while the agent is busy. Bram keeps them with the repo across reloads and restarts.

Every item moves from proposal, to altered files, to a commit or drop, and hooks hold the agent to that order: no file alterations without an approved item, no commit without your approval. Between those steps you can dwell as long as you like to:

  • discuss and refine a proposal

  • discuss and refine an implementation

  • create, refine, and close issues

When there is a selected item in the Worklist are selected, a message to the agent addresses that item. Otherwise it's open-ended chat. For small things that you want to commit immediately you can end your message with "just do it" to bypass the Worklist.

Workflow conventions

The rules an agent follows when driving the Bram workflow (proposing Worklist items, moving them from proposal to commit, coordinating commits and issues) live in app/__shell/conventions.md. Each agent loads that file automatically: Claude through CLAUDE.md and the installed .claude hook/config path, Codex through a repo-local AGENTS.md block that setup installs, OpenCode through an instructions entry in .opencode/opencode.json, Antigravity through always-on rules in .agents/rules/. These aren't merely advisory: a PreToolUse hook (for OpenCode, a plugin; for Antigravity, a hook group in .agents/hooks.json) on each agent enforces the core rule, rejecting file edits that aren't covered by an approved Worklist item β€” so the convention enforces itself rather than relying on the agent's goodwill.

Prerequisites

  1. A local git repo in which you develop your app. Start Bram from that repo's root folder: cd there in your terminal and run bram. Anywhere else (your home directory, a folder that isn't a git repo, or a subfolder of one), Bram starts nothing and says where to start from.

  2. git β€” usually preinstalled on macOS and Linux; install via your package manager if missing.

  3. GitHub CLI (gh) - Powers the Issues tab in the agent pane and the agent's issue create / close / comment operations. Install from https://cli.github.com/ and run gh auth login once. Without it, the Issues tab shows an empty state.

  4. XMLUI CLI - optional. If you are developing an XMLUI app, or if you are developing Bram itself (the agent pane UI is an embedded XMLUI app) you will want the XMLUI MCP server. Follow the steps here to get it.

  5. whisper-server β€” optional. Powers the 🎀 dictation buttons in the agent pane. Tested on macOS and Windows, see Voice input below for install and per-platform status.

Install

macOS / Linux

curl -fsSL https://github.com/judell/bram/releases/latest/download/install.sh | bash

The script detects your platform, verifies the archive's SHA256 against the published SHA256SUMS, extracts the binary, and copies it to /usr/local/bin (if writable) or ~/.local/bin. On macOS it also clears the com.apple.quarantine xattr. No sudo required.

Windows

From PowerShell:

irm https://github.com/judell/bram/releases/latest/download/install.ps1 | Out-String | iex

From Command Prompt:

curl.exe -fsSL https://github.com/judell/bram/releases/latest/download/install.ps1 -o "%TEMP%\bram-install.ps1" && powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%TEMP%\bram-install.ps1" && del "%TEMP%\bram-install.ps1"

Downloads bram-windows-amd64.zip, verifies its SHA256, extracts bram.exe to ~/bin, and adds ~/bin to your user PATH.

Smart App Control

Bram's Windows binaries are unsigned. On a machine where Smart App Control (SAC) is on, Windows may refuse to run them. Most users never see this.

Smart App Control is a reputation filter that Windows turns off on its own for developer and enterprise-managed machines ("so you can work with fewer interruptions," per Microsoft). If it's on and blocks Bram, Microsoft's documented remedies are to turn it off or to use a signed build ("There is currently no way to bypass Smart App Control protection for individual apps"). Defender keeps protecting the machine either way ("Smart App Control works alongside your other security software, such as Microsoft Defender"), and current Windows builds can turn SAC back on later. Because SAC judges each file by its reputation, one Bram release can be allowed and the next refused.

To check your machine (0 = Off, 1 = On, 2 = Evaluation):

(Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\CI\Policy').VerifiedAndReputablePolicyState

To turn it off: Windows Security β†’ App & browser control β†’ Smart App Control settings.

Two caveats:

  • Turning it back on. Microsoft's support page says "Recent Windows updates allow Smart App Control to be re‑enabled without requiring a clean installation" (since the April 2026 update for 25H2). Its developer page still calls the switch "a one-way operation".
  • The October 2026 update. KB5127648 can grey out the toggle on 24H2, 25H2 and 26H2, until Microsoft fixes it.

Sources: What is Smart App Control (Microsoft Support); Test App Signatures with Smart App Control (Microsoft Learn); re-enabling without reinstalling (topedia); KB5127648 greys out the toggle (IT-Connect).

First-run setup

The first time you launch claude, codex, opencode or agy in a repo, Bram checks what that provider needs and prompts once if anything is missing β€” no prompt on later launches. Accepting Bram's setup prompt installs the Worklist conventions the agent reads each session plus provider-specific hooks that enforce the Worklist and show permission menus. A provider-neutral authorization record and watcher-revert fallback back up those hooks.

The agents differ in the trust step you see after Bram writes those files:

  • Claude setup is repo-local. Bram writes .claude/bram-conventions.md and .claude/settings.json hook registrations that point at ~/.bram/bram-guard. Claude reads that project config on launch; there is no separate Codex-style hook trust menu. The Claude PreToolUse hook is the safety gate for Write, Edit, and Bash; the permission hook shows Claude permission and AskUserQuestion prompts in Bram's agent pane.
  • Codex setup has an explicit trust/approval step. Bram updates ~/.codex/config.toml with hook registrations that point at ~/.bram/bram-guard, writes Bram developer_instructions, and adds a repo-local AGENTS.md block. Codex then shows its hook approval screen; approve it only when it points at Bram-owned paths such as ~/.bram/bram-guard, ~/.codex/config.toml, and this repo's AGENTS.md. The Codex PreToolUse hook gates apply_patch, Bash, Write, Edit, and mutation-shaped MCP tools; the Codex permission hook shows PermissionRequest / PostToolUse menus in Bram's agent pane.
  • OpenCode setup is repo-local, with no trust screen. Bram writes .opencode/plugins/bram.js and adds an instructions entry to .opencode/opencode.json so OpenCode loads the conventions every session. It does this only where OpenCode can run: its CLI is on your PATH, it is the active agent, or the plugin is already installed. The plugin is OpenCode's counterpart of the PreToolUse hook: before each tool call that can change the project, it asks ~/.bram/bram-guard, and it refuses the call unless the answer is an allow, including when the guard can't be reached. It also forwards OpenCode's turns and permission prompts to Bram's agent pane. Setup keeps a .opencode/plugins/bram.js you wrote yourself (one without Bram's marker) and reports that it did.
  • Antigravity setup is repo-local; the trust screen you see is agy's own folder-trust prompt the first time it opens a workspace. Bram merges a bram-worklist-guard group into .agents/hooks.json, keeping your own groups, and writes the conventions as always-on rules in .agents/rules/bram-conventions-<n>.md. It does this only where Antigravity can run: agy is on your PATH, it is the active agent, or Bram's group is already installed. The group runs ~/.bram/bram-guard as a PreToolUse hook before agy's write_file, edit_file, run_command and call_mcp_tool, and the call is refused unless the answer is an allow. Setup keeps a rule you wrote yourself under one of those names, and leaves alone a .agents/hooks.json that isn't JSON; it reports both. Where .agents/ has no tracked files and no .gitignore, Setup writes a .agents/.gitignore naming what it seeded.
  • Do not approve unexpected Codex paths. If the Codex approval screen lists hook commands other than ~/.bram/bram-guard or config changes somewhere other than the expected Codex/project files, stop and inspect them first.

Hook names mean the same thing in Claude and Codex:

  • PreToolUse runs before a tool executes and blocks mutations that are not covered by the Worklist or by an explicit direct-edit authorization.
  • PermissionRequest lets Bram render permission prompts from structured hook payloads instead of scraping the terminal grid.
  • PostToolUse, when present, is post-tool bookkeeping for the same hook-driven permission/menu path.

A healthy Codex hook screen should show Bram's installed lifecycle hooks as both Installed and Active. In the current setup that means at least PreToolUse, PermissionRequest, and PostToolUse each show 1 / 1; lifecycle events Bram does not use, such as SessionStart or Stop, can remain 0 / 0.

Setup internals: hook adapters, guard source-of-truth, and how conventions.md binds each provider

Once you launch an agent through Bram's terminal, the agent pane checks what that provider still needs for the current repo and prompts only when setup is missing.

Current behavior:

  • Claude in a fresh repo β€” prompt once. Setup installs the provider-neutral core plus the Claude-specific adapter.
  • Claude in a repo that is already set up β€” no prompt.
  • Codex in a fresh repo β€” prompt once. Setup installs the provider-neutral core, the codex hook adapter, and the codex developer_instructions, and it also refreshes the shared Claude-side artifacts that live in the repo.
  • Codex in a repo where setup has already run β€” no prompt. The repo and user-global Codex setup artifacts are already in place.
  • OpenCode in a fresh repo β€” prompt once. Setup installs the provider-neutral core, the OpenCode plugin, and the instructions entry in .opencode/opencode.json.
  • OpenCode in a repo where setup has already run β€” no prompt.
  • Antigravity in a fresh repo β€” prompt once. Setup installs the provider-neutral core, Bram's hook group in .agents/hooks.json, and the always-on rules in .agents/rules/.
  • Antigravity in a repo where setup has already run β€” no prompt.

When the prompt runs, Bram installs two layers:

  • A provider-neutral core: Bram records the latest structured approved: / drop: payload in resources/.worklist-authorization.json and uses that local record when validating Worklist removals. The desktop watcher can revert an invalid prune as a defense-in-depth fallback if a hook ever fails to fire.
  • A Claude adapter: ~/.bram/bram-guard guard claude-worklist, registered in .claude/settings.json as a PreToolUse hook for Write, Edit, Bash, and mcp__.*. The hook denies edits to project files not covered by a proposed/applied worklist item (with the explicit opt-out phrase "just do it" in the last user message as the escape hatch), validates worklist-prune authorization for changes to resources/worklist.json itself, and blocks mutation-shaped Bash commands without worklist coverage. Setup also registers ~/.bram/bram-guard guard claude-permission-menu for Claude permission and AskUserQuestion surfacing in the agent pane.
  • A Codex adapter: ~/.bram/bram-guard guard codex-worklist, registered in ~/.codex/config.toml as a PreToolUse hook with matcher ^(apply_patch|Bash|Write|Edit|mcp__.*)$. Same coverage logic as the Claude hook, broadened to catch Codex's apply_patch tool and MCP filesystem write/edit/create/move calls. Setup also writes developer_instructions into the Codex config so the gate prose lands in the developer-role context part of every session, not just the user-role AGENTS.md, and registers ~/.bram/bram-guard guard codex-permission-menu for PermissionRequest / PostToolUse menu surfacing with the xterm grid retained as fallback.

Every hook is the same compiled Rust binary, bram-guard, built from src-tauri/src/bin/bram-guard.rs (the logic lives in src-tauri/src/guard.rs) and shipped beside the bram executable. The first argument after guard picks the hook: claude-worklist, claude-permission-menu, codex-worklist, codex-permission-menu, opencode-worklist or antigravity-worklist. Hook configs never reference the binary's own location. They reference ~/.bram/bram-guard, which Bram re-points at its own bram-guard on every launch: a symlink on macOS and Linux, a hardlink (or copy) of bram-guard.exe on Windows. Moving or updating the app therefore never orphans the registration. Earlier releases installed Python hook scripts (.claude/hooks/*.py, ~/.bram/codex-*.py); Setup deletes each one once no Claude settings file (or, for the Codex scripts, ~/.codex/config.toml) still references it.

PreToolUse hooks are the generic extension point β€” both Claude Code and codex expose them β€” so the two adapters share the same shape: each runs before the agent invokes a tool, receives a JSON payload describing the pending call on stdin, and can exit 0 to allow, return a deny decision to block (stderr/permissionDecisionReason goes back to the agent as a tool error), or fail to launch. OpenCode has no such hook, so its adapter is a plugin (.opencode/plugins/bram.js) whose execute.before tool hook asks the same guard (~/.bram/bram-guard guard opencode-worklist) and throws to refuse the call; OpenCode's model reads the message as the refusal. The plugin fails closed: no guard, no answer, or an unreadable answer is a deny. Antigravity does expose PreToolUse, in .agents/hooks.json; its group runs ~/.bram/bram-guard guard antigravity-worklist, which maps agy's tools onto Claude's before the shared policy decides. Because agy runs a call when a hook exits 0 with empty output, the registered command turns empty output into a deny.

That means first-run setup is provider-aware in when it prompts but provider-symmetric in what it installs: launching either claude or codex and accepting the prompt sets up the shared core, the Codex-side AGENTS.md guidance block, the Codex developer_instructions, the Worklist guard hooks, and the permission-menu surfacing hooks. The OpenCode plugin and its instructions entry are the exception: Setup writes them only where OpenCode can run, so projects whose users never run OpenCode get no .opencode/ directory. Antigravity's hook group and rules are the same kind of exception: projects whose users never run agy get no .agents/hooks.json or .agents/rules/.

How conventions.md governs each agent

app/__shell/conventions.md is the canonical project convention file. It governs Claude, Codex, OpenCode and Antigravity in different ways:

  • Claude: direct prompt binding plus enforcement. Setup copies that file to .claude/bram-conventions.md, adds an @-import block to CLAUDE.md, and registers the bram-guard PreToolUse hook. A new Claude session therefore reads the conventions file directly and is also mechanically blocked from unsafe worklist edits. Existing projects with the legacy .claude/xmlui-desktop-conventions.md path are migrated to the new name on the next Setup run.
  • Codex: repo-local AGENTS.md plus native hook enforcement. Setup writes a marked Bram block into repo-root AGENTS.md, installs top-level developer_instructions in ~/.codex/config.toml, and registers the Codex Worklist guard as a native PreToolUse hook. Codex launches also receive the same concise Worklist guidance as a startup seed. The app reinforces that with the shared local authorization record in resources/.worklist-authorization.json and the watcher-revert fallback as defense in depth.
  • OpenCode: an instructions entry plus plugin enforcement. Setup adds the conventions to the instructions list in .opencode/opencode.json, which OpenCode loads every session, and seeds the plugin described above as the Worklist guard.
  • Antigravity: always-on rules plus hook enforcement. Setup cuts the conventions into always-on rules (.agents/rules/bram-conventions-<n>.md, each under agy's 24,000-byte rule limit), which agy loads every session, and registers the hook group described above as the Worklist guard.

So the practical rule is: every agent is governed by the same Worklist conventions, with Claude reading the imported conventions file directly, Codex receiving the equivalent guidance through AGENTS, top-level developer_instructions, and its native hook adapter, OpenCode loading them as instructions under its plugin, and Antigravity loading them as always-on rules under its hook group.

The agents also differ in how they call Bram's Worklist lifecycle routes. Claude, OpenCode and Antigravity use the loopback HTTP endpoints directly (for Antigravity, behind agy's own command permission). Codex's sandbox refuses loopback connections (curl: (7) even when Bram is listening, #130), so it drives the identical lifecycle over a filesystem channel instead β€” writing resources/.worklist-intent.json and reading resources/.worklist-result.json, which the host dispatches through the same handlers as the HTTP routes.

The provider hooks validate direct edits to resources/worklist.json. Proposal authoring and iterate-time prose refinement are allowed there; mechanical prune / status-advance operations are expected to go through POST /__worklist/mutate instead. Every provider's guard rejects direct Worklist edits that remove items or change their status, which keeps the shared backend endpoint as the canonical state machine for advance / prune. The watcher-based fallback (compare old/new worklist snapshots, consult resources/.worklist-authorization.json, restore prior contents if the prune wasn't authorized) remains as defense-in-depth β€” it fires later than a native hook, but it covers the case where a hook fails to launch (e.g., the ~/.bram/bram-guard link is missing or points at a deleted build) or where a future provider integration lacks a comparable extension point.

The guard has no runtime dependencies: no Python, no interpreter on PATH. If ~/.bram/bram-guard is missing, Bram's Setup status reports the project as needing Setup, because the expected hook commands are derived from that link.

Configuration

.bram.json at project root is the primary config file. Legacy .xmlui-desktop.json is still accepted as a compatibility alias from Bram's prior name.

Startup

Bram autostarts an agent in the terminal at launch. Configure it under shell in .bram.json (the same keys Settings writes):

{
  "shell": {
    "agent": "claude",
    "continueLast": true
  }
}
  • agent β€” which provider to launch, claude, codex, opencode or antigravity (defaults to claude).
  • args β€” optional extra arguments appended to the launch command.
  • continueLast β€” when true, resume the most recent session (claude --continue / codex resume --last / opencode --continue / agy --continue) instead of starting fresh.
  • firstCommand β€” optional command typed into the agent once it's ready.

Launch options

For projects where the app is the point and Bram is plumbing, for example a repo teammates clone to read and annotate an XMLUI app, Bram can start minimized and open the app in your browser:

bram PROJECT_DIR --minimized --open-app=/architecture
  • --minimized starts with the Bram window minimized.
  • --open-app[=<route>] waits until the target app is being served, then opens it in the system browser, optionally at a route. The address is the project's declared server (http://localhost:<port><path>), or Bram's built-in server when the project has a root index.html.

The same, per project, in .bram.json, so a plain bram PROJECT_DIR does it (command-line flags win):

{
  "launch": { "minimized": true, "openApp": "/architecture" }
}

openApp is true for the app's own address, or a route. In the running app, the header's Open app β†— button opens the same address, and the β“˜ dialog shows it with a Copy button.

A command to run at each launch

A repo can name a helper for Bram to run each time it opens, such as a script that starts the app's back end:

{
  "launch": { "run": "./start.sh" }
}
  • It runs once per launch, from the project root (sh -c, or cmd /C on Windows), and Bram doesn't wait for it. Its output goes to .bram/bram-traces/launch-run.log, and the Status tab's Launch command section shows how its last run ended.
  • Bram doesn't own it. Unlike server, it isn't the app's address, and Bram doesn't stop it when it quits. Whatever it starts keeps running. So the command should return quickly and reuse what's already running, as Bram Studio's start.sh does.
  • It's a setting. Settings β†’ Launch command shows the command and a Run it each time Bram opens switch. Both are saved for this computer in .bram/settings.json, which overrides the repo's .bram.json. The switch is on by default when a repo names a command; to have it off, set "runAtLaunch": false beside run.
  • It asks first. A cloned repo's command doesn't run until you click Allow on the banner, on each computer. Allow runs it right away, too, and is kept for that exact command: change the command and Bram asks again. Don't allow turns the switch off. Turning the switch on in Settings counts as Allow.
  • Turning it off can stop it too. A repo can also name a stop command, "stop": "./start.sh --stop", which Bram runs when the switch goes off, but only after the run command was allowed on this computer. Bram can't stop the server itself, since the command detaches it. Quitting Bram stops nothing.

The Companion App section in Settings

Settings β†’ Companion App gathers these keys in one place, split by who sets them. From the repo shows what the app's makers committed for everyone (the name, greeting, prompts, launch and stop commands), each with where it came from; Propose a change… asks the agent for a Worklist item that edits .bram.json, since Bram never writes that tracked file itself. For this computer holds your preferences: run the launch command, start minimized, show the app inside Bram, and open it at launch. These save to .bram/settings.json over the repo's defaults.

A repo's own first message

The first time Bram wakes in a repo it hasn't seen, it says hello. A repo can supply that hello itself β€” useful when the repo is an app whose users arrive knowing nothing about Bram:

{
  "greeting": { "file": "docs/welcome.md", "name": "Bram Studio", "orientMe": false }
}

Bram introduces the text β€” "Hello β€” this is the agent that comes with Bram Studio. Its makers left you this introduction:" β€” then quotes the file (Markdown, up to 16 KB; name falls back to the folder name). Because .bram.json is committed, the message is there the moment the repo is cloned. "orientMe": false hides the Orient me tour offer for repos whose first-time reader is an end user rather than a developer. The file path must be inside the repo; a missing or escaping path falls back to Bram's own greeting.

Voice input

Bram supports two ways to dictate instead of type:

  • 🎀 Whisper buttons (recommended). Local, low-latency dictation via whisper-server. Click a 🎀 button in the agent pane (next to the message box, a feedback box, an issue comment) to start recording, and click again when you're done. Your words appear in the box as you speak, so when you stop there's no wait: the text is already there to edit or send. Speak over a selection and the words replace it; with no selection they go in at the caret. A pause doesn't start a new capital, and a question you continue across a pause stays one question. Live text uses the same whisper-server and model, so there's nothing extra to install. This is the better experience β€” lower latency, your choice of model, good transcription quality β€” but it needs local setup.
  • The agent's native /voice command. No local setup, but support varies by agent and platform. It's the zero-install fallback, and the working path where the Whisper button isn't proven yet.

Bram spawns the local whisper-server on the first record click and kills it on app exit β€” you don't manage the process; you just need the binary, ffmpeg, and a model file installed.

macOS

brew install whisper-cpp ffmpeg
mkdir -p ~/.local/share/whisper-models
curl -L -o ~/.local/share/whisper-models/ggml-small.en.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin

small.en is ~466 MB, English-only, real-time on Apple Silicon. Swap in a different model from the same Hugging Face repo for other size/accuracy/language tradeoffs. The bundled Info.plist declares NSMicrophoneUsageDescription, so first use triggers the standard macOS mic-permission prompt. The model path the app loads is ~/.local/share/whisper-models/ggml-small.en.bin.

Windows

On Windows, Bram launches whisper-server natively and talks to it through http://127.0.0.1:18080 from the WebView, exactly as it does on macOS. WSL is not used and not required. Earlier versions ran the engine inside WSL via wsl.exe bash -lc; if you set that up for a previous release, nothing inside the distro is reachable any more and the components below have to exist on the Windows side.

One-time setup. In PowerShell:

winget install Gyan.FFmpeg

# whisper-server: take whisper-blas-bin-x64.zip from a whisper.cpp release
# that publishes Windows binaries (the tagged vN.N.N releases often carry
# none; the dated build tags do). Extract it somewhere permanent and put
# that directory on your PATH β€” the exe needs its DLLs beside it.
mkdir "$env:LOCALAPPDATA\Programs\whisper"
# ...extract the zip's contents there, then:
[Environment]::SetEnvironmentVariable(
  'Path',
  [Environment]::GetEnvironmentVariable('Path','User') + ";$env:LOCALAPPDATA\Programs\whisper",
  'User')

# the model (~466 MB)
mkdir "$env:USERPROFILE\.local\share\whisper-models"
curl.exe -L -o "$env:USERPROFILE\.local\share\whisper-models\ggml-small.en.bin" `
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin

Relaunch Bram after changing PATH β€” a running process keeps the environment it started with, so the 🎀 will keep reporting whisper-server missing until you do.

That's the whole install. Bram handles starting and stopping whisper-server on its own β€” the first 🎀 click after launching Bram spawns it (the button shows ⏳ for a few seconds while the model loads), and every click after that is fast until Bram exits.

On speed. The blas build runs on the CPU. On a machine without a fast CPU this is noticeably slower than macOS, where whisper.cpp uses the GPU through Metal. If transcription drags, a smaller model (ggml-base.en, ggml-tiny.en) buys back most of the time for some accuracy. The cublas/cuda release assets are considerably faster but need an NVIDIA GPU; they do nothing on Intel or AMD integrated graphics.

Notes:

  • Mic permission. WebView2 inherits the standard Windows microphone prompt. On first 🎀 click Windows asks to allow mic access; click Yes.
  • Already running? If you happen to have whisper-server listening on port 18080 (e.g., started manually in another terminal), Bram detects it via a preflight probe and uses it instead of spawning a new one β€” no conflict.
  • Sanity check after install. In a new PowerShell window, where.exe whisper-server and where.exe ffmpeg should each print a path, and ls "$env:USERPROFILE\.local\share\whisper-models\" should show ggml-small.en.bin. If all three look right, relaunch Bram and you're done.
  • Upgrading from a WSL setup. The BRAM_WSL_DISTRO environment variable is gone and is ignored if set. A model inside your distro can be copied out rather than downloaded again: wsl cp ~/.local/share/whisper-models/ggml-small.en.bin /mnt/c/Users/<you>/.local/share/whisper-models/ggml-small.en.bin.

Linux

The same setup is expected to work on Linux, using the host process path and port 18080.

Target app

An optional pane above the agent pane, off by default β€” a project iframe for previewing your app inside Bram. Most people run their app in their own server and view it in their own browser, so it stays hidden unless you turn it on (Settings β†’ UI β†’ "Show target app"). It's handy for a very simple app or a quick check, not the common case. When enabled, Bram runs a basic static webserver and reloads the pane automatically as project files change.

Serving a real backend: fixed origin, project server, URL parameters

Working with a real backend

Bram binds the target app HTTP server to 127.0.0.1:<random-port> (it uses port 0 and lets the OS pick). That's fine for projects that talk only to public APIs or static files. It breaks when your project needs a fixed origin β€” OAuth callbacks, CORS allowlists, hardcoded API base URLs.

Compatibility note. The target app is an iframe. Backends that send X-Frame-Options: DENY or Content-Security-Policy: frame-ancestors 'none' (common for security-sensitive admin UIs) cannot be loaded into the target app regardless of port. Workarounds: configure the backend's dev mode to relax those headers, or serve the UI files via a permissive dev server (e.g. npx http-server) while keeping the real backend running for API calls. Otherwise, open the project in a standalone browser.

Declare a project server

Add .bram.json at the project root:

{
  "server": {
    "command": "python3 -m http.server 8080",
    "cwd": "xmlui",
    "port": 8080,
    "path": "/"
  }
}
field meaning
command shell command to bring up the project's server. Run via sh -c (Unix) or cmd /C (Windows).
cwd working directory for the command, relative to the project root. Optional; defaults to the project root.
port TCP port the iframe should target. Bram probes this port at startup.
path URL path appended to http://localhost:<port> for the iframe. Optional; defaults to /.

At startup, Bram:

  • probes 127.0.0.1:<port>. If it's already listening, it logs a notice and reuses the running server (useful when you start the server manually for log visibility);
  • otherwise spawns command in cwd, with stdout/stderr forwarded to Bram's own stderr (prefixed [server]);
  • waits up to 5s for the port to come up, then points the target app iframe at http://localhost:<port><path>. The iframe retries once on load error to absorb the case where the server takes a moment to bind;
  • on app exit, kills the spawned child.

The agent pane continues to load from Bram's internal loopback server regardless of this setting.

The app-under-test does not need to be an XMLUI app β€” .bram.json is Bram's own config file, separate from XMLUI's config.json. Legacy .xmlui-desktop.json remains supported.

URL parameters

Use query strings to parameterize the frontend without rebuilding β€” e.g. ?city=santarosa to switch tenant. Pass them on the command line to your server's command or bake them into path (e.g. "path": "/?city=santarosa").

Working example

community-calendar uses .bram.json for GitHub-OAuth-via-Supabase development. See docs/app-architecture.md for the Supabase URL-Configuration setup that requires the fixed localhost:8080/** origin.

Fallback: the redirect pattern

If you can't add a config file (e.g. you're working in a repo you don't own), you can still target a fixed origin by adding a self-redirect at the top of the project's index.html:

<script>
  if (location.hostname === '127.0.0.1' && location.port !== '8080') {
    var devQuery = location.search || '?defaultParam=value';
    location.replace('http://localhost:8080' + location.pathname + devQuery + location.hash);
  }
</script>

Run your frontend on a known port in a separate terminal (python3 -m http.server 8080) and launch Bram from the project root. Its iframe loads the random-port URL once, your script bounces it to localhost:8080. .bram.json is the preferred mechanism β€” it auto-spawns the server, shows logs, and doesn't pollute the project's HTML.

Service workers, auth callbacks, and DevTools

Service workers don't register on macOS/Linux

The target app iframe loads at tauri://localhost, and the WebKit engines on macOS (WKWebView) and Linux (WebKitGTK) don't treat custom-scheme origins as secure contexts. Service-worker registration silently fails there, so project features that depend on a service worker β€” Mock Service Worker (MSW), XMLUI's in-page apiInterceptor, custom offline caches β€” won't activate inside Bram on those platforms. Windows uses WebView2 (Chromium) with the http://tauri.localhost form, which is a secure context, so service workers register normally there.

Apps that hit a real HTTP backend are unaffected; the constraint only applies to in-page request interception. If you're developing against MSW or apiInterceptor, run your project in a regular browser tab at localhost:8080 while keeping Bram pointed at the same server for the agent loop.

Auth callbacks won't reach the target app

The target app webview has its own browser storage, isolated from your system browser's storage at the same origin. That breaks any auth flow that hands off to the system browser and expects a session to come back into the webview:

  • Magic links in email. Clicking the link opens your default browser, completes auth there, and stores the session in the browser's localStorage. The target app never sees it.
  • OAuth provider redirects that leave the webview have the same shape β€” the callback session lands in the wrong storage.

Even when the redirect script above lines the target app up on localhost:8080, that origin's storage in the Tauri webview is a different store from localhost:8080 storage in Safari or Chrome.

Workaround for email auth: send a one-time code, not a link. If your backend supports OTP codes (Supabase, Auth0, Clerk, Cognito all do), have the user paste the code from the email into a field in your dialog. No callback URL, no cross-context handoff. Works identically in the browser and inside Bram.

For Supabase specifically:

  1. Add {{ .Token }} to the Magic Link email template (Supabase dashboard β†’ Authentication β†’ Email Templates) so the email includes the 6/8-digit code. Docs: https://supabase.com/docs/guides/auth/auth-email-templates
  2. After signInWithOtp, render a code-input field and call verifyOtp({ email, token, type: 'email' }). Docs: https://supabase.com/docs/guides/auth/auth-email-passwordless
  3. The existing onAuthStateChange handler fires on verifyOtp success β€” no other plumbing needed.

community-calendar implements this in xmlui/components/SignInDialog.xmlui and xmlui/shell.js (window.signInWithEmail + window.verifyEmailOtp).

DevTools

Tauri uses the platform's native webview, so the DevTools you get inside the target app depend on the OS:

Platform Webview DevTools
macOS WKWebView Safari Web Inspector
Linux WebKitGTK Safari Web Inspector
Windows WebView2 (Chromium) Chromium DevTools

To open them, right-click inside the target app β†’ Inspect Element in dev/debug builds (cargo run or cargo tauri dev). Release builds disable DevTools by default. The execution context belongs to the target app document specifically. The shell window and the right pane both load at tauri://localhost (the parent shell directly, the target app via the scheme handler that proxies project content under /__project/*), so they share an origin and therefore a localStorage / IndexedDB partition β€” a console session in either reaches the same storage. A regular browser tab pointed at the project's own localhost:8080 server, by contrast, is a different origin with its own independent storage.

WebKit quirks worth knowing

The macOS/Linux Web Inspector behaves differently from Chromium's DevTools in a few ways that bite when you're testing auth flows:

  • const/let redeclaration throws. Pasting const sb = … a second time in the same console session yields "Unexpected identifier 'sb'. Expected ';' after variable declaration." Chromium silently redeclares; WebKit doesn't. Wrap repeated snippets in an async IIFE ((async () => { … })();) so the bindings are scoped to each call.
  • Frame/context switcher is sparser. The dropdown that picks the execution context (top-level vs iframes) often won't expose every frame the page contains. Right-clicking inside the frame you actually want and choosing Inspect Element is more reliable than picking it from the dropdown.
  • Service-worker and storage panels are less complete than Chromium's. If you need to inspect IndexedDB or service-worker scope details, run the same project in a regular Chrome/Edge tab pointed at localhost:8080.

If you'd rather use Chromium DevTools on macOS/Linux, you can run your project in a regular browser tab pointed at its localhost:8080 origin β€” but remember that the tab's localStorage is a separate store from the target app's (the target app is at tauri://localhost, a different origin), so a session created there won't carry into Bram.

Build

The frontend is static β€” no bundler, no package.json. The only build step is the Tauri/Rust build.

From src-tauri/:

  • Dev: cargo run (or cargo tauri dev with the Tauri CLI)
  • Release: cargo tauri build

Tauri docs: https://tauri.app/develop/, https://tauri.app/distribute/.

Calling Bram from project code

Because the target app is same-origin with the parent shell (tauri://localhost), project code can reach the Tauri command bridge directly through window.parent β€” no postMessage shim needed:

const { invoke } = window.parent.__TAURI__.core;
const url = await invoke("get_right_pane_url");

Use this when an XMLUI app embedded in the target app needs to read filesystem state, hit one of Bram's __-prefixed loopback endpoints, or invoke any of the Rust IPC commands. The helpers.js script loaded by the embedded XMLUI exposes (toShell, toTurn, openExternal, logToHost) is built on top of this bridge β€” opt into the helpers for project XMLUI apps that need to talk back to the running agent.

Layout

  • orientation/ β€” this repo's target app, an overview and architecture site. The root index.html redirects to it.
  • app/ β€” parent shell (Tauri webview entry, terminal wiring, vendor scripts, and __shell/helpers.js that the target app includes).
  • src-tauri/ β€” Rust backend (PTY for the terminal, custom tauri:// URI scheme handler that proxies the target app iframe to the project's HTTP server, filesystem watcher, IPC handlers).
  • scripts/ β€” auxiliary scripts.

About

No description, website, or topics provided.

Resources

Security policy

Stars

66 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages