diff --git a/agent.md b/agent.md
new file mode 100644
index 0000000..77fff93
--- /dev/null
+++ b/agent.md
@@ -0,0 +1,122 @@
+# YouTube CLI Agent
+
+## Project Overview
+This is a command-line interface for browsing and downloading YouTube videos. The application allows users to search YouTube, display videos in pages of 15, and download videos using yt-dlp with progress indication.
+
+## Core Features
+- **Search YouTube videos** with keyword queries
+- **Display videos** with title, author, duration, and type (short/video)
+- **Download videos** using yt-dlp with progress indication
+- **Configure download locations** through configuration files
+- **Handle short videos** (videos with /shorts/ in URL) with special "(short)" prefix
+- **Pagination support** to view more than 15 videos per search
+- **Network share integration** for copying downloaded videos
+
+## Project Structure
+```
+youtube-cli/
+├── youtube_cli/                 # Main package directory
+│   ├── __init__.py             # Package initialization
+│   ├── __main__.py             # Main entry point
+│   └── main.py                 # Core application logic
+├── setup.py                    # Python package setup
+├── requirements.txt            # Python dependencies
+├── README.md                   # Project documentation
+├── prompt.md                   # Prompt template
+├── structure.md                # Project structure documentation
+└── run.sh                      # Run script
+```
+
+## Main Components
+
+### youtube_cli/main.py
+The core application logic file containing:
+- `YouTubeCLI` class with all main functionality
+- Search videos using yt-dlp with pagination support
+- Display videos in formatted tables with Rich library
+- Download videos with progress indication
+- Configuration management
+- Archive tracking for downloaded videos
+- Network share copying functionality
+- Update checking for yt-dlp
+
+### Key Methods in YouTubeCLI Class
+- `search_videos()`: Search YouTube videos using yt-dlp
+- `display_videos()`: Display videos in a formatted table
+- `download_video()`: Download individual videos with progress
+- `download_playlist()`: Download YouTube playlists
+- `load_config()`: Load configuration from file or use defaults
+- `load_archive()`: Load archive of already downloaded videos
+- `add_to_archive()`: Add videos to download archive
+- `copy_to_network_share()`: Copy downloaded videos to network share
+- `check_for_updates()`: Check and update yt-dlp if needed
+
+## Configuration
+The application creates a default configuration file at `~/.config/youtube_cli/config.json` if one doesn't exist. Configuration includes:
+- `download_dir`: Default download directory (set to `/Volumes/MediaServer/Youtube/`)
+- `default_locations`: List of default download locations including Tech, AI, Art, Homes, Cooking, Fitness, Music, Gaming, Education, Travel, Business, Science, History, Comedy, News, Sports, Nature, Photography, Language, and Automotive categories
+- `max_videos_per_page`: Number of videos per page (default: 15)
+- `yt_dlp_args`: Custom yt-dlp arguments for video format and extraction
+- `network_share_path`: Network share path for copying videos
+- `default_network_subfolder`: Default subfolder on network share
+
+## Usage Examples
+```bash
+# Search for videos
+youtube-cli "python tutorial"
+
+# Download a specific video
+youtube-cli --download "https://www.youtube.com/watch?v=xyz123"
+
+# View help
+youtube-cli --help
+
+# Check for yt-dlp updates
+youtube-cli --check-update
+
+# Update yt-dlp
+youtube-cli --update
+```
+
+## Dependencies
+- Python 3.6+
+- yt-dlp (for video downloading)
+- rich (for formatted console output)
+- requests (for API calls)
+
+## Installation
+### From Source
+```bash
+git clone https://github.com/yourusername/youtube-cli.git
+cd youtube-cli
+pip install -e .
+```
+
+### Using pip
+```bash
+pip install youtube-cli
+```
+
+## How It Works
+1. **Search**: Users enter a search query to find YouTube videos
+2. **Display**: Videos are shown 15 at a time with title, author, duration, and type
+3. **Navigation**: Users can go to next page (n), search for new term (s), or quit (q)
+4. **Selection**: Users can select videos by number to download
+5. **Download**: Videos are downloaded using yt-dlp with progress indication
+6. **Tracking**: Downloaded videos are tracked in an archive file
+
+## Special Features
+- **Short Video Detection**: Automatically detects and marks short videos with "(short)" prefix
+- **Pagination**: View 15 videos at a time with option for more
+- **Multiple Download Locations**: Choose from default locations or specify custom paths
+- **Network Share Integration**: Copy downloaded videos to network shares after download
+- **Update Checking**: Automatically checks for and updates yt-dlp when needed
+- **Archive Tracking**: Keeps track of already downloaded videos to avoid duplicates
+
+## Technical Details
+- Uses yt-dlp for all YouTube operations
+- Implements Rich library for beautiful console output
+- Supports both individual video and playlist downloads
+- Handles JavaScript challenges with remote components
+- Includes retry mechanisms for downloads
+- Cross-platform compatibility (macOS and Linux)
\ No newline at end of file