---
name: traces-get-started
description: Set up Traces for an individual or team, privately share the current onboarding session, return the relevant links, and optionally set up agent and Git-based sharing.
metadata:
  author: traces
---

# Get Started with Traces

## Route the request

Classify the request before setup:

- **Individual:** set up the user's personal Traces workspace.
- **Named team:** use the supplied team name.
- **Unnamed team:** ask what the team should be called, then wait for the answer before setup work.
- **Ambiguous:** ask whether setup is personal or for a team.

## Common setup

After the route is known:

1. Confirm this agent provides an authoritative trace ID or source-path hint for the current session. Stop if it does not.
2. Read the [installation guide](https://www.traces.com/docs/getting-started/installation). When installation is needed, select the command most appropriate for the user's platform and package manager.
3. Check whether `traces` is installed. Install it only when missing, using the selected command.
4. Run `traces whoami`. Run `traces login` when authentication is needed.
5. Run `traces namespace list` to identify the personal workspace and accessible organizations.
6. Record whether this session installed the CLI. Use that only to decide whether an individual closeout includes a short CLI primer.

## Individual route

1. Privately share the exact current session to the personal workspace.
2. Return the personal profile URL and private trace URL.
3. When this session installed the CLI, include:

   | Goal | Command |
   | --- | --- |
   | Open the TUI | `traces` |
   | Share the current session | `traces share --cwd .` |
   | Check setup and integrations | `traces status` |
   | Diagnose issues | `traces doctor` |

4. Offer relevant next actions: team setup, agent integration, or GitHub.

## Team route

1. Reuse a matching accessible organization or create the requested organization.
2. Inspect available MCP tools for a team-messaging app such as Slack or Microsoft Teams.
3. Privately share the exact current session to the organization.
4. For an organization admin, run `traces org invite <slug> list --json` and select the pending invite with unlimited uses and no expiry. A newly created organization has this default invite. If an older reused organization has none, create one with `traces org invite <slug> code --max-uses 0 --no-expiry --json`.
5. Only after this team setup created the organization and resolved its invite, return the organization URL, private trace URL, invite URL, and this copyable message. Do not offer this message during individual setup:

   > Join {organizationName} on Traces to start sharing agent sessions:
   >
   > 1. Join your team: {inviteUrl}
   > 2. Install Traces: https://www.traces.com/docs/getting-started/installation
   > 3. Set up sharing: in `path/to/your/repo`, run `traces setup`
   > 4. Manage sessions: `traces`
   >
   > Read the docs to learn more: {docsUrl}

   Replace the placeholders before showing or sending the message.

6. When a messaging MCP is available, say:

   ```text
   Looks like you have {messagingApp} MCP installed. Who should I send this invite to? You can name people, @mentions, or a channel.
   ```

7. Resolve the requested recipients through the MCP. Then show:

   ```text
   Great, want to send this message to {people} on {messagingApp}?

   > {draftMessage}
   ```

   Send only after confirmation. Use the copyable invite message unless the user supplies replacement text.

8. For a non-admin reused organization, return the organization and members-settings URLs. Explain that an admin can create or share an invite.

## Optional next actions

After the successful route closeout, offer only relevant next actions. Set up agent integration, GitHub, and share settings only when the user chooses them.

## Recovery

- If login or browser authorization is incomplete, pause and provide the next action.
- If the exact current-session trace cannot be identified, stop before sharing.
- If a command fails, report the failure and retry only the affected action after recovery.
- Report only completed work in the closeout.