Sessions
A session is the atomic unit of work in Ren: a single conversation or task execution between one or more humans and one or more agents. Everything you do on the platform, from a quick question to a multi-day project, lives inside a session.
Unlike a single-player chat thread, every session is multiplayer from the start, fully recorded, and shareable. A teammate can review an agent’s output mid-stream, a second agent can take a subtask, and anyone can catch up later. You never have to “upgrade” a private chat into a shared one.
How sessions work
Turn-based attribution
Every message in a session is attributed to its sender: a specific human or a specific agent. There is no anonymous “the AI said” bucket. When three people and two agents are in the same session, you can always see who said what, who ran which tool, and who approved which action.
This matters for accountability and for context. When an agent reads back through a session to decide what to do next, it sees the same attributed history everyone else sees: no information asymmetry.
Session lifecycle
A session moves through four statuses:
| Status | Meaning |
|---|---|
| idle | No agent is currently working. Waiting for human input. |
| busy | An agent is actively processing or running a tool. |
| waiting | An agent has paused and needs human input to continue. |
| error | Something went wrong. The agent stopped and needs attention. |
Most sessions spend their time cycling between idle and busy. The waiting status is intentional. It is how an agent signals that it cannot proceed without a human decision, not a failure state.
Where sessions live
Every session belongs to a project and runs inside a pod. The project scopes permissions and data; the pod provides the compute environment where the agent actually executes. Switching the pod or project mid-session is not supported. If you need a different environment, start a new session.
Multiplayer by default
Anyone in the same project can join a session. There’s no invite step and no private mode. Updates flow to every participant in real time: when an agent produces output, everyone sees it immediately; when someone types a message, the agent sees it on the next turn.
Switching agents mid-session
Sessions are not locked to a single agent. The agent selector lets you switch which agent handles the conversation at any point. This is useful when a task changes shape: for example, starting with a general-purpose agent for exploration, then switching to a specialized code-review agent for the final pass.
Switching agents does not erase history. The new agent reads the full session transcript and continues from where the previous one left off.
Use @-mentions and context injection
Typing @ in the message composer opens a context menu with four mention types:
- @agent: Pull another agent into the session. The mentioned agent receives the conversation context and can respond in-thread.
- @file: Attach a file from the project. The agent reads the file content directly, no copy-paste needed.
- @user: Notify a teammate. They get a push notification and can jump into the session.
- @memory: Reference a stored memory or note. The agent loads the referenced context without re-deriving it from scratch.
Each mention type injects different context into the session. This is how you give an agent exactly the information it needs without cluttering the prompt with everything.
Inline authentication
When an agent needs access to an external service (an API key, an OAuth token, a database credential), it does not ask you to paste secrets into the chat. Instead, the session surfaces an inline auth prompt: a button embedded directly in the conversation.
The prompt appears in yellow when credentials are needed and turns green once connected. Behind the scenes, the credentials are stored in a vault: an encrypted secret store scoped to the project. The agent never sees the raw credential; it receives a short-lived token or session that the vault manages.
This pattern keeps secrets out of chat history, out of agent memory, and out of session replays.
Replays
Every session is recorded from start to finish. A replay is a shareable link that lets anyone, even people outside your project, watch the session unfold message by message, exactly as it happened.
You control who can view by distributing the link. There’s no separate permission grant. This makes it easy to share a debugging session with a vendor, walk a teammate through a decision trail, or demo a workflow to a stakeholder.
Replays are read-only. Viewers cannot resume the session or inject messages. They watch the history as it was recorded.
Tasks and todos
Inside a session, agents can create and track todos, lightweight task items with a status lifecycle:
- pending: Created but not yet started.
- in_progress: The agent is actively working on it.
- completed: Done.
- cancelled: Intentionally dropped.
Todos give you a running checklist of what the agent is doing, which is especially useful in long sessions where the agent is working through a multi-step plan. You can see at a glance what has been finished and what is still in progress, without reading every message.
Subagent sessions
When an agent delegates work to another agent, it creates a subagent session: a child of the parent session. The subagent runs independently, and its results flow back into the parent when it finishes.
This keeps the main conversation clean. You do not see the subagent’s internal tool calls and reasoning cluttering your thread; you see the outcome. If you need to dig deeper, you can navigate into the subagent session from the parent.
Creating sessions
Sessions can originate from several entry points:
- The Ren UI: Click into a project and start a new session. Pick an agent, type a message, go.
- Integrations: A Slack message, a GitHub event, or another integration can create a session automatically.
- Programmatic: The API and CLI both support session creation for scripted workflows.
From the CLI:
ren sessions create --pod-id <podId> --project-id <projectId> --title "Investigate flaky test"ren sessions listRegardless of how a session is created, it behaves the same way: multiplayer, recorded, and attributed.