Learning Session Organizer

A native Pi package that privately captures learning-session questions and turns them into auditable, organized Markdown reports. Companion integrations for Claude Code, Codex, MCP clients, and the CLI remain available.

Prerequisites

• Node.js 24 or newer
• Pi

Installation

Choose one Pi package source:

# Local checkout
pi install /absolute/path/to/learning-session-organizer

# GitHub
pi install git:https://github.com/firefly0916/learning-session-organizer.git

# npm (prepared for after the release operator publishes 0.1.0)
pi install npm:learning-session-organizer

Publication status: [email protected] has not yet been published to the public npm registry. Use the npm command only after the release operator publishes and verifies the public package; until then, use the local or Git source.

Pi auto-discovers both the native extension and Skill from the package metadata; do not launch Pi with pi -e.

List installed packages before updating or uninstalling:

pi list

Use the exact source shown by pi list; package management is source-specific. For example:

# npm source
pi update npm:learning-session-organizer
pi uninstall npm:learning-session-organizer

# Git source
pi update git:https://github.com/firefly0916/learning-session-organizer.git
pi uninstall git:https://github.com/firefly0916/learning-session-organizer.git

# Local source (replace with the exact absolute path shown by pi list)
pi update /absolute/path/to/learning-session-organizer
pi uninstall /absolute/path/to/learning-session-organizer

A relative install argument such as . does not necessarily remain the installed source identity, so do not assume it for later commands; copy the exact source from pi list instead.

Run pi config to open Pi's resource configuration TUI and enable or disable package resources in global settings. Run pi config -l when you instead want project-local overrides; Tab switches scope in the TUI.

Usage

Ask Pi to start a learning session, optionally naming a topic or goal. Starting is explicit; merely installing the package or opening a chat does not capture anything. Continue learning normally, and ask Pi to show status, pause recording for private discussion, resume, or exclude the current turn (for example, “do not record this turn”). Session identity comes from the current Pi session; no token, host, or session id is passed to native tools.

When you ask to finish and generate a report, the Skill audits all captured questions page by page, organizes them, writes sections with complete question coverage, and publishes the report. Completion means section submission and publication both succeeded. Ask for an export and provide a destination directory when you want a separate copy; the package never guesses an export location.

Switching away from an identity stops runtime capture and binding only; it does not change or mutate that identity's persisted learning-session state. Returning to the original active identity restores capture. If the original identity was explicitly paused, it remains paused with no automatic resume.

A new or forked identity is independent, inactive, and unbound until learning_session_start is called there. A fork never inherits the source identity's binding or token.

Privacy and captured content

All learning records and reports stay local. Capture includes only visible user messages and final assistant messages. It excludes model thinking, tool calls and results, compaction summaries, and whole control-command turns such as skip, pause, resume, finish, and delete. Native Pi calls never expose a bearer token.

Pausing creates a private interval. Deleting a learning session requires explicit confirmation and is irreversible; a content-free deletion barrier remains so delayed capture cannot recreate deleted content.

Data locations

By default, the resolved learning home is the platform application-data directory plus learning-session-organizer:

• macOS: ~/Library/Application Support/learning-session-organizer
• Linux: ${XDG_DATA_HOME:-~/.local/share}/learning-session-organizer
• Windows: %APPDATA%\learning-session-organizer

Override the resolved learning home before starting Pi:

export LEARNING_SESSION_HOME=/safe/private/path/learning-session-organizer

It contains:

• learning.sqlite3 — the local ledger and report database
• reports/<reportRunId>/ — published Markdown, questions.json, and manifest.json
• spool/ — emergency capture spool files if SQLite is temporarily unavailable
• barriers/ — content-free deletion barriers

Protect this directory as private data and include it in backups only when desired.

Legacy integrations

Claude Code and Codex plugin manifests, generic MCP configuration, and the learning-session-organizer / learning-session-mcp CLI binaries remain packaged for compatibility. These integrations use their existing hook or MCP lifecycle. Unlike native Pi, the MCP protocol supplies a host session id and bearer token; keep the bearer secret and never put it in prompts or reports. See .mcp.claude.json, .mcp.codex.json, and .mcp.json for packaged server launch configuration.

Release and operator documentation

• Changelog
• Security policy
• Privacy notes
• Supported environment
• Installation notes
• v0.1.0 release runbook

Publication is credentialed and manual. If a defect is found after 0.1.0 is published, prepare a new version; do not attempt to overwrite the immutable npm version.

Build, test, and validate

From a checkout:

corepack prepare [email protected] --activate
corepack pnpm install --frozen-lockfile --ignore-scripts
corepack pnpm typecheck
corepack pnpm lint
corepack pnpm test
corepack pnpm test:e2e
corepack pnpm build
corepack pnpm validate:package
corepack pnpm validate:plugins
npm pack --dry-run

Uninstall and data cleanup

Remove the installed package independently of its data by running pi list, then passing the exact listed source to pi uninstall as shown in Installation. Package uninstall does not delete existing learning data or published reports. After uninstalling, delete the resolved learning home listed above only if you intentionally want permanent data cleanup. If LEARNING_SESSION_HOME was set, delete that configured directory instead. Review the path first; data deletion cannot be undone.