Perceptor

Perceptor is a CLI coding tutor built around a Socratic method system prompt. It's told outright to never hand over a direct answer, never send a student to outside tutorials, and instead break whatever they're stuck on into a small, immediately doable exercise. The whole tool is really just that constraint enforced consistently across a conversation loop with Claude, plus a couple of special commands layered on top.

One of those commands lets a student ask about "codebase structure" mid-conversation. Rather than a slash command, it's detected from plain language: the input is scanned against a list of trigger phrases, and if one matches, a static analysis of the current directory gets appended to the message before it ever reaches the model.

async respond(userInput) {
  const needsCodebaseAnalysis = this.shouldAnalyzeCodebase(userInput);
  let messageContent = userInput;

  if (needsCodebaseAnalysis) {
    try {
      const analysis = this.codebaseAnalyzer.analyzeCurrentDirectory();
      const formattedAnalysis = this.codebaseAnalyzer.formatAnalysisForLLM(analysis);
      messageContent = `${userInput}\n\n[CODEBASE ANALYSIS]\n${formattedAnalysis}`;
    } catch (error) {
      messageContent = `${userInput}\n\n[CODEBASE ANALYSIS ERROR: ${error.message}]`;
    }
  }

  this.conversationHistory.push({ role: 'user', content: messageContent });

  const response = await this.anthropic.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 1000,
    system: this.systemPrompt,
    messages: this.conversationHistory
  });

  const assistantMessage = response.content[0].text;
  this.conversationHistory.push({ role: 'assistant', content: assistantMessage });

  return assistantMessage;
}

The rest of the tutor is conversation-history bookkeeping: every turn gets appended to this.conversationHistory and replayed in full on each call, so the Socratic thread (and whatever it's already made the student figure out for themselves) carries forward instead of resetting each time.