AI Workforce OneHQDocs

Start and stop sessions

hq sessions lists the sessions in your teams; hq start, hq stop and hq restart run them from your terminal, with the same rules as HQ.

The same rules as HQ.

Only the session owner or a team owner can start, stop or restart a session, exactly as in HQ. Everyone else sees it in the list as view only.

List your sessions

hq sessions lists the sessions of every team you can reach: the first characters of the id, the name, the team, whether it is running, who owns it (you for your own), and whether you may operate it.

3 sessions in 2 teams
  7c21e0b4  fix login bug       Backend team        running   you             can operate
  1a2b3c4d  nightly             Backend team        stopped   Ana             view only
  9f9f9f9f  landing page        Website             stopped   you             can operate

Add --team <t> to list one team, by its hq-… name or its name. If one team's list cannot be read, hq names it (hq: could not list the sessions of team "…".) and still prints the others.

Start, stop and restart

Name a session by the first characters of its id or by its exact name, the same way as hq attach. Add --team <t> when the same name exists in two teams. The rawName a script read from --json works as a name too (see Use it from a script).

# start a stopped session
hq start 9f9f9f9f

# stop a session
hq stop "fix login bug"

# stop and start it again, resuming its conversation
hq restart 7c21e0b4
  • Start wakes a sleeping AI Team Cloud Computer for the session, and starts one that is off, as pressing Start in HQ does. hq says so first, for example hq: team "…" is sleeping. Starting the session wakes it. It returns once HQ has accepted the start. Follow the session with hq attach.

  • Stop and Restart ask first when Claude or Codex is answering in the session right now:

    Claude is answering in "fix login bug" right now. Stop it anyway? [y/N]

    Anything but y keeps it running. In a script, or anywhere without a terminal to ask at, hq refuses instead and tells you to pass --yes.

A session that is already running (for hq start) or already stopped (for hq stop) is not an error: hq says so and exits 0. A session HQ is still starting says "is already starting", with the hq attach command to follow it: hq only says running once HQ lists the session as running.

Every start, stop and restart is recorded in your organization's Audit log in HQ as coming from the HQ CLI, for example "Stopped a session fix login bug in Backend team from the HQ CLI on Jean's MacBook." The computer's name shows to people who can manage remote access; everyone else who can read the Audit log sees a short device id instead, such as "on device 3f2a9c1b".

When hq says no

What you seeWhy
Only the session owner or a team owner can do this.You can watch this session but not operate it. The same sentence HQ shows.
hq: no session "…" you can see. Run hq sessions to list them.No session you can see has that name or id.
Team "…" is running as many sessions as it can (…). Stop one of its sessions first, or give the team more room in HQ.The team is at its session limit.
This AI Team's Cloud Computer is busy right now, so another session could not start. Stop a session you no longer need, or move the team to a bigger size, then try again.The team has a free slot, but its Cloud Computer is too busy (memory at 80% or more, or the processor at full capacity).
Team "…" is paused. An owner can resume it in HQ.The team is paused.
This organization's plan is not active, so its sessions cannot be started or stopped. An owner can fix billing in HQ.The plan needs attention.
Too many requests. Try again in 34 seconds.More than 30 starts and restarts in a minute, or a team woken too often (6 times in 10 minutes). hq says how long HQ asked you to wait. Stopping is never limited.
HQ refused this request because it was not signed by this computer. That is a bug in this app, not an expired login, so signing in again will not help. Update the app and try again.Your login is fine, but this copy of hq sent a change without its device signature. Update hq. If it keeps happening, tell us.

Use it from a script

Add --json to any of the four commands to get one JSON document on stdout. Refusals stay plain text on stderr, with exit code 1.

# the ids of the sessions you may operate in one team
hq sessions --team hq-3f9a1c2e --json | jq -r '.[] | select(.canOperate) | .id'

# stop without asking, and read the result
hq stop 7c21e0b4 --yes --json

Each listed session has id, name, rawName, team (id, alias, name, org), state (running, idle, starting or stopped; starting while HQ is still starting it, which can still fail), owner, ownerIsMe, canOperate, canType, midTurn and engine. A start, stop or restart prints id, name, rawName, team, action, result (started, stopped, restarted, already_starting, already_running or already_stopped) and status.

name is the name as hq displays it: any control character (an escape sequence, a line break) is replaced with a space so it cannot change your terminal, and any bidirectional text control (such as U+202E, which would show the name reversed) is removed. The hq sessions table shows the same cleaned names. rawName is the exact name HQ holds. In the JSON, every control character in it is written as a \uXXXX escape, so the line hq prints is still safe to show. A JSON parser gives your script the exact value; print name, not rawName, to a terminal (jq -r .rawName would write those characters out as they are). hq start, hq stop and hq restart match either one.

midTurn comes from the AI Team Cloud Computer itself, which reports whether its agent is busy. It is about the whole Cloud Computer, so while one session is answering, every running session on that team reads true.

Every flag and exit code is in the CLI reference.