Monitor and respond to penpal document review comments on markdown files in thoughts/ directories.
Penpal is a local web app for reviewing markdown files inside thoughts/
directories (e.g. thoughts/shared/plans/api-design.md). It is for reviewing
research documents, implementation plans, guides, and similar artifacts -- NOT
source code or PRs. Humans and AI agents can have conversations anchored to
specific text in these markdown files.
A file is "in review" whenever it has open comment threads. There is no explicit review request step -- creating a comment thread on a file automatically puts it in review. Resolving all threads on a file removes it from review.
penpal_find_project
with your working directory to get it. Use this name for all subsequent
penpal tool calls.penpal_files_in_review for the project to discover files with open
comment threads. The response includes all open threads per file and the
oldest pending thread (where the last comment is from a human) with its full
content.thoughts/) so you have
full context.
b. Reply to the oldestPending thread first -- no need to call
penpal_list_threads or penpal_read_thread for it.
c. Then process any remaining threads where the last comment is from a human.penpal_wait_for_changes in a loop to wait for new activity. This
tool blocks for up to 30 seconds and returns immediately when a comment is
created, replied to, resolved, or reopened. It also maintains your agent
heartbeat automatically."changed": true, check the returned files list
for new or updated threads and respond to them.penpal_wait_for_changes even when idle -- this maintains the
"agent active" heartbeat indicator in the penpal UI| Tool | Purpose |
|---|---|
penpal_find_project | Get the project name for your working directory. Call first if you don't know it. |
penpal_wait_for_changes | Block until comments change (or 30s timeout). Returns files in review. Use in a loop. |
penpal_files_in_review | List all files with open threads, including thread details and oldest pending thread content |
penpal_list_threads | List comment threads on a file (optionally filter by status) |
penpal_read_thread | Read a full comment thread with all replies |
penpal_create_thread | Create a new comment thread anchored to text |
penpal_reply | Reply to an existing thread |