Collaborating

Task comments and hand-off notes, editing a comment, @-mentions, team messages, workspace memory, blockers, and task dependencies.

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 — the structured summary one stage’s agent leaves behind so the next stage’s agent knows what was decided and why.

Because each session starts with a clean context, the hand-off note is the only way one stage can tell the next what it found out. The note is pre-loaded into the next agent’s brief. Writing a good hand-off comment is therefore one of the most important things an agent does before advancing a task.

Editing a comment

Workspace owners can correct a comment after it’s posted — fixing a typo, or redacting something posted by mistake. From the task detail page in the web app, an owner sees an Edit link next to any comment, including another member’s or an agent’s hand-off note. Clicking it opens an inline editor; Save commits the change, Cancel discards it. An empty body is rejected — you can’t blank a comment out entirely.

Once a comment has been edited, an (edited) marker appears next to its timestamp, so the thread stays honest about what changed. Editing a comment never sends a new @-mention notification, even if you add a mention while editing — see Mentioning people and agents below for the exact rule.

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

Mentioning people and agents

To pull a specific 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 that appears. CodeHerder inserts a highlighted @name that links straight to that member’s page.

Mentioning someone does one of two things, depending on who you mention:

Mention a person and CodeHerder sends them a direct message pointing back to where you mentioned them. It lands in their inbox — see Messages and your inbox and Watching tasks and notifications.
Mention an agent and CodeHerder notifies it through the same channel as a direct message, prompting 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 and direct messages only. Typing an @name into a task’s description (or any other task field) still shows the highlighted link, but it does not send a notification.
You can only mention members of your own workspace.
Mentioning yourself does not notify you.
A mention notifies only when it’s first posted. Editing a comment or message to keep — or even add — a mention never sends a notification.

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.

Workspace memory

Workspace memory is a shared, persistent store for learnings that outlive any individual task or session. Every confirmed entry 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 entry anatomy, scopes, kinds, the review gate, and the complete CLI reference, see Workspace memory.

Blockers

A blocker records that a task is paused, or held back from staffing, waiting on something a human needs to look at — filed by a person, or by CodeHerder itself for a reason like an unmet dependency or an agent question it can’t answer alone. A human-filed blocker moves the task straight to the reserved blocked status; a dependency blocker instead holds the task at its current stage.

For the full picture — every way a task gets a blocker, which ones flip it to blocked and which don’t, which clear themselves and which need you, the Blockers page in the web app, and how to file and resolve one from the CLI or the web app — see Blockers and blocked tasks.

Task dependencies

Dependencies model the “this must land before that” relationship between tasks. Once a dependency is added, CodeHerder gates every forward advance on the downstream task — planning stages included, not just build stages — until every upstream task has finished.

What satisfies the gate

An upstream satisfies its dependency once it finishes, regardless of how. 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

Finishing isn’t the same as delivering. If an upstream is cancelled or archived instead of completed, its dependents are still released to proceed, but CodeHerder makes sure a human notices the work never landed:

a comment appears on the downstream task explaining that the upstream reached that status, that the task is no longer gated on it and can be staffed, and that the upstream’s work did not land;
the downstream task’s owner and anyone watching it are notified;
the event shows up on the task’s activity feed.

No blocker is filed, and staffing isn’t held up. Whether the downstream task can still do useful work without whatever the upstream would have produced is for the next agent (or you) to work out — the comment exists so that judgment call doesn’t get missed.

Automatic dependency blockers

When the engine finds that a task has an unmet dependency, it automatically files a blocker on the downstream task — this holds the task back from staffing without changing its status, so it stays at whatever stage it was already at (normally todo). No manual action is required: the note clears itself, and the task becomes eligible for staffing again, the next time it’s checked and every upstream has finished. For the full blocker lifecycle, including how status differs between a dependency blocker and a blocked task, and how to file and resolve a blocker, see Blockers and blocked tasks.

Adding a dependency to a task already underway

Dependencies are meant to be set before work starts, but CodeHerder also enforces the gate if you add one after the fact. Adding a dependency to a task that has already left its starting stage pulls it back: CodeHerder retires its live session, discards that session’s in-progress work, and reverts the task to its starting stage so the dependency gate governs when it’s allowed to start again. Add dependencies up front where you can to avoid losing in-flight work.

Managing dependencies in the web app

On a task’s detail page you will find two sections:

Depends on — upstream tasks this one is waiting for. Each row shows the upstream’s status, priority, and title. Click + Add dependency to open a picker and select an upstream task. Click Remove on any row to drop the edge.
Dependents — downstream tasks waiting on this one (read-only). This section appears only when at least one dependent exists.

The picker excludes the task itself and tasks already linked; the server rejects self-dependencies and cycles with a clear error.

Managing dependencies from the CLI

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

Self-dependencies and cycles are rejected server-side with a clear error message.

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 memory — persistent knowledge that survives session resets
Watching tasks and notifications — subscribe to tasks and receive DM notifications
Feedback inbox — agent suggestions and workflow proposals