Highwind: dev servers, AI agents and a browser in one Mac window

Highwind organizes things as Workspace → Project → Service. A workspace groups projects. A project is a folder. A service is a process that runs from a project folder.

Workspaces

A workspace is a named group of projects, for example "My SaaS" with the api, frontend and worker repositories. Each workspace has a name and a color from a palette of 16. Its tab in the top row shows a square in that color and a count of running services out of the total ("4/22"). A white dot on the tab means an agent in that workspace is waiting for input.

Create a workspace: click + at the end of the workspace row.
Workspace tab context menu: Add Project, Edit, Start All, Stop All, Restart All, Move Left, Move Right, Delete.
Switch workspaces with ⌥2 to ⌥9 (⌥1 is Focus). Switching opens the view you last had selected in that workspace.

Focus

Focus is a special workspace, always first in the row and always ⌥1. It shows views from any workspace in one place. Right-click a view tab and choose Add to Focus, or drag the view tab onto the Focus tab. Remove from Focus takes it out, and Clear All on the Focus tab empties Focus. Clicking + while Focus is selected creates a view that belongs to Focus itself and can hold panes from every workspace.

Projects

A project is a folder, usually a git repository. The project menu lists the projects of the selected workspace, each with its services, the agents working in it and its quick commands. A service belongs to the project whose folder contains its working directory. An agent belongs to the project of the folder it runs in.

Add a project with + in the project menu header, or Add Project in the workspace tab menu.
Deleting a project keeps its services. They move to "No Project".
If a project folder is moved or deleted, the project menu shows a warning. Click it to choose the new folder (the services move with it) or remove the project and its services.
Clicking a project menu item shows its pane if the current view has it. Otherwise Highwind switches to the most recently used view that has it.

Services

A service runs a shell command in a folder, using a login shell so your profile is loaded. Its state is one of stopped, starting, running, stopping, failed or crashed. Right-click a service in the project menu or in its pane header and choose Edit to open the Edit Service sheet. It has these tabs:

General: name, command, folder, Requires, and "Restart when it crashes".
Commands: quick commands for this service.
Links: URLs for this service, opened from its header.
Patterns: log patterns that send notifications for this service.
Notifications: notification settings for this service.
Agents: per-service overrides of the agent launch defaults from Settings → Agents.

A service can also have a port and environment variables. These are not in the Edit Service sheet. Set them through the MCP tools create_project and update_project, the REST API, or the service JSON file in ~/.highwind.

Required services (start order)

A service can require other services, for example a website that needs its API. Turn them on under Requires in the General tab of Edit Service. Starting the service first starts each required service (and their own requirements) and waits until it is running and, when it has a port, accepts connections on that port. If a required service is not ready within 2 minutes, the service is not started, it shows as failed, and its log names the service that did not start. Highwind does not let you create a cycle.

Stopping a view keeps services that something else still needs: another view that is running and contains the service, or a running service that requires it. The view tab menu names them, for example "API keeps running for SF Admin". Restart on a view asks first when some of its services are also used elsewhere: Restart All, Skip Shared or Cancel.

Restart on crash

Restart on crash is set per service and is off by default. Turn on "Restart when it crashes" in the General tab of Edit Service. When the service fails or crashes, Highwind starts it again up to 3 times, 2 seconds apart. If it then stays up for 10 seconds, the count resets. Quick commands are never restarted.

Port conflicts

Before a service starts, Highwind checks whether its port is already in use. The port comes from the service port setting, a PORT environment variable, or the first localhost link. If the process holding the port is a leftover Highwind process or an orphan from the same folder, Highwind stops it.

Quick commands

Quick commands are one-off shell commands for a service, such as tests, a database seed, a build or a deploy. They run next to the main process and do not replace it. Add one from the quick commands menu in the pane header (Add Quick Command) or the Commands tab of Edit Service. Run them from the pane header, the actions bar under the log, the project menu, or the command palette (⌘P).

Each run shows as running, done or failed. Click it to see its output in a popover. ⌘-click a finished command to run it again.
A command runs in the service folder. A relative working directory is inside the service folder, and a full path is used as is.
A command with no output for 90 seconds sends a notification, and is stopped after 180 seconds without output. The maximum run time is 45 minutes. At most 2 run at the same time per service.
Collapsed panes show the quick commands menu on hover.

Links

Links are URLs for a service, such as the localhost dev server, staging or docs. They show in the pane header. Click a link to open it in a browser pane in Highwind. ⌘-click opens it in your default browser. Right-click for Open in Panel, Open in Browser, Edit and Delete. Add links from the links menu in the pane header (Add Link) or the Links tab of Edit Service.

When a service prints a localhost URL with a port, such as http://localhost:3000, a banner asks whether to add it as a link. Accepting adds a link named "dev" and then offers to open it.

Logs and log patterns

A service pane shows its output with ANSI colors. Localhost URLs in the output are clickable. Highwind keeps 1000 lines per service by default (Settings → Advanced → Logs → "Lines kept per project"). ⌘K clears the active service log and ⇧⌘K clears all logs in the view. The log has no search or filter.

Log patterns send a macOS notification when a line matches. A pattern has a name, a match type (Contains Text or Regular Expression) and a severity (info, warning or error). Global patterns are in Settings → Log Patterns. Per-service patterns are in the Patterns tab of Edit Service. To make one from existing output, select text in the log, right-click and choose Add Pattern from Selection. Matches are collected per service for 5 seconds and sent as one notification. Clicking it opens the service.