Forge — a browser-accessible Claude Code workstation (NixOS module)
  • HTML 54.3%
  • Python 26.3%
  • Nix 18.5%
  • JavaScript 0.9%
Find a file
Pedro Araújo 092cfdc265
All checks were successful
CI / check (push) Successful in 1m1s
Hide the worktree × on mobile (#57) (#58)
Reviewed-on: #58
2026-11-12 06:51:58 +00:00
.forgejo ci: add Forgejo Actions workflow (nix flake check + launcher parse) (#9) 2026-07-17 11:47:23 +01:00
modules Prune: delete merged branches and offer to force dirty worktrees (#56) 2026-11-09 10:44:46 +00:00
web Hide the worktree × on mobile (#57) (#58) 2026-11-12 06:51:58 +00:00
.gitignore Forge: browser Claude Code workstation as a reusable NixOS flake 2026-07-09 14:51:09 +01:00
CLAUDE.md docs: add CLAUDE.md — track work as Forgejo issues 2026-07-15 09:30:28 +01:00
flake.lock Forge: browser Claude Code workstation as a reusable NixOS flake 2026-07-09 14:51:09 +01:00
flake.nix Worktree sessions under a channel (#51) 2026-10-31 12:13:37 +00:00
LICENSE Forge: browser Claude Code workstation as a reusable NixOS flake 2026-07-09 14:51:09 +01:00
README.md Prune: delete merged branches and offer to force dirty worktrees (#56) 2026-11-09 10:44:46 +00:00

Forge

A browser-accessible Claude Code workstation for NixOS.

Forge turns a headless NixOS box into a web app where each of your repos gets its own persistent terminal ("channel") running Claude Code — reachable from any browser, phone included. Close the tab, come back later, the session is still there.

channels in a sidebar, a terminal in an iframe

What you get

  • One channel per repo — each is a ttyd web shell exec'ing into a persistent tmux session that runs Claude Code (or any command you choose). Detach/reattach across browser disconnects for free.
  • A launcher served by nginx on port 80: a sidebar of channels, an Alt+K command palette (switch channels, split panes, open lazygit), a JuiceSSH-style keybar for touch devices (Esc/Tab/arrows/Ctrl-chords), and an upload dropzone (drop/paste a file → it lands on the box and its path is typed into the active session).
  • Tuned for the browser terminal: extended keys (Shift+Enter, Ctrl-chords), mouse scroll, and OSC 52 clipboard all work through xterm.js.
  • One route to expose: everything is same-origin behind nginx:80, so you put a single reverse-proxy route (+ your auth of choice) in front of it.

Requirements

  • NixOS with flakes enabled.
  • nixpkgs unstable — the default sessionCommand uses pkgs.claude-code, which lives in unstable. On stable nixpkgs, set sessionCommand to your own binary/wrapper.
  • A real login user on the host to own the sessions (Forge does not create it).

Usage

Add Forge as a flake input and enable the module on the host:

{
  inputs.forge.url = "git+https://git.rdbytes.pt/pedromcaraujo/forge?ref=main";
  # (or github:<you>/forge once mirrored)

  outputs = { self, nixpkgs, forge, ... }: {
    nixosConfigurations.my-workstation = nixpkgs.lib.nixosSystem {
      modules = [
        forge.nixosModules.forge
        ({ ... }: {
          myServices.forge = {
            enable = true;
            user = "me";                       # existing login user
            order = [ "app" "infra" ];         # sidebar order + 1..9 hotkeys
            channels = {
              app   = { cwd = "/home/me/code/app"; };
              infra = { cwd = "/home/me/code/infra"; };
            };
          };
        })
      ];
    };
  };
}

Then front http://<host>:80 with your reverse proxy + authentication. ttyd, the upload sidecar, and the palette sidecar all bind loopback only.

Using the launcher

Once it's up, open the launcher in a browser. The active channel fills the screen; everything else is chrome around it.

Switching channels

  • Click a channel in the sidebar (desktop) or the pill row (mobile).
  • Command palette — Alt+K (Option+K on Mac), or tap the Forge brand on a phone. Type to filter, ↑/↓ to move, Enter to activate, Esc to close. The palette also lists actions (see below).
  • The status dot on each channel shows what it is doing now: hollow = no session, grey = a session nobody has prompted yet, green = a turn running right now, amber = it is waiting on you. All of it is read from the terminal title Claude Code sets on itself — ⠂ … while working, ✳ … when waiting, and the text stays the literal Claude Code until there is a conversation to summarise, which is what tells an untouched session apart. Claude's own answer rather than a guess, and nothing to install for it.
  • Ctrl/Cmd/middle-click a channel opens it in a new browser tab.

Host vitals — CPU and RAM gauges for the whole box sit at the foot of the sidebar (a compact pill next to the channel chips on mobile), refreshed every 5s. They turn amber past 75% and red past 90%; the second line adds absolute memory and disk use, and the tooltip has load average, swap, and uptime. This is the box, not a per-channel breakdown — put that in Claude Code's own status line if you want it.

Light / dark theme — the ☀️/🌙 button in the sidebar header toggles a high-contrast light theme (chrome and terminal) tuned for e-ink readers like a Boox: black-on-white, no cursor blink, no glow/shadows. The choice is per-device (saved in localStorage), so one browser can run light while another stays dark. The dark default follows the deploy's theme option.

Palette actions (run against the current channel's tmux session)

  • Split a second Claude pane right/below, or a plain shell split.
  • Zoom (toggle fullscreen) the active pane.
  • Kill the side pane (the lone main pane is protected).
  • Open lazygit in a popup.

Worktree sessions — more than one Claude per project, each on its own branch so they never edit the same checkout.

  • Palette → Create worktree, type a name (or name@base to branch from something other than the repo's current HEAD), Enter. Forge runs git worktree add, starts a session in it and switches to it.
  • Worktree sessions sit indented under their channel in the sidebar (after the channel's pill on a phone), each with its own status dot. They share the channel's issues drawer and upload folder.
  • Close with the row's × or the palette's Close worktree: the session is killed and the worktree removed if it is clean. With uncommitted changes Forge asks before deleting it. The branch is always kept.
  • Prune worktrees (palette) tidies the current channel at once, after showing the list: it closes its worktrees and deletes local branches already merged into the main checkout's HEAD (fast-forward, squash or rebase merged) that have no checkout left. Unmerged branches are never deleted. Worktrees with uncommitted changes are only removed if you confirm a second prompt; a Claude that is mid-turn and the session you're in are always kept.
  • Any linked worktree of the repo is listed, including ones made by hand or by claude --worktree; clicking one that isn't running (e.g. after a reboot) starts its session. Names are letters, digits, - and _.

Under the hood a worktree session is the tmux session <channel>~<name>, served by the channel's own ttyd (/<channel>/?arg=<name>), so creating one needs no rebuild and no new port.

Sending files — drop a file anywhere on the page, paste an image, or tap the dropzone to pick one. It uploads to the box under uploadDir/<channel>/ and its path is typed into the active session, ready for Claude to read.

On a phone / tablet

  • A keybar sits at the bottom: Esc · Tab · Enter · Mode · ↑ ↓ ← → · Home · End · PgUp · PgDn, plus ☰ (palette) and ⟳ (reconnect a stale session). These go straight to the session, so they work even where the soft keyboard's own keys don't. Mode sends Shift+Tab — the chord you can't type on a phone — to cycle Claude Code's permission/plan mode.
  • A compose box lets you type a line into a normal input and send it with one tap — this sidesteps Android IME quirks that duplicate characters when typing straight into the terminal.
  • The soft keyboard stays closed when you switch channels. Tap the terminal itself when you actually want to type; use the keybar/compose box otherwise.
  • ⟳ (or reselecting the channel) reconnects a session that went stale after the phone slept — the tmux session and its scrollback are still there.

Persistence — every channel runs inside tmux new-session -A, so closing the tab or losing the connection never kills your work. The next visit re-attaches.

Add Forge to your home screen (it's an installable PWA) for an app-like, full-screen shell.

Options (myServices.forge)

Option Default Description
enable false Turn Forge on.
user "pma" Login user that owns the ttyd/tmux sessions and palette sidecar.
channels {} Attrset name -> { cwd; basePath?; command?; worktrees?; panel?; }. One channel per entry. command overrides sessionCommand for that channel alone; worktrees = false hides worktree sessions for it.
order [] Explicit channel order (sidebar, 1..9 hotkeys, default channel). Omitted channels append alphabetically.
basePort 7681 First loopback port; channel N binds basePort + N. Sidecars take the two ports above the last channel.
sessionCommand ${pkgs.claude-code}/bin/claude Command run inside each tmux session, unless that channel sets its own command.
worktreeDir ".claude/worktrees" Where worktree sessions are created. Relative → inside each channel's cwd (added to the repo's local .git/info/exclude); absolute → <worktreeDir>/<channel>/<name>.
sessionEnvFiles [] Files sourced (if readable) before sessionCommand — inject tokens without baking secrets into the module.
theme Tokyo Night xterm.js colour theme.
branding "Forge" Product name in the launcher/PWA.
uploadDir /var/lib/forge-uploads Where the upload sidecar writes files.
maxUploadBytes 26214400 Per-upload cap (also nginx client_max_body_size).
nginx.default true Claim the default vhost + bind :80 + open the firewall. Disable to front Forge yourself.

Injecting secrets

Forge never reads secrets directly. To give sessions API tokens, write them to a shell file (e.g. via sops-nix) and point sessionEnvFiles at it:

myServices.forge.sessionEnvFiles = [ "/etc/profile.d/forge-tokens.sh" ];

Each channel sources those files before launching, and re-sources them inside the tmux session so freshly-rotated tokens reach already-running sessions.

Layout

modules/forge.nix      options + wiring
modules/ttyd.nix       one ttyd web shell + tmux session per channel
modules/launcher.nix   nginx launcher, /channels.json, upload + palette sidecars
modules/shell.nix      system tmux.conf tuned for the browser terminal
web/                   launcher page, sidecars (upload.py, tmux_ctl.py), PWA assets

License

MIT.