Coding

CLAUDE.md

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

promptBeginner5 min to valuemarkdown

0 views

Jan 15, 2026

Sign in to like and favorite skills

View Original Source

Share:

Related Skills

PromptBeginner5 minmarkdown

Markdown Converter

Agent skill for markdown-converter

PromptBeginner5 minmarkdown

Nano Banana Pro

Agent skill for nano-banana-pro

PromptBeginner5 minmarkdown

1password

Agent skill for 1password

CLAUDE.md

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

Project Overview

Bookmark Organizer is a Python tool for reorganizing and categorizing Chrome bookmarks. It can parse exported bookmark HTML files, check URL accessibility, use AI for intelligent categorization, and generate a new categorized bookmark file.

Key Features

Parse Chrome bookmark HTML files
Check URL accessibility (concurrent processing)
AI-powered intelligent classification
Generate reorganized HTML bookmark files
Caching mechanism for performance

Quick Start

Installation

# Install in development mode
pip install -e ".[dev]"

# Or using uv
uv sync --dev

Basic Usage

# Parse and organize bookmarks
python -m bookmark_organizer --input bookmarks.html --output organized.html

# Enable AI classification (requires .env configuration)
cp .env.example .env
# Edit .env with your OPENAI_API_KEY

# Use caching for faster re-runs
python -m bookmark_organizer --cache bookmarks_cache.json

Common Development Commands

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_models.py

# Run with coverage
python -m pytest tests/ --cov=src/bookmark_organizer --cov-report=html

# Run tests in verbose mode
python -m pytest tests/ -v

# Run specific test
python -m pytest tests/test_models.py::TestBookmarkItem::test_init_basic

Code Quality

# Lint and format code
ruff check .
ruff format .

# Type checking
mypy src/

# All quality checks
ruff check . && ruff format . && mypy src/

Environment Setup

# Copy environment variables template
cp .env.example .env

# Check current configuration
python examples/env_usage_example.py

CLI Usage

# Show help
python -m bookmark_organizer --help

# Check version
python -m bookmark_organizer --version

# Run with different configurations
python -m bookmark_organizer --verbose
python -m bookmark_organizer --max-workers 20
python -m bookmark_organizer --request-timeout 15

Architecture Overview

Core Modules

The project follows a pipeline architecture with clearly separated responsibilities:

src/bookmark_organizer/parser.py

Parses Chrome's HTML bookmark exports
Extracts bookmark metadata (URL, title, add_date, icon)
Filters out invalid URLs and empty titles

src/bookmark_organizer/checker.py

Checks URL accessibility using HEAD/GET requests
Concurrent processing using ThreadPoolExecutor
Extracts content preview (meta description or page text)
Handles timeouts and various HTTP status codes

3. Classifier (

src/bookmark_organizer/classifier.py

Two classification modes:
- AI-powered: Uses OpenAI-compatible APIs for intelligent categorization
- Simple: Keyword-based rules for basic categorization
Batch processing with configurable batch size
Supports multiple AI providers (DeepSeek, OpenAI, Moonshot, etc.)

src/bookmark_organizer/generator.py

Generates Chrome-compatible HTML bookmark files
Organizes bookmarks by category
Separates accessible and failed URLs
Escapes HTML special characters

src/bookmark_organizer/models.py

BookmarkItem: Core data model with validation (Pydantic)
ParsedBookmarks: Container for parsed bookmark collections
ProcessingStats: Statistics and metrics collection
All models use Pydantic for type validation and JSON serialization

src/bookmark_organizer/config.py

Centralized configuration using Pydantic BaseModel
Auto-loads
```
.env
```
files using python-dotenv
Environment variable support with
```
BOOKMARK_ORGANIZER_*
```
prefix
Default values with validation

src/bookmark_organizer/cli.py

Click-based command-line interface
Supports input/output file paths, caching, performance tuning
Export/import cache functionality
Verbose/silent modes

Data Flow

HTML Input → Parser → [Bookmarks] → Checker → [Bookmarks + Status] → Classifier → [Bookmarks + Category] → Generator → HTML Output
                ↓
            [Cache] ←───────────────────────────────────────────────┘

Key Configuration

Environment Variables

```
OPENAI_API_KEY
```
: Required for AI classification
```
OPENAI_BASE_URL
```
: API base URL (default: https://api.deepseek.com/v1)
```
AI_MODEL
```
: Model name (default: deepseek-chat)
```
BOOKMARK_ORGANIZER_MAX_WORKERS
```
: Concurrent threads (default: 10)
```
BOOKMARK_ORGANIZER_REQUEST_TIMEOUT
```
: HTTP timeout in seconds (default: 10)
```
BOOKMARK_ORGANIZER_BATCH_SIZE
```
: AI batch size (default: 20)

See

.env.example

for complete configuration template.

Testing Structure

Test Organization

test_models.py: Model validation and serialization tests
test_parser.py: HTML parsing tests with fixtures
test_checker.py: HTTP request mocking with pytest-mock
test_classifier.py: AI classification tests with mocked API
test_generator.py: HTML generation and formatting tests
test_config.py: Configuration loading and validation tests
test_integration.py: End-to-end workflow tests
conftest.py: Shared fixtures and path configuration

Test Configuration

Uses pytest with coverage plugin
MyPy strict mode for type checking
Ruff for linting and formatting
Pre-commit hooks for quality gates

Important Files

pyproject.toml: Project configuration, dependencies, and tool settings
.pre-commit-config.yaml: Pre-commit hooks for code quality
.env.example: Environment variables template
README.md: User documentation and quick start
CONTRIBUTING.md: Contribution guidelines
TESTING_GUIDE.md: Comprehensive testing documentation
ENV_SETUP_GUIDE.md: Environment configuration guide

Development Notes

Type Annotations

100% type coverage with strict MyPy configuration
Uses Python 3.9+ built-in generic types (
```
list
```
,
```
dict
```
instead of
```
List
```
,
```
Dict
```
)
Pydantic models for runtime type validation

Error Handling

Try-catch blocks for network operations
Graceful degradation: falls back to simple classification if AI fails
Detailed logging at appropriate levels (DEBUG, INFO, WARNING, ERROR)

Concurrency

ThreadPoolExecutor for concurrent URL checking
Configurable worker count
Batch processing for AI classification to respect rate limits

Caching

JSON-based cache for check results
Includes URL status, content preview, and classification
Export/import functionality for sharing results

Common Patterns

Adding a New Test

def test_new_feature(self) -> None:
    """Test description"""
    # Arrange
    pass

    # Act
    pass

    # Assert
    assert True

Modifying Configuration

# In config.py
class AppConfig(BaseModel):
    new_option: int = Field(default=10, description="Description")

Adding a New Module

Create module in
```
src/bookmark_organizer/
```
Add tests in
```
tests/test_<module>.py
```
Update exports in
```
__init__.py
```
Add CLI options if needed
Update documentation

Troubleshooting

Import Errors

Ensure package is installed:
```
pip install -e .
```
Check
```
conftest.py
```
for path configuration
Verify Python interpreter matches installed environment

Test Failures

Clear pytest cache:
```
python -m pytest --cache-clear
```
Check for network calls in tests (use mocking)
Verify environment variables are set correctly

AI Classification Issues

Verify
```
OPENAI_API_KEY
```
is valid
Check
```
OPENAI_BASE_URL
```
matches your API provider
Monitor rate limits if processing large batches
Review API costs and usage

Performance Considerations

URL Checking: Default 10 workers, increase for faster processing
AI Classification: Batch size of 20 balances speed vs. rate limits
Caching: Always use for repeated runs on same bookmarks
Timeouts: 10 seconds default, adjust for slow networks
Memory: Processes bookmarks in batches, not all at once

Security Notes

Never commit
```
.env
```
file (already in
```
.gitignore
```
)
API keys stored in environment variables only
No sensitive data in code or documentation
HTTPS required for bookmark URLs
Rate limiting respects API provider limits