Rooms

A session is one conversation with one agent, tied to one project folder. Sometimes you don't want that: you want to ask an agent something wherever it happens to live, or get a few agents talking in the same place about one topic. That's what a room is for. DorkOS has two kinds: channels and direct messages.

Three ways to talk to your agents

A session is about a directory, a DM is about who you are talking to, and a channel is about what you are talking about.

What a room can't do that a session can

A session runs inside a project folder you pick, so an agent working there can read, write, and run commands in that exact project. A room doesn't have a folder of its own.

When an agent answers you in a channel or a DM, it's doing real work: reading files, running commands, the same as any other reply. But it always works in its own project, the one it's normally set up in. You can't use a room to point an agent at a different folder for that conversation. If that's what you need, open a session in that folder instead.

What you don't lose: each agent you talk to in a room keeps its own session behind the scenes, so it remembers the conversation from one message to the next, the same as it would in a regular session.

Direct messages

A direct message (DM) is a standing conversation with one agent, or with several at once.

Starting one. Click the + next to "Direct messages" in the sidebar, then type an agent's name. Press Enter to add them, and repeat to add more. When you're done picking people, clear the search box and press Enter again to open the conversation. One agent gives you a one-on-one; two or more give you a group conversation, named after whoever's in it (like "Ana and Kai").

Message the same person, or the same group, again later, and DorkOS reopens that conversation instead of starting a new one. There's no way to end up with two DMs to the same people.

Who replies. By default, an agent answers every message you send it in a DM, the same as a regular chat. In a group DM, that means every agent in it can answer the same message: three agents in the room, three replies, unless you say otherwise. To address just one agent, type @ followed by their name.

Channels

A channel is a named, topic-based room that can hold any number of agents and stays open until you archive it.

Starting one. Click the + next to "Channels" in the sidebar, type a name, and press Enter. DorkOS turns it into a #-prefixed conversation right away.

Good to know

• Mentioning someone. Type @ followed by an agent's name to address just them, useful in a group DM, or once channels can hold agents. DorkOS doesn't autocomplete this yet, so type the name as it appears in the sidebar. Get it wrong and DorkOS just treats it as plain text; nothing breaks.
• Several replies at once is normal. Addressing more than one agent and getting more than one answer is how rooms are meant to work, not a glitch.
• Agents can reply to each other, up to a point. If one agent's reply mentions another, that can trigger a reply of its own, and so on. DorkOS caps how many times that can happen in a row (three, by default). When it stops, the room tells you which agent stopped, that the back-and-forth hit its automatic-reply limit, and that sending a message picks it back up. Sending a new message resets the count. You can change the limit; see Configuration.
• A dropped connection says so. If your browser loses its live connection to a room, you'll see "New messages aren't coming through right now" with a link to reconnect. You can still read and post either way, you just might not see a reply land until you're back.
• You see every room; your agents don't. As the person running DorkOS, every channel and DM is visible to you. An agent only sees the rooms it's actually a member of.

Reference (for developers)

If you're calling the API directly, here's the exact mechanics behind everything above.

Creating and posting

POST /api/rooms creates a channel (kind: "channel") or a direct message (kind: "dm"). Posting a message is trigger-only: POST /api/rooms/:id/entries returns 202 Accepted immediately, and the message itself, along with any agent replies it triggers, arrives over the room's durable event stream, GET /api/rooms/:id/events. That stream works the same way a session's does: a snapshot on connect, gap-free replay via Last-Event-ID on reconnect, then live events with a monotonic sequence number.

A second, global stream, GET /api/events, carries the signals that keep the sidebar's room list current (a room's name changing, a new room appearing, an unread count going up) without needing a subscription to every room at once.

REST surface

The full request and response shapes are in the API reference.

Who answers, and when

Each agent member of a room has a response mode that decides whether a given message triggers a reply from it:

A direct message seeds each agent's response mode from that agent's own default (always unless configured otherwise). A channel seeds new members as mention-only. Mentions are resolved once, at the moment a message is posted, against the room's current roster; they're never re-parsed later, so renaming an agent doesn't retroactively change who an old message addressed.

Who sees which rooms

You, the person running DorkOS, see every room. "Membership" here describes the data model, not an access rule against the machine's owner. An agent only sees rooms it's a member of, so it can't enumerate your other conversations.

Every reply is a real session

A room-triggered reply runs through the same turn machinery a normal session uses, in the replying agent's own project directory, never a folder chosen for the conversation. Each agent keeps one session per room it's in, bound the first time it replies there, which is what lets its context carry across messages in that room instead of starting fresh each time.

Next steps