Create or join a Works

A Works is the folder on your machine that holds one project, its plan and its record. See a Works. Nothing appears on the board until the desktop is connected to one. Creating a Works writes a folder on this machine and nowhere else.

Open setup

• On first launch. When the app finds no Works on this machine, it opens a conversation headed Let's set up your first Works in place of an empty board.
• Any time after that. Open the Works menu from the button at the top of the rail. It reads Connect a Works when none is connected. Choose Create or join a Works…. The conversation opens headed Set up a Works.

Set it up in conversation

An agent holds the setup conversation. Tell it about the company you are setting up, or the one already on this machine that you want to open. It works out with you where the Works goes, which product repository it works from, its first Line and its North Star.

• The top of the pane shows the Directory the conversation is about and the Runtime hosting it. If this machine has more than one agent runtime, the runtime chip opens Host this conversation on. Switching starts a new conversation.
• Suggestion chips such as I don't have a repo yet, Set it up here, Join one that exists and What is a Line? fill in the message box. They do not send anything.
• Enter sends. Shift+Enter starts a new line.

Nothing is written until you approve

When the agent is ready to create the Works, it cannot run the command itself. The pane shows a card with what approving runs and The command, verbatim. Read it, then press Approve and run it, or Not this to keep talking.

When the command succeeds, the pane closes and the new Works connects to the board. The setup agent goes away. The Works' own Superintendent answers for it from then on.

Opening a Works that already exists

If the path already holds a Works, the pane shows an Already a Works card with its Lines and North Star. Open it connects that Works without writing anything to it.

If no agent can run

The conversation needs an agent runtime on this machine. See executors and your model account. When none can be started, setup falls back to a fixed set of questions, and then to the form below.

Use the form in Settings

Settings → General has a Create or join a Works form. Open Settings from the Works menu.

1. Path — where the Works lives.
2. Repository — the product repository its Line works from.
3. Line — the first Line's name. It starts as main.
4. North Star — required for a new Works, and kept exactly as you write it.

Press Create or join. The status line under the button shows the command as it runs, and its output or error when it finishes. On success the Works is connected. Pointed at a folder that is already a Works, the same form joins it: it wires the Line and connects instead of creating anything.

Switch between Works

The Works menu lists every Works found on this machine and every one this app has opened, most recent first. The squares beside the rail button are shortcuts to the same list.

hm works onboard /path/to/works --line main --repo /path/to/repo --north-star "Your North Star"

hm works doctor