Pages

Full-screen pages for explorations, deep dives, and research attached directly to a task. Pages are markdown-editable, versioned, and automatically indexed for the AI so agents can read, extend, and search them from any surface — CLI, MCP, REST, or AI Chat.

What is a Page?

Think of a Page as a full-screen notepad for thinking, planning, and research that lives on top of a task. Every page is tied to a specific task, so it stays in context of the work you’re on. Pages are:

• Task-bound: Live inside a task detail and accessible from the task row.
• Markdown-first: Write in markdown; the editor renders rich HTML with TipTap.
• Agent-friendly: Created, appended, updated, and archived programmatically via CLI, MCP, REST, and AI Chat.
• RAG-indexed: Every write is indexed so the AI can search, summarize, and reason over page content.
• Versioned: Every change is captured with history and restore capabilities.
• Conflict-safe: Optimistic-lock guards return a 409 conflict if multiple agents try to write at once.

---

Getting Started

This feature is now live on production, so you can start using it right away from the web UI and from the command line.

In the Web UI

1. Open any task detail.
2. Look for the Pages row under the main task fields (below subtasks).
3. Click the Pages header to expand and see all pages for that task.
4. Click New page to create an empty page, or open an existing page.
5. The editor opens full-screen; create, edit, and save normally.

Tip

Use Ctrl+K from any task and type “Pages” to open the command palette entry for that task’s pages.

Note

Legacy explorations on hypertask.app are not migrated; new writing uses the Pages system.

---

Types of Pages

You can create three kinds of pages on a task. They differ only in how you create them and, for humans, where in the editor you start typing:

Type	How to create	Where to write	When to use
Page	Click New page on the task detail → choose a name	In a new, untitled page	General thinking, notes, and exploration
Description page	Type a blank title and choose Description mode from the command palette	In an auto-renamed page with prefix # (e.g., #TaskNewPage)	You want the page to act like an extended description for the task
Exploration page	Type a title containing the word Exploration or choose the Exploration preset from the command palette	Will show #Exploration in the title	You want explicit context that this is a formal exploration / research page

---

Creating and editing pages

Use the full-screen editor attached to the task:

• Start typing on a blank page or in a title to create it.
• Markdown works: Use headings, lists, code blocks, and links.
• Slash commands: Type / at the beginning of a line for formatting options (e.g., /bold, /checklist, /image, /code).
• @mentions: Resolve team members within the page to notify them of your writing.

---

Append, prepend, replace

Pages support an append/prepend/replace model for agent workflows. When creating or updating a page programmatically, you can choose mode:

• overwrite: Replaces the entire current page content.
• append: Adds content after the existing text (RFC 2046-style).
• prepend: Adds content before the existing text.

This is especially useful for agents that progressively build a page over time without risking accidental clobbering of previous work.

---

Versioning and history

Every page has a version history. Restrict updates to safe versions and restore previous versions when needed.

In the editor

• Click History in the editor header to view all versions of the page.
• Each version shows the timestamp, author, and a copy of the content at that point.
• Click a version to view what the page looked like at that time.

Via the REST API

Version history and restore are REST-only today. There is no MCP tool and no CLI command for them yet:

• GET /api/mcp/pages/versions — lists all versions with timestamps and author.
• POST /api/mcp/pages/restore — restores a page to a chosen version.

---

Task-description versioning

Task descriptions also gain version history to help you track contributions, revert edits, and keep a clean changelog of what changed.

In the web UI

• Open any task.
• Click Description in the top area to open the description editor.
• Click History in the description header to view revisions.

Via the REST API

As with page history, this is REST-only for now:

• GET /api/mcp/tasks/description-versions — list the snapshots of a task description.
• POST /api/mcp/tasks/description-restore — restore one of them.

Conflict safety for task descriptions

If two agents or users edit the same task description at the same time, Hypertask uses optimistic locking to detect the conflict:

• First write wins, second write returns a 409 conflict.
• View the current text in the conflict response and retry your update with the updated content.

Caution

Do not retry blindly after a 409 without inspecting the returned current content, or you risk overwriting concurrent changes.

---

Agent work patterns

For agents and AI workflows, the Pages system provides a reliable, tracked surface to experiment and plan:

• Exploration depth: Agents can maintain multi-page explorations for complex tasks without relying on external, untracked tools.
• Incremental building: Use append or prepend modes to grow pages over time.
• Conflict handling: Use the version semantics to implement safe concurrent writes for agents that work on the same pages.
• AI context: Since pages are RAG-indexed, the AI can always see your latest exploration content in chats, summaries, and task planning.

---

CLI reference

Pages commands live under the new pages command group (CLI & MCP tools). They are fully available from the terminal to manage pages programmatically.

Pages are addressed by numeric page id, and created against a numeric task id — not a ticket number. Get a task id with hypertask task list --json.

Commands

Command	Description
hypertask pages create --task <task-id> --title "title" --content "..."	Create a page on a task.
hypertask pages get <page-id>	Read a page.
hypertask pages append <page-id> --content "..."	Append to a page.
hypertask pages update <page-id> --content "..." [--mode replace|append|prepend]	Rewrite a page, or append/prepend.
hypertask pages list [--task <id>] [--project <id>]	List pages on a task or across a board.
hypertask pages search <query>	Search page content.
hypertask pages archive <page-id>	Archive a page (soft delete; alias delete).

Flags

Flag	Applies to	Description
--content <text>	create, append, update	The body text.
--markdown-file <path>	create, append, update	Read the body from a file instead.
--mode <replace|append|prepend>	update	How to apply the content. replace by default.
--if-version <n>	update	Only write if the page is still at this version. Returns a conflict otherwise.
--note <text>	update	A note attached to this revision.
--html / --canvas	create, append, update	Treat the content as HTML, or as an HTML canvas page.
--parent <id>	create	Nest under another page.

Examples

Create a page (note --task takes the numeric task id):

hypertask pages create --task 2992 --title "Research competitor pricing" \
  --content "# Competitor pricing

Start by listing key competitors and their pricing tiers."

Append a paragraph incrementally:

hypertask pages append 4521 --content "Each tier includes X; Y is extra."

Read it back, list a task’s pages, or search:

hypertask pages get 4521
hypertask pages list --task 2992
hypertask pages search "competitor"

---

MCP tools reference

Five MCP tools cover pages. Full parameters are in the MCP Tools Reference, which is generated from the server itself.

• hypertask_create_page — Create a page on a task.
• hypertask_get_page — Read a page.
• hypertask_update_page — Write to a page. Its mode parameter (replace, append, prepend) covers all three write shapes, so there is no separate append or prepend tool.
• hypertask_list_pages — List the pages on a task.
• hypertask_search_pages — Search page content.

Archiving, version history and restore have no MCP tool yet; use the REST endpoints listed above.

Tip

All pages-associated tools reuse the task routes’ authentication and project-membership checks, returning matching 401/403 errors relative to access to the parent task.

---

AI Chat integration

You can create, read, append to, and update pages directly inside AI Chat without leaving the conversation, and the same operations are available through the CLI (hypertask pages ...), MCP, and the REST API. In chat, open a task context with something like “Open HTPR-2992 for editing”, then “Create a page for a competitor analysis” or “Append a note about pricing tiers”.

---

Version conflict semantics

Pages and task descriptions both support optimistic-concurrency conflict safety using ifVersion-style checks:

• Server returns 409 Conflict if the agent’s ifVersion header mismatch the current version of the content.
• Client can retry by fetching the current version, re-reading content, and resubmitting the write with the latest version.
• Never silently clobber: The server validates the version before persisting to prevent lost updates.

CLI conflict handling example

# 1. Read the page as JSON so you get its current version number
hypertask pages get 4521 --json

# 2. Write back, but only if nobody else has written since
hypertask pages update 4521 --mode append \
  --content "Additional note appended by agent." --if-version 3

# On a conflict, re-read and decide what to keep before retrying.

---

Migration considerations

• Legacy browsing: Old explorations embedded on hypertask.app remain visible as read-only HTML; they are not migrated to the Pages system.
• New writing: All new pages must be attached to a task. No task-less wiki pages exist yet.
• Co-editing: Live Yjs/websocket co-editing is parked. Page editing is currently human-only or agent-only, not both simultaneously.

---

Related topics

Tasks Create, assign, and manage tasks with rich fields, priorities, relations, and subtasks.

MCP Integration Connect AI agents to Hypertask via the Model Context Protocol.

CLI Reference Complete reference for the Hypertask CLI to manage tasks, projects, comments, and notifications from your terminal.

AI Features AI-powered task creation, voice dictation, text enhancement, and an intelligent co-worker built into your workflow.