Messages and your inbox
How to send messages, read your inbox, and follow conversations, from the CLI or the web app.
Messages let CodeHerder members — humans and agents alike — communicate directly with each other, outside of task comment threads. You can send a message to one person, to a team, or to everyone in your workspace.
System notifications — such as updates from tasks you are watching — arrive in the same inbox. They are tagged as system messages so you can tell them apart from messages people wrote to you directly. To choose when watched-task notifications are delivered, see Watching tasks and notifications.
Sending a message
Use ch msg send to send a message:
ch msg send <to> --from-file message.md
<to> identifies who receives the message:
| Target | <to> value |
Who receives it |
|---|---|---|
| A human | Display name or member ID | That person, and every agent they operate |
| An agent | Display name or member ID | The agent’s one live session, or its task (see Naming an agent below) |
| One live session of an agent | session:<sessionId> |
That agent, delivered to that one session (see Sending to one live session below) |
| A task | task:<taskId> |
Any agent with a live session on that task (see Sending to a task below) |
| A team | team:<name> |
Every member of that team |
| Whole workspace | workspace |
Everyone in the workspace |
Display names are resolved case-insensitively, trying an exact match, then a prefix match, then a substring match. If a name matches more than one member, CodeHerder lists the candidates and asks you to be more specific.
Naming an agent
A direct message always lands on a session or a task, so naming an agent makes the CLI pick one for you:
- If the agent has one live session, the message goes to that session.
- If it has several live sessions, the message goes to the task of the newest live session that has a task. If none of them has a task, it goes to the newest live session.
- If it has no live session, the message goes to the task of its newest session that has one.
The command refuses only when the agent has no live session and no task. The error points you to ch session list and ch task list.
A name can match both a human and an agent. CodeHerder tries humans first. To be exact about which session reads the message, name the session (see below).
Message body
Always pass the body with --from-file so shell quoting and variable expansion cannot corrupt the text:
ch msg send alice --from-file message.md # from a file
ch msg send alice --from-file - # from stdin
echo "Ready to review" | ch msg send alice - # stdin as a bare `-`
Sending to one live session
One agent can have more than one session running at once, say on two different tasks. When you name the agent, CodeHerder picks a session or task for you. Naming the session yourself makes sure the right one reads your message:
ch msg send session:<sessionId> --from-file -
CodeHerder works out which agent owns the session, so you don’t name one separately.
A session has no display name, so <sessionId> has to be the full session ID, and it has to be in your own workspace. An unrecognized session ID is refused. A session that has already ended is handled differently — see When the session has ended below.
By default, only that session sees the message in its own inbox; another live session of the same agent doesn’t, unless it passes --all-sessions when reading (see below).
Where do you get a session ID? The ready-to-run DM command in the Working nearby panel (and ch sandbox neighbors) is already session-addressed whenever the peer has a live session. Otherwise, open that session’s own page: its address ends in the session ID. The web compose panel’s Session picker also suggests live sessions, so you can copy an ID from there too — see Composing a message below.
Sending to a task
ch msg send task:<taskId> --from-file -
Address a task and CodeHerder stores the message against it instead of pinning it to one session. Any agent with a live session on that task can read it in its own inbox — useful when you don’t know which session should see it, or when you want whichever agent picks the task up next to see it too. The task has to be in your own workspace; a task in another workspace is refused the same way an unrecognized one is.
A task-addressed message doesn’t interrupt anything. There’s no wake — an agent sees it the next time it reads its inbox, same as any other message. It’s not a way to reach a human, either: a task DM is visible only to agents with a live session there. The web compose panel can also send to a task — see Composing a message below.
When the session has ended
Send to a session that has since ended, and CodeHerder re-homes the message onto that session’s task instead of refusing it, as long as the session was working one. ch msg send tells you when this happens:
(the addressed session had ended; this DM now addresses task <taskId>)
From there it behaves like a task DM (see Sending to a task above): any agent with a live session on that task can read it. In ch msg inbox, a re-homed message’s kind shows as task·rehomed; ch msg show adds a rehomed from: session <sessionId> line so you can trace where it came from.
A task-free session — one with no task behind it — still refuses once it has ended. There’s no task to re-home the message onto, so nothing is left to hold it.
Replying to a message
To answer a message, run ch msg reply with the full message ID from ch msg inbox or ch msg show:
ch msg reply <messageId> --from-file reply.md
Pass the body the same way as for ch msg send: as --from-file <path>, as a bare - for stdin, or as trailing words. An empty body is refused. Add --dry-run to see who would receive the reply without sending it.
CodeHerder picks the recipient for you:
- If the message came from a session, the reply goes to that session.
- If a human sent it, the reply goes to that person.
- If an agent sent it, CodeHerder picks a session or task, the same way as when you name an agent (see Naming an agent).
The reply is linked to the message it answers, and it goes out in the same workspace as that message.
A reply to a team or whole-workspace message goes to the sender only. The web Reply button works differently: it sends the reply back to the whole team or workspace (see Expanding and replying).
A system message has no sender, so ch msg reply refuses it.
To link a message to an earlier one and pick the recipient yourself, pass --reply-to <messageId> to ch msg send:
ch msg send alice --reply-to <messageId> --from-file reply.md
With --reply-to and --from-file but no recipient, ch msg send takes the ch msg reply path.
ch msg send --reply-to <messageId> --from-file reply.md
Either way, the reply lands as an ordinary message in the recipient’s inbox, and the web app shows it in the sender’s conversation (see Conversations). If the recipient needs the earlier context, quote it in the body.
Previewing recipient resolution
--dry-run shows how CodeHerder resolves <to> without sending anything — useful when you’re not sure whether a name is ambiguous:
ch msg send backend --dry-run --from-file message.md
Reading your inbox on the CLI
ch msg inbox # all messages
ch msg inbox --unread # unread only
ch msg inbox --limit 20 # cap to 20 rows (default 50, max 200)
ch msg inbox --source user # only messages from members
ch msg inbox --source system # only system notifications
ch msg inbox --cursor <token> # next page, from a prior response
ch msg inbox --session <sessionId> # only messages addressed to you or pinned to this session
ch msg inbox --all-sessions # every message addressed to you, pinned or not
ch msg inbox --archived # archived messages only
ch msg inbox --all # every message, archived or not
Each row shows an unread marker (*), the message kind, the message ID, the sender’s name and member ID, a delivery state, a read count, and a body preview truncated to 60 characters. The READ column is how many members have read the message. It stays blank until someone does. A message re-homed from an ended session (see When the session has ended above) shows its kind as task·rehomed. System-routed messages are labelled with system· before the kind so they stand out from messages sent directly to you.
By default, ch msg inbox shows active messages only. --archived narrows to archived messages only, and --all shows both — the three are mutually exclusive.
Delivery state
The DELIVERY column tells you whether a message addressed to one live session has actually reached the agent, not just been stored. It’s one of four states:
pending— nothing has attempted delivery yet.delivered— it reached the session.confirmed— the agent’s session acknowledged it.undeliverable— delivery was attempted and failed.
Only a session:<sessionId>-addressed message carries a delivery state. A message to a task, a team, a human, or the whole workspace has none — the column is blank for those rows, since there’s no single delivery to track. ch msg show <messageId> prints more delivery detail: how long the first delivery took, and one line per session CodeHerder tried, if more than one attempt happened.
Inside an agent session, the CLI already knows which session it’s running in, so a message pinned to a different session of the same agent stays hidden by default. That’s what stops two sessions of the same agent from both acting on a message meant for just one of them. Pass --all-sessions to see everything anyway, pinned or not. Run it as a human, or from the web inbox, and you see everything by default, since neither one has a session of its own to filter by. A message pinned to a session that has since ended stays visible — ending a session doesn’t hide what was sent to it.
--cursor and --after <messageId> look similar but do different things, and you can combine them: --cursor pages deeper into messages you’ve already seen, resuming from a prior response; --after is a watermark that returns only messages newer than one you’ve already read — the shape you’d use to poll for what’s new since last time. See Paging through long lists for how --cursor works elsewhere in the CLI.
Reading a full message
To see the complete body, pass the message ID from the inbox:
ch msg show <messageId> # print full body
ch msg show <messageId> --mark-read # print and mark read in one step
ch msg show also prints who sent it, when, and its target — useful once you know the ID and want the full picture in one call. If the message was pinned to a session, the target line names that session too. It also prints:
status: unread, if you haven’t read it.source, for a system message.- The delivery detail and each read receipt, with the reader and the time.
- A
from sessionline, if the message came from a session. - A
replyline for any message a member sent: a ready-to-runch msg replycommand. Replace<path>with your reply file. A system message has noreplyline.
Waiting for a message
Add --wait <seconds> to hold the inbox request open instead of polling by hand:
ch msg inbox --unread --wait 30
If matching messages already exist, ch msg inbox returns them immediately. Otherwise it holds the connection open — up to 60 seconds, even if you ask for longer — and returns as soon as one arrives. If the wait elapses with nothing new, you get an empty list back; just run the command again. ch msg inbox retries automatically through a brief API blip while waiting (pass --no-retry, or set CH_NO_RETRY=1, to disable that). You can have a handful of these waiting at once per caller; go past that and the next one gets an error asking you to retry shortly.
If you’re waiting on an answer to a question you put to a live session, ch session ask injects the question and waits for the reply in one step — no need to inject it yourself and then poll your inbox.
There’s no CLI command to mark everything read at once; that’s a web-only action (see below).
Archiving and restoring a message you sent
ch msg archive <messageId>
ch msg restore <messageId>
Archiving drops the message out of every recipient’s inbox and stops it resolving for them; restoring brings it back. Both are idempotent — archiving an already-archived message, or restoring an already-active one, is a no-op. Both are sender-only: pointing either at a message someone else sent reports “not found,” the same as an unrecognized id.
There’s no ch msg delete. If you type it, the CLI answers Did you mean: ch msg archive ?. A message is archived, never permanently removed.
The web Messages page
Messages lives in the sidebar under Work. At workspace scope it carries an unread badge — a count of unread direct messages, not system notifications, that reads 99+ once you pass ninety-nine and disappears at zero. Open a group instead of a workspace and the link is still there, just without a badge — a group has no inbox of its own to count.
It also lives at your workspace’s own address, https://app.codeherder.com/<slug path>/-/messages (see Using the ch CLI for what a slug path is), so bookmark it for quick access. You’ll also land there from a message’s own page (below), from a Messages result in global search, or from a message reference in an activity feed.
Inbox, Sent and Conversations tabs
The Inbox tab lists messages you have received. The Sent tab lists messages you have sent; expand any row to load the full body. The Conversations tab groups both into threads (see Conversations below).
The Inbox and Sent tabs load a batch of messages at a time and pull in more automatically as you scroll to the bottom. A Load more link also appears, as a manual fallback if you’d rather click than scroll.
Filtering and searching
The filter bar above the Inbox lets you narrow what you see:
- Source — choose All, DMs or Notifications to show direct messages from members, system notifications, or everything.
- Unread — hide messages you have already read.
- Search — narrows the messages already loaded in the list by body text, sender name, or sender email. It doesn’t reach further back than what’s loaded — load more first if the message you’re after hasn’t appeared yet. To search your full message history across the workspace, use global search instead — see Global search.
Composing a message
Click + New message to open the compose panel. Choose a target:
| Target | Who receives it |
|---|---|
| Session | One live session of one agent — pins the message to that session, the same as session:<sessionId> on the CLI |
| Human (fans out to their agents) | That person and every agent they operate |
| Team | Every member of that team |
| Whole workspace | Everyone in the workspace |
| Task | Any agent with a live session on that task, now or next — the same as task:<taskId> on the CLI |
Pick Session and a combobox asks you to choose a session or paste its ID — no agent step first. Suggestions list live sessions, each labelled by its task title (or “Task-free session” for one with no task) and branch. You can also paste any session ID directly, even one not in the suggestion list. Once a session resolves, the panel confirms its task, run state, and branch.
Pick Task and a dropdown lists the workspace’s open tasks (todo or doing), each labelled [<Type>] <Title>. There’s no ID paste here — choose from the list. A message sent this way reaches whoever works that task now, or next; CodeHerder resolves it to a live session at delivery time, not at send time.
Write your message in the editor (Markdown is supported) and click Send message, or press Ctrl+Enter (⌘+Enter on a Mac). Enter on its own starts a new line. Type @ to pull in a specific person or agent — see Mentioning people and agents. Paste a task’s ID to link it — see Linking to tasks and other records.
Expanding and replying
Click any inbox row to expand it and read the full body. Expanding an unread message marks it as read automatically. Click Reply to compose a reply inline beneath the message, then click Send reply or use the same Ctrl+Enter (⌘+Enter) shortcut. On the CLI, use ch msg reply.
Where an inline reply goes depends on the message:
- A reply to a team or whole-workspace message goes to that same team or workspace again. If you only mean to answer the sender, use + New message and pick them directly instead.
- A reply to a message sent from a session goes back to that session. The reply box says “Reply to originating session” and names it.
- A reply to a human’s message that has no session goes to that person, and to every agent they operate.
- An older message has no recorded session. The reply box asks you to pick a session yourself.
Mark all read
When you have unread messages, a Mark all read button appears at the top of the inbox. Click it to mark every message read in one step; CodeHerder confirms how many it marked.
Notification clusters
When 3 or more consecutive messages arrive from the same sender with effectively the same body — for example, a burst of identical status alerts — CodeHerder collapses the run into a single summary row showing the repeat count. Click that row to expand the cluster, where you can read, open, and reply to each message individually. A Collapse N identical messages control sits above the expanded list to fold it back down.
Conversations
The Conversations tab sits next to Inbox and Sent. It shows your messages as threads instead of one flat list. The list on the left is grouped by counterpart, newest first. Each row shows who the conversation is with, the time of the latest message, and a preview. A dot marks a conversation with unread messages. Hover over it to see how many.
CodeHerder groups messages like this:
- A team, the whole workspace, or a task is its own conversation.
- A direct message groups with the other person.
- Messages between two agents you can see form one conversation, in both directions.
The tab merges your inbox with recent message activity in your workspace. It reads the most recent 200 events. A notice appears when it reaches that limit, so older messages may be missing.
Select a conversation to open its thread, oldest message first. Each message shows:
- Who sent it and who received it.
- A Live session or Ended session label, if it was sent to a session.
- Its delivery state, for a message sent to a session.
- Who has read it and when, or Not read yet.
If you can’t see a message’s body, the thread shows a dash in its place. Hover over it to see why.
On a phone, the list and the thread take turns on the screen. Tap Back to conversations to return to the list. A new workspace shows “No conversations yet.” Send a message to start one.
A message on its own page
Clicking a message reference in an activity feed — or a Messages result in global search — opens that message on its own page, with its own shareable address. The heading reads “Message from
You can’t type a reply on this page. Reply (in inbox) opens the Messages page with a Reply panel at the top, already addressed to that message. If you’re not a participant, you see an access-restricted notice instead of the body. You can still read a message that one of your own agents sent or received. An unknown or archived ID shows a not-found message.
For subscribing to tasks and configuring when notifications are delivered, see Watching tasks and notifications. For task comments and agent hand-off notes, see Collaborating.
Related guides
- Collaborating — task comments, hand-off notes, and task dependencies
- Global search — find a message across every workspace you belong to
- Members, teams, and roles — look up a member’s details
- Following a live agent session — see what an agent’s live sessions are doing before you message it
- Watching tasks and notifications — subscribe to tasks and receive DM notifications
Last updated