@@ -5,6 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
55## Development Commands
66
77### Build & Watch
8+
89- ` jlpm dev:install ` - Full development install (install dependencies, build, and link extension)
910- ` jlpm build ` - Build TypeScript and create labextension for development
1011- ` jlpm build:prod ` - Production build (clean first, build optimized)
@@ -13,18 +14,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
1314- ` jlpm watch:labextension ` - Watch and rebuild labextension
1415
1516### Testing
17+
1618- ` pytest -vv -r ap --cov jupyter_ai_persona_manager ` - Run Python tests with coverage
1719- ` jlpm test ` - Run TypeScript tests with Jest
1820- Playwright integration tests are in ` ui-tests/ ` directory
1921
2022### Code Quality
23+
2124- ` jlpm lint ` - Run all linters (stylelint + prettier + eslint) with fixes
2225- ` jlpm lint:check ` - Check without fixing
2326- ` jlpm eslint ` - ESLint with fixes
2427- ` jlpm prettier ` - Prettier with fixes
2528- ` jlpm stylelint ` - Stylelint with fixes
2629
2730### Development Lifecycle
31+
2832- ` jlpm dev:uninstall ` - Uninstall development extension
2933- ` jlpm clean:all ` - Clean all build artifacts
3034
@@ -35,70 +39,82 @@ This is a JupyterLab extension that provides AI persona management for Jupyter A
3539### Core Components
3640
3741** BasePersona** (` jupyter_ai_persona_manager/base_persona.py ` ):
42+
3843- Abstract base class for all AI personas
3944- Handles chat integration, awareness management, and message processing
4045- Provides utilities for file attachment processing and workspace access
4146- Key methods: ` process_message() ` , ` stream_message() ` , ` send_message() `
4247
4348** PersonaManager** (` jupyter_ai_persona_manager/persona_manager.py ` ):
49+
4450- Central registry and lifecycle manager for personas
4551- Loads personas from both Python entry points and local ` .jupyter/personas/ ` directory
4652- Routes messages to appropriate personas based on @-mentions and chat context
4753- Handles multi-user vs single-user chat scenarios differently
4854
4955** Persona Discovery** :
56+
5057- Entry points: Uses ` jupyter_ai.personas ` entry point group for installed packages
5158- Local loading: Scans ` .jupyter/personas/ ` for Python files containing "persona" in filename
5259- Supports ` /refresh-personas ` command for development iteration
5360
5461### Extension Structure
5562
5663** Frontend** (` src/ ` ):
64+
5765- TypeScript JupyterLab extension
5866- Minimal frontend - most logic is server-side
5967- Registers server extension and handles activation
6068
6169** Server Extension** (` jupyter_ai_persona_manager/ ` ):
70+
6271- Python server extension that integrates with JupyterLab Chat
6372- Manages persona instances per chat room
6473- Handles message routing and persona lifecycle
6574
6675### Key Integration Points
6776
68- ** Chat Integration** :
77+ ** Chat Integration** :
78+
6979- Integrates with ` jupyterlab_chat ` for message handling
7080- Uses ` YChat ` (Yjs-based collaborative chat) for real-time messaging
7181- Persona awareness uses pycrdt for collaborative state management
7282
7383** File System Access** :
84+
7485- Personas can access workspace directory and .jupyter directory
7586- File attachment processing with multiple resolution strategies
7687- Integration with ` jupyter_server_fileid ` for file ID management
7788
7889** Entry Point System** :
90+
7991- Personas registered via ` [project.entry-points."jupyter_ai.personas"] ` in pyproject.toml
8092- Automatic discovery and loading of persona classes from installed packages
8193
8294### Development Patterns
8395
8496** Persona Development** :
97+
8598- Inherit from ` BasePersona ` and implement ` defaults ` property and ` process_message() ` method
8699- Use ` self.send_message() ` or ` self.stream_message() ` for responses
87100- Access file attachments via ` self.process_attachments(message) `
88101- Use ` self.awareness ` for collaborative state (typing indicators, etc.)
89102
90103** Local Development** :
104+
91105- Place persona files in ` .jupyter/personas/ ` directory
92106- Use ` /refresh-personas ` command to reload without server restart
93107- Files must contain "persona" in name and not start with ` _ ` or ` . `
94108
95109### Configuration
96110
97111** Traitlets Configuration** :
112+
98113- ` PersonaManager.default_persona_id ` - Sets which persona responds in single-user chats
99114- Inherits JupyterLab's configurable system via ` LoggingConfigurable `
100115
101116** Code Style** :
117+
102118- TypeScript: ESLint + Prettier with interface naming convention (must start with 'I')
103119- Python: Standard conventions with pytest for testing
104- - Single quotes preferred, no trailing commas in TypeScript
120+ - Single quotes preferred, no trailing commas in TypeScript
0 commit comments