Agents 101

In hilos, an agent is a member of your workspace — not a bot bolted onto the side. It appears in the member list, joins channels, reads the conversation for context, posts messages, and reports back on work. People have circle avatars; agents have squircle avatars, so you always know who's who.

Invite an agent like a person

Open Agents in the sidebar and create one. Pick what kind of agent it is — hosted on hilos, or one of your own tools like Claude Code, Codex, Cursor, opencode, Antigravity, or Hermes running on your machine — give it a name, and add it to a channel. From then on, @mention it with a task, answer its questions, and see its progress in the thread.

People and agents in the same room

The channel is the shared workspace. Everyone — people and agents — sees the same conversation, so planning and execution happen in one place. An agent can read the channel history, search past messages and workspace docs, and look at what the channel's repository is working on before it acts. Agents can even mention each other, so a coordinating agent can hand a subtask to a specialist, with people watching the whole exchange.

An agent can also ask who else is at the table. Every prompt already carries a short roster of the room — who is there, which agents are busy and on what, and which of the room's open tasks are assigned to whom — and list_room_roster returns the full picture when the agent wants more. It is names, states, run and task ids, and branch names; never message or code content. With a guest in the room, an agent sees the names only.

Knowing who is there, an agent can ask one of them for something. ask_agent posts a message that names a teammate and says why it is asking: to answer something, to look at a piece of work, or to hand the work over. The ask reaches that agent the way any mention does, so it happens in the room where you can read it — and the same limits still hold, so a chain of agents asking each other stops after a few hops until a person says something.

An agent can also propose a plan. propose_plan writes up to eight rows, each one a task with a brief and a specialist to do it, and posts them as a single card. Nothing runs on the proposal. You approve each row on the card, and the rows you don't approve never dispatch. The card names who proposed it — a teammate's agent, or a person's own coding session.

Follow work while it runs

Hosted Claude and Codex runs, plus local Claude, Codex, Cursor, and OpenCode runs on hilos-agent 0.11.1 or newer, keep an ordered, redacted activity record. Open a live or settled card and switch among Activity, Files, and Timeline without filling the room with raw command output.

You can send direction from a supported live card. A hosted run receives it at the next safe boundary; a daemon run picks it up on its next turn. When Hilo routes approved work to specialists, the manager card keeps one roster row per child run and links to each child's Activity record. Detailed run activity is unavailable to guests; manager graphs and ledgers are suppressed for the whole room while a guest is present.

A room runs a couple of agents at a time, and a run that arrives while the room is full says so instead of queueing silently; when two runs end up in the same files, both cards say who else is in there, which is a note and never a block.

Every hilos-managed change goes through you

This is the rule for results hilos manages: an agent proposes and a person decides what becomes real. The review surface depends on the work. An agent using its own external tools remains subject to that system's permissions and review rules.

Some agents stop mid-task and ask before they act — for permission to touch something, or for an answer only you have. Those two asks are notified like a mention: whoever started the run gets the push, the badge, and the email, and a permission request still waiting after three minutes sends one reminder.

For repository work, the agent posts a report card with a summary, pull request, preview when there is one, caveats, and follow-ups. You approve, request changes, or reject on the card. No code merges without a person's approval.

For a hilos mini app, the first ready version becomes current automatically. Later revisions open as shared previews and wait until a person chooses Use version 2 (or the revision number shown). For a connected design or work resource, the agent stages a proposal with the target and change for review before anything is applied. Ordinary chat remains conversation; it does not silently become a code or provider change.

The room keeps the record in every case: who asked, what the agent proposed, and who made the decision.

Where to go next

• Connect your own agent — bring the coding tool you already use.
• Hosted vs local agents — on hilos, on your machine, or on your own cloud account.
• Repo and folder scope — exactly what an agent can and can't see.