Projects & workspace
Key takeaway: A project in Heygents is a workspace, not a folder of tickets. It records where your code lives, whether the thing is currently up, what it is supposed to become, and what needs doing next. Each project has a status, an accent colour, a live health dot, and four tabs: Info, Plan, Tasks and Automations.
A project in Heygents is not a folder of tickets. It is a workspace that knows where your code lives, whether the thing is currently up, what it is supposed to become, and what needs doing next. This page covers the project list and every tab of the workspace.
The project list
Your projects live in the My Projects section of the left nav rail, and the same list appears on the Home dashboard and as the Projects tab on phones. Each row shows the project name, its open-task count, live chat-activity badges, and a health dot pinned to the far right.
Above the list sit status filter tabs - All, In dev, Live, Idea, Paused and Hidden - along with an Add button and an Arrange toggle. The active filter is remembered, so if you mostly care about what is Live, Heygents opens that way tomorrow too.
Statuses
Status is a single field on each project, editable on the Info tab. It drives the filter tabs and how prominently a project shows up in your day.
| Status | Use it for |
|---|---|
| In dev | Actively being built. Your working set, the projects you expect to touch this week. |
| Live | Shipped and running for real users. These are the ones whose health dot you care about most. |
| Idea | Captured but not started. Real enough to record, not real enough to schedule. |
| Paused | Deliberately parked. Still yours, not currently moving, and skipped by all-project automation rules. |
| Hidden | Not a status but a flag. Hidden projects vanish from the normal list and only appear under the Hidden filter. |
Hiding is reversible and non-destructive: nothing is deleted, the project keeps its notes, tasks and history, and the command palette can still jump to it. Use Hidden for archived or one-off projects you do not want in your daily view; use Paused for work you fully intend to return to.
Drag to reorder
Drag any project row up or down to change its position. The order is saved immediately and is the order you see everywhere - the rail, Home, and the mobile project switcher. Put the two or three projects you are actually working on at the top and let everything else settle below; it is the cheapest prioritisation the app offers.
Arrange (bulk) mode
The Arrange toggle turns the rail into a bulk-edit surface. Every row grows a checkbox and an inline remove control, and clicking a row selects it instead of navigating to it. A footer bar appears with:
- Select all / Clear - operate on the whole filtered list at once.
- Hide - reversible; flags every ticked project as hidden.
- Remove - destructive; asks for one confirmation that names the count and lists exactly which projects will go.
Arrange mode is the tool for a spring clean: filter to Idea, tick the ones that never happened, hide them, and turn Arrange back off.
The right-click context menu
Right-clicking a project row opens a compact context menu with the per-project actions:
- Edit project - opens that project's Info tab, ready to edit.
- Hide project / Unhide project - the same reversible flag as Arrange mode, for a single row.
- Delete project - removes it for good.
This is deliberately a menu rather than a row of icons: the only fixed element on each row is the health dot, so the list stays readable even when the rail is collapsed to icons.
Health dots
The dot on the right of every row is the project's live health verdict, refreshed on a schedule you control. It combines whatever checks apply to that project: whether its URL responds, whether its port is listening, and whether its process or container is running. Green means everything checked came back healthy, a warning colour means something is degraded, red means something that should be up is down, and a neutral dot means the project is not monitored from this server - usually because no hosting details have been filled in yet.
Inside the project view, a Scan now action re-checks that one project immediately instead of waiting for the next scheduled pass. Health is always paired with text as well as colour, so the state is readable without relying on hue.
Project accent colours
Every project gets a stable accent colour derived from its name, so the same project is always the same colour. When its workspace is open, the accent tints the utility header (with the project name shown up front) and the chat message input. The project pane itself stays neutral.
This is a navigation aid, not decoration. With several projects and several chats open, the colour is the fastest way to confirm which project you are about to run an agent against.
URL hash links
The open project is encoded in the address bar as #/<project>. That means every project has its own shareable link, bookmarking works, and a refresh returns you to exactly where you were rather than dumping you on Home. If you open Heygents with no hash, it falls back to the last project you had selected.
Inside the project workspace
Opening a project shows a pinned identity header - the name, the status, and a live health badge - above a tab strip: Info, Plan, Tasks and Automations. The strip scrolls horizontally on narrow screens so labels never wrap, and it resets to Info each time you switch projects (except when a task notification sends you straight to Tasks).
On desktop the workspace is a two-column layout: the project pane on the left and the AI chat / terminal dock on the right, which can be widened, collapsed, or maximised over the project pane for a full-width conversation.
Info
Info is the project's settings surface, and it is always editable - there is no separate edit mode and no Save button to remember. Changes are auto-saved as you type, and flushed if you navigate away mid-edit. It holds:
- Name and status.
- Runtime location and agent host - where the project runs and which machine executes AI work for it.
- Repository and working directory - the working directory is the single most important field, because it is the root every AI run, file browse and Deep Scan is confined to.
- Links - the live URL and anything else worth one click.
Below the editable fields, Info shows the live status and infrastructure readout for the project, and at the very bottom, project deletion.
Plan
Plan is where you write down what the project is for. It has five sections plus notes.
- Goal - free text describing the vision, shown read-only and edited with an Edit control. This is the text the Deep Scan grounds its development and feature ideas in, so a vague goal produces vague suggestions. It is worth ten minutes.
- Roadmap - the same inline-edit pattern, for what is coming and in what order.
- Readme - a configurable path, defaulting to
README.md. A View toggle loads the actual file from the working directory and renders it in a scrollable preview, with a Copy button for the loaded content. If the path is wrong you get a clear soft error rather than an empty box. - CLAUDE.md - the identical workflow for your agent instructions file, defaulting to
CLAUDE.md. Being able to read it here, next to the goal, is the fastest way to spot that your agent instructions have drifted from your actual intent. - Project State (Google Drive) - a Sync to Drive button that publishes a
PROJECT_STATE.mdsummary, the file the automation agent reads, and reports the timestamp and destination on success.
Saving the Goal, the Roadmap, or either file path also refreshes that Drive state in the background, so what the automations read stays current without you thinking about it.
Notes & files
At the bottom of Plan sits the notes and files panel: free-form notes attached to the project, plus uploaded files. Use it for the things that have nowhere else to live - a deploy checklist, a credentials location reminder, a screenshot of the bug, the email from the client that explains why a weird decision was made.
Tasks
The Tasks tab is the project's AI-generated task list plus the Deep Scan that produces it. A Deep Scan is a grounded, read-only review that reads the actual repository and returns a concrete, prioritized list rather than generic advice, with each task categorised and rankable by urgency. From here you can hand any task straight to an agent to complete.
Tasks get their own page: see Tasks & Deep Scan.
Automations
The project's Automations tab holds the scheduled rules that run without you, grouped into sub-categories: All, Scan, Fix and Site Health. Rules that target every project (or a selected group that includes this one) appear here too, marked as global and read-only, so you can always see what is scheduled to touch this project even if it was configured elsewhere.
Full details are in Automations.
One workspace per project, with the real state in it
Heygents keeps health, plan, tasks and AI runs in the same place, so checking on a project takes one click instead of four tools.
Open Heygents →A workflow that holds up
- Order the rail honestly. The top three are what you are working on. Everything else goes below, Paused, or Hidden.
- Write the Goal once per project. It pays for itself the first time a Deep Scan comes back with suggestions that actually fit the project.
- Trust the health dots for the Live ones. That is what they are for. Stop manually checking whether the site is up.
- Use Plan as the memory. When you return to a project after six weeks, Goal, Roadmap, README and notes should be enough to reload the context in five minutes.
- Clean up in Arrange mode, not one row at a time. Once a quarter, filter to Idea, tick the dead ones, hide them.
Frequently asked questions
What is the difference between hiding and deleting a project?
Hiding is a reversible flag: the project keeps everything and simply stops appearing in the normal list, remaining available under the Hidden filter and in the command palette. Deleting removes the project from Heygents. Hide by default; delete only when you are sure.
Why does my project show as not monitored?
Health checks need something to check. Fill in the project's URL, port, or process and container details on the Info tab and the dot starts reporting a real verdict instead of a neutral one. A neutral dot means the project is not monitored from this server, which usually just means no hosting details have been filled in yet.
Can I change a project's accent colour?
The accent is derived automatically from the project name, so it stays stable and consistent everywhere without you managing a palette, and renaming a project changes its colour. While a project is open the accent tints the utility header and the chat message input, which is a navigation aid rather than decoration: it confirms which project you are acting on.
Do I have to use every tab?
No. Info alone gives you live health and a place your code path is recorded, and the working directory is the single most important field because it is the root every AI run, file browse and Deep Scan is confined to. Plan and Tasks are where the leverage is, but they can wait until the project is worth the effort.