https://github.com/neverdecel/linky
AI-powered LinkedIn automation agent that intelligently handles recruiter conversations using conversational AI and strategic job matching
https://github.com/neverdecel/linky
ai ai-agent automation career conversational-ai gemini job-search linkedin networking playwright recruiting typescript
Last synced: 3 months ago
JSON representation
AI-powered LinkedIn automation agent that intelligently handles recruiter conversations using conversational AI and strategic job matching
- Host: GitHub
- URL: https://github.com/neverdecel/linky
- Owner: Neverdecel
- License: mit
- Created: 2025-06-26T16:43:42.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-06-27T10:35:16.000Z (3 months ago)
- Last Synced: 2025-06-27T11:40:26.974Z (3 months ago)
- Topics: ai, ai-agent, automation, career, conversational-ai, gemini, job-search, linkedin, networking, playwright, recruiting, typescript
- Language: TypeScript
- Size: 75.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Linky 🤖
> **⚠️ IMPORTANT LEGAL & ETHICAL DISCLAIMER**
>
> **Use at Your Own Risk**: This tool automates LinkedIn interactions and may violate LinkedIn's Terms of Service. Users are solely responsible for ensuring compliance with LinkedIn's policies and applicable laws in their jurisdiction.
>
> **Ethical Use Only**: Linky is designed for intelligent, respectful communication with recruiters - not for spam or deceptive practices. We strongly recommend:
> - ✅ Always test thoroughly in **Safe Mode** before production use
> - ✅ Consider enabling AI disclosure to maintain transparency
> - ✅ Use for genuine job searching and professional networking only
> - ✅ Respect recruiter time with thoughtful, relevant responses
> - ❌ Never use for mass messaging or inappropriate content
>
> **No Warranty**: This software is provided "as-is" without any guarantees. The authors are not responsible for account restrictions, policy violations, or other consequences of use.
>
> **Platform Risk**: LinkedIn actively works to detect and prevent automation. Your account may be restricted or banned for using any automation tools, regardless of their design or intent.An intelligent LinkedIn automation agent powered by Google Gemini AI and built with ADK (Agent Development Kit) design patterns. Linky provides sophisticated multilingual conversation management, strategic recruiter interaction, and intelligent job opportunity analysis tailored to your personal preferences.
## ✨ Features
### Core AI Capabilities
- **AI-Powered Conversations**: Uses Google Gemini with ADK patterns for intelligent, contextual responses
- **ADK Language Detection Agent**: Specialized AI agent with 95%+ accuracy for multilingual detection
- **Strategic Conversation Management**: ADK-powered multi-phase conversation planning and optimization
- **Intelligent Multilingual Support**: Context-aware responses in Dutch, English, and other languages
- **LLM Interaction Logging**: Comprehensive AI interaction tracking for evaluation and improvement### Advanced Conversation Intelligence
- **Recruiter Type Detection**: AI-driven classification of internal vs external recruiters
- **Dynamic Question Generation**: Strategic question sequencing based on conversation goals
- **Multi-turn Conversations**: Persistent context with session management across interactions
- **Salary Negotiation Strategy**: Extract their budget first without revealing your expectations
- **Phone Call Deflection**: Maintain control through strategic written communication preference### Safety & Production Features
- **Three-Tier Safety System**: Safe mode → Debug mode → Production mode progression
- **ADK Callback Patterns**: Execution control and monitoring at critical points
- **Response Tracking**: Prevent duplicate messages with conversation history persistence
- **Prompt Injection Protection**: Input sanitization and output validation
- **Session State Management**: Robust handling of LinkedIn sessions and conversation state
- **Optional AI Disclosure**: Configurable transparency about AI assistance## 🚀 Quick Start
```bash
# 1. Clone the repository
git clone https://github.com/Neverdecel/linky.git
cd linky# 2. Install dependencies
npm install# 3. Set up configuration
cp .env.example .env
cp config/profile.example.yaml config/profile.yaml# 4. Configure your credentials and preferences
# Edit .env and config/profile.yaml# 5. Test in safe mode (no messages sent)
npm run start:safe
```## 📋 Prerequisites
- Node.js 18+
- Google Gemini API key ([Get one here](https://aistudio.google.com/app/apikey))
- LinkedIn account credentials
- Playwright browser automation## 🔧 Configuration
### 1. Environment Variables (`.env`)
```env
# Run mode: safe, debug, production
RUN_MODE=safe# LinkedIn credentials
LINKEDIN_EMAIL=your-email@example.com
LINKEDIN_PASSWORD=your-password# Google Gemini API
GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL=models/gemini-2.0-flash# Logging
LOG_LEVEL=debug
```### 2. Profile Configuration (`config/profile.yaml`)
Customize your job preferences, requirements, and AI assistant persona:```yaml
personal:
name: "Your Name"
current_role: "Software Engineer"
location: "Amsterdam, Netherlands"requirements:
salary:
minimum: 85000
ideal: 95000
currency: EUR
schedule:
days_per_week: 4
hours_per_day: 8
must_have:
- "Modern tech stack"
- "Hybrid work options"
- "Good work-life balance"ai_assistant:
enabled: true
persona: "professional_assistant"
assistant_style:
tone: "professional"
communication_style: "strategic"
behavior:
ask_clarifying_questions: true
negotiate_strategically: true
extract_salary_first: true
```### 3. AI Configuration (`config/ai-config.yaml`)
Advanced AI model and safety settings:```yaml
models:
classification:
primary: "gemini-1.5-flash"
temperature: 0.1
max_tokens: 500
response_generation:
primary: "gemini-1.5-flash"
temperature: 0.7
max_tokens: 800safety:
input_sanitization:
enabled: true
output_validation:
enabled: true
rules:
- no_personal_phone: true
- no_salary_disclosure: true
- professional_tone: true
- max_length: 150quality:
min_confidence_score: 0.6
regenerate_on_low_quality: true
```### 4. System Prompts (`config/system-prompt.yaml`)
Fine-tune the AI's behavior and response style.## 🎯 Usage
### Safe Mode (Recommended for Testing)
```bash
npm run start:safe
```
- ✅ Logs into LinkedIn
- ✅ Reads messages
- ✅ Generates responses
- ❌ Does NOT send messages### Debug Mode
```bash
npm run start:debug
```
- Same as safe mode but with detailed logging### Production Mode ⚠️
```bash
npm run start:prod
```
**WARNING**: This will send actual messages to recruiters!### View Generated Responses
```bash
npm run view:responses
```## 🏗️ How It Works
### ADK-Powered Processing Pipeline
1. **Session Initialization**: LinkedIn session manager establishes persistent connection
2. **Message Scanning**: Intelligent detection of recruiter communications with context
3. **Language Detection**: ADK Language Detection Agent identifies language with 95%+ accuracy
4. **Recruiter Classification**: Multi-phase AI analysis determines recruiter type and intent
5. **Strategic Analysis**: ConversationStrategyAgent plans optimal response approach
6. **Profile Matching**: AI evaluates opportunity fit against your configured preferences
7. **Dynamic Prompting**: Context-aware prompt generation for optimal responses
8. **Response Generation**: LLM creates professional, language-matched responses
9. **Callback Enhancement**: ADK callbacks optimize and validate responses
10. **Safety Validation**: Multi-layer safety checks before any action
11. **State Persistence**: Conversation history and context saved for future interactions
12. **LLM Logging**: All AI interactions logged for evaluation and improvement## 📁 Project Structure
```
linky/
├── src/
│ ├── agents/ # Core automation agents
│ │ ├── linkedin-agent.ts # LinkedIn browser automation
│ │ ├── gemini-client.ts # AI integration with ADK patterns
│ │ ├── language-detection-agent.ts # ADK specialized language detection
│ │ ├── conversation-strategy-agent.ts # Strategic conversation planning
│ │ └── safe-mode-handler.ts # Mode-aware execution control
│ ├── utils/ # Utilities and helpers
│ │ ├── adk-prompt-templates.ts # ADK prompt engineering templates
│ │ ├── linkedin-session-manager.ts # Session state persistence
│ │ ├── yaml-config.ts # Enhanced configuration management
│ │ ├── response-tracker.ts # Conversation history tracking
│ │ └── logger.ts # Winston logging configuration
│ └── types/ # TypeScript definitions
├── config/
│ ├── profile.yaml # Your preferences (git-ignored)
│ ├── profile.example.yaml # Profile configuration template
│ ├── ai-config.yaml # AI model and safety settings
│ └── system-prompt.yaml # AI behavior configuration
├── logs/ # Application and LLM logs
│ └── {session-id}/ # Session-specific logs
│ └── llm-interactions.log # AI conversation history
├── screenshots/ # Debug screenshots
└── data/ # Response history database
```## 🛡️ Security & Safety
- **Input Sanitization**: Protects against prompt injection attacks
- **Gemini Safety Settings**: Uses Google's built-in content filtering
- **Safe Mode Testing**: Test everything before going live
- **Response Tracking**: Prevents duplicate responses to the same recruiter
- **Privacy Protection**: Personal data excluded from repository## 🔍 Advanced Features
### 🧠 ADK Strategic Conversation Management
Powered by Google AI Developer Kit patterns for intelligent conversation optimization:**Multi-Step Strategic Analysis**:
- Analyzes recruiter communication style and behavior patterns
- Identifies conversation phase (initial, information gathering, evaluation, decision)
- Plans optimal question sequencing for maximum information extraction**Goal-Oriented Response Planning**:
- Prioritizes salary and remote work information extraction
- Maintains conversation control through strategic deflection
- Optimizes for negotiation positioning**Conversation State Management**:
- Persistent conversation history across sessions
- Context-aware follow-up responses
- Adaptive communication based on recruiter behavior### AI Disclosure
Configure transparent AI assistance disclosure:
```yaml
ai_disclosure:
enabled: true
message: "✨ AI-assisted response"
```### Phone Call Management
- Automatically deflects phone call requests to LinkedIn messaging
- Maintains professional boundaries while gathering information
- Strategic positioning for written communication advantages### Salary Negotiation Strategy
- Strategically extracts recruiter's budget without revealing yours
- Uses collected information for fit analysis and decision making
- Maintains professional discretion throughout the process### 🌍 ADK Language Detection Agent
Advanced language detection using Google AI Developer Kit patterns for multilingual accuracy:**Tool Specialization Pattern**:
- Dedicated `LanguageDetectionAgent` following ADK best practices
- AI-first approach with sophisticated prompt engineering for professional contexts
- No heuristics or regex patterns - pure AI-driven detection**Multi-Agent Consensus System**:
- Primary detection using optimized language analysis prompts
- Contextual detection focusing on professional/business language patterns
- Consensus algorithm combining results for maximum accuracy**LinkedIn-Optimized Detection**:
- Specialized recognition of recruitment language patterns
- Context-aware analysis for Dutch/English professional communication
- Handling of mixed-language content (company names, technical terms)**Integration & Performance**:
- Language detection occurs **before** response generation (ADK best practice)
- 95%+ accuracy on Dutch and English recruitment messages
- Real-time detection with fallback strategies for reliability**Example Accuracy**:
```
✅ Dutch: "Op dit moment help ik een groeiende consultancy..." → nl (95% confidence)
✅ English: "I'm currently helping a growing consultancy..." → en (99% confidence)
✅ Mixed: "Het salaris range voor deze AI Engineer role..." → nl (90% confidence)
```**Architecture Benefits**:
- **Hierarchical Delegation**: Main agent delegates to specialized language agent
- **Safety-First**: Input sanitization and output validation
- **Evaluation-Driven**: Confidence scoring and reliability metrics
- **Model-Agnostic**: Works across different AI providers## 🏛️ ADK Architecture
### Design Patterns Implementation
The system implements Google ADK's best practices for agent development:
#### 1. **Hierarchical Delegation Pattern**
- `LinkedInAgent` acts as root coordinator
- Delegates specialized tasks to appropriate agents
- Maintains context across agent boundaries#### 2. **Multi-Agent Consensus Pattern**
- Language detection uses multiple analysis phases
- Recruiter classification with confidence scoring
- Response generation with strategic optimization#### 3. **Callback Safety Pattern**
- Pre-execution validation callbacks
- Response enhancement callbacks
- Post-execution monitoring callbacks#### 4. **Tool Specialization Pattern**
- Each agent has minimal, focused capabilities
- LinkedInAgent: Browser automation only
- GeminiClient: AI interactions only
- SafeModeHandler: Execution control only#### 5. **Progressive Enhancement**
- Start with basic automation
- Add AI capabilities incrementally
- Layer safety features progressively
- Deploy with systematic evaluation### Production-Ready Features
- **Session Management**: Persistent state across restarts
- **LLM Logging**: Complete AI interaction history
- **Graceful Degradation**: Fallback strategies at every level
- **Model Agnostic**: Easy to switch AI providers
- **Evaluation Framework**: Built-in performance tracking## 📊 Monitoring & Debugging
### Comprehensive Logging System
- **Structured Logging**: Winston-based with multiple levels and session tracking
- **LLM Interaction Logs**: Complete AI conversation history in `logs/{session-id}/`
- **Screenshots**: Automatic capture during critical automation steps
- **Response History**: SQLite database tracking all interactions### Performance Monitoring
- **API Usage Tracking**: Token consumption and latency metrics
- **Success Rate Analysis**: Conversation completion and quality metrics
- **Error Pattern Detection**: Common failure points identification
- **Session Analytics**: Detailed per-session performance reports## 🚨 Troubleshooting
### Common Issues
1. **Login Failures**
- Verify LinkedIn credentials in `.env`
- Check for 2FA requirements
- Ensure account isn't restricted2. **Message Not Sending**
- Confirm `RUN_MODE=production` in `.env`
- Check safe mode overrides
- Verify LinkedIn UI selectors3. **AI Response Errors**
- Validate Gemini API key
- Check API quotas and billing
- Review prompt length limits## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
This tool is for educational and personal use. Users are responsible for complying with LinkedIn's Terms of Service and applicable laws. Use responsibly and ethically.
---
**Made with ❤️ for intelligent job searching**