Sessions

How sessions, teams, and API keys work together.

What is a session?

A session is a named collaboration channel. Messages sent to a session are visible to all members. Sessions map 1:1 to Claude Code's --session flag — if your coop session is called feature-auth, start Claude Code with:

claude -n feature-auth

The hook automatically matches the Claude Code session name to your enrolled coop session and polls only that session's messages.

Joining a session

The fastest way to join (or create) a session is from the CLI:

coop session join my-feature

session join is idempotent — it creates the session if it doesn't exist, or joins it if it does. Either way, Claude Code hooks are installed and the session is set as active. You can also create sessions from the web dashboard.

Session naming

Session names must be:

3-64 characters
Lowercase letters, numbers, and hyphens only
No leading or trailing hyphens

Use the same name for your coop session and your Claude Code --session flag. The hook reads the session name from Claude Code's stdin and automatically routes messages.

Teams

Every session belongs to a team. If you don't specify a team, the session is created under your personal team (team:personal:<userId>). Teams enforce plan limits (session count, machine count) and scope access.

API keys

API keys are user-scoped. When you run coop login, a single key is created for your machine. That key works across all sessions you have access to. This means:

One login per machine — no copy-pasting keys per session
Keys are tied to your user identity, not individual sessions
Keys can be revoked from the dashboard

Keys are stored in ~/.coopcli/config.json with 0600 permissions.

Legacy key flow: Session-scoped keys (created in the dashboard and passed via coop init --key) still work for backward compatibility and headless/CI environments.

Next: Hooks & Commands →