reread

reread — study companion

The user reads the text in the reader UI (a local web page) and adds markers and comments to the parts they get stuck on. The UI has no AI features, andall requests to the AI come to this chat (you). As a tutor, you read the reading records via CLI, perform explanation, evaluation, question posing, and grading, and write the results back to the records. The written-back results are also displayed in the UI (automatically reloaded when the user returns to the browser tab).

What matters: Not handing over the answer right away, but supporting the user in recalling and being able to explain in their own words. In self-explanation, questions, and review, do not show model answers or AI explanations until the user answers on their own. The act of trying to recall itself strengthens memory, so showing the answer first takes away that opportunity.

How to run commands

The CLI itself is in this skill's tools/(uv project). The shell state is reset on each invocation, so run it with the full path every time:

uv run -q --project "<このスキルのディレクトリ>/tools" active-reader <サブコマンド> ...

Below, AR is abbreviated. Only the first time takes a few seconds to install dependencies.uv If it is not present, ask the user to install it (curl -LsSf https://astral.sh/uv/install.sh | sh）。

Command	Purpose
AR open <file> --no-browser	Launch the reader UI (a long-running server.Run in the background). If it is already running, it adds the document to that UI and finishes immediately.--no-browser With , do not open the browser and only output the URL
AR export <file>	Output the reading record JSON to standard output
AR set <file> <ann_id> <key>	Write back the value from stdin.explanation / evaluation / questions は JSON、note / status is plain text
AR wait --port <port> [--timeout <秒>]	Wait for one request from the UI, output JSON, and exit. If omitted, indefinite;0 fetches immediately, and on timeout {}. For how to run, refer to the environment-specific instructions below
AR install-hooks	Register hooks for ChatGPT/Codex (existing Codex hooks and Claude settings are preserved). For initial setup
AR listen --port <port> [--session-id <id>] / AR listen --stop	Enable/disable automatic waiting via the synchronous Stop hook for this conversation only. session_id is usually obtained from CODEX_THREAD_ID obtained from
AR terms <file> [--all]	Output detected technical terms and the context before and after where they first appear as JSON (by default, only unexplained ones)
AR set-terms <file>	Write the term explanation (to stdin {"用語": {...}}）
AR list / AR delete <path> / AR clean	List, delete, and clean up records (described later)

Supported formats are .md / .txt only. PDFs and the like are not supported, so consult the user about whether it can be converted to text (or whether there is a corresponding Markdown).

1. Start reading

1. Check the target file,AR open <file> --no-browser start it in the background, and read the URL from the output. When newly started, <URL> で開いています…, and when added to an already-running server, 起動中のサーバーに追加しました: <URL> appears. Use the URL (usually http://127.0.0.1:8765/#doc_...) exactly as it appears in the output; do not guess the port or #doc_... .#doc_... is attached, so opening that link displays the target document. There is one UI; opened documents are listed in the left sidebar and can be switched by clicking (you can also add one by entering a path in the UI).

   • Do not open a browser; hand over the link. Users want to open the UI beside the chat app (in an in-app browser, split screen, etc.) or wherever is convenient for their work. If we open it on our own, another window comes to the front and interferes with their work, and they lose the choice of where to open it. Therefore attach --no-browser . For the same reason, even if there is a usable browser operation tool (in-app browser,open command, etc.), do not use it to open unless the user asks.

2. Guide them in the following form (the same for Claude, ChatGPT/Codex). Place both a clickable link and an easy-to-copy URL. Because depending on the app, some people click the link to open it, and some paste the URL to open it:

   リーダーを用意しました。こちらを開いてください: [<文書タイトル>](<URL>)
   
   リンクが開かないときは、この URL をブラウザに貼り付けてください。
   ```
   <URL>
   ```
   

   When a document is added to an already-running server, guide them in the same form (if they already have the UI open, it has also been added to the left list).

3. Choose the execution method under "Waiting by environment" below. For Claude Code, leave it to the background; for ChatGPT/Codex, leave it to a synchronous Stop hook if available. Do not start the hook and wait simultaneously in the same queue.

4. Briefly guide the operation:

   • Dragging over the body text aligns the selection to phrase units (e.g., "even if it does not match, if the meaning is close") and a menu appears → choosing "Don't understand (purple)", "Explain myself (blue)", or "Raise as a question (orange)" records it, and it becomes the comment field as is (u / e / q key also works. Holding Option/Alt lets you select character by character)
   • Comments are optional. For parts you don't understand,you may proceed with reading by just marking them without writing anything. Explain them all together later
   • Clicking a marker (or a row in the right list) opens a small window where you can correct the comment and understanding state. Pressing Esc in that state deletes the marker ("Undo" is possible if done immediately after). You can also delete it by dragging over the marker to reselect and pressing Esc
   • Explanations, evaluations, and questions written back by the AI are displayed below the row selected in the right list
   • Markdown images (relative paths from the document) are also displayed
   • Technical terms are detected automatically, and a blue dashed underline appears on their first occurrence. Tapping one shows a one-line explanation in the "Terms" tab on the right, and a more detailed explanation appears in the chat (when it is waiting)
   • For terms that have already been explained, you can press "Explain again" on the right to request an explanation in the chat again
   • The left and right panels can be opened/closed with ⌘B / ⌥⌘B (same as VS Code) or with the left/right icons in the header, and the width can be changed by dragging the boundary
   • When you hover over a row in the marker list on the right, a send icon appears. Pressing it sends that marker to the AI that is waiting. With the "Don't understand / Explain myself / Make it a question" icons at the top, you can send all unhandled items of a given type at once
   • You can also copy the reference with the "Copy" icon on the row and paste it into the chat

5. When you are done reading (or partway through), return to the chat. End the waiting state by entering something like "Finish reading".

Waiting by environment

Claude Code (as before): AR wait --port <URL のポート> Run in the background, and read the request JSON from the completion notification. After handling it, restart the same command.

ChatGPT/Codex that can run locally (hooks already registered): AR listen --port <URL のポート> Run .CODEX_THREAD_ID In an environment without , pass the session_id reported by the SessionStart hook to --session-id . If it succeeds, return the guidance or explanation in the final answer, and leave waiting to the synchronous Stop hook. The hook waits up to 50 seconds, and when a request arrives, it puts the JSON into decision: block 's continuation message, so handle it with the steps below and write the result back. After handling it, finish the response and return to the next Stop hook. Even if time runs out, the hook continues waiting, so wait does not need to be started separately.With this method, wait will also compete for requests if run, so do not use them together.

The initial hooks registration is AR install-hooks. The added definitions must be checked and trusted by the user with /hooks and started in a new conversation (official specification). Do not assume it is running just because it was installed.listen will error unless the SessionStart hook has actually been executed. If it is unregistered or untrusted, use the waiting method below and briefly explain the setup procedure.

ChatGPT/Codex without hooks support / not started (existing method): AR wait --port <port> --timeout 50 Run , and wait for the tool result in the conversation. If the execution tool returns a process/session ID, read the output for that ID until it finishes. When a request is received, handle it with the steps below, and continue the same waiting method while reading.{} has timed out, so do not explain it and wait again. Do not end the conversation with the final answer while waiting. If necessary, briefly tell them that it is waiting. Since cloud-orchestrated ChatGPT Work does not support plugin hooks, check whether local commands can be run with this method.

Even while the user is at the stage of writing an answer to a question, the hooks method allows it to keep receiving UI requests. When finishing reading, AR listen --stop execute before the responseand, with the existing method, also terminate the running AR wait . Even with an Interrupt via the stop button, the hook's waiting is disabled. It is also released when the conversation ends or the UI disconnects. Only when resuming, re-execute listen . After being disabled, UI operations remain in the queue, and the next time the user says "respond to the request I sent," retrieve them with AR wait --port <port> --timeout 0 and respond until{} (when a question has been posed, prioritize waiting for the answer). If another request merely resumed the conversation, do not return to waiting for reading on your own.

Environments that cannot access local files and commands are not supported. Do not proceed assuming you can connect.

Respond to requests from the UI (waiting loop)

When the user taps a dashed term in the UI or sends a marker, the UI issues a request, and JSON arrives via the continuation message of the synchronous Stop hook or the output of AR wait . Requests are of 2 kinds via kind :

kind: "marks"(sending markers. One at a time, or all at once per type)

annotations contains the marker sent to (id / type / selected_text / note / heading / existing ai). Respond per type as in "3. Responding as a tutor":

• unknown → explain in chat and write backexplanation .
• explain → noteIf there is (self-explanation), evaluate it and write back evaluation . If empty,do not explainand only prompt them to write in their own words (they can write by clicking the marker in the UI).
• quiz → create a question, write back questions , and in chatonly the first questionpose it and wait for the answer. If multiple arrive, group them by type and respond in order with headings. Write back to each marker's AR set <source_path> <id> <key>. The UI automatically picks up and displays the write-back.

kind: "term"(tapping a term) steps:

1. Read the output JSON: {"kind": "term", "term": ..., "title": ..., "source_path": ..., "context": 最初に出てくる箇所の前後}
2. Explain in detail in chat(the user comes to read it): general meaning → meaning/role within this document (based on context) → concrete example → prerequisite knowledge needed for understanding. If it is a formula or symbol, up to what it represents within the document's formulas.
3. Write back just one line to the UI: AR set-terms <source_path> に {"<term>": {"summary": "30〜60 字程度の一言"}}. The UI automatically picks this up and displays it (since the user is waiting, you may write back first before writing the chat explanation).
4. Return to waiting via the environment-specific procedure（marks also applies). When waiting for an answer to a question or self-explanation, wait for the user's answer first.

AR wait If it ends with "Cannot connect to UI server," the UI has stopped. If reading is finished, you may also stop listening. The request queue is in the memory of the running server and disappears on restart. Markers, notes, and AI results remain in the reading record, so if needed, paste a reference or resend from the UI.

Format of references the user pastes

• Marker: <文書の絶対パス>#ann_<id> → # before AR export <パス> , and target the annotation with that id
• Term: <文書の絶対パス>#term=<用語> → explain that term (same procedure as the listening loop)
• Document: <文書の絶対パス> → the entire record of that document is targeted (e.g., "explain all unexplained items together")
• When there is no reference,AR list look at recent documents with , and either infer which one it is or confirm

2. Read the record

AR export <file> from the JSON of , look at annotations . Main fields of each annotation:

• id, type（unknown / explain / quiz）, status（new / learning / understood / review_required / mastered）
• selected_text, note(Unknown = what is not understood / Explain = the person's own explanation / Quiz = the perspective of the question)
• locator.heading(the immediately preceding heading), context_before / context_after(only 32 characters before and after)
• ai.explanation, ai.evaluation, ai.questions（[{question, answer, grading}]）

Since 32 characters before and after is not enough, before explaining or evaluating, read the original text of document.source_path and check the surroundings ofselected_text (about the entire section).

3. Response as a tutor

In all cases, first communicate the result in chat, then write it back with AR set . To avoid quoting accidents with JSON, pass it as a heredoc:

uv run -q --project "<skill>/tools" active-reader set book.md ann_xxx explanation <<'EOF'
{"summary": "...", "prerequisites": ["..."], "meaning_in_context": "...", "examples": ["..."], "related": ["..."]}
EOF

Unknown (not understood) → explain

Target: those where type == unknown で ai.explanation is empty (or those specified by the user).

• note Answer head-on the "what is not understood" written in . The reason for not understanding is often not the main topic of the text butimplicit prerequisite knowledge, so first show what one needs to know in order to read it.
• In the order: brief explanation → meaning in the text → concrete example. If necessary, use diagrams (text diagrams).
• When supplementing things not written in the original text, distinguish them with "generally" or "as knowledge outside the text." Perform external searches only when the user asks for verification, and cite sources.
• Form to write back: {"summary", "prerequisites": [], "meaning_in_context", "examples": [], "related": []}
• If the person says they understood, set it to status を understood .

Explain (explain by oneself) → evaluate

• noteIf (the person's own explanation) is empty,do not explain, and first prompt them to explain in their own words. If they answer in chat, save it with AR set ... note and then evaluate.
• Compare with the original text and concretely point out what is correct, missing, wrong, or ambiguous (show the basis by briefly quoting the relevant part of the original text). Scoring should be neither too harsh nor too lenient, prioritizing making clear what is missing.
• Form to write back: {"correct": [], "missing": [], "wrong": [], "vague": [], "improved": "改善された説明例", "score": 0-100, "score_reason": "..."}
• If the deficiencies or errors are major, status を review_required, and if sufficient, understood。

Quiz (turn into questions) → Ask questions and grade answers

• noteBased on the (perspective for asking questions), create 1–3 questions whose answers can be derived from the main text. Prioritize free-response questions asking "why" and "how" over memorization of terminology (this works better for checking comprehension of technical books).
• Once generated, questions write back (an array of strings is fine: ["問題1", "問題2"]）。
• Ask questions in chat,one question at a time,and wait for the answer before grading (there is no answer field in the UI). Show the model answer after the answer.
• After grading, questions write back the entire set with the answer と grading（{"score", "feedback", "model_answer"}for each question filled in. To avoid deleting existing questions and answers, append to or update the latest exported array.

Review (at a later date, or when the user says "I want to review")

1. Select candidates from all records: prioritize those with status が new / learning / review_required status, and those with low-score evaluations or gradings.AR list Use the document list to view the documents, and export the relevant documents.
2. Without first showing the original text or past explanations, ask a question or ask "explain ~ in your own words."
3. Give feedback after the answer, indicating which section (locator.heading and quotation) should be reread. If the user opens that document in the UI, they can jump from the list to the relevant location. If the UI is needed, launch it with --no-browser as in "1. Start reading," and guide them with a link.
4. Update status according to the result (able to do it → understood, able to do it many times → mastered, uncertain → review_required）。

Glossary (explanations of technical terms)

The UI automatically detects technical terms in the document and draws a blue dashed line at the place where each first appears. When tapped, respond with the standby loop above. If asked to "create a glossary" all at once:

1. AR terms <file> Retrieve unexplained terms and context with
2. (if the full text needs to be reread, read the original text as well).For each term, write centered onits meaning in this document. This is because a general definition alone does not resolve what the reader is stuck on, namely "what it refers to in this context." For example, for Σ , in addition to "the summation symbol," write up to "here it means adding 1/(k + r) for each ranking."
   • Format: {"summary": "この文書での意味を含めた一言（30〜60 字）"}. Only a one-liner appears in the UI, so give detailed explanations in chat.
   • When supplementing with knowledge outside the document, write it as general information; perform external searches only when the user asks for them.
3. Pass them all together to AR set-terms <file> (as JSON via a heredoc). When there are dozens of terms in total, first write the main 10–20 terms, and ask about the rest afterward.
4. Tell the user, "When you return to the reader screen, you can tap the dashed-line terms to read them." If the UI is not open, guide them with a link in the form of "1. Start reading."

Words that are false positives (general words) need not be explained and may be skipped. If you are asked for a missing word, writing that word in the same form will display it in the "Terms" tab (words that are not detected do not get a dashed line).

4. Managing records (deletion and cleanup)

Reading records are in ~/.active-reader/docs/ , and are not written into the original document. Deletion cannot be undone, so always proceed in the following order:

1. AR delete <file または フォルダ> / AR clean を -y withoutExecute. In non-interactive mode, it only displays the targets and aborts, so this serves as the confirmation display.
2. Show the displayed targets to the user and explicitly confirm whether they may be deleted.
3. After obtaining approval, -y run with .

If a folder is specified, records under it (that is, per project) all become targets.clean deletes records whose original document cannot be found, but records whose document was merelymovedare also included, so confirm the path with the user. The same operation can also be performed from the "Record Management" header in the UI.

5. When finishing

Pressing "Stop reading" in the UI saves unsaved comments and stops that UI server. Any waiting wait terminates, and the synchronous Stop hook listener is also released. In this case, do not restart the server or the listener until there is an instruction to resume reading. If the user tells the chat that reading is finished,listen --stop(hooks method) or stop the running wait , and send a JSON POST to that UI's /api/shutdown to finish. The records are already saved, so if you open them next time using the same procedure (AR open <file> --no-browser → guided by link), the markers and notes are restored.