v0.8.4

Prerequisite

Run bram from a folder that is a git repository. A standalone local repository works; one hosted on GitHub or GitLab is better, because Bram's issue features (the Issues tab, closing issues on push) use the issues there.

Install

macOS / Linux

curl -fsSL https://github.com/judell/bram/releases/download/v0.8.4/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.

Confirm the install:

bram --help

Windows

From PowerShell:

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

From Command Prompt:

curl.exe -fsSL https://github.com/judell/bram/releases/download/v0.8.4/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.

Confirm the install in a new PowerShell window:

bram --help

Audit-friendly manual install

# Download artifact + checksums
curl -fsSLO https://github.com/judell/bram/releases/download/v0.8.4/SHA256SUMS
curl -fsSLO https://github.com/judell/bram/releases/download/v0.8.4/bram-macos-arm64.tar.gz   # or your platform
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf bram-*.tar.gz
sudo mv bram /usr/local/bin/

Other platforms: replace bram-macos-arm64.tar.gz with bram-macos-intel.tar.gz, bram-linux-amd64.tar.gz, or bram-windows-amd64.zip.

On macOS, if installing from a browser download instead of curl, also run:

xattr -d com.apple.quarantine bram

On Windows, use Expand-Archive on bram-windows-amd64.zip, then move bram.exe to a directory on your PATH.

Release notes

Bram's working files leave your project's resources/ folder. At the first launch after this update, Bram moves its state into .bram/, a dot-folder that ignores itself, so it no longer collides with a project's own resources/ and can't be staged by accident. Personal settings move with it, into .bram/settings.json. The pane is quicker too: buttons that sat silent for up to 30 seconds answer at once, a Worklist change no longer re-renders the whole pane, and a gate click made while the agent is working is queued instead of lost.

50 commits since v0.8.3. Refs #466, #467, #469, #470, #474.

What happens when you update

The first launch of 0.8.4 checks each project's resources/ folder before it opens anything else.

• Only Bram's files there: the folder is renamed to .bram/ in one step, and a .migrated-from note is left inside it. Nothing else changes in your project, and the agent is told on its next turn that resources/ paths in earlier turns now live under .bram/.
• Your own files there too: a banner offers Move Bram's files or Not now. Moving takes only Bram's entries, at the next launch, and leaves yours in resources/. Not now can be reversed from the Status tab (Move at next launch).
• Bram's files tracked in git: nothing moves. Status says which, and a Worklist item is the way to untrack them. Bram never edits a tracked file itself.
• An item mid-claim: the move waits for the next launch. An approval that's already finished, or whose item is gone, no longer holds it up.
• On Windows, a file held open under the folder blocks the rename. Bram retries for about 2 seconds, keeps resources/ for this run, and tries again at the next launch. It never moves part of the folder.

The Status tab shows what moved, what was left and why, for each project. bram --state-dir-plan <root> prints the same without opening a window.

Settings. Personal settings now live in .bram/settings.json, and the root .bram.json is for settings a team shares (server).

• An untracked root .bram.json is folded into .bram/settings.json at startup and removed. Where both have a value, settings.json wins.
• A tracked root .bram.json is left alone. If it holds personal settings an earlier Bram wrote, Bram asks the agent once to propose an item that moves them out and restores the file to what's committed.

Serving. /__bram/ serves the state folder. /resources/ still works in this release as an alias, trying the old folder first, so a target app's own resources/ files still load.

The pane

• Buttons answer at once. Restart, Setup, the Commits tab's Pull, and deleting or renaming a session waited up to 30 seconds after the work was done before showing any result. They're now plain requests that show "…" or "Restarting…" while they run and answer as soon as the host does. The delay is inside XMLUI's APICall and is reported upstream as xmlui-org/xmlui#3956. The state-move buttons got the same treatment.
• A Worklist change no longer re-renders the whole pane. Seven data sources moved into the components that show them. Across 10 Worklist changes, whole-pane re-renders went from 166 to 0 on Windows and from 86 to 0 on macOS, and render time fell 46% on macOS (#470 (a), xmlui-org/xmlui#3941).
• A compaction is one line in the Transcript, such as "Context compacted (auto, 969k → 7k tokens) · 192 lines · Show", instead of the full hand-off text. A Settings switch starts them expanded (#470 (b)).
• The footer shows no model while a new session is still starting, instead of pairing the new provider with the old session's model, and it hides the old session's subagent chips until the new one is confirmed.
• Quotes inside an AskUserQuestion answer are kept in the Transcript instead of cutting it short.

The Worklist gate

• A click made mid-turn is queued. Start, Start & commit or Commit, clicked while the agent is working, is held and delivered when the turn ends. The row shows one line and a Cancel. The approval is recorded on delivery, so its time limit starts then. A queued click is dropped if the pane reloads.
• Pause enforcement, per repo (Claude). A Settings switch pauses the Worklist's requirement that edits belong to an approved item, for Claude in that repo. The header shows a pause icon while it's on. Other guard checks still apply, and Codex, OpenCode and Antigravity stay enforced (#466).
• Delegated work keeps its item locked (Claude). When the agent hands an item to a background subagent, the row stays claimed until the subagent stops, so Commit and Drop can't run under it and its edits are credited to the item. The strip names the subagent, and Release frees a stuck hold.
• A commit waits out another process's git lock for up to 2 seconds before refusing, counting git's own time against that limit.

Windows

• A CLI installed after Bram started is found. The terminal's PATH now merges the registry's current entries, and a launch that fails because the command isn't on PATH says so.
• The sign-in fallback offers the agent you just left, instead of the first one in a fixed order.
• Smart App Control guidance is rewritten from Microsoft's own documentation.
• Build scripts warn before building when free disk is low or the target folder is large.

Security

• The loopback root no longer serves .git or other dot paths. A request for /.git/config or any path with a segment starting with . (or .., a leading slash, backslash or drive colon) answers 404 and is traced.

Orientation sites

• Bram's own orientation site is reworked: the Worklist diagram leads, drawn as two loops, then screenshots of a real lifecycle, and citations open inside the site (#467).
• Setup keeps every repo's site engine current from the template in app/__shell/reference/orientation-template/. It refreshes only files marked as the engine, and keeps each site's own content.
• The home page lists cited work in one table: date, link, source.

Under the hood

• Every script finds the state folder through one resolver (scripts/bram_state.py, scripts/bram-state.sh), 29 scripts in all.
• Demo instances hydrate into .bram/; --legacy-layout keeps the old layout for exercising the mover.
• scripts/pane-age-health.py reports pane slowness by pane age, active time and session size. Its answer so far: a sluggish pane is fixed by a reload, not a new session.
• The subagent roster finds the model past large attachment records.
• Acceptance: the move was run on XMLUI, Bram Studio, community-calendar and Bram itself on macOS, and on Bram and a demo instance on Windows, with the before and after recorded on #469. The full Rust suite passes on both platforms (1390 on Windows).

Known rough edges

• Other pane actions still use XMLUI's APICall. If one seems to hang for about 30 seconds after the work is done, that's xmlui-org/xmlui#3956.
• Setup still edits a tracked AGENTS.md. That waits on #393.
• On Windows, the Status tab can show a path with mixed separators (…\resources/). It's cosmetic.
• scripts/pane-age-health.py doesn't find the trace in .bram/ unless given --trace-dir .bram/bram-traces.
• Pausing enforcement has no lock of its own: nothing stops an agent from setting the flag. This is recorded in docs/authorization.md.
• Pause enforcement and delegated-claim retention are Claude only.
• v0.8.3's known rough edges still apply unless listed above as fixed.

Credits

István Novák (@Dotneteer) raised the resources/ collision from XMLUI (#469), and XMLUI was one of the four projects the move was accepted on. Raymond Yee (@rdhyee) asked for a way to pause Bram in a repo (#466); the per-repo pause for Claude is the first piece. Andrew Schulman (@aschulman42-cell) filed the agent-pane findings in #470: the pane's responsiveness and the collapsed compaction line are the first two answered here. Josh Goodman (@jogoodma) measured XMLUI's render passes on the community-calendar app (xmlui-org/xmlui#3941) and found that what was left was the cost of re-rendering whole component trees, which is what moving the pane's data sources into their components addresses. István's earlier measurements on that thread started it. Margaret-Anne Storey (@margaretstorey) asked for a private research diary (#476), which has opened a discussion of where Bram's state outside git should live.

Change log

• Demo script sends git its stdin as bytes, so Windows keeps the board
• Port test waits for the dropped owner's port to close
• Release v0.8.4
• The index.lock wait counts git's own time against its budget
• An untracked root .bram.json folds into .bram/settings.json
• Pane buttons answer at once: five APICalls become plain fetches
• The loopback root no longer serves .git or other dot paths
• The tracked-settings note picks its recipe from HEAD's .bram.json
• Stop tracking the root .bram.json; personal settings live in .bram/
• The state-folder mover ignores a finished authorization
• Bram asks the agent to clean up a dirty tracked .bram.json
• Status says the state folder moved, instead of "would move"
• State-move banner says why Bram is moving its folder
• Demo fixture hydrates into .bram/; scenario branches keep their layout
• State-move buttons answer in milliseconds, not 30 s
• After the move: sessions told, /__bram/ served, instructions folder-neutral
• Mixed state folders: Move Bram's files or Not now, applied at next launch
• Settings move into .bram/settings.json; the root .bram.json is left alone
• Startup moves Bram's state folder from resources/ to .bram/
• Setup harness expects the Antigravity matcher that covers MCP tools
• Transcript keeps quotes inside AskUserQuestion answers
• Sign-in fallback offers the agent you just left
• Delegated claims: retention moves into the claim's choke points
• Delegated work keeps its item's claim until the subagent stops
• pane-age-health.py: pane slowness by pane age, active time and session size
• Commit route waits out a held index.lock; test-drive trace follows the archive
• Subagent roster finds the model past large attachment records
• Build scripts warn on low disk and a large target dir
• Scripts find Bram's state folder through one resolver
• Windows first wave for 0.8.4: registry PATH, footer model, collapsed compaction
• Home page drops the Demo heading above the video
• Home page lists cited work in one table: date, link, source
• Pane data sources move into the components that show them
• A gate click taken mid-turn is queued until the turn ends
• Smart App Control guidance grounded in Microsoft's own documentation
• Footer hides subagent chips while a new session is unconfirmed
• Setup keeps orientation site engines current from the template
• Orientation template: port the site engine from Bram's own site
• Orientation site: screenshots tell the Worklist story; citations open in-site
• Pause Worklist enforcement for Claude, per repo (v1)
• Orientation site: the Worklist caption names declared files
• Orientation site: the Worklist diagram leads, drawn as two loops
• Orientation site: a dialog reads the real doc instead of retelling it
• Orientation site: the overview no longer describes arrow styles
• Orientation site: every arrow solid; say in words what depends on a person
• Orientation site: the providers diagram is a data flow diagram
• Orientation site: three real pages, and the providers drawn as one kind of thing
• Orientation site: drop the machine name from its signatures
• Orientation site: say what the system diagram shows, in one sentence
• Orientation site: drop "main thread" from its two signatures
• Orientation site and homepage: one calm light palette, no dark mode
• Orientation site: Start, Diagrams, Overview; the owner's own words first

Troubleshooting

• bram not found on PATH. Re-run the install script, or follow its printed PATH advice.
• macOS Gatekeeper blocks first launch. The install script clears the quarantine xattr automatically. For browser downloads, run the xattr -d com.apple.quarantine command above.
• Linux/WSL: error while loading shared libraries: libwebkit2gtk-4.1.so.0. Tauri's WebView dynamically links WebKitGTK. On Ubuntu/Debian 22.04+, install the runtime libs with sudo apt install -y libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1 librsvg2-2. WSL2 also needs WSLg (ships with Windows 11 and recent Windows 10 builds).
• Tool Descriptions show nothing (trace says reason=no-key). The optional Haiku-generated intent headers need ai.describeCommands: true in .bram.json and ANTHROPIC_API_KEY visible to Bram's own process. macOS/Linux: export it in your shell profile and launch bram from a terminal — a Dock/Finder-launched Bram doesn't read shell profiles. Windows: set a user-scoped environment variable — setx ANTHROPIC_API_KEY "sk-ant-…" (or System Properties → Environment Variables) — then restart Bram and any open terminals; a PowerShell $PROFILE export is not enough, because it reaches shell-launched processes only, not a GUI-launched Bram. One user-scoped variable serves Bram's description calls and the agent CLIs inside Bram's PTY alike. Note: when Claude Code notices the key and asks whether to use it, answer No — accepting switches the CLI from your claude.ai login (and disables claude.ai connectors) to pay-as-you-go API billing. The key is stored in plaintext (HKCU\Environment on Windows, your dotfile elsewhere) — same posture either way; treat it with dotfile-grade care.
• Update. Re-run the install command.
• Uninstall. Delete the binary from /usr/local/bin/bram, ~/.local/bin/bram, or ~/bin/bram.exe.