Skip to main content
The 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.
​
action
string
One of welcome_back, no_workspace, not_set_up, or error. Determines what the rest of the response contains.
​
user
string
Your display name as registered in the Hyper workspace. Present when action is welcome_back.
​
workspace
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

The happy path. You’re authenticated, your workspace is set up, and the briefing is ready.
action: welcome_back
user: Alex Chen

--- org/identity.md ---
Hyperlink is a B2B SaaS tool helping engineering teams share AI context
across sessions and teammates. The product is in closed beta, targeting
engineering leads at Series A–C companies.

--- profile ---
# Alex Chen
**Role:** Backend Engineer
**Focus areas:** API design, PostgreSQL, auth systems
**Current sprint:** Shipping row-level security for multi-tenant orgs

--- recent activity ---
Alex pushed changes to the auth module yesterday.
The team decided to defer the billing integration to Q3.
Maya opened a PR for the new onboarding flow — review requested.

​
Example Calls

​
Basic session start

connect()

​
Session start with timezone

connect(tz="America/Los_Angeles")
Timestamps in the briefing will now show Pacific time (e.g., 2:30 PM PDT) instead of UTC.

​
Joining a new workspace

connect(join_token="tk_9fKx2mLpQrT7")

​
When to Call connect

If you’ve configured the SessionStart lifecycle hook, connect fires automatically at the start of every conversation. You only need to call it manually in clients that don’t support hooks.
Call connect 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.