connect tool is the entry point for every Hyper-powered session. It resolves who you are, identifies your workspace, and returns a structured briefing — your organization’s identity, your personal profile, and a digest of recent activity. Any AI client configured with the SessionStart lifecycle hook calls connect automatically, so your assistant always has full team context before you send your first message.
Parameters
Returns
connect returns a structured response with an action field that tells you the outcome of the connection attempt, followed by workspace and user sections when the connection succeeds.
string
One of
welcome_back, no_workspace, not_set_up, or error. Determines what the rest of the response contains.string
Your display name as registered in the Hyper workspace. Present when
action is welcome_back.string
Your workspace’s organization identity document, your personal profile, and a summary of recent activity. Present when
action is welcome_back.Response by Action
- welcome_back
- not_set_up
- no_workspace
- error
The happy path. You’re authenticated, your workspace is set up, and the briefing is ready.
Example Calls
Basic session start
Session start with timezone
2:30 PM PDT) instead of UTC.
Joining a new workspace
When to Call connect
Callconnect at the start of a conversation if no HYPER BRIEFING block is already present in your context window. The briefing block is injected by the SessionStart hook — if it’s there, the session is already bootstrapped and calling connect again is redundant.
You should also call connect manually when:
- Switching between workspaces mid-session using a
join_token - Debugging authentication issues
- Running Hyper in a client that doesn’t support lifecycle hooks
Relationship to Other Tools
connect is the prerequisite for everything else. Once a session is connected and a briefing is present, the ask, remember, correct, ask-with-history, and mute tools all operate with full workspace context. Without a successful connect, those tools may return incomplete results or errors.