Using HoneyDew¶
HoneyDew is a shared task board for you and your AI assistant. Start with a card, keep progress on the board, and leave a clear handoff when the work is ready.
Start the app¶
From your HoneyDew checkout, install dependencies once and start the servers:
Open http://localhost:5173 for the board. The REST API runs at http://localhost:8000. Choose Settings (gear) → Docs at the top right anytime; these guides ship inside the app and do not require the separate documentation server.
Your first task¶
- Select your board using the board title / switch control in the header.
- Choose Add card in the appropriate column. Give it a concrete title, a description of the result you want, and an owner.
- Set priority, a due date, and labels as needed. Priorities run from Low (1) to Urgent (4).
- Create the card. Click it to open the detail view; its ticket number is the stable ID you can share with your agent.
- Drag cards between columns as work progresses. A typical flow is To Do → In Progress → Done, with Blocked for work that needs input.
The profile selector determines the active identity for UI actions; it is not a login or an access boundary. Give agent actions the configured agent profile, not your human identity.
Search and filter a board¶
The search bar sits directly below the board header. Search titles and descriptions with case-insensitive keywords, or use #123 for an exact issue number. Multiple words must all match. A plain number can also match an issue ID or text in its title/description.
Open Filters beside search to combine project/label, status, priority, task/Epic type, author, lease state, and prerequisite readiness. Project labels include labels inherited from a task’s Epic. Author means the profile on the card, not the current lease owner. Currently leased follows the server’s live lease state, including release and expiry.
Date created and Date last updated each offer Today, Last 7 days, Last 30 days, or an inclusive custom From/To range. Leave either end blank for an open range. Dates use the issue timestamps and the browser’s local calendar; timezone-naive timestamps retain the installation’s local time.
Date last updated tracks direct issue activity: saved field changes, comments, label changes, prerequisite links, Epic membership, and attachment additions, removals or renames. Linking/unlinking prerequisites updates both issues; changing Epic membership updates the child and affected Epics. Editing a shared label updates directly labeled issues, and renaming a status updates issues in that column. Existing ordering, lease and archive updates also count. Repeating an operation without changing anything does not count (a lease renewal changes its expiry and does count). Derived changes such as prerequisite readiness, Epic progress, or inherited project labels do not propagate update dates to other issues. Historical dates are preserved; earlier unrecorded relationship activity is not backfilled. See API timestamp semantics for details.
Filters apply together to non-archived issues on the current board. Columns display matching / total counts; hidden issues and prerequisite relationships are unchanged. Remove individual filter chips or use Clear all to restore the board. Press Escape within the filter panel to collapse it and return focus to Filters.
The current search and filters are included in the URL (f_ parameters), so copying a link or refreshing restores the view. They carry across board switches; Back/Forward restores the view associated with each board history entry. Editing filters replaces the current history entry rather than adding an entry per keystroke.
Plans, dependencies, and files¶
- Epics hold a larger Markdown plan. Link concrete child tasks so progress stays visible beside the plan.
- Dependencies say which tasks must finish first. Tasks can depend on tasks or Epics on the same board; cycles are rejected. In the issue editor, type a number (with or without
#), title, or description keywords into Prerequisites, then choose a match. Selected prerequisites appear as removable chips. A prerequisite Epic is satisfied when the Epic itself reaches Done. Unsatisfied prerequisites prevent an agent from acquiring a lease. - Descriptions and comments support Markdown: headings, checklists, tables, links, and code blocks. Put decisions, blockers, verification, and result links on the card.
- Attachments keep deliverables with a card or Epic. Upload, drop, or paste files in the Attachments area. Files queued on a new card upload after the card is created. See Attachments for limits and storage options.
Work with an agent¶
Connect OpenClaw or Cursor, then ask it to list your boards and read a specific task. Assigning a card does not itself start an agent: the agent must be running and instructed to check the board. Periodic work requires a separately configured schedule in your agent host.
A reliable agent workflow discovers the real board, column, and profile IDs; searches for an existing matching card; acquires a task lease before work; posts progress; and records verified results before moving to Done. A status column is not a lease. See the API reference for atomic acquire, renew, and release operations.
Review and hand off¶
Open the completed task, review its comments and attachments, and move it back to an active column if more work is needed. Agents should transfer work to your configured profile when your input is required. Only measured model/token/time usage should be recorded.
Completed cards are soft-archived after 72 hours by default, not deleted. Change this in Configuration. API clients can retrieve history with GET /api/cards?include_archived=true.
Troubleshooting¶
| Symptom | What to check |
|---|---|
| Board cannot load | Confirm ./start.sh is running and GET http://localhost:8000/health returns {"status":"healthy"}. |
| Agent cannot reach localhost | Localhost is the machine/container running that agent. Use an API address reachable from that runtime, through a trusted private connection. |
| Agent does not know HoneyDew | Open Connect, install the supplied context, and start a fresh agent session. |
| Another worker owns the task | Wait for release or expiry; do not overwrite a live lease. |
| Card is missing | Clear search/filters, then check the selected board and archived history. |
HoneyDew has no built-in authentication. Keep it on localhost or a trusted private network; do not expose its API publicly without an authentication layer.
Settings and navigation¶
Settings opens as one workspace with a left navigation column on desktop and horizontally scrollable section tabs on mobile. Storage, agent connection setup, and Docs stay inside the same dialog. Switch sections without losing drafts; closing Settings discards unsaved form changes. Saving keeps the section open and shows confirmation. Theme choice previews colors before applying them to the selected board. Use arrow keys (Up/Down on desktop, Left/Right on mobile) or Home/End to navigate the tabs, then Tab to reach the panel.
The top-right gear opens agent MCP connections, attachment storage, per-board theme choice, HoneyDew configuration, new board/profile creation, and Docs. Configuration includes display names and the completed-task archival interval. New profiles become available in the profile selector without changing existing task authors.
Board selection is stored as ?board=<id> and the active author profile as profile=<id>. Switching either updates the URL; refresh and browser Back/Forward restore both. Changing boards does not change your author identity. Legacy profile-only links still select the corresponding named board when available.
Click outside a task, settings, storage, or Docs modal to close it; Escape and the close button also work. Clicking inside or dragging a selection from inside to outside does not dismiss it. Pending attachment uploads retain their close confirmation; active saves cannot be dismissed.
Comment blocks use each author’s home-board theme (the board named after their display name), independent of the board being viewed. Profiles without a matching board use Midnight. Change the board theme in Settings → Theme choice. Executive is a cool white/slate light theme with navy accents; Linen uses warm ivory and muted teal. Both apply to board cards, filters, settings, and task dialogs. Comments retain an author-colored accent with light surfaces on light boards.