pi-cs (Pisces)

The CS Student Edition for Pi Coding Agent

Your intelligent, adaptive AI co-pilot that swims deep into every aspect of your Computer Science degree.

"Your Personal AI Teaching Assistant for Computer Science — From Homework to Thesis"

---

What is Pisces?

Pisces is a Pi Coding Agent package that transforms Pi into a deeply integrated academic co-pilot — the equivalent of a senior TA living inside your terminal.

It covers every dimension of a CS degree:

Need	Command	What it does
Manage workspace activation	/pisces	Activate, deactivate, or check workspace status
Set up semester context	/skill:semester	Init, update, or inspect your SEMESTER.md context
Stuck on an assignment	/skill:homework	Hints, pseudocode, guided walkthrough — no cheating
Starting a new project	/skill:project	Requirements → architecture → scaffolded codebase
Code review before submitting	/skill:review	Strict TA-level review with severity tiers
Don't understand a concept	/skill:explain	Feynman-style: analogy + diagram + code example
Interview/LeetCode prep	/skill:leetcode	Optimized solutions with complexity proofs
Exam in 3 days	/skill:exam	Quiz mode, mind maps, and revision plans
Research paper / thesis	/skill:research	Paper summaries, literature surveys, citations

---

Quick Start

# 1. Install Pisces globally (recommended for most students)
pi install npm:@aethrekh/pi-cs

# 2. Mark your university workspace (one-time setup)
cd ~/university
pi
/pisces --activate

# 3. Initialize your semester context
/skill:semester --init

# 4. Start working
/skill:homework
/skill:explain binary search trees
/skill:leetcode 42

After step 2, Pisces activates in ~/university and all its subdirectories. Outside that workspace, Pi runs as stock — no skills, no persona.

---

Workspace Activation

Pisces uses a .pisces marker file to decide where it is active. Outside a marked workspace Pi is completely silent — no skills load, no persona injects, no extensions run. Inside a workspace the full Pisces experience turns on.

Marking a workspace

cd ~/university        # navigate to your workspace root
/pisces --activate     # creates .pisces here and reloads Pi

How workspace discovery works

Pisces walks up the directory tree from where Pi was started, up to 15 levels, stopping at your home directory. This means you can start Pi from any subdirectory and Pisces will still find the marker:

~/university/           ← .pisces lives here
├── fall2025/
│   └── CS301/
│       └── lab1/       ← start Pi here; Pisces walks up and activates

Workspace commands

/pisces --status      # show activation state, workspace root, semester, and skills
/pisces --activate    # mark the current directory as a Pisces workspace
/pisces --deactivate  # remove .pisces from the nearest workspace above cwd
/pisces --setup       # guided first-time setup: checks prerequisites, activates, prompts for semester init
/pisces --doctor      # health check: Node version, workspace active, SEMESTER.md, stale files

Switching workspace context

Pi's working directory is fixed at session start — there is no mid-session directory change mechanism in the Pi extension API. To switch workspace context, start a new Pi session (/new or restart Pi) from the target directory. /pisces --status always reflects the startup directory, not wherever you have cd'd during the session.

---

Semester Context

Pisces becomes dramatically more useful when it knows your academic context. Create a SEMESTER.md in your university root:

semester: Fall 2025
year: 2025
week: 7
year_of_study: 2

## Courses
- CS301: Operating Systems
- CS315: Database Systems
- CS320: Software Engineering

active_project: shell-implementation

Pisces auto-detects this file at startup and greets you with relevant context:

"Hey! I see you're in Week 7 of Fall 2025. You have 3 active courses. What are we working on today?"

---

Skills Reference

/skill:semester

Semester context management. Three modes:

/skill:semester            # status if SEMESTER.md exists, prompts --init if not
/skill:semester --init     # scaffold a new SEMESTER.md interactively
/skill:semester --update   # update week, courses, active project, or other fields
/skill:semester --status   # show everything Pisces currently detects

/skill:homework

Guided learning mode. Pisces uses the Socratic method — hints, pseudocode, and guided questions. Never produces complete submittable solutions for graded work.

/skill:homework
> Here's my problem: implement Dijkstra's algorithm...
> I've tried a basic BFS but it doesn't handle weights

/skill:project

Full project kickoff. Requirements analysis, architecture proposal, tech stack recommendation, and scaffolded boilerplate.

/skill:project
> Build a REST API for a student grade tracker
> Tech stack: open to suggestions
> Deadline: 3 weeks

/skill:review

TA-level code review. Covers correctness, efficiency, style, robustness, and tests. Every issue is rated (🔴 Critical / 🟠 Major / 🟡 Minor / 🔵 Suggestion).

/skill:review --mode=deep
[paste your code]

/skill:explain

Feynman-style explanations with real-world analogies, Mermaid diagrams, and connections to your prior knowledge.

/skill:explain virtual memory
/skill:explain the CAP theorem --depth=advanced
/skill:explain recursion --style=analogy

/skill:leetcode

Structured problem solving for interview prep. Full solutions with brute force → optimal progression, complexity proofs, and test cases.

/skill:leetcode 42
/skill:leetcode trapping rain water --lang=python
/skill:leetcode --mode=interview    # simulates a real interview

/skill:exam

Exam preparation toolkit. Interactive quizzes, concept mind maps, day-by-day revision plans, and Anki-compatible flashcards.

/skill:exam CS301 --mode=quiz
/skill:exam operating systems --mode=mindmap
/skill:exam --mode=plan          # builds schedule based on your exam date

/skill:research

Academic research assistant. Paper summaries, literature surveys, citation generation, and literature review writing.

/skill:research "Attention is All You Need"
/skill:research attention mechanisms --mode=survey
/skill:research --mode=cite arxiv:1706.03762 --format=bibtex

---

Academic Integrity

Pisces has academic integrity built in at every level:

• ✅ Always provides hints, explanations, and pseudocode
• ✅ Helps you debug your own code
• ✅ Writes complete code for personal projects, /skill:leetcode, and /skill:project
• ❌ Never writes complete solutions for graded assignments
• ❌ Never submits or helps disguise AI-generated work as your own

When Pisces detects a potential integrity issue, it redirects to guided learning mode and asks for clarification.

---

Configuration

Create a .pi-cs.json file to override defaults. Pisces checks these locations in order, first match wins:

1. .pi-cs.json in the current working directory (project-level)
2. ~/.pi/pi-cs.json (user-level)
3. ~/.config/pi-cs/config.json

{
  "student": {
    "name": "Alex",
    "year_of_study": 2,
    "primary_language": "python"
  },
  "explanations": {
    "default_depth": "intermediate",
    "prefer_visuals": true
  },
  "productivity": {
    "burnout_nudges": true,
    "session_warning_minutes": 180
  }
}

See config/schema.json for the full configuration reference.

---

Installation

Requirements: Pi >= 0.78.0, Node.js >= 18

# Recommended — installs Pisces globally
pi install npm:@aethrekh/pi-cs

After a global install the gatekeeper extension loads in every Pi session, but Pisces is silent by default — no skills, no persona, no extensions run until you activate a workspace with /pisces --activate. This means Pisces is available everywhere you want it without affecting non-university Pi sessions.

# Local install — loads the extension only in the exact install directory
cd ~/university
pi install npm:@aethrekh/pi-cs -l

With a local install, the extension itself only loads when Pi is started from ~/university exactly — not from any subdirectory. Combined with workspace scoping, this offers the tightest possible containment, but requires you to always start Pi from that one root. Most students should use the global install.

	Global	Local (-l)
Extension loads	In every Pi session	Only from exact install directory
Skills / persona active	Only inside a .pisces workspace	Only inside a .pisces workspace
Works from course subdirectories	Yes	No — exact directory only
Recommended	Yes	Edge case only

---

Project Structure

pi-cs/
├── SYSTEM.md                    # Core academic persona (Pi system prompt)
├── pi-package.yaml              # Package manifest
├── src/
│   ├── skills/
│   │   ├── semester/SKILL.md       # /semester skill
│   │   ├── homework/SKILL.md       # /homework skill
│   │   ├── project/SKILL.md        # /project skill
│   │   ├── review/SKILL.md         # /review skill
│   │   ├── explain/SKILL.md        # /explain skill
│   │   ├── leetcode/SKILL.md       # /leetcode skill
│   │   ├── exam/SKILL.md           # /exam skill
│   │   └── research/SKILL.md       # /research skill
│   ├── extensions/
│   │   ├── gatekeeper.ts           # Workspace gating; /pisces command
│   │   ├── lib/
│   │   │   ├── config.ts           # Shared config loader (loadConfig, deepMerge)
│   │   │   ├── workspace.ts        # .pisces discovery (walks up 15 levels)
│   │   │   └── workspace-state.ts  # Shared activation state across extensions
│   │   ├── semester-detector.ts    # Auto-loads SEMESTER.md (workspace-gated)
│   │   ├── folder-detector.ts      # Detects CS folder structures (workspace-gated)
│   │   ├── integrity-guard.ts      # Academic integrity monitoring (workspace-gated)
│   │   └── progress-tracker.ts     # Weekly stats & burnout nudges (workspace-gated)
│   └── templates/
│       └── semester-init.md        # SEMESTER.md raw template
├── config/
│   ├── schema.json              # Config schema
│   └── defaults.json            # Default values
└── tests/
    ├── index.test.ts            # Lifecycle hooks & config tests
    └── extensions/              # Per-extension unit tests

---

Roadmap

• 8 core skills
• 4 background extensions + workspace gatekeeper
• Semester context system
• Academic integrity guard
• Workspace-scoped activation (.pisces marker, /pisces command)
• arXiv live search integration
• Model routing presets
• Obsidian vault sync
• /debug interactive debugging skill
• VS Code companion extension

---

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

For bugs, use the bug report template.

---

License

MIT — see LICENSE

---

Made for CS students, by CS students.

---

Star History