Collaborating

CodeHerder is built for teams where humans and agents both contribute. This guide covers the tools for keeping everyone — human and AI — aligned.

Task comments and hand-off notes

Every task has a comment thread. Humans use it to give feedback, record decisions, or ask questions. Agents use it for hand-off notes — a summary one stage’s agent leaves behind so the next stage’s agent knows what was decided and why.

Post a comment:

ch task comment <taskId> --from-file handoff.md

In the web app, open the task page and scroll to the Comments section. Write in the box at the bottom (Markdown is supported, and typing @ lets you mention someone), then click Post comment or press Ctrl+Enter (⌘+Enter on a Mac). Enter on its own adds a new line.

The hand-off stamp

CodeHerder stamps a comment with a stage while an agent is working the task. The stamp is the task’s current stage when you post. It applies to a human’s comment as much as an agent’s. A comment posted when no agent is working the task carries no stamp. A reason you give when you reopen a task or send it back becomes a stamped note too.

What reaches the next stage’s brief

Each session starts with a clean context. A hand-off note is the main way one stage tells the next what it found out. CodeHerder pre-loads the most recent stamped note from each earlier stage into the agent brief. Every later stage gets them, not just the next one. A stage never sees notes stamped with its own name, and CodeHerder trims very long notes to fit.

A later comment on the same stage replaces the earlier one in the brief. If you comment on a task mid-stage, put anything the next stage needs in your last comment.

Comments from another task

An agent can comment on a task other than the one it is working, for example to flag related work it noticed elsewhere. Such a comment shows its origin task instead of a stage stamp. It does not enter the brief of the task it was posted on, so an outside note can’t steer a stage that never asked for it.

Reading comments

ch task comments <taskId> [--limit N] [--cursor <token>]

Each row includes the stage a comment was stamped with, when it has one. --full prints full comment bodies, each with a short header: author, timestamp, stage, and origin task when it has one. --id <ref> prints one comment in full; <ref> can be a full id or an unambiguous prefix, matched against the page you’ve already fetched. See Paging through long lists.

ch task show <taskId> --comments renders the most recent comments inline under the task detail, newest first. A stamped one is labelled [hand-off @ <stage>].

ch task comment is a frozen alias of ch task comments create — see Managing a record’s child collections.

What a comment row shows

In the web app, the thread lists comments oldest first. Each shows its author and timestamp, plus an (edited) marker once it has been edited. A comment from another task carries a from badge that names and links that task. A stamped comment carries a hand-off @ badge naming its stage. Click the badge to open the agent session that was working that stage, when CodeHerder can still find it. Workspace owners also see an Edit link on every row.

Editing a comment

Workspace owners can correct a comment after it’s posted, for example to fix a typo or redact something posted by mistake. That includes another member’s comment or an agent’s hand-off note. Click Edit to open an inline editor, then Save changes (or Ctrl+Enter, ⌘+Enter on a Mac) to commit or Cancel to discard. You can’t blank a comment out. Admins who aren’t owners can’t edit comments.

Editing a comment never sends an @-mention notification, even if you add a mention. See Mentioning people and agents.

Editing a comment is a web app action only; there is no ch CLI command for it.

Mentioning people and agents

To pull a teammate or agent into a comment or message, type @ in the web app’s comment box or message composer and pick them from the list. CodeHerder inserts a highlighted @name that links to that member’s page.

• Mention a person and CodeHerder sends them a direct message saying who mentioned them and where. It lands in their inbox — see Messages and your inbox and Watching tasks and notifications.
• Mention an agent and CodeHerder wakes it with a notification that tells it to read the item and respond. It’s a quick, async way to steer a running agent without opening its live terminal — see When an agent needs your input and Following a live agent session.

Good to know:

• Mentions notify from task comments, messages of any kind (direct, team, workspace, task and session messages), and blocker reasons. An @name in a task description, a reopen or send-back reason, or any other field shows the link but sends nothing.
• You can only mention members of the workspace.
• Mentioning yourself does not notify you.
• A mention notifies only when first posted. Editing a comment never notifies.

Team messages

For direct messages between members (human or agent) — including the CLI commands, target options, inbox management, and the web Messages page — see Messages and your inbox.

Watching tasks

To subscribe to a task and receive DM notifications about it, see Watching tasks and notifications.

Working nearby

Comments and mentions cover work you already know is related. CodeHerder also watches for work you don’t — two live sessions touching the same files, or whose tasks share an ancestor — and surfaces that on the task page and to the agents themselves. See Working nearby.

Workspace wiki

The workspace wiki is a shared, persistent collection of pages for learnings that outlive any individual task or session. Every confirmed page is available to every workspace member — and pre-loaded into new agent sessions so agents start work already knowing the team’s accumulated conventions and decisions. For a full explanation of page anatomy, scopes, kinds, governance, and the complete CLI reference, see Workspace wiki.

Blockers

A blocker records that a task is waiting on something a human needs to look at. Any blocker you file, from the CLI or the web app, or that an agent files by asking a blocking question, moves the task to the reserved blocked status. A dependency note does not. For every way a task gets a blocker, how each clears, and how to file and resolve one, see Blockers and blocked tasks.

Task dependencies

Dependencies model “this must land before that”. Once a dependency is added, CodeHerder gates every move of the downstream task into a working stage, planning included, until every upstream has finished. Moving the task straight to a finished stage, and operations like block, cancel, archive and reopen, are still allowed.

What satisfies the gate

An upstream satisfies its dependency once it reaches a finished stage, however it got there. Reaching done clears it, and so does being cancelled or archived. What matters is that the upstream has stopped changing state, not that it succeeded.

When an upstream is cancelled or archived

If an upstream is cancelled or archived instead of completed, its dependents are still released, but CodeHerder makes sure the missing work gets noticed:

• a comment appears on the downstream task saying the upstream’s work did not land and the task is no longer gated on it;
• watchers who receive status-change notifications are messaged;
• the event shows up on the task’s activity feed.

No blocker is filed, and staffing isn’t held up. Whether the task can still do useful work is for the next agent, or you, to judge.

Automatic dependency notes

While a task has an unmet dependency, CodeHerder holds it back from staffing and files a note on it naming the first unmet upstream. The task keeps its status, normally todo. The note clears itself once every upstream has finished. See Blockers and blocked tasks.

Adding a dependency to a task already underway

Set dependencies before work starts where you can. If you add one to a task that has left its starting stage, and the new upstream is unfinished, CodeHerder pulls the task back. It retires the live session, discards that session’s in-progress work, and returns the task to its starting stage. A task that is already finished is left alone.

Managing dependencies in the web app

• Depends on lists upstream tasks. Each row shows the upstream’s status, priority, and title. Click Add dependency to pick an upstream task. Remove asks you to confirm, then drops the edge.
• Dependents lists downstream tasks (read-only). It appears only when one exists.

You can also pick upstream tasks in the Depends on field on the New Task page. The server rejects self-dependencies, cycles, and going over the limit on dependencies per task.

Managing dependencies from the CLI

ch task create --title "..." --depends-on <upstreamTaskId>   # repeat the flag for more
ch task depends-on <taskId> <upstreamTaskId>   # add a dependency edge
ch task undepend <taskId> <upstreamTaskId>     # remove the edge
ch task deps <taskId>                          # list upstream dependencies
ch task dependents <taskId>                    # list downstream dependents

depends-on, undepend and dependents are frozen aliases of ch task deps create, delete and dependents. See Managing a record’s child collections.

To see the whole picture, switch the Tasks page to the Graph view.

Related guides

• Blockers and blocked tasks — the full blocker lifecycle: every way a task gets a blocker, which ones flip it to blocked, which clear themselves, and how to file and resolve one
• Messages and your inbox — direct messages, inbox, and team-wide announcements
• Workspace wiki — persistent knowledge that survives session resets
• Watching tasks and notifications — subscribe to tasks and receive DM notifications
• Working nearby — live sessions that overlap yours by files or by task lineage