Console UI review¶
Reviewed October 16, 2026. Scope: starting work, project selection and creation, project pages, navigation, keyboard interaction, and narrow screens. This review combines source inspection, a live local preview, and official product references.
Reference patterns¶
| Reference | Documented behavior | Application to Humagen |
|---|---|---|
| ChatGPT projects | Projects collect related chats, files and instructions; creation starts from Projects in the sidebar | Use one name for the concept throughout the console; make the selected context visible before sending |
| Claude projects | Projects have names and descriptions; standalone chats can be moved into or out of projects | Treat projectless work as a valid choice, show descriptions when choosing context, and keep project identity distinct from presentation |
These are documented reference flows, not claims that Humagen duplicates their interfaces. Humagen's useful difference is choosing an answering agent alongside the project in the composer. Both controls should remain quiet and readable.
Findings and changes¶
| Priority | Finding | Result |
|---|---|---|
| High | The prompt bar says No project, which reads as a status rather than an invitation to choose | Untouched state says Select project. Projectless is an explicit choice in the picker and remains visible after selection |
| High | Creating a project requires leaving the prompt bar and finding the sidebar plus | The picker offers Create project, accepts a name and optional description, selects the result, refreshes the sidebar, and keeps the message draft |
| High | Projects are called Areas in navigation and settings, but Project in the prompt bar | Projects is now used throughout the relevant console surfaces, including error messages and storage's Projectless grouping |
| High | At phone widths, an expanded sidebar compresses the main column; a picker anchored beside attachments can extend past the viewport | The expanded sidebar overlays the page with a dismiss control on small screens. The project panel and long labels are bounded to the available width |
| Medium | Project names alone are weak context when several projects have similar names | The picker searches names and descriptions and shows descriptions with each result. Projectless and creation stay available when no result matches |
| Medium | A second form inside the message form could submit a draft when someone searches or creates a project | Project creation uses explicit buttons without nesting forms. Enter in search does not send; Enter in creation validates and creates |
| Medium | Closing a popover through its child callback leaves focus on an element being removed | Popover close now returns focus to its trigger, matching the existing Escape behavior |
| Medium | Translucent project descriptions overlap the greeting and message text | The project panel uses the console's solid panel surface; existing fonts, agent colors and quiet text controls remain |
| Low | Sidebar creation requires discovering that Enter submits the name | Sidebar creation now has a visible Create project button and a pending state |
Next work¶
| Priority | Follow-up | Boundary |
|---|---|---|
| High | Project deletion should explain that shared memory is removed and require a deliberate confirmation | Current project deletion is immediate. This pass did not change deletion behavior |
| Medium | Make project and conversation destinations survive refresh and support sharing a direct link | Project selection is local UI state; the address currently returns to the root for project views |
| Medium | Let people edit conversation titles and project display titles | Conversation titles are currently generated by an optional title agent or derived from the first message. Add dedicated update operations and permission checks before exposing edit controls |
| Medium | Configurable console headings and labels | Add optional workspace display configuration with named keys, defaults and plain-text limits. Apply the same values to navigation, headings, empty states and accessible labels. Keep routes, project identifiers, permission names and API fields stable |
| Low | Simplify the first view of workspace tools | Keep starting work and returning to conversations prominent; progressively expose agent administration and operational tools. The Home redesign already in progress is separate from this change |
Display configuration should be workspace-owned, with defaults for missing keys. It should not rename stored project identities: those currently connect memory, conversations, schedules and limits. A project display title needs its own field and API contract. Configuration is a follow-up, not implemented in this pass.
Verification¶
- Web typecheck and the existing web suite, plus a regression covering an empty workspace, the distinction between untouched and explicit Projectless, loading state, and the prohibition on nesting a form inside the composer.
- Live browser: search with no results, Enter in search without sending the draft, duplicate-name failure, successful creation with description, draft preservation, immediate selection and sidebar refresh, and inherited selection from a project.
- Desktop and 390-pixel viewport inspection, including an open project picker. At 390 pixels, document width equals viewport width after the overflow fix.
No authenticated competitor accounts or production workspace data were used.
Project icons and the collapsed rail¶
Follow-up review: ChatGPT's official project screenshots show icons beside project names and a folder-plus creation action. Claude's project guide places project navigation in the sidebar. The live Claude page required sign-in; ChatGPT's live page presented a browser check. The comparison therefore uses official documentation and the published ChatGPT screenshot, without claiming to have inspected either signed-in interface.
Humagen now uses shared Humagen folder, open-folder and folder-plus icons in project navigation and the composer. Projectless work uses a conversation icon. A folder remains in the collapsed rail and opens a named project list, including creation when permitted. Opening a project closes the flyout and highlights its folder. This keeps projects reachable without filling the rail with identical, unlabelled project icons.
Navigation links reveal text labels on hover and keyboard focus. New conversation
uses a compose symbol, execution history uses a history symbol, the sidebar
toggle shows its opening or closing direction, and collapsed Settings uses a
gear. Home remains directly reachable in both sidebar states. The shared icons
and tooltip live in packages/render-web.
Verified in the local browser: collapsed project navigation, selection and active state, keyboard opening and Escape focus restoration, keyboard tooltip labels, and a 390-pixel viewport with no horizontal overflow. A regression covers the collapsed Projects entry and project-creation permission.
A flatter sidebar, after Claude's desktop app¶
Follow-up review against Claude's desktop app, from a screenshot of its signed-in sidebar: a short flat list (New, Projects, Artifacts, Scheduled, Customize, More), then Pinned, then Chats and tasks. Humagen's sidebar had Home and New conversation side by side, though both open the same empty conversation, and two labelled groups of eight tools under the task list.
Humagen now follows the same shape:
- New is home. The separate Home entry is gone, and New is current on the empty conversation at the bare address.
- Projects opens a page of project cards with a New Project button, instead of an expanding list in the sidebar. Deleting a project returns to it.
- Inbox and Scheduled stay at the top level, since people use them daily.
- More folds Agents, Knowledge, Storage, Evals, Execution history, Analytics and Alerts. It stays open while one of its pages is on screen, shows a dot when an alert is waiting, remembers its state per browser, and is a flyout in the collapsed rail.
- Pinned holds conversations a person pins from the pin beside each task.
Pins are saved with their preferences (
pinnedonPUT /api/preferences), so they follow the person to another browser. - Conversations rows (once called Tasks) are one line: the agent's orb and the title, with the state and project in the row's tooltip and read out to screen readers.
Verified in the local browser with make dev: pinning, a pin surviving a
reload, More open and folded, the Projects page, and the collapsed rail.
One console for agents across systems¶
Second pass, after the first one above. Humagen is a place to run work with agents, project by project, so the navigation follows the work rather than the platform's parts.
- Sidebar order: New, Projects, Schedules, Alerts, Inbox, Knowledge, Agents, Artifacts, then Pinned and Conversations. There is no More menu.
- Execution history leaves the sidebar: each task already holds the history of every run in it, and a run anywhere opens its task.
- Evals live on the agent or knowledge source they test.
- Analytics is the Overview tab of Alerts, next to the rules that watch it.
- Storage is named Artifacts.
- Deep links: every page, tab and selection is a path, such as
/agents/lead/accessor/knowledge/handbook/evals, and back and forward work. - One page layout: one centered column with a back link, a title and meta line, actions on the right, and tabs that stay in view while scrolling.
- Agents: Prompt, Model, Access, Knowledge, Memory, Evals, Alerts and Revisions tabs.
- The model is a policy: a primary and ordered fallbacks.
- Agents it may call, and sources it reads, are picked from a searchable list. A switch per agent did not scale.
- Approving a call to another agent is no longer offered. Agents call through one host tool, so that approval named a tool the agent never held, and the agent could not start.
- Alerts:
- Rules can be edited and paused.
- They can be scoped to a project, notify chosen people and roles, wait out a cooldown, and watch spend.
- Schedules: each one has a page with its upcoming times and recent runs, and it can be edited without losing either.
Patterns¶
The console is built from a small set of usage patterns. A change uses one of
them; it does not add a new kind of UI. Web-only layout lives in
apps/web/src/ui.tsx. Anything Slack also draws lives in the shared packages:
the model and ordering in packages/core (such as HomeModel,
orderNotifications, HOME_NEEDS), the words in
packages/components/src/copy.ts.
| Pattern | What it is for | Renders it | When not to use it |
|---|---|---|---|
| Page | One screen with one title (its only h1), a line on what it is for, its own actions on the right and tabs under it | Page |
A pane inside another page; there the title is an h2. Home's title is its greeting, drawn by HomePage |
| Page actions | A page's own actions in its header: at most one primary action as a button, and the rest beside it. With more than two in all, the rest are one More menu, a text control reached by Tab and worked with the arrow keys, Escape and Enter, with destructive ones (Archive, Delete) last after a rule. On a phone the header is its title, its meta and at most two controls on one line | PageActions, MoreMenu |
Actions on one row or one item of a list; those sit at the row's end |
| Destructive action | Undoable acts at once, permanent asks twice. Archive and Mute act at once, since they can be undone. Delete Project, a schedule's Delete and an artifact's Delete Version ask once to start and once to confirm, in words, in place on the page with no modal: the question, the action and Keep It, with focus on Keep It. Escape or moving focus away keeps things as they are | Confirm |
An action that can be undone; asking twice there only slows people down |
| Section | A titled part of a page: a heading, its count, a hint and its actions | Section |
A single line or a single control; put it in the page or the section above |
| Box | A section that stands on its own as a panel, such as Home's Needs you | Section box (the card panel) |
Every part of a long page; boxes inside boxes |
| Row that opens something | A list item whose whole row is the control: what it is on the first line, who, where or when under it | RowButton, or a button in a rows list |
Rows that hold several controls of their own; put those controls at the row's end |
| Text action | A section's way to the rest, in Title Case and underlined, so it reads as a control on a phone too: Open Inbox, See All | textAction |
The page's main action, which is a primary button |
| Text link | A control inside a line of text, a row's details or a table cell: an agent's name, Open the run, Download. Underlined and 24px tall | textLink |
Anything a person reaches for first; give it a button |
| Back link | Where the page sits: the list it came from | Page's back |
Navigation between siblings; use tabs |
| Tabs | The parts of one thing, each with an address in route.ts |
Tabs |
Filters over one list; use chips |
| Chips | Selections and attachments: a kind filter, a file to send, a tag on a row | KindChips, Chip, the composer's attachments |
Actions, and one choice on its own (a lone pill reads as a stray control) |
| Text controls under the composer | Choices under the chat bar, such as Best Fit or All of Them, as text, never boxes; the + menu's agents, project and channel, and attachments, are chips | The composer (Composer.tsx) |
Anywhere else |
| Count | How many there are, beside its label in a heading or a tab, never on its own and never a status color. Hidden at zero. Read as "Needs you, 3" | Count, Section count, Tabs |
A count that is the content, such as a figure on Monitor; use Stat |
| Empty | What a list or box says when it has nothing, in words, with what to do next | Empty on a page, a quiet line in a box |
Hiding the section: an empty box says so, rather than vanishing |
| Loading | A list being read, at the height it will have | SkeletonRows, or a still "Loading" line where something waits on a person |
Spinners; anything that moves on Home or in the inbox |
| Error | What could not be done, and where to look instead | Problem for a failed action, a quiet line in a box for a failed read |
Toasts that vanish before they are read |
Agents are told apart by color (AgentMark), never by letters in boxes.
Anything waiting on a person does not animate.
Home under the chat bar¶
October 22, 2026. The owner sent a phone screenshot of Home: under the chat bar, a lone starter pill and, far below, a bare line, "Needs you · 1", that read as text rather than a way into the inbox.
Home now has two boxes under the chat bar, side by side on a desktop and stacked on a phone:
- Needs you lists the five newest things waiting on the person, each a row
with who raised it and when, read with
needs=trueonGET /api/inbox. The heading carries the count of all of them, and Open Inbox goes to the rest. - What's new lists announcements from the person's projects, unread first and marked "Unread" for screen readers as well as by the dot, with where each was posted. See All opens the inbox's announcements.
- A box with nothing in it says so. A person with nothing in either sees one Welcome box saying what Home is for.
- While Home reads, each box says "Loading" without moving; a read that failed says the inbox has it all.
The starter prompts and the chat bar belong to the conversation work and were not changed here.
Audit at phone and desktop width¶
October 22, 2026. Every console page and tab at 390x844 and 1280x800, against the patterns above, with the layout checks below.
| Where | What broke the patterns | Fix |
|---|---|---|
| Home | "Needs you · N" was a bare line that read as text; What's new had no box or way to the rest | The two boxes above |
| Every page on a phone | The sidebar button sat 8px from the edge, inside the gutter | It sits on the 16px gutter |
| Settings on a phone | The section strip scrolled under both screen edges | The strip scrolls inside the gutter |
| Inbox | The page had no h1: the mailbox's title was an h2, and the page was the one top-level screen without Page |
The Inbox is a Page, as docs/architecture/projects.md asks: its title and open count are the page's, and the mailbox leaves out its own (heading={false}), with Open, Resolved and All at the end of the filters' row |
| Project | The meta line did not say who answers there | It names the lead, the agent that answers a Slack or GitHub message that tags no agent, with its AgentMark: "Account · in Field · Lead globex-helper" |
| Pages with a back link, project crumbs | "‹ All projects" and the crumbs were 18px tall text | 24px tall, still text |
| Artifacts, Monitor, Limits | Three copies of a "linkish" style, 18px tall | One textLink, 24px tall |
| Monitor, Schedules, Directory, an agent's Access | Agent names, "Open run" and project links were 18 to 20px tall, and some only underlined on hover, so they read as plain text | textLink, or a 24px line |
| Directory | The agents list drew a second rule under the tabs | The tabs' rule is the only one above the first row |
| Search fields, limit fields | The 20px input was the only target inside a 32px frame | The input fills its frame |
| Switches | The label, which is the target, was 20px tall | 24px at least |
| Project Overview | Counts written "Sub-projects (0)" and "Scheduled (0)" | Count beside the heading, hidden at zero |
| Project, Schedule | Six and four boxed buttons in the header, three rows of them on a phone, Delete beside the everyday ones | PageActions: New Conversation and Run Now are the primary actions, the rest are under More, Archive and Delete last after a rule. Each keeps its permission check and does what its button did |
| Project Context, Knowledge | The new knowledge editor drew its own headings, and with no sources in the workspace it showed only a disabled Save Knowledge, without saying why | Two Sections, as the rest of the tab; with nothing to name it says the workspace has no sources yet. make screens seeds two sources and captures the project's and the workspace's Context tabs |
| Project, Schedule | Delete Project and a schedule's Delete acted at once, though neither can be undone | They ask twice with Confirm, the pattern Delete Version already used, now one shared control |
| Inbox | The same announcements were "What's new" on Home and "Updates" in the inbox | "What's new" in both; the address is unchanged |
| Home, Slack Home | An urgent item looked like any other | An item above normal says so in words before when it came ("Urgent · just now"); a normal one says nothing more |
Left as they are: the mailbox's group counts ("NEEDS YOU 3") and a project inbox's "3 open" use the shared web package's own styles, and the run history panel beside a conversation writes its counts as "Running (2)"; both sit next to the conversation work.
Checking a UI change¶
make screens builds Humagen and the console, starts Humagen on a free loopback port
with the development sign-in, the seeded agents and state in memory, adds
announcements, failed runs and a schedule through the API, and captures every
page and tab at 390x844 and 1280x800. It uses an installed Chromium or Chrome
(CHROMIUM names one) and downloads none. Screenshots go to .screens/, which
git ignores: index.html shows phone and desktop side by side, and a page that
scrolls also gets name.full.png. A screen may act on the page once it is drawn (act), so project-more
and schedule-more show the More menu open, and the chat's states show
completion and the + menu, each checked like the rest. Text in a floating layer
(data-layer, or a menu, dialog, listbox or tooltip) is checked against its own
lines, not against the page under it. SCREENS_ONLY=home,inbox captures only those.
The run fails when a screen breaks a layout check (scripts/screens/checks.ts,
a pure function of the measured page, tested in checks.test.ts):
- No horizontal overflow: the document is exactly as wide as the window.
- On a phone, no text or control past the 16px gutter.
- No control under 24 by 24 pixels (WCAG 2.5.8). A control with words of its own inside a paragraph is exempt; a field or checkbox is measured by its label.
- Exactly one h1 on every page.
- No line of text over another in the main column.
The CI job "Console screens" runs it on every pull request that changes
apps/web, packages, scripts/screens, the Makefile, the lockfile or the
workflow, and uploads .screens/ as the
console-screens artifact.
Every UI change lists the screens it changes, with the before and after
screenshots from make screens, in its pull request.
Stable agent colors¶
AgentMark, agent tints, run strokes and usage bars use a workspace-wide hue
reservation returned by GET /api/agents. Reservations are written through
pkg/state before use, so every reader gets the same color after a restart
and adding, removing or renaming other agents never recolors a name. A deleted
name keeps its reservation, including when it is created again.
The first twelve hues keep the old hash's preferred color where available.
A collision takes an unused hue; after twelve reservations the allocator fills
successive gaps between hues. This is the smallest change that guarantees
unique hue values without changing agent specs or adding a configuration choice.
A larger hash palette alone would still collide. The server returns assignments
only for readable agents. Each workspace has at most 10,000 reserved names;
exhaustion or a failed write refuses the list rather than returning colliding
assignments. A mark reserves its space without drawing an orb until its server
hue arrives.
A bounded GET /api/agent-hues lookup, behind runs:read, batches at most
100 explicitly named readable agents for readers without agents:read.
A second route, GET /api/project-agent-hues, uses the same bounded handler
behind projects:read, for project readers without run or agent permissions.
The host selects the route the reader may call. Hidden and missing names are
both omitted. No names are enumerated.
The host clears the palette on identity changes and retries failed lookups at
most twice. Tints and non-mark accents retain the original hue while loading.
Distinct hue values do not guarantee perceptually distinct colors for thousands
of agents. Names remain beside marks wherever people choose an agent.
The agent-colors screenshot state includes more than twelve custom agents,
checked at phone and desktop widths by make screens.
The built-in handle rename retains each agent's original color reservation. Both spellings resolve to that reservation, so history and new conversations keep the same mark; unrelated agents retain distinct assignments.
Contextual agent and project discovery¶
Project/agent matching belongs beside the composer's agent and project choices. The picker names the action Find an Agent or Project and shows matches in the same panel. Selection keeps the current draft and uploads, and sends nothing. The new-conversation picker owns this action; an existing conversation retains its project. Home has no separate discovery link below the composer.
Action icons and failure spacing¶
Use the existing inline Lucide-style geometry for action and navigation icons. Reply uses a returning arrow, Fork uses branching, and skill and memory actions use a wrench and bookmark. Keep visible labels on less frequent actions. Shared footer icons use 16px geometry with 44px coarse-pointer targets.
Inbox recovery reads as distinct sections: sender and time, alert context, actionable failure, and related objects. Companion runtime diagnostics start collapsed. The failure callout, actions and reference form one shared stack; metadata and related-object names wrap instead of truncating into ambiguous chips. No notification or pending-person indicator animates.
Notifications in navigation¶
The bell is a normal top-level navigation link with an active state and a live
count, available in the expanded sidebar and collapsed rail. /notifications
uses the normal page shell, a reading-width list and separated update groups.
Preferences have a direct link in its header and remain a separate personal
settings route. The delivery feed no longer appears as a bordered disclosure
inside navigation or preferences.
Navigation uses one semantic shared icon per destination: a database for sources, wrench for skills, brain for memory, plug for integrations, network for coordination, shield for policies, sliders for controls and a record for audit. Search uses a magnifying glass. Icons supplement the existing text labels.
Conversation drawers and search¶
Desktop inspectors dock beside the conversation. Keep the reading column and composer within the remaining width; only compact screens use a modal edge drawer. Use one title aligned with its project/channel metadata and shared 18px header icons in 36px controls. Share contains placement controls; More contains less frequent conversation views. Charcoal surfaces give the sidebar, conversation and drawer separate planes without floating rounded containers.
AI Elements conversation and Aceternity sidebar and modal informed the review. Implementation retains Humagen's existing React primitives, shared icons and native dialog semantics.
Search uses a centered native modal with readable result excerpts, filters, arrow-key navigation, Escape and focus return. It searches existing readable workspace content through the bounded server API; search never invokes an agent. DES-012 records indexing coverage and limits.
Composer context hierarchy¶
The plus menu groups choices by what the person is adding: files, agents, projects or skills. Use one shared row size, semantic icon and trailing chevron for categories. Each pane has a clear title and Back control. Channel choices belong inside their project and use the same full-width selected rows; a single default General channel remains internal. Existing conversations keep their locked project.
Choosing a skill uses the existing skill tag and preserves the current text and files. The visible list belongs to the exact loaded project, so stale results cannot cross a project change. Search and selection never send the message.