Skip to content
wloop

Install

Homebrew

Section titled “Homebrew”

On macOS or Linux:

Terminal window
brew install wloophq/tap/wloop
wloop init

wloop init checks the requirements, writes your configuration and installs the pieces below, asking before each one. You can also install them one by one:

Terminal window
wloop install        # the GitHub and Slack plugins, and the MCP server, hooks, permissions and skills in every Claude Code home
wloop app install    # macOS: wloop.app and the LaunchAgents of the daemon and the menu bar
wloop doctor         # what is still missing, with the command that fixes each item
wloop open           # the cockpit in your browser

What install writes

Section titled “What install writes”

A release ships the GitHub and Slack plugins beside the binary, each in plugins/<id>/ with its manifest, its profile layer, its binary and the binary’s SHA-256. wloop install checks each binary against the checksum shipped with it, refuses one that differs, copies the plugins to <state>/plugins/bundled/<id>/ and records their checksums in <state>/plugins/checksums. The daemon runs a bundled plugin only when its binary has the recorded checksum, so run install after every upgrade; wloop doctor shows each plugin’s path, hash, trust, protocol and health.

It also writes into each Claude Code home it finds:

  • the registration of wloop‘s MCP server at user scope, with the URL from mcp.port, the X-Loop-Key header, and wloop hook mcp-headers as the headersHelper that names the session in X-Loop-Session;
  • the Stop, SessionStart and UserPromptSubmit hooks (wloop hook stop || true, and so on);
  • the permissions in settings.json: mcp__wloop__turn_end, mcp__wloop__slack_send_message, mcp__wloop__slack_react, mcp__wloop__slack_edit and mcp__wloop__slack_delete allowed, so an agent posts, reacts, edits and deletes its own messages on Slack without a prompt; install also removes those tools from ask, where earlier releases put the first;
  • the bundled skills (wloop, wloop-review, wloop-address, wloop-nudge and wloop-profile), also into ~/.agents/skills for Codex.

The hooks and the headersHelper call the binary by its absolute path: on macOS the one you ran install by, a symlink such as Homebrew’s bin/wloop included; on Linux the file the symlink points to. wloop doctor and the daemon accept a hook that runs the same binary by its link or its target, and install rewrites it to its own path.

It finds the homes on its own: ~/.claude, CLAUDE_CONFIG_DIR when set, every agent_home of the configuration and of each projects entry, and every Orca Claude profile home. --home <dir> (repeatable) names them instead. It backs up settings.json and the MCP registration before their first change, replaces a skill only while it is unedited, prints every entry it adds, changes or removes, and is safe to run again. --dry-run prints and changes nothing. It needs no daemon.

Run it again after changing mcp.port and after every upgrade.

macOS: the app and the daemon

Section titled “macOS: the app and the daemon”

wloop app install builds ~/Applications/wloop.app from the binary you run it with, signs it ad hoc, and installs two LaunchAgents:

  • io.github.wloophq.wloop runs wloop serve through your login shell, so the daemon gets your profile’s PATH, at login and again whenever it exits;
  • io.github.wloophq.wloop.app runs the menu bar at login and restarts it only after a crash, so Quit stays quit until the next login.

macOS gives notifications to apps, not to bare binaries, and the stable path of the bundle keeps your answer to the notification permission across upgrades. The first start asks to allow notifications: allow them.

On a Mac where you do not want the menu bar, wloop app install --no-menu-bar installs only the daemon’s LaunchAgent.

Linux

Section titled “Linux”

Run wloop serve under your init system. A systemd user service, for example:

~/.config/systemd/user/wloop.service
[Unit]
Description=wloop daemon


[Service]
ExecStart=/bin/sh -lc 'exec wloop serve'
Restart=always


[Install]
WantedBy=default.target
Terminal window
systemctl --user daemon-reload
systemctl --user enable --now wloop.service

The login shell (sh -l) gives the daemon the PATH where gh, git, orca and claude live. Without notifications, each automatic round still waits in its approval window, and the cockpit and the terminal client let you act on it.

Check the setup

Section titled “Check the setup”
Terminal window
wloop doctor

doctor changes nothing. It checks gh, each workspace manager, the configuration, every agent home, the review profile, the LaunchAgents, the daemon and its jobs, each plugin, and prints the fix for each problem on its own line. See Troubleshooting.