Getting the most
out of Pisces.
The complete, technically precise guide — from installation and semester context to every skill, the integrity system, and practical workflows for every situation you'll encounter.
What Pisces Is
(and isn't)
Pisces runs inside the Pi terminal agent and activates automatically in every session after installation. You interact with it through natural conversation and slash commands — no new interface to learn.
- ▸Guide you through problems using hints and the Socratic method
- ▸Scaffold new projects from scratch with complete boilerplate
- ▸Review your code with TA-level rigour
- ▸Explain any CS concept from first principles, calibrated to your level
- ▸Provide full solutions and analysis for LeetCode and interview prep
- ▸Build exam revision plans, quizzes, and mind maps
- ▸Help with research papers, citations, and literature surveys
- ▸Write complete solutions to graded assignments
- ▸Submit or disguise work as your own
- ▸Replace your professor, lecture attendance, or genuine thinking
- ▸Guarantee citation accuracy for papers beyond its knowledge cutoff
Installation
Requirements: Pi ≥ 1.0.0, Node.js ≥ 18. Pisces activates automatically in every Pi session after installation — no further setup required to start using it.
pi install npm:@aethrekh/pi-csSetting Up
Semester Context
The most impactful thing you can do is create a SEMESTER.md file in your university root. This is the primary signal Pisces uses to personalise responses — greetings, explanation depth, course-aware exam prep, and project context all rely on it. Run /semester --init to scaffold it from the built-in template, or create it manually.
semester: Fall 2025
year: 2025
week: 7
year_of_study: 2
## Courses
- CS301: Operating Systems
- CS315: Database Systems
- CS320: Software Engineering
- MATH210: Discrete Mathematics
active_project: shell-implementation (CS301 final project)
## Notes
Office hours: Prof. Martinez — Tuesdays 3-5pm
Study group: Thursdays 6pm
Feeling weak on: Virtual memory, page tables| Field | Format | Effect |
|---|---|---|
semester: | Any string | Shown in greeting; used for context |
year: | 4-digit integer | Calendar year for reference |
week: | Integer | Current week; shown in greeting |
year_of_study: | 1–6 | Drives explanation depth (1=freshman, 4=senior, 5–6=graduate) |
- COURSECODE: Name | e.g. CS301, ECE202 | Lists active courses; enables course-aware exam prep |
active_project: | Any string | Shown in greeting; provides project context |
Course codes must match [A-Z]{2,4}\\d{2,4} (e.g. CS301, ECE202). Lines that don't match this pattern are silently skipped.
Current working directory (process.cwd())~/university/~/uni/~/college/~/school/~/Documents/university/~/Documents/uni/SEMESTER.md in your university root (e.g. ~/university/). Pisces will find it regardless of which course subfolder you are working in.Pisces re-runs semester detection every time you cd to a new directory — no restart needed. At the start of each semester, update semester:, year:, week:, year_of_study:, and the course list. Each week, increment week: by one and update active_project: if it has changed.
How Auto-Detection
Works
Two background extensions run silently at startup and on every directory change. Understanding them helps you structure your workspace to give Pisces the most context.
Triggers on startup and cd. Parses SEMESTER.md using the rules above and injects semester context into the session. If no file is found, the greeting invites you to run /semester --init.
Triggers on startup and cd. Analyzes your working directory and its path to identify university workspace, semester folder, course folder, project type, and project health flags.
University workspace detection — looks for university, uni, college, or school (case-insensitive) anywhere in the path. If found, identifies your semester folder one level below the university root (patterns: fall2025, spring24, sem1, semester2) and course folder two levels below (patterns: CS301, ECE202).
| Type | Detected by |
|---|---|
| rust | Cargo.toml |
| go | go.mod |
| python | requirements.txt, pyproject.toml, setup.py, Pipfile |
| java | pom.xml, build.gradle |
| cpp | CMakeLists.txt, Makefile |
| web | index.html, vite.config.*, next.config.*, webpack.config.* |
| typescript | package.json, tsconfig.json |
| unknown | (none of the above) |
- ▸tests/, test/, or __tests__/ — test coverage present
- ▸.github/ — CI/CD configured
- ▸Dockerfile or docker-compose.yml — Docker setup
- ▸README.md or readme.md — documentation present
When any of these are missing, Pisces surfaces a warning in its context summary and brings it up proactively during project work.
Configuration
Config is loaded from the following locations in priority order (earlier entries override later ones). Partial overrides work — only specify the fields you want to change.
.pi-cs.json in current working directory (project-level)~/.pi/pi-cs.json (user-level)~/.config/pi-cs/config.json (XDG-compliant)Built-in defaults{
"student": {
"name": "Alex",
"year_of_study": 2,
"primary_language": "python",
"timezone": "America/New_York"
},
"explanations": {
"default_depth": "intermediate",
"prefer_visuals": true,
"use_analogies": true
},
"code": {
"style": "balanced",
"always_include_complexity": true,
"always_include_tests": false
},
"integrity": {
"enabled": true,
"strictness": "balanced"
},
"productivity": {
"burnout_nudges": true,
"session_warning_minutes": 180,
"weekly_summary": true
}
}| Field | Values | Effect |
|---|---|---|
| student.year_of_study | 1–6 | Fallback when SEMESTER.md is absent; SEMESTER.md takes precedence at runtime |
| student.primary_language | python, typescript, java, cpp, go, rust, … | Default language for generated code examples |
| student.timezone | IANA string | Enables deadline-aware context (e.g. 'due tonight') |
| explanations.default_depth | beginner · intermediate · advanced | Applied when --depth= is not specified on /explain |
| explanations.prefer_visuals | true / false | Generates Mermaid diagrams for structural concepts |
| code.style | verbose · balanced · concise | Controls inline comment density in generated code |
| code.always_include_complexity | true / false | Appends Big-O analysis to all algorithm output |
| code.always_include_tests | true / false | Appends test cases alongside every code solution |
| integrity.strictness | strict · balanced · relaxed | How aggressively medium-risk patterns trigger clarification |
| productivity.session_warning_minutes | Integer ≥ 30 | Minutes before Pisces suggests a break (default: 180) |
| productivity.weekly_summary | true / false | Shows study time, sessions, streak, skill breakdown at session end |
Create .pi-cs.json in any project directory to override config only when working there. Example — enabling tests for a course project that requires a test suite:
{
"code": {
"always_include_tests": true
}
}Skills Reference
Skills are invoked with slash commands. You can include context inline or paste it after the command — Pisces will ask for whatever it needs.
Semester
Manage your semester context file. Three modes cover the full lifecycle of SEMESTER.md — creating it, keeping it current, and verifying what Pisces sees. Running /semester without a flag shows status if the file exists, or prompts --init if not.
/semester # status if SEMESTER.md exists, prompts --init if not
/semester --init # scaffold a new SEMESTER.md interactively
/semester --update # update week, courses, active project, or other fields
/semester --status # show everything Pisces currently detectsRun at the start of each new semester. Pisces asks for your semester, year of study, courses, active project, and any weak topics — all in one message — then outputs a filled-in SEMESTER.md with real values (no placeholders), tells you where to place it (~/university/ recommended), and greets you with the new context so you can see personalisation working immediately.
Run any time you need to change a field without starting over. Tell Pisces what changed (e.g. "I'm on week 6 now" or "add CS320 to my courses") and it outputs the complete updated file ready to copy-paste.
Shows a structured summary of everything Pisces currently detects: source file path, semester and week, courses, active project, weak topics, and folder context (detected project type, tests, CI). If nothing is detected, offers to run --init.
--update each week (increment week:) and whenever your active project changes. At the start of each semester, use --init to start fresh rather than editing the file manually.Homework
Guided help on assignments using the Socratic method. Never produces complete, submittable code for graded work. Pisces works through a five-step process: problem intake → decomposition → escalating hint ladder → implementation review → reinforcement.
/homework
/homework implement Dijkstra's algorithm
/homework [paste problem statement]- ▸The full problem statement (paste it directly)
- ▸Which course it is from
- ▸What you have already tried
- ▸Where specifically you are stuck
- ▸Concept reminder — what underlying idea applies here
- ▸Algorithm sketch in plain English
- ▸High-level pseudocode (never full implementation)
- ▸Data structure or pattern hint
- ▸Edge case prompts
Project
Full project kickoff from a brief or idea to scaffolded codebase. Complete code generation is allowed — this skill bypasses the integrity guard entirely.
/project
/project build a REST API for a student grade tracker
/project [paste assignment brief]- ▸Requirements analysis — structured functional and non-functional requirements
- ▸Architecture proposal — Mermaid diagram showing components and data flow
- ▸Tech stack recommendation — table with layer, choice, and reasoning
- ▸Project scaffolding — folder structure, README, .gitignore, dependencies, CI workflow
- ▸Weekly milestones — deadline-aligned breakdown of what to build each week
| Language | Key files generated |
|---|---|
| Python | src/, tests/, requirements.txt, Makefile, .github/workflows/ci.yml |
| TypeScript | src/, tests/, package.json, tsconfig.json, .github/workflows/ci.yml |
| C/C++ | src/, include/, tests/, CMakeLists.txt, Makefile |
Review
Strict, honest, TA-level code review. Every issue is rated by severity across correctness, quality, efficiency, style, robustness, and testing.
/review [paste code or reference a file]
/review --mode=quick # high-level only
/review --mode=deep # full analysis including security and performance
/review --mode=style # style and readability onlyOverall: ✅ Good foundation / ⚠️ Needs work / ❌ Significant issues
What works well:
- [specific genuine positives]
Key areas to address:
- [top 2-3 highest-impact issues]Followed by a full structured pass covering: Correctness (bugs, edge cases, off-by-one), Code quality (naming, DRY, readability), Efficiency (Big-O, memory), Style (PEP 8, Google style), Robustness (error handling, security), and Testing (coverage, edge cases).
| Symbol | Level | Meaning |
|---|---|---|
| 🔴 | Critical | Bug, crash, or security issue — must fix before submission |
| 🟠 | Major | Significant correctness or quality issue — should fix |
| 🟡 | Minor | Style or readability — worth fixing |
| 🔵 | Suggestion | Optional improvement or alternative approach |
Line 23: ⚠️ ISSUE
current: if (arr.length > 0) { return arr[arr.length]; }
problem: Off-by-one — last element is arr.length - 1
fix: if (arr.length > 0) { return arr[arr.length - 1]; }Explain
Teaches any CS concept from first principles using the Feynman technique — analogy, diagram, code example, and connections to what you already know.
/explain virtual memory
/explain the CAP theorem --depth=advanced
/explain recursion --style=analogy| Depth | Target | Characteristics |
|---|---|---|
| beginner | Year 1, no prior CS | Heavy analogies, no jargon, simple code |
| intermediate | Years 2–3 | Balanced formal + intuitive, standard CS terms |
| advanced | Senior / graduate | Formal, precise, complexity-focused, edge cases |
- ▸--style=visual — emphasises Mermaid diagrams
- ▸--style=analogy — leads with a real-world analogy before any formal definition
- ▸--style=formal — skips analogies, leads with precise definition and complexity
- ▸--style=code — leads with a minimal working code example
- ▸One-sentence core — the clearest possible statement of the concept
- ▸Real-world analogy — a concrete mental model
- ▸Formal definition — precise terminology and complexity
- ▸Visual representation — Mermaid diagram for structures and algorithms
- ▸Code example — minimal, language-appropriate, commented
- ▸Connections to prior knowledge — explicit links to your courses
- ▸Common misconceptions — the top 1–3 things students get wrong
- ▸Feynman test — Pisces asks you to explain it back
- ▸Foundations — algorithms, data structures, complexity, recursion, dynamic programming
- ▸Systems — OS concepts, memory management, networking, concurrency, compilers
- ▸Theory — automata, computability, formal languages, cryptography
- ▸Applied — databases, web development, machine learning, distributed systems
- ▸Math — discrete math, linear algebra, probability for CS
- ▸Practice — design patterns, software engineering, testing, DevOps
LeetCode
Structured problem-solving for interview prep and competitive programming. Always bypasses the integrity guard — full solutions are provided.
/leetcode 42
/leetcode trapping rain water --lang=python
/leetcode --mode=guided # step-by-step walkthrough
/leetcode --mode=review # review your own attempt
/leetcode --interview # simulate a real interview- ▸Problem analysis — category, difficulty, key insight, related patterns
- ▸Approach ladder — brute force → optimized → optimal, with complexity at each step
- ▸Full solution — with inline comments on every non-obvious step
- ▸Complexity analysis — Big-O time and space with lower-bound argument
- ▸Test suite — basic case, edge cases (empty, duplicates, negatives), boundary conditions
- ▸Related problems — 2–3 problems that practice the same underlying pattern
- ▸Pisces presents the problem and waits for your approach
- ▸Hints are only given when you explicitly ask
- ▸Times the session
- ▸Debriefs afterward with what a real interviewer would have noted
| Pattern | Key structures | Classic problems |
|---|---|---|
| Two Pointers | Array | Two Sum II, Container With Most Water |
| Sliding Window | Array, String | Longest Substring Without Repeating, Min Window Substring |
| Binary Search | Sorted Array | Search in Rotated Array, Find Peak Element |
| BFS/DFS | Graph, Tree | Number of Islands, Word Ladder |
| Dynamic Programming | Array, Matrix | Climbing Stairs, Coin Change, LCS |
| Backtracking | Implicit Tree | Permutations, Subsets, N-Queens |
| Heap / Priority Queue | Heap | Top K Elements, Merge K Sorted Lists |
| Monotonic Stack | Stack | Valid Parentheses, Largest Rectangle in Histogram |
| Trie | Trie | Word Search II, Autocomplete |
| Union Find | Array | Number of Provinces, Redundant Connection |
Exam Prep
Structured exam preparation — quizzes, mind maps, revision plans, and flashcards. Adapts to your course syllabus from SEMESTER.md.
/exam CS301 --mode=quiz
/exam operating systems --mode=mindmap
/exam --mode=plan # day-by-day revision schedule
/exam --mode=flashcards # Anki-compatible Q&A pairs- ▸Course name or topic
- ▸Exam date (days until)
- ▸Topics covered — paste syllabus if available
- ▸Exam format — MCQ, short answer, coding, or oral
- ▸Your weakest areas
If SEMESTER.md has course information, Pisces pre-fills what it already knows.
Adaptive interactive session — one question at a time. Difficulty adjusts based on performance (3 correct in a row = harder; 2 wrong in a row = drops back to fundamentals and re-explains). Question formats vary by topic: trace-through for algorithms, explain-in-your-words for theory, proof-by-induction for math.
Score: 14/20 (70%)
Time: 23 minutes
Strong areas: Sorting algorithms, Graph traversal
Weak areas: Dynamic Programming (4/8), Concurrency (2/4)Mermaid diagram of the full topic with all key concepts, relationships, and sub-concepts. Also outputs a flat list for linear revision and notes which concept pairs are frequently tested together.
Builds a day-by-day schedule from today to the exam, allocating topics by weight and your stated weak areas.
Day 1: Arrays, Strings, Hashing — review + 3 practice problems
Day 2: Trees & Graphs — trace 2 BFS and 2 DFS problems on paper
Day 3: Dynamic Programming — memoization vs tabulation
Day 4: Sorting + Complexity — all sort algorithms, trade-offs
Day 5 (Eve): Light review + one timed past paper — rest by 10pmGenerates Q&A pairs in Anki-compatible format — copy-paste directly into Anki's text import.
Q: What is the time complexity of building a heap from n elements?
A: O(n) — bottom-heavy nature means most insertions are cheap.
Q: State the four Coffman conditions for deadlock.
A: Mutual exclusion, Hold and wait, No preemption, Circular wait.Research
Academic research assistant for paper discovery, summarisation, literature reviews, and citation management.
/research "Attention is All You Need"
/research --mode=survey # literature survey on a topic
/research --mode=compare # compare two or more papers
/research --mode=cite arxiv:1706.03762 --format=bibtex
/research --mode=review # help write a literature review section| Mode | What it produces |
|---|---|
| --mode=summarize | TL;DR, problem statement, approach, results, limitations, key terms |
| --mode=survey | Scope, key papers, theme-based organisation, open problems, timeline |
| --mode=compare | Side-by-side table: approach, assumptions, results, limitations, when to choose |
| --mode=cite | BibTeX, APA, or IEEE citation — specify with --format=bibtex|apa|ieee |
| --mode=review | Outline first → confirm → write with in-text citations and gap statement. For a full paper, generates the standard 9-section CS scaffold with IEEE LaTeX starter. |
@article{vaswani2017attention,
title={Attention is all you need},
author={Vaswani, Ashish and others},
journal={Advances in neural information processing systems},
volume={30},
year={2017}
}When you need a complete paper scaffold, --mode=review provides the standard 9-section CS paper structure: Abstract → Introduction → Related Work → Problem Formulation → Methodology → Evaluation → Discussion → Conclusion → References — along with an IEEE LaTeX starter and writing tips specific to CS papers.
- ▸Paper discovery — arXiv.org, Semantic Scholar, Papers With Code
- ▸Citation management — Zotero (free), Mendeley
- ▸Writing — Overleaf (LaTeX), Connected Papers (visual citation graph)
- ▸Reading strategy — 'How to Read a Paper' by S. Keshav (3-pass method)
Academic Integrity
System
The integrity guard runs automatically on every skill call (except /leetcode and /project, which always produce complete code). It operates in three tiers.
Inputs matching these patterns redirect to guided mode without asking:
"write my entire assignment / homework / lab / project"
"do my homework / assignment for me"
"complete my assignment / task for me"
"just give me the code for my [assignment]"
"finish my assignment for me"Inputs containing words like assignment, homework, graded, due tomorrow trigger a clarification question:
These contexts bypass medium-risk detection entirely, even if the input also contains medium-risk words:
- ▸"practicing", "learning", "just curious", "not for grade"
- ▸"personal project", "side project"
- ▸"leetcode" (anywhere in input)
The guard never hard-blocks a conversation. It always redirects gracefully to guided mode with an explanation of how Pisces can still help.
Progress Tracking
The progress-tracker extension records every session automatically. Data is stored locally at ~/.pi-cs/sessions.json. Sessions older than 90 days are automatically pruned. Each record includes date, duration, skills used, and topics worked on.
📊 This Week's Summary
⏱ Total study time: 14h 30m
📅 Sessions: 8
🔥 Current streak: 5 days
🛠 Most used skills:
- /homework: 4 sessions
- /leetcode: 3 sessions
- /explain: 2 sessionsEnable with productivity.weekly_summary: true in your config (on by default).
- ▸Long single session — triggers when duration ≥ session_warning_minutes (default: 180)
- ▸Heavy week — triggers when total weekly study time exceeds 40 hours
- ▸Streak milestone — positive reinforcement at 7+ consecutive days
Counts consecutive calendar days (backwards from today) that have at least one recorded session. A day with zero sessions breaks the streak.
Recommended
Folder Structure
Structure your workspace to maximise what Pisces auto-detects. Semester and course folder names are matched by pattern, so names like fall2025, spring24, and CS301 are recognised automatically.
~/university/
├── SEMESTER.md ← semester context (detected in this root)
├── fall2025/ ← matches semester pattern (fall + 4 digits)
│ ├── CS301/ ← matches course pattern (2-4 letters + 2-4 digits)
│ │ ├── assignments/
│ │ │ └── shell/ ← cd here; Pisces detects CS301 context
│ │ │ ├── src/
│ │ │ ├── tests/ ← hasTests = true
│ │ │ ├── Makefile ← detected as cpp project
│ │ │ └── .github/ ← hasCi = true
│ │ └── notes/
│ ├── CS315/
│ └── CS320/
└── personal-projects/
└── my-api/
├── src/
├── tests/
├── package.json ← detected as typescript project
└── README.md- ▸SEMESTER.md at the university root is found from any subdirectory
- ▸Semester folders: fall2025, spring24, sem1, semester2 (and similar patterns)
- ▸Course folders: CS301, ECE202, COS226 — exactly 2–4 uppercase letters + 2–4 digits
- ▸Project type is detected from the immediate working directory, not recursively
- ▸Tests, CI, Docker, and README presence are checked in the working directory
Practical
Workflows
Six end-to-end patterns for the most common situations you'll encounter as a CS student.
- 1Spend 15+ minutes attempting the problem on your own
- 2cd to your assignment directory — Pisces detects the course context
- 3/homework — paste the full problem statement, describe what you tried, say where you are stuck
- 4Work through Pisces' hints one at a time, implementing each step yourself
- 5Share your implementation when it is partially working; Pisces will point out bugs without fixing them
- 6Answer Pisces' follow-up: explain what your solution does in one sentence
- 1cd to your projects folder
- 2/project — describe the project, deadline, and whether the tech stack is mandated
- 3Review the requirements and architecture output; discuss with Pisces if anything needs adjustment
- 4Copy the scaffolded structure and initial files into your directory
- 5Set active_project: in SEMESTER.md to keep Pisces aware of what you're building
- 6/review --mode=deep before every major milestone
- 1/exam [course name] --mode=mindmap — see all topics at a glance
- 2Identify the 3–4 topics you are weakest on
- 3/exam --mode=plan — provide the exam date and weak areas; get a day-by-day schedule
- 4For each weak topic: /explain [topic] followed by the Feynman test
- 5Daily: /exam --mode=quiz on the day's topics
- 6Day before: /exam --mode=flashcards for quick review; one timed past paper
- 1Pick a topic (e.g. dynamic programming)
- 2/leetcode give me a medium dynamic programming problem
- 3Attempt it yourself for 20–25 minutes
- 4/leetcode --mode=review — paste your solution for feedback
- 5/leetcode [same problem] --mode=solution — see the optimal approach
- 6Re-implement from memory, then /leetcode [number] --interview to simulate
- 1/research [your topic] --mode=survey — get oriented in the literature
- 2For each key paper: /research --mode=summarize [paper title]
- 3/research --mode=compare [paper A] [paper B] for direct comparisons
- 4/research --mode=review — draft your literature review section with Pisces' structural guidance
- 5/research --mode=cite [paper] --format=bibtex — generate bibliography entries
- 6Verify every citation against Google Scholar before submitting
- 1Finish your own implementation first
- 2/review --mode=quick — identify the top issues
- 3Fix all 🔴 Critical and 🟠 Major issues
- 4/review --mode=deep — full pass for remaining issues
- 5Fix 🟡 Minor issues if time allows
- 6/review --mode=style if the course has a style rubric