Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (115 loc) · 5.45 KB

CLAUDE.md

File metadata and controls

139 lines (115 loc) · 5.45 KB

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

This is a Claude Code plugin called "pearpass-plugin" that helps developers work with PearPass Desktop - a secure, distributed password manager built with React Native, Expo, and end-to-end encryption using sodium-native (libsodium).

Repository Structure

pearpass-plugin/
├── plugin.json              # Plugin manifest
├── .claude-plugin/
│   └── marketplace.json     # Marketplace definition for installation
├── skills/                  # 5 skills for development guidance
│   ├── pearpass-dev.md      # Development workflow
│   ├── pearpass-security.md # Security review patterns
│   ├── pearpass-architecture.md # Codebase architecture
│   ├── pearpass-test.md     # Testing patterns
│   └── pearpass-pear.md     # Pear Runtime specifics
├── commands/                # 6 slash commands
│   ├── pearpass-dev.md      # Start development server
│   ├── pearpass-build.md    # Build for iOS/Android
│   ├── pearpass-test.md     # Run test suites
│   ├── pearpass-lint.md     # Code linting
│   ├── pearpass-i18n.md     # Internationalization
│   └── pearpass-security-audit.md # Security checks
├── agents/                  # 4 specialized agents
│   ├── security-reviewer.md # Audit encryption and security
│   ├── code-explorer.md     # Navigate codebase architecture
│   ├── component-dev.md     # React component development
│   └── test-generator.md    # Generate tests
├── hooks/                   # 4 automated hooks
│   ├── security-crypto-warning.md  # Warn on crypto file edits
│   ├── security-secrets-check.md   # Check for hardcoded secrets
│   ├── quality-i18n-reminder.md    # i18n reminders
│   └── quality-test-reminder.md    # Test coverage reminders
└── docs/                    # Development documentation
    ├── RESEARCH.md          # Codebase analysis
    ├── PLAN.md              # Implementation plan
    └── NEXT_STEPS.md        # Roadmap and testing status

Plugin Architecture

Skills

Skills are context-loading documents that Claude uses to assist with specific topics:

  • Triggered by natural language matching the description field
  • Provide comprehensive guidance without executing code
  • Each skill has YAML frontmatter with a description

Commands

Slash commands for specific actions:

  • /pearpass-dev - Start development server
  • /pearpass-build - Build for platforms
  • /pearpass-test - Run test suites
  • /pearpass-lint - Lint code
  • /pearpass-i18n - Manage translations
  • /pearpass-security-audit - Run security checks

Agents

Specialized subagents for complex tasks:

  • security-reviewer - Uses Glob, Grep, Read to audit security
  • code-explorer - Deep codebase exploration
  • component-dev - React/styled-components development
  • test-generator - Generate Jest and Maestro tests

Hooks

Automatic warnings triggered during development:

  • security-crypto-warning - PreToolUse on crypto files
  • security-secrets-check - PreToolUse on git commits
  • quality-i18n-reminder - PostToolUse on UI components
  • quality-test-reminder - PostToolUse on new components

PearPass Quick Reference

Technology Stack

Technology Version Purpose
React Native 0.79.5 Mobile framework
Expo ~53.0.17 Development platform
sodium-native 5.0.9 libsodium crypto
styled-components 6.1.19 CSS-in-JS
Lingui 5.3.3 i18n
Jest 29.7.0 Unit testing
Maestro - E2E testing

Security Architecture

  1. Master Password → Argon2id → Derived key
  2. Vault Key → XSalsa20-Poly1305 → Encrypted credentials
  3. Worklet isolation → Crypto in separate thread
  4. SecureStore → iOS Keychain / Android Keystore
  5. Biometrics → expo-local-authentication

Key Directories in PearPass

Directory Purpose
src/components/ UI components
src/hooks/ Custom React hooks
src/context/ React Context providers
packages/pearpass-lib-vault-core/ Encryption worklet

Installation Commands

# Install from GitHub
claude plugins add https://github.com/grandcamel/pearpass-plugin

Key Gotchas

  1. plugin.json format: Skills/commands/agents/hooks use explicit file path arrays
  2. Skill frontmatter: Must have description field for trigger matching
  3. Command frontmatter: Must have description and optionally arguments
  4. Agent frontmatter: Must have description and tools fields
  5. Hook frontmatter: Must have event, tools, and optionally match_files

Security Guidelines

When contributing to this plugin:

DO

  • Use sodium_malloc patterns in examples
  • Reference OPSLIMIT_SENSITIVE for password hashing
  • Show randombytes_buf for nonce generation
  • Include authentication checks in crypto examples

DON'T

  • Include actual secrets or credentials in examples
  • Show insecure patterns without clear warnings
  • Use Buffer.alloc for sensitive data in examples

Development Notes

  • The docs/ folder contains research and planning documents
  • All skills focus on guidance specific to PearPass patterns
  • Agents are designed for PearPass's React Native + Expo + sodium-native stack
  • Hooks target common security and quality issues in password manager development