An intelligent, AI-powered job application automation system built with Stagehand and Google Gemini. This system can automatically navigate job sites, fill application forms, upload resumes, and submit applications with comprehensive reporting and analytics.

• 🚀 Features
• 📋 Prerequisites
• 🔧 Installation
• ⚙️ Configuration
• 🏃‍♂️ Usage
• 📊 Reports and Analytics
• 🏗️ Project Structure
• 🎯 How It Works
• 🔍 Testing and Demo
• 🛠️ Advanced Configuration
• 🤝 Contributing
• 🔒 Security Policy
• 📝 License
• 🚨 Important Notes
• 📞 Support

• Intelligent Page Detection - AI-powered analysis of job sites and application forms
• Multi-Site Support - Works across different job platforms and company career pages
• Smart Form Filling - Contextual field analysis and intelligent data entry
• Resume Upload - Automated file upload with multiple fallback strategies
• Error Recovery - Robust error handling with retry logic and screenshot debugging
• Multi-Language Support - Handles job sites in different languages

• Real-time Progress Tracking - Live updates during job processing
• Comprehensive Analytics - Success rates, processing times, and error analysis
• Professional Markdown Reports - Detailed reports with statistics and recommendations
• Screenshot Documentation - Visual debugging with automatic screenshot capture
• Error Pattern Analysis - Identifies common failure modes for optimization

• Robust Error Handling - Multiple retry strategies and graceful degradation
• Form Validation - Pre-submission checks to prevent failures
• Rate Limiting - Respectful automation with appropriate delays
• Session Management - Handles authentication and session persistence

• Node.js (v16 or higher)
• Google API Key (for Gemini AI model)
• Resume file (PDF format recommended)

1. Clone the repository

   git clone https://github.com/classyrazy/brown-envelope.git
   cd brown-envelope

2. Install dependencies

   yarn

3. Environment setup Copy the example environment file and configure:

   cp .env.example .env

4. Configure your environment variables (see Configuration section below)

Create a .env file with the following variables:

# Google AI API Key (Required)
GOOGLE_API_KEY=your_google_api_key_here

# Personal Information
APPLICANT_FIRST_NAME=John
APPLICANT_LAST_NAME=Doe
APPLICANT_EMAIL=john.doe@example.com
APPLICANT_PHONE=+1234567890
APPLICANT_COUNTRY_CODE=+1
APPLICANT_PHONE_WITHOUT_COUNTRY_CODE=234567890
APPLICANT_COUNTRY=United States
APPLICANT_CITY=New York

# Professional Information
APPLICANT_LINKEDIN=https://linkedin.com/in/johndoe
APPLICANT_PORTFOLIO_URL=https://yourportfolio.com
APPLICANT_GITHUB_URL=https://github.com/yourusername
APPLICANT_EXPERIENCE_LEVEL=Mid-level
APPLICANT_EDUCATION_LEVEL=Bachelor's Degree
APPLICANT_COURSE_OF_STUDY=Computer Science
APPLICANT_SKILLS=JavaScript,TypeScript,React,Node.js
APPLICANT_SALARY_RANGE=$60,000 - $80,000

# File Paths
RESUME_PATH=/path/to/your/resume.pdf

# Optional Authentication
DEFAULT_PASSWORD=YourDefaultPassword123!
LINKEDIN_PASSWORD=YourLinkedInPassword123!

1. Go to Google AI Studio
2. Create a new API key
3. Copy the key to your .env file

Run the job application process:

yarn start

Test the resume upload functionality:

# Uncomment the test function in index.ts and run:
yarn start

Edit the jobs.ts file to add your target job listings:

export const AvailableJobs: Job[] = [
  {
    job_title: "Frontend Developer",
    company_name: "Tech Company",
    job_url: "https://company.com/careers/frontend-developer"
  },
  // Add more jobs...
];

The system generates comprehensive reports after each run:

• Reports are saved in ./reports/ directory
• Screenshots are saved in ./screenshots/ directory
• Each report includes timestamp for easy tracking

• Summary Statistics - Success rates, processing times, error counts
• Detailed Job Results - Individual job processing outcomes
• Error Analysis - Common failure patterns and recommendations
• Visual Documentation - Screenshots of key moments and errors

# Job Application Report

## Summary
- Total Jobs Processed: 50
- Successful Applications: 32
- Success Rate: 64%
- Total Processing Time: 1h 45m

## Detailed Results
[Table with individual job results]

## Recommendations
[AI-generated insights for improvement]

job-applier-stagehand/
├── agent/
│   ├── applier/
│   │   ├── applier.ts          # Main automation logic
│   │   └── rules.ts            # AI prompts and rules
│   └── types.ts                # TypeScript interfaces
├── utils/
│   ├── index.ts                # Personal information utilities
│   └── reporter.ts             # Reporting system
├── reports/                    # Generated reports
├── screenshots/                # Debug screenshots
├── jobs.ts                     # Job listings to process
├── index.ts                    # Main entry point
└── README.md                   # This file

The system uses AI to analyze each page and determine:

• Page type (job detail, application form, sign-in, etc.)
• Required actions and form fields
• Error conditions and recovery strategies

• Analyzes form fields contextually
• Maps personal information to appropriate fields
• Handles different field types (text, dropdowns, checkboxes)
• Skips irrelevant or risky fields

• Multiple upload strategies with fallbacks
• Intelligent file input detection
• Error recovery and retry logic

• Pre-submission validation
• Form error detection and correction
• Success verification with multiple indicators

• Real-time progress tracking
• Comprehensive result documentation
• Error pattern analysis
• Performance metrics

The system has been tested on various job platforms including:

• ✅ Company career pages
• ✅ Job board applications
• ✅ Multi-step application forms
• ✅ File upload scenarios
• ✅ Authentication flows

📹 Watch Demo Video Link to Google Drive video demonstration

Extend the field mapping logic in applier.ts to handle specific form fields:

const fieldMappings = [
  {
    keywords: ['custom field', 'special input'],
    value: 'your custom value',
    label: 'Custom Field',
    instruction: 'Fill custom field with specific data'
  }
];

Add custom page detection rules in rules.ts:

export const customPageRules = `
  Analyze this page for custom scenarios:
  - Custom company application flow
  - Specific form requirements
  - Special authentication methods
`;

1. Update AI Rules: Modify extractJobDetailRules in rules.ts
2. Add Handler: Create new case in handlePageType() switch statement
3. Implement Logic: Add new handler method for the page type

private async handleCustomPageType(job: Job): Promise<void> {
  console.log('🎯 Handling custom page type');
  // Your custom logic here
}

Extend the fillApplicationForm() method for specific form requirements:

private async fillCustomFields(job: Job): Promise<void> {
  await this.page.act(`Fill in the "Why do you want this job?" field with a compelling reason`);
  await this.page.act(`Select "Senior" from the experience level dropdown`);
  await this.page.act(`Check the "Remote work" checkbox if available`);
}

The system supports resume uploads via RESUME_PATH. Extend for additional files:

private async uploadCoverLetter(): Promise<void> {
  const coverLetterPath = process.env.COVER_LETTER_PATH;
  if (coverLetterPath) {
    await this.page.act(`Upload "${coverLetterPath}" to the cover letter field`);
  }
}

private async uploadPortfolio(): Promise<void> {
  const portfolioPath = process.env.PORTFOLIO_PATH;
  if (portfolioPath) {
    await this.page.act(`Upload portfolio file from "${portfolioPath}"`);
  }
}

Add custom environment variables to .env:

# Custom Configuration
CUSTOM_FIELD_VALUE=Your custom response
COVER_LETTER_PATH=/path/to/cover-letter.pdf
PORTFOLIO_PATH=/path/to/portfolio.pdf
APPLICATION_DELAY_MS=3000
MAX_RETRIES=3
ENABLE_SCREENSHOTS=true
ENABLE_VERBOSE_LOGGING=true

The system automatically captures screenshots for:

// Screenshot naming convention
- `application_form_${companyName}.png` - Application forms
- `error_${companyName}_${timestamp}.png` - Error states
- `unknown_page_${companyName}.png` - Unrecognized pages
- `job_not_found_${companyName}.png` - Missing job listings
- `success_${companyName}.png` - Successful submissions

Enable comprehensive logging in your environment:

# Logging Configuration
LOG_LEVEL=debug
ENABLE_CONSOLE_LOGS=true
ENABLE_FILE_LOGS=true
LOG_DIRECTORY=./logs

Console log examples:

🔄 Processing job: Frontend Developer at TechCorp
📍 Navigating to: https://techcorp.com/careers/frontend-dev
🔍 Page analysis: Application form detected
✅ Form filled successfully
📤 Application submitted
⏱️  Processing time: 45 seconds

Monitor live browser activity during automation:

# Browser session URL provided in console
Watch live: https://browserbase.com/sessions/[session-id]

Track performance metrics:

interface PerformanceMetrics {
  totalJobs: number;
  successfulApplications: number;
  successRate: number;
  averageProcessingTime: number;
  errorRate: number;
  commonErrors: string[];
}

The system implements multiple error handling approaches:

// Automatic retries with exponential backoff
const retryDelays = [1000, 2000, 4000, 8000]; // milliseconds

// Graceful fallback and detailed logging
try {
  await this.page.click('submit-button');
} catch (error) {
  console.log('❌ Submit button not found, trying alternative selectors');
  await this.tryAlternativeSubmission();
}

// Retry with manual intervention points
if (authFailed) {
  await this.page.screenshot({ path: 'auth_failure.png' });
  console.log('🔐 Authentication failed - manual intervention may be required');
}

// Pre-submission validation
const validationErrors = await this.validateForm();
if (validationErrors.length > 0) {
  console.log('⚠️ Form validation issues detected:', validationErrors);
  await this.fixValidationErrors(validationErrors);
}

// Example: Send results to CRM
async function updateCRM(applicationResult: ApplicationResult): Promise<void> {
  await fetch('https://your-crm.com/api/applications', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(applicationResult)
  });
}

// Example: Slack notifications
async function sendSlackNotification(message: string): Promise<void> {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: message })
  });
}

# Run specific tests
npm test -- --testNamePattern="form filling"
npm test -- --testNamePattern="file upload"
npm test -- --testNamePattern="error handling"

describe('Job Application Flow', () => {
  it('should complete full application process', async () => {
    const result = await jobAgent.processJob(testJob);
    expect(result.success).toBe(true);
    expect(result.applicationSubmitted).toBe(true);
  });
});

# Test with real job sites (be respectful of rate limits)
npm run test:e2e

• Rate Limiting: System includes appropriate delays between requests
• Terms Compliance: Always review and comply with job site terms of service
• Human Review: Review applications before final submission when possible
• Quality Control: Ensure application quality and relevance

• Targeted Applications: Apply only to relevant positions
• Personal Touch: Customize applications when possible
• Professional Conduct: Maintain professional standards in all interactions
• Transparency: Be honest about your qualifications and experience

• JavaScript-Heavy Sites: Some dynamic sites may need manual intervention
• CAPTCHA Challenges: Cannot automatically solve CAPTCHA verification
• Complex Workflows: Multi-page flows may require customization
• File Format Support: Optimized for common formats (PDF, DOC, DOCX)
• Browser Detection: Some sites may detect automation

• Manual Checkpoints: System allows for manual intervention points
• Screenshot Analysis: Visual debugging helps identify issues
• Fallback Strategies: Multiple approaches for critical operations
• Error Recovery: Robust error handling with continuation options

• Environment Variables: All personal data stored in .env file
• No Hardcoded Secrets: API keys and passwords secured properly
• Local Storage: All data processing happens locally
• Session Security: Browser sessions properly managed and cleaned

• Minimal Data Retention: Reports and screenshots cleaned regularly
• Secure Transmission: HTTPS for all external communications
• Access Control: Secure API key management
• Audit Trail: Comprehensive logging for security monitoring

• Website Terms: Respect robots.txt and terms of service
• Data Privacy: Comply with GDPR, CCPA, and local privacy laws
• Professional Ethics: Maintain honesty in applications
• Rate Limits: Respect website rate limiting and anti-bot measures

This tool is for educational and personal use. Users are responsible for:

• Compliance with website terms of service
• Accuracy of application information
• Professional and ethical use of automation
• Understanding local laws and regulations

# Node.js version conflicts
nvm use 18  # or latest LTS

# Dependency conflicts
rm -rf node_modules package-lock.json
npm install

# Environment variables
cp .env.example .env
# Then configure all required variables

• Page Loading: Increase timeout values for slow sites
• Form Detection: Check screenshot outputs for debugging
• File Upload: Verify file paths and permissions
• Authentication: Update credentials and check for 2FA requirements

• Parallel Processing: Limit concurrent applications to avoid rate limiting
• Memory Management: Monitor memory usage for long-running sessions
• Error Recovery: Review error patterns in reports for optimization
• Network Stability: Ensure stable internet connection for best results

• Setup Guide: Complete installation and configuration instructions above
• API Reference: Technical documentation in /docs/ directory
• Examples: Sample configurations and use cases
• FAQ: Common questions and solutions

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share experiences
• Code Review: Submit PRs for community review
• Best Practices: Share tips and optimization strategies

For enterprise use or complex customization needs:

• Custom implementation services
• Integration with existing systems
• Compliance and security consulting
• Training and onboarding

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: [security@yourproject.com]
• General: [contact@yourproject.com]

• Bug Reports: Within 48 hours
• Feature Requests: Within 1 week
• Security Issues: Within 24 hours
• General Questions: Within 3-5 business days

• Stagehand - Browser automation framework
• Google Gemini - AI model for intelligent automation
• Playwright - Browser control and automation
• TypeScript - Type-safe development

• Open source automation community
• Job seekers sharing their challenges
• Contributors and beta testers
• Stagehand and Playwright communities

⚠️ Important Disclaimer: This tool is designed for educational and personal use to assist job seekers. Always respect website terms of service, maintain professional standards, and use responsibly. The authors are not responsible for any misuse of this software or violations of third-party terms of service.

Made with ❤️ for job seekers everywhere

We welcome contributions! Please see our detailed contribution guidelines below.

1. Fork and Clone

   git clone https://github.com/YOUR_USERNAME/job-applier-stagehand.git
   cd job-applier-stagehand

2. Install Dependencies

   npm install

3. Environment Setup

   cp .env.example .env
   # Configure your environment variables

4. Development Commands

   # Development mode with auto-reload
   npm run dev
   
   # Production build
   npm run build
   
   # Run tests
   npm test
   
   # Type checking
   npm run type-check

// Good: Clear interfaces and error handling
interface JobApplication {
  company: string;
  position: string;
  status: ApplicationStatus;
}

async function fillJobForm(page: Page, jobData: JobApplication): Promise<boolean> {
  try {
    // Implementation with proper error handling
    return true;
  } catch (error) {
    logger.error('Form filling failed:', error);
    return false;
  }
}

• Unit tests for utility functions
• Integration tests for automation flows
• End-to-end tests for complete workflows

1. Before Submitting

   • Ensure all tests pass
   • Update documentation if needed
   • Follow code style guidelines
   • Write descriptive commit messages

2. PR Requirements

   • Clear description of changes
   • Type of change (bug fix, feature, docs, etc.)
   • Testing completed
   • Documentation updated

• Job Site Support: Add support for new job platforms
• Form Analysis: Improve AI-powered form detection
• Error Handling: Enhance error recovery mechanisms
• Reporting: Add new report formats or analytics
• Testing: Improve test coverage
• Documentation: Enhance docs and examples

Please do not report security vulnerabilities through public GitHub issues.

For security issues, please email: [security@yourproject.com]

Include:

• Type of issue
• Location of affected source code
• Step-by-step reproduction instructions
• Potential impact assessment

1. Environment Security

   # Use strong, unique API keys
   GOOGLE_AI_API_KEY=your_secure_api_key_here
   
   # Never commit .env files
   echo ".env" >> .gitignore

2. System Security

   • Keep Node.js and dependencies updated
   • Use dedicated user account for automation
   • Run in isolated containers when possible

1. Dependency Management

   # Regular security audits
   npm audit
   npm audit fix
   
   # Keep dependencies updated
   npm update

2. Input Validation

   function validateJobData(data: unknown): JobData {
     if (!isValidJobData(data)) {
       throw new ValidationError('Invalid job data');
     }
     return data;
   }

• Fingerprinting: Automated browsers can be detected
• Rate limiting: Excessive requests may trigger anti-bot measures
• Account security: Using saved credentials poses risks
• Session persistence: Browser sessions should be properly cleaned

• Human-like behavior: Realistic delays and interactions
• Session management: Fresh sessions for each application
• Credential rotation: Regular credential updates
• Monitoring: Comprehensive logging and alerting

• Personal Information: Handle personal data with care and minimal retention
• File Uploads: Validate file types and sizes before processing
• Logging: Avoid logging sensitive information in plain text
• Storage: Use secure storage and encryption for sensitive data

This project aims to comply with:

• GDPR: European data protection regulations
• CCPA: California Consumer Privacy Act
• Industry Standards: OWASP security guidelines

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 Job Application Automation Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

• Stagehand: MIT License (BrowserBase Inc.)
• Google Generative AI: Apache 2.0 (Google LLC)
• See package.json for complete dependency list

1. Commercial Use: This software can be used commercially under MIT terms
2. Attribution: Attribution appreciated for commercial use
3. Liability: Software provided "as is" without warranty
4. API Compliance: Users responsible for third-party service compliance

• Stagehand - Browser automation framework
• Google Gemini - AI model for intelligent automation
• Playwright - Browser control and automation
• TypeScript - Type-safe development

• Open source automation community
• Job seekers sharing their challenges
• Contributors and beta testers
• Stagehand and Playwright communities

• Initial release of Job Application Automation system
• Stagehand browser automation integration with Google Gemini AI
• Intelligent form detection and filling capabilities
• Multi-strategy file upload system with 6 fallback approaches
• Comprehensive error handling and recovery mechanisms
• Detailed markdown report generation with analytics
• Support for multiple job sites and international platforms
• Environment-based configuration for security
• TypeScript implementation with full type safety
• Professional documentation suite

• AI-Powered Analysis: Uses Google Gemini 2.5-flash for page analysis
• Smart Form Filling: Intelligent field detection and data mapping
• Robust File Upload: Multiple strategies for resume/cover letter uploads
• Error Recovery: Comprehensive error handling with retry mechanisms
• Progress Tracking: Real-time progress updates and statistics
• Report Generation: Detailed markdown reports with analytics
• Multi-Site Support: Works across various job platforms
• Security First: Environment-based personal information management

• TypeScript for type safety and better development experience
• Stagehand framework for browser automation
• Google Gemini AI for intelligent page interaction
• Comprehensive logging and debugging capabilities
• Modular architecture for easy extension
• Professional error handling and validation