Beacon Split
An agent-first development workspace.
Beacon is not another code editor. It is the surface you work from when your
main collaborator is Claude Code — with Codex beside it, if you want a second
opinion — and you have several projects open at once.
Website · Install · What it does · Building it · Contributing · Architecture
The unit of the application is not a file. It is:
Workspace → Project → agent session
Everything is pointed at one goal: flow, speed, and as little context
switching as possible. Every frequent action is a keystroke, or at most a
click or two. If something you do daily takes a trip through three menus, that
is a bug.
What it does
Runs the real thing. A claude session and a shell per project, each in its
own PTY. Beacon does not reimplement Claude Code — colours, prompts,
permissions, selection and scrolling are whatever the CLI does, because it is
the CLI.
A second agent, if you want one. Codex gets a panel of its own (⌘⇧O) and
its own conversations, and can work in the same project at the same time as
Claude Code. It starts hidden, and without it installed nothing else changes. A
project can also give each agent a git worktree of its own, so two agents never
save over each other's files — off unless you turn it on.
Sessions outlive the window. A background daemon owns them. Close Beacon and
your work keeps running; open it again and it reattaches, scrollback intact.
Tells you which project needs you. With three projects open, the expensive
thing is not switching tabs — it is a permission prompt going unseen for twenty
minutes. Tabs report what Claude is actually doing, from Claude Code's own
hooks rather than guessed from terminal output, and a project that stops and
waits can say so with a system notification.
Shows what a session is costing. How much of the five-hour allowance is
left, and how full each project's context is — enough to decide which project
to spend the rest of it on, and when a conversation is worth clearing.
A drawer for things to copy. Ask Claude for an environment variable, a
command to run elsewhere, or the body of an email, and it lands in a drawer on
the right edge with a copy button — instead of being selected out of a
terminal. It works through one MCP tool that Beacon passes to each session
itself, so there is nothing to install and nothing to connect.
Files, editor and git, at the size they deserve. A file tree with the
operations you expect, a light editor, a .env view that keeps values hidden
until asked and adds or edits variables in place, and git status, diff, stage
and commit. Deleting moves to the trash. Nothing here is trying to become an
IDE.
Keyboard first. A command palette, quick open, and shortcuts you can
rebind. Layouts are a tree of splits with four presets, and every divider
drags.
Yours to look at. Light and dark, how much of the desktop shows through the
window, and whether what shows through is frosted.
Install
Beacon runs on macOS, Windows and Linux. Releases carry an Apple Silicon and an
Intel build for macOS — Apple Silicon is the one it is developed and tested on
— an x64 installer for Windows 10 and 11, and for Linux an x86_64 AppImage and a
.deb, which the Arch package is made from.
From a release, on macOS — download the latest, open the
.dmg, drag Beacon to Applications.
macOS will refuse it the first time with "Beacon Split is damaged and can't be
opened". It is not damaged: the build is not signed with an Apple Developer ID.
Clear the quarantine flag once:
xattr -dr com.apple.quarantine "/Applications/Beacon Split.app"
That removes a check macOS applies to software it cannot verify. It is a
reasonable thing to do for a build you chose to download; it is not something to
do casually. See docs/DISTRIBUTING.md for the
alternatives.
From a release, on Windows — run the -setup.exe from the latest
release. It installs for your user only and needs no administrator.
The installer is not code-signed, so SmartScreen will say "Windows protected
your PC" the first time: More info → Run anyway. Beacon's window has its
own minimise, maximise and close buttons at the top right, and frosting uses
Windows 11's Mica.
From a release, on Linux — download the .AppImage from the latest
release, make it executable and run it:
chmod +x 'Beacon Split_'*'_amd64.AppImage'
./'Beacon Split_'*'_amd64.AppImage'
It carries its own GTK and WebKit and needs nothing installed. It is built on
Ubuntu 22.04, so it wants glibc 2.35 or newer — every current distribution. As
on Windows, the window has no system title bar: Beacon draws its own minimise,
maximise and close buttons at the top right. Translucency needs a compositor;
without one the window is simply opaque.
From a release, on Arch Linux — install beacon-split-bin, which
repackages the release's .deb against Arch's own GTK and WebKitGTK:
git clone https://github.com/hxst1/Beacon-Split.git
cd Beacon-Split/packaging/aur/beacon-split-bin
makepkg -si
Unlike the AppImage, it runs natively on Wayland, and it is updated by
pacman rather than by Beacon itself. With NVIDIA's driver Beacon turns off
WebKitGTK's DMA-BUF renderer on its own (ADR-096); set
WEBKIT_DISABLE_DMABUF_RENDERER=0 to keep it if your driver handles it.
The notification sounds go through the webview, which on Linux plays audio
through GStreamer — an optional dependency of webkit2gtk that distributions
do not install by default. Without gst-plugins-good the sounds are silent and
nothing else changes; system notifications are unaffected.
From source — see Building it. A build made on the machine
it runs on is never quarantined.
What you need installed
Beacon runs the tools you already have rather than bundling its own, and checks
for them on first run. Anything missing is explained in the panel it affects,
and in Settings → Requirements.
| Needed for | Install |
|---|
| Claude Code | The Claude panel — the point of the application | curl -fsSL https://claude.ai/install.sh | bash |
| Git | The Git panel, and Quick Open honouring your ignore rules | xcode-select --install |
| Codex (optional) | The Codex panel | brew install --cask codex or npm install -g @openai/codex |
On Windows:
| Needed for | Install |
|---|
| Claude Code | The Claude panel | irm https://claude.ai/install.ps1 | iex in PowerShell |
| Git for Windows | The Git panel — and Git Bash, which Claude Code prefers for its commands | winget install --id Git.Git -e --source winget |
| Codex (optional) | The Codex panel | npm install -g @openai/codex |
On Linux:
| Needed for | Install |
|---|
| Claude Code | The Claude panel | curl -fsSL https://claude.ai/install.sh | bash |
| Git | The Git panel, and Quick Open honouring your ignore rules | your distribution's own — sudo pacman -S git, sudo apt install git |
| Codex (optional) | The Codex panel | npm install -g @openai/codex |
Settings → Requirements offers the command for the package manager you actually
have, rather than guessing at your distribution.
An agent installed with npm works too: Beacon looks through npm's .cmd shims
to the program they start.
Claude Code needs a Pro, Max, Team or Enterprise account, and you sign in by
running claude once in a terminal. Codex needs a ChatGPT plan or an API key,
and signs in the same way, with codex. Beacon does not handle signing in — it
runs the CLIs you already use.
Keyboard
⌘ on macOS, Ctrl on Linux and Windows. All of these are editable in
Settings → Keyboard. In a terminal on Windows, Ctrl+C copies when something is
selected and interrupts when nothing is, and Ctrl+V pastes; Ctrl+Shift+C and
Ctrl+Shift+V always copy and paste.
| |
|---|
⌘K | Command palette |
⌘P | Quick open |
⌘, | Settings |
⌘1 … ⌘9 | Switch to project tab |
⌘⇧[ / ⌘⇧] | Previous / next project |
⌘E / ⌘G / ⌘O / ⌘J | Toggle Files, Git, the editor, the terminal |
⌘⇧O | Toggle the Codex panel |
⌥⌘← / ⌥⌘→ | Move the keyboard between panels |
⌘↩ | Fullscreen the focused panel |
⌘⇧R | Restart Claude |
⇧↩ | New line in a Claude or Codex prompt, instead of sending it |
⌘S / ⌘F / ⌥⌘G | Save / find / go to line, in the editor |
Building it
You need Node 20+, pnpm 10+, Rust 1.85+, and the Xcode command line tools. On
Windows, instead of Xcode: the Rust MSVC toolchain (winget install Rustlang.Rustup) and Visual Studio's C++ build tools ("Desktop development with
C++"); the WebView2 runtime ships with Windows 11.
On Linux, instead of Xcode: a C toolchain, and the webview Tauri draws into,
which the system does not ship. On Arch:
sudo pacman -S --needed base-devel rustup webkit2gtk-4.1 patchelf
rustup default stable
On Debian or Ubuntu the same list is build-essential libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev libxdo-dev libssl-dev patchelf.
On a rolling distribution pnpm app:build stops after the executable and says
why: the tool Tauri drives to put an AppImage together needs a gdk-pixbuf
layout that gdk-pixbuf 2.44 no longer produces. The release AppImage is built
on Ubuntu in CI, which is where it belongs anyway — see
ADR-093. target/release/beacon-split runs.
git clone https://github.com/hxst1/Beacon-Split.git
cd Beacon-Split
pnpm install
pnpm app:dev
| |
|---|
pnpm app:dev | Run it, with the frontend hot-reloading |
pnpm app:build | Produce a .app and a .dmg — on Windows an installer .exe and an .msi, on Linux an .AppImage or, where linuxdeploy cannot run, the executable alone |
pnpm check | Typecheck, tests, rustfmt, clippy — what CI runs |
Where things live
crates/beacon-core/ Domain model, config, sessions, git, files. No Tauri, no UI.
crates/beacon-daemon/ Owns the PTYs, so sessions outlive the window.
src-tauri/ Desktop shell: window setup and the IPC surface.
src/ React frontend.
ipc/ The only module that talks to Tauri.
app/ Window shell: title bar, workbench, panels, shortcuts.
features/ Everything else, one directory per thing.
docs/ Architecture, roadmap, and every decision worth recording.
Two rules hold the shape:
beacon-core never depends on Tauri. It is why session management could
move into a daemon without touching the UI.- The UI never imports
@tauri-apps/api outside src/ipc/. When the
transport changes, one directory changes.
Your files
Removing a project from Beacon removes it from Beacon. It never deletes a
repository. Deleting a file moves it to the system trash, and every file path is
confined to its project — absolute paths, .., and symlinks pointing outside
are all refused.
.env values are never logged, never cached outside the file they came from,
and never sent anywhere.
Contributing
Genuinely welcome — read CONTRIBUTING.md first. The short
version: the scope is deliberately narrow, docs/DECISIONS.md explains why
things are the way they are, and a change that contradicts one of those
decisions is welcome as long as it says which one and why it was wrong.
Documentation
Claude Code, and Anthropic
Beacon is not affiliated with, endorsed by, or partnered with Anthropic.
It runs Claude Code as Anthropic publishes it. Beacon does not bundle it,
modify it, patch it, or restrict any way it can sign you in — it starts the
claude on your PATH in a terminal, the same one you would start yourself.
ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL and the Bedrock and Vertex settings
are passed straight through for that reason.
You sign in to Claude yourself, by running claude once, through
Anthropic's own flow. Beacon never asks for, handles, stores, proxies or
forwards a Claude account credential or session token, and it cannot: it has no
account system, no server, and no idea who you are. Your usage is billed to
you, under your own agreement with Anthropic.
That also means Beacon is for one person on their own machine. Do not put it
somewhere other people reach your signed-in Claude — sharing an account is
against Anthropic's terms, and everyone using Claude Code needs their own
subscription or API key. Your own devices reaching your own machine is a
different thing, and fine.
Your use of Claude Code is governed by Anthropic's terms, and its
usage limits assume ordinary individual use. Beacon opens several projects at
once because switching between them costs you attention — not to multiply what
one person would otherwise do.
Claude and Claude Code are trademarks of Anthropic PBC. Beacon uses those names
only to say what it runs.
The same goes for Codex: Beacon is not affiliated with OpenAI, runs the codex
you installed, and never touches how it signs you in. Codex and OpenAI are
trademarks of OpenAI.
Licence
AGPL-3.0.
Use it, change it, run it however you like. If you distribute a modified
version — including running one as a service other people use — you have to
publish your changes under the same licence. That is the whole point: work put
into Beacon stays available to everyone using it.
The copyright holder is not bound by this and may also license Beacon under
other terms. Contributions are made under the same licence and grant that
right; see CONTRIBUTING.md.
