Learning Thread

Learning Thread is a native Pi learning harness. It preserves a canonical, section-by-section lesson while structured state keeps side questions, understanding checks, and permanent notes distinct throughout a natural conversation.

Install the learn command

Install dependencies and link the package once:

npm install
npm link

Then launch Learning Thread from any project directory:

learn

Pi owns model authentication and selection. Use /login for API keys or supported subscription providers—including ChatGPT Plus/Pro through OpenAI Codex—and /model to choose the active model.

All additional arguments are passed to Pi:

learn --offline

For repository-local development, npm run learn starts the same launcher without linking it globally.

Start a lesson with explicit learning intent (ordinary questions and tasks remain ordinary Pi requests):

I want to understand why Earth has seasons.
My answer is that axial tilt changes the angle and duration of sunlight.
Continue.
Why are the seasons opposite in the two hemispheres?

The LLM manages lesson planning, checkpoints, and side questions as conversational processes. Learning Thread does not assume that a topic requires code or a particular programming language. If you explicitly request coding help, Pi's ordinary tools follow the language and environment you specify. Only navigation and note actions remain custom commands: /btw, /back, /progress, /note, and /thread-help.

The full interaction model is documented in docs/commands.md.

Rich lesson display

Lesson sections, branches, progress, and notes render as styled Markdown in the terminal. Inline LaTeX ($...$ or \\(...\\)) has a readable Unicode representation. Responses with display LaTeX ($$...$$ or \\[...\\]) are typeset by MathJax and rendered as high-resolution terminal images; terminals without an image protocol receive a text fallback. Original LaTeX remains unchanged in exported notes.

Standard Markdown images are displayed inline when they use a local path or a PNG/JPEG/GIF/WebP data URL. Relative paths resolve from the directory where learn was launched. Kitty, iTerm2, Ghostty, WezTerm, and Warp support inline terminal images; other terminals receive a labeled fallback. Web image URLs remain clickable rather than being downloaded automatically.

Install as a Pi package

From another Pi project:

pi install /absolute/path/to/LearningAgent

The pi.extensions manifest loads extensions/learning-thread.ts.

Verification

npm run tui:check
npm run tui:test

Tests cover learning-state transitions, branch return anchors, qualitative checkpoints, domain-neutral prompting, complete Markdown notes, and the learn launcher.