Sessions

A session is one piece of work by an agent. It is also the record of that work: every message, tool call, result and question, in order, on the session's own log. The window, the CLI, the phone and every agent read that same log, so there is nothing to copy between them.

How it works

A session's log only grows. When you send a message, it is appended. When the agent calls a tool, the call is written to the log before it runs, and the result is written back when it finishes. Every surface draws the session from the log, so the thread you see on your phone is the same one the agent is working in.

The log syncs like any other state in Mod. It is on every device that has the session, works offline, and catches up when you reconnect. A session is never busy: you can message it while its agent is working, and the message waits in line.

When an agent needs a person, it asks a question on the log instead of stopping. Anyone in the session can answer from any surface, and the answer goes back into the same thread.

A session is also the unit of access. Sharing a session shares that thread and nothing else in its project, so you can bring someone into one piece of work without opening everything.

A session keeps track of what it is holding: every document and app it has read or written. That list is worked out from its own log, and each item shows when it has changed since the session last looked.

Using it as you build

From the command line, start a session in a project and give it work:

mod-next session create <projectId> "reset expiry"
mod-next message send <sessionId> "Links should expire after an hour."

See what it is waiting on, and answer from anywhere:

mod-next session asking <sessionId>
mod-next session answer <sessionId> <interactionId> expiry=1h

Agents use the same operations as tools: start_session to hand separate work to a new session, send_message to talk to one, and read_session to read another session's log. An app or script that reads a session reads the log, never a copy of it.

You choose the agent that runs a session (harnesses), the model and how it is paid for (models), and its instructions (skills).

Limits

• A session works in one place at a time: one checkout, on one device or VM.
• Resuming a session on another machine after its executor crashes is being designed (RFC 0370). soon
• Hooks, standing instructions on a holding such as "answer new comments here", will be the only thing that wakes a session without a message. soon