> ## Documentation Index
> Fetch the complete documentation index at: https://hmm.heyhyper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# connect: Start a Hyper Session and Load Your Briefing

> Resolve your identity and load your workspace briefing at the start of every session. Call connect whenever no HYPER BRIEFING block is present.

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

<ParamField name="join_token" type="string" required={false}>
  A workspace join token. Pass this to connect to a workspace other than the one associated with your current Hyper token. Your admin can generate a join token from the Hyper desktop app. If a token is already present at `~/.hyper/join_token`, it's used automatically without passing it here.
</ParamField>

<ParamField name="tz" type="string" required={false}>
  Your IANA timezone string (e.g. `America/Los_Angeles`, `Europe/Berlin`). When provided, all timestamps in the briefing and system-prompt datetime footers are rendered in your local timezone instead of UTC.
</ParamField>

## 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.

<ResponseField name="action" type="string">
  One of `welcome_back`, `no_workspace`, `not_set_up`, or `error`. Determines what the rest of the response contains.
</ResponseField>

<ResponseField name="user" type="string">
  Your display name as registered in the Hyper workspace. Present when `action` is `welcome_back`.
</ResponseField>

<ResponseField name="workspace" type="string">
  Your workspace's organization identity document, your personal profile, and a summary of recent activity. Present when `action` is `welcome_back`.
</ResponseField>

### Response by Action

<Tabs>
  <Tab title="welcome_back">
    The happy path. You're authenticated, your workspace is set up, and the briefing is ready.

    ```text theme={null}
    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.
    ```
  </Tab>

  <Tab title="not_set_up">
    Your account exists but onboarding hasn't been completed. Open the Hyper desktop app to finish setup — it walks you through workspace creation and profile configuration.

    ```text theme={null}
    action: not_set_up
    ```

    <Warning>
      Until onboarding is complete in the desktop app, `connect` will continue returning `not_set_up`. No briefing data is available yet.
    </Warning>
  </Tab>

  <Tab title="no_workspace">
    You're authenticated but not yet associated with a workspace. This usually means you need a join token from your team admin.

    ```text theme={null}
    action: no_workspace
    ```

    To resolve this, either:

    * Pass a `join_token` to `connect`: `connect(join_token="tk_abc123")`
    * Ask your admin to place a token at `~/.hyper/join_token`
    * Open the Hyper desktop app to create or join a workspace
  </Tab>

  <Tab title="error">
    Something went wrong — typically an authentication or network issue. Check that `~/.hyper/token` exists and is valid, then try re-authenticating via the desktop app.

    ```text theme={null}
    action: error
    ```
  </Tab>
</Tabs>

## Example Calls

### Basic session start

```python theme={null}
connect()
```

### Session start with timezone

```python theme={null}
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

```python theme={null}
connect(join_token="tk_9fKx2mLpQrT7")
```

## When to Call connect

<Tip>
  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.
</Tip>

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.