paseo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Voice-controlled terminal assistant using OpenAI's Realtime API (via Whisper STT, GPT-4, and TTS). Backend server with Expo app for all platforms (iOS, Android, and Web).

Monorepo Structure

This is an npm workspace monorepo:

• Root: Workspace configuration and shared TypeScript config
• packages/server: Backend server (Express + WebSocket API)
• packages/app: Cross-platform app (Expo - iOS, Android, Web)

Environment overrides

• PASEO_HOME – path for runtime state such as agents.json. Defaults to ~/.paseo; set this to a unique directory (e.g., ~/.paseo-blue) when running a secondary server instance.
• PASEO_PORT – preferred voice server + MCP port. Overrides PORT and defaults to 6767. Use distinct ports (e.g., 7777) for blue/green testing.

Example blue/green launch:

PASEO_HOME=~/.paseo-blue PASEO_PORT=7777 npm run dev

Running and checking logs

Both the server and Expo app are running in a Tmux session. See CLAUDE.local.md for system-specific session details.

Android

Take screenshots like this: adb exec-out screencap -p > screenshot.png

Testing with Playwright MCP

CRITICAL: When asked to test the app, you MUST use the Playwright MCP connecting to Metro at http://localhost:8081.

Use the Playwright MCP to test the app in Metro web. Navigate to http://localhost:8081 to interact with the app UI.

Important: Do NOT use browser history (back/forward). Always navigate by clicking UI elements or using browser_navigate with the full URL. The app uses client-side routing and browser history navigation breaks the state.

Expo troubleshooting

Run npx expo-doctor to diagnose version mismatches and native module issues.

Orchestrator Mode

When asked to go into orchestrator mode, you must only accomplish tasks by managing other agents. Do NOT perform the work yourself.

Agent Control Best Practices

• When agent control tool calls fail, make sure you list agents before trying to launch another one. It could just be a wait timeout.
• Always prefix agent titles so we can tell which ones are running under you (e.g., "🎭 Feature Implementation", "🎭 Design Discussion").
• Launch agents in the most permissive mode: Use full access or bypass permissions mode.
• Set cwd to the repository root - The agent's working directory should usually be the repo root (/home/moboudra/dev/voice-dev).

Agent Use Cases

You can run agents to:

• Implement a task - Spawn an agent to write code and implement features
• Have a design discussion - Discuss architecture and design decisions
• Have a pairing session - Collaborate on problem-solving
• Test some feature - Run tests and verify functionality
• Do investigation - Research and explore the codebase

Clarifying Ambiguous Requests

CRITICAL: When user requests are ambiguous or unclear:

1. Research first - Spawn an investigation agent to understand the current state
2. Ask clarifying questions - After research, ask the user specific questions about what they want
3. Present options - Offer multiple approaches with trade-offs
4. Get explicit confirmation - Never assume what the user wants

Investigation vs Implementation

CRITICAL: When asked to investigate:

• Investigation agents MUST NOT fix issues - They should only identify, document, and report problems
• Always ask for confirmation - After investigation, present findings and ask: "Should I proceed with implementing fixes?"
• Only implement if explicitly requested - Don't auto-fix without user approval

Strategic Planning and Task Breakdown

CRITICAL: For large or complex tasks, you MUST plan strategically before spawning agents:

1. Break down the work into small, focused tasks
2. Design the agent workflow: What agents will you need? In what order?
3. Plan checkpoints: Where do you need review agents? Test agents? Integration points?
4. Ensure each agent commits their work before moving to the next phase
5. Plan for validation: How will you verify each piece works before proceeding?

Example workflow for a large feature:

• Investigation agent → Design discussion agent → Multiple implementation agents (one per component) → Test agent → Review agent → Integration agent

Rigorous Agent Interrogation

CRITICAL: Agents start with ZERO context about your task. You must always provide complete context in your initial prompt.

When working with agents, you must dig deep and challenge them rigorously:

For Implementation Agents

• Don't accept surface-level completion: Ask them to show you the code they implemented
• Trace the implementation: Ask them to walk through the code flow step by step
• Uncover gaps: Dig hard to find possible gaps in their understanding
  • "Show me exactly where you handle error case X"
  • "What happens if the user does Y before Z?"
  • "Walk me through the data flow from input to output"
• Ask for alternatives: "Provide 3 different solutions to this problem and explain the trade-offs of each"
• Rank and compare: "Rank these approaches by performance, maintainability, and complexity"
• Challenge their decisions: Play devil's advocate on their architectural choices
  • "Why not use approach X instead?"
  • "What are the downsides of your solution?"
  • "How will this scale?"

For Investigation/Debugging Agents

• Don't stop at the first answer: Keep digging deeper
• Explore different angles: "What are 3 other possible causes?"
• Request proof: "Show me the specific code that proves this hypothesis"
• Challenge assumptions: "How do you know that's the root cause? What else could it be?"
• Ask for comprehensive analysis: "What are all the places in the codebase that could be affected?"

For Review Agents

• Security review: "What are the security implications? Any OWASP vulnerabilities?"
• Edge cases: "What edge cases are not handled?"
• Performance: "Where are the performance bottlenecks?"
• Maintainability: "How maintainable is this code? What would make it better?"

Debugging with Logging and Playwright

CRITICAL: When debugging frontend or server issues:

• Frontend debugging: Use Playwright MCP to interact with the app at http://localhost:8081
  • Take screenshots to verify UI state
  • Click through flows to reproduce issues
  • Use browser console to check for errors
  • Verify network requests and responses
• Server debugging: Add strategic logging to trace execution
  • Log request/response payloads
  • Log state transitions
  • Log error conditions
  • Use server logs to correlate with frontend behavior
• Full-stack debugging: Combine both approaches
  • Use Playwright to trigger frontend actions
  • Check server logs to see backend behavior
  • Verify data flow from client → server → client

Agent Management Principles

• Keep agents focused - Each agent should have a clear, specific responsibility
• You can talk to them - Send prompts and guidance as they work
• Monitor progress - Check status and provide feedback
• Always provide context - Remember: agents start with zero knowledge of your task
• Verify work rigorously - Don't trust, verify. Ask agents to prove their work
• Commit frequently - Ensure each agent commits their changes before moving on
• Plan for quality gates - Use test and review agents as checkpoints

CRITICAL: ALWAYS RUN TYPECHECK AFTER EVERY CHANGE.