mirror of https://github.com/Ark0N/Codeman.git synced 2026-09-30 12:39:42 +02:00

Files

T

Codeman maintainer bd286bf502 docs(wiki): catch the manual up to 1.29.0 and add the three run modes it never had

The wiki was written for seven run modes and never received Grok Build, DeepSeek
Harness or OMP. They now appear everywhere the others do: the modes table and
per-CLI notes, install commands, environment prefixes, the Quick Start table, the
requirements rows, the vocabulary, and every "seven modes" count.

The 1.27 to 1.29.0 changes land on the pages that own them: attaching a case to an
existing container, multi-case adoption and the copy-a-case picker (Docker Cases);
file reads over ssh in remote cases and what stays unavailable (Remote SSH Sessions,
Working With Files, Security); single-page app routing, frame recovery, localhost
links as tabs and the egress guard (Web Tabs); DeepSeek as the one non-Claude mode
with real stop/blocked signals and Approvals items, Codex's own work detection,
last-response, the model-endpoint routes and refreshed counts (HTTP API, Driving
From An Agent, Hooks, Notifications, Keeping Agents Running, Core Concepts);
Shift+drag, right-click copy, Auto Copy, the Ctrl+Z guard, font weight, the vertical
rail and its activity sort (Keyboard Shortcuts, Input And Voice, The Dashboard,
Settings Reference); the 600px phone cutoff, Codex shift arrows and iPhone Duo
(Mobile Guide); the Docker Compose route and its update rule (Installation, Running
As A Service); four new symptom entries and a "which CLIs" question (Troubleshooting,
FAQ).

Custom model endpoints are deliberately left to #430, which adds that page and edits
Agent CLIs, Settings Reference and the sidebar; these edits stay out of the regions
#430, #428 and #376 touch, and all three still merge cleanly on top.

Both READMEs: the web-tab menu entry is labelled "Add URL" in the UI, not
"Add dashboard".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2026-09-15 19:05:59 +02:00

6.9 KiB

Raw Blame History

Notifications and Approvals

An agent that stops to ask a question, with nobody watching, is a run that quietly wasted an hour. This page covers every way Codeman tells you it needs you, and how to answer without opening the session.

The signals, cheapest first

Surface	Reaches you	Default
Tab alert	While the dashboard is open	On
Browser title flash	Another tab in the same browser	On
Desktop notification	Another window on the same machine	Opt-in
Push notification	Anywhere, even with no tab open	Opt-in
Approvals Inbox	One queue across every session	Opt-in
Phone overview	Phone home screen, NEEDS YOU section	On
Away Digest	Afterwards, as a summary	Opt-in

Tab alerts

The tab itself changes state:

State	Meaning
Yellow, blinking	The agent is waiting for input from you.
Red, blinking	A question or permission prompt is blocking the session.

These are a steady colour with a pulse layered on top, not a blink to transparent, so a tab needing attention looks that way at every point in the cycle.

They survive a reload. The alert state is re-seeded from the server on page load, so reloading the dashboard while a permission dialog is blocking a session does not leave you with a normal-looking tab.

For Claude sessions, these come from Claude Code's hooks and are precise about why the session stopped; DeepSeek Harness sessions report the same states themselves. For the other CLIs there are no hooks, so you get the coarser output-based signal.

Window title and OS notifications

The browser tab title is prefixed codeman:<host>, so several Codeman instances across several machines stay distinguishable at a glance. Override the hostname with codeman web --title-hostname <name>.

Desktop notifications use the same prefix. Enable them in App Settings → Notifications.

Push notifications

Push reaches your phone with no Codeman tab open at all, which is the only option that works while you are actually away.

Setup:

Open Codeman over HTTPS. Web push requires a secure context. Tailscale gives you real HTTPS; --https gives you a self-signed certificate; plain HTTP over a LAN address will not work.
App Settings → Notifications → Subscribe, and accept the browser prompt.
On iOS, add Codeman to your home screen first. Safari only delivers web push to installed web apps, not to tabs.

Once subscribed, a blocking prompt reaches your phone even from a locked screen.

The Approvals Inbox

Opt-in, off by default. Claude sessions, plus DeepSeek Harness sessions, whose terminal front door reports its prompts to Codeman.

One queue of every prompt currently waiting on a human, across all your sessions, answerable in place. When you have eight workers running, this is the difference between checking eight tabs and checking one list.

Turn it on in App Settings. Surfaces:

A header bell with a count, hidden entirely while the count is zero. Never shown on phones.
A drawer listing each waiting card.
NEEDS YOU strips at the top of the phone overview home screen.

Each card shows the session, the case, and the captured prompt with its options. Answering sends the keystroke into the session for you: a digit for a menu choice, Escape to decline, or free text for an idle prompt.

Behaviour worth knowing:

One item per session. A newer prompt supersedes the older one, because the older one is no longer on screen.
Menu answers are validated against the live screen. Codeman re-captures the pane before sending, and refuses with a conflict if the dialog is no longer there. Otherwise your keystroke would land in the composer as stray text.
Permission and question items clear only on definitive signals: the turn ending, the dialog completing, an answer, a supersede, the session exiting, or a 12 hour timeout. They do not clear on a heuristic "looks busy again" signal, because that signal is wrong often enough to lose a real prompt.
In memory only. Restarting the server clears the queue; the prompts themselves are still sitting in the sessions.

Approve and Deny from the notification

With the inbox enabled, push notifications carry Approve and Deny buttons. Those are handled by the service worker directly, so they work with no tab open: tap Approve on a locked phone and the agent continues.

With the inbox off, the buttons are stripped from the notification payload entirely rather than being shown and failing.

The phone overview

On phones, tapping the "C" logo gives a session overview with NEEDS YOU first, then current sessions, then past ones. Rows use the same language as the tab strip: a green dot when fine, pulsing while working, yellow when waiting for input, red when a question is pending.

Answer strips let you resolve a prompt straight from the home screen without opening the session.

The Away Digest

Retrospective rather than live: what happened while you were gone, aggregated from the lifecycle log, run summaries, live sessions, token statistics, and recent subagents.

It is the morning-after view for an overnight run. Enable its header button in App Settings → Header & Panels.

Recommended setup for unattended runs

HTTPS access, ideally Tailscale. See Remote Access.
Push notifications subscribed, with Codeman installed to the home screen on iOS.
Approvals Inbox on.
Auto-resume on usage limit on, for each session you leave running. See Keeping Agents Running.

That combination means a blocking question wakes your phone and can be answered in two taps from the lock screen.

Gotchas

No push over plain HTTP. It is a browser requirement, not a Codeman one.
iOS needs the home screen install. A Safari tab will never receive push.
The bell is invisible at zero. That is deliberate, not a broken setting.
Approvals need real signals. They are built on hook events, which Claude emits and DeepSeek Harness reports itself; the other CLIs do neither.
A stale menu answer is refused, not sent. If you answer a card for a dialog that has since gone away, Codeman declines rather than typing a digit into the composer.

6.9 KiB Raw Blame History