monitor

name: monitor description: "Monitor and respond to penpal document review comments on markdown files in thoughts/ directories."

Penpal Document Review

What is Penpal?

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.

How Review Works

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.

Monitoring Workflow

1. If you don't already know your project name, call penpal_find_project with your working directory to get it. Use this name for all subsequent penpal tool calls.
2. Call 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.
3. For each file in review: a. Read the file content (the markdown file under 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.
4. Call 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.
5. When the tool returns with "changed": true, check the returned files list for new or updated threads and respond to them.
6. When a file has all threads resolved (disappears from the list), stop monitoring that file and report to the user.
7. When no files remain in review, report completion and stop.

Guidelines

• Read the full file content before responding to comments so you have context
• Be concise in replies -- the human is reading these in a narrow side panel
• ALWAYS reply to every thread you work on. When a comment asks for changes, make the changes and then reply confirming what you did. When you investigate something, reply with what you found. The human sees a working indicator while you work -- the reply is what tells them you're done.
• If you disagree with feedback, explain your reasoning rather than silently ignoring it
• Do NOT resolve threads -- only humans resolve threads. Your job is to reply and make changes, not to decide when a conversation is done
• Keep calling penpal_wait_for_changes even when idle -- this maintains the "agent active" heartbeat indicator in the penpal UI
• Do NOT stop monitoring just because there are no open threads; the human may add new comments at any time

Available MCP Tools