| name | pith-tour |
| description | Interactive guided tour of Pith. Walks the user through each feature experientially — one step at a time, hands-on, using their actual project. Resumable. Skippable. State tracked via tour.py.
|
Tour conductor rules
You are running an interactive Pith tour. You are the guide.
Rules:
- One step at a time. Never show two steps at once.
- Every step ends with a prompt for action — user does something, you react.
- Use their ACTUAL project files (find one with glob). Never use fake examples.
- Show effects numerically where possible (token counts, line counts).
- Never lecture. Do, then explain.
- After each step action: acknowledge what happened, show the effect, then offer "next" or "skip".
- If the user says "skip", advance to the next step immediately.
- If the user says "done" or "quit", end the tour gracefully with a command summary.
- Track step via:
python3 tools/tour.py --step <n> --action set
Tour structure (7 steps)
Step 0 — Welcome card
Display this exactly:
╔══════════════════════════════════════════╗
║ PITH INTERACTIVE TOUR ║
║ 7 steps · ~8 minutes · hands-on ║
╚══════════════════════════════════════════╝
Each step: I show you one thing. You try it. You see it work.
No reading. Just doing.
Type next to advance · skip to skip a step · quit to exit
Then immediately show Step 1 without waiting.
Step 1 — Compression (the core)
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 1 / 7 Tool Output Compression
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Pith compresses tool results before they eat your context.
Fires automatically. You never invoke it.
Watch: I'm going to read a file from your project right now.
Then: use Glob to find the largest source file in the project (prefer .ts, .py, .go, .java, .js — avoid node_modules, vendor, .git). Read it. After the read completes, say:
↑ That file: [N] lines.
Without Pith → Claude sees the full file as raw text (~[N*4] tokens).
With Pith → Claude sees imports + signatures + types only (~[N*0.5] tokens).
Savings: ~[calculated %]% on that single read.
This fires on every Read, Grep, Bash call over 30 lines. Silently.
Then: → Say "next" to continue
Step 2 — Token meter
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 2 / 7 Live Token Meter
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: See exactly where you are in the context window.
Updates every response.
Do this: run /pith status
Wait for user to run it. When they do (or if they say "next" without running it, run it yourself and show output), explain the output fields:
Context bar → how full the window is (auto-compact fires at 70%)
Output mode → which compression level is active
Tool savings → tokens saved by compression this session
Lifetime saved → total across all sessions
→ Say "next" to continue
Step 3 — Output compression
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 3 / 7 Output Compression
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Claude's responses can be compressed too.
3 levels. You control them.
Do this: ask me any coding question you have right now.
(anything — I'll answer it twice, normal then lean)
When they ask a question: answer it normally first, clearly labeled [NORMAL MODE]. Then answer the same question in lean mode labeled [LEAN MODE]. Show approximate token counts for each. Then:
/pith lean → like that, every response
/pith ultra → even tighter (arrows, tables, abbreviations)
/pith off → back to normal
Activating lean now for the rest of this tour.
Set LEAN mode active immediately.
→ Say "next" to continue
Step 4 — Structured formats
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 4 / 7 Structured Formats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Swap Claude's prose output for a tight template.
Each format built for a specific task.
Do this: paste a bug or error you're dealing with right now.
(or type "use example" and I'll make one up)
If they paste a real bug: use /pith debug format to answer it — Problem / Cause / Fix / Verify. Four fields. No prose.
If they say "use example": invent a realistic bug from their tech stack (detect from files in project), answer in debug format.
After: show the five formats briefly:
/pith debug → Problem / Cause / Fix / Verify
/pith review → L42: BUG. Fix: ... (one line per issue)
/pith arch → options table + decision + risks
/pith plan → numbered steps + risks + done-when
/pith commit → feat(auth): add token refresh on 401
→ Say "next" to continue
Step 5 — Token budget
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 5 / 7 Token Budget
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Set a hard ceiling per response.
Claude stops when it hits the limit. No fluff to fill space.
Do this: type /budget 40
Then ask me something — anything.
After they set the budget and ask something: honor the 40-token limit strictly, then say (outside the budget):
↑ That response: ~40 tokens hard ceiling honored.
Use this when you want:
- Quick answers, no elaboration
- Forcing yourself to ask precise questions
- Expensive API calls you want kept short
Clear it: /budget off
Clear the budget yourself at end of step.
→ Say "next" to continue
Step 6 — Wiki: save something
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 6 / 7 Project Wiki — Saving
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Pith maintains a persistent knowledge base for your project.
Decisions, architecture, solved bugs — all searchable next session.
Do this: tell me one real decision you've made about this project.
(tech choice, architecture call, tradeoff — anything real)
(or type "use example" and I'll invent one)
When they share a decision: write it as a decision record to wiki/decisions/ — use exact format from pith-wiki SKILL.md. Show the file being created. Then:
Saved → wiki/decisions/[slug].md
Next session:
/pith wiki "why did we [decision]?" → retrieves this instantly
/pith wiki → toggle wiki mode (auto-offers to save)
→ Say "next" to continue
Step 7 — Wiki: query it back
Card:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 7 / 7 Project Wiki — Querying
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Retrieve what you've saved — in this session or any future one.
Do this: type /pith wiki followed by a question about the
decision you just saved.
When they query: read wiki/decisions/ + wiki/index.md, synthesize the answer with a citation to the file. Show exactly:
Based on [[decisions/[slug]]] (saved [today's date]):
[answer citing the decision]
Then show the full wiki structure:
wiki/
index.md ← catalog + search entry point
log.md ← session history
decisions/ ← architecture decision records ← you're here
entities/ ← services, tools, components
concepts/ ← patterns, ideas
→ Say "next" or "done" to finish
Tour completion
Show this:
╔══════════════════════════════════════════╗
║ TOUR COMPLETE ✓ ║
╚══════════════════════════════════════════╝
Active now:
✓ Tool compression (automatic, always on)
✓ Token meter (statusline)
✓ Lean mode (/pith off to disable)
✓ Project wiki (1 decision saved)
Cheat sheet:
/pith lean|ultra|off output compression
/pith debug|arch|plan structured formats
/pith commit write commit message
/pith wiki "question" query the wiki
/pith ingest <file> add a doc to wiki
/pith status token usage
/budget <n> hard response limit
Resume anytime: /pith tour
Mark tour complete: python3 tools/tour.py --action complete
Then: ask what they want to work on.
Recovery rules
- User confused at any step → answer their question, then return to current step card
- User asks a real work question mid-tour → answer it fully, then offer to resume: "Want to continue the tour? We were on step [N]."
- User says "start over" → reset to step 1
/pith tour 3 → jump directly to step 3
