linkedin-agent

Autonomous LinkedIn Agent with real-time terminal UI and LLM-powered content generation

An AI-driven agent that monitors GitHub repos, generates posts via LLM, and streams logs through a retro terminal interface.

---

🔗 Quick Links

• 📄 Abstract
• ✨ Key Highlights
• ✨ Features
• 🏗️ Architecture
• 🛠 Tech Stack
• 📦 Dependencies and Packages
• 📋 Prerequisites
• ⚙️ Installation
• 🚀 Quick Start
• 💡 Usage
• 🌐 API Endpoints
• ⚙️ Configuration
• 🔧 Environment Variables
• 📂 Project Structure
• 📜 License

---

📑 Table of Contents

1. Abstract
2. Key Highlights
3. Features
4. Architecture
5. Tech Stack
6. Dependencies and Packages
7. Prerequisites
8. Installation
9. Quick Start
10. Usage
11. API Endpoints
12. Configuration
13. Environment Variables
14. Project Structure
15. License

---

Abstract

This repository hosts H0NEYP0T-466/linkedin-agent, an intelligent automation system that autonomously monitors GitHub repositories and generates LinkedIn posts using AI. The project features a real-time terminal-style web interface built with React and Vite, allowing users to monitor agent activity through live log streaming. At its core, the agent leverages FastAPI for backend services, including asynchronous LLM interactions via LongCat API, RSS-based web scraping for tech news, and Telegram bot integration for approval workflows. Data persistence is handled through JSON and Markdown storage, while the frontend provides an interactive command-line experience with WebSocket-powered updates. The architecture supports full lifecycle management of autonomous posting tasks, from repository discovery to content generation and social media publishing.

Key Highlights

This project is an autonomous LinkedIn Agent that monitors GitHub repositories, generates AI-powered content, and manages a real-time terminal interface. 🤖 The system combines web scraping, LLM integration, and Telegram notifications to create a seamless content pipeline for tech professionals.

Key capabilities include: real-time log streaming via WebSocket connections, RSS feed monitoring for AI/ML news, and GitHub activity tracking with README parsing. The agent uses LongCat's OpenAI-compatible API to generate LinkedIn posts from repository data, with approval workflows handled through Telegram bot integration.

Built with a modern React frontend featuring a retro terminal UI, the application provides live status updates, command-line-like interaction, and responsive design. All operations run asynchronously in FastAPI, ensuring smooth performance while managing storage, message queuing, and network resilience.

Features

The LinkedIn Agent project delivers a fully autonomous social media automation platform with real-time monitoring and interactive control capabilities.

🔍 GitHub Repository Monitoring: Continuously tracks public repositories, commit activity, and README content for configured GitHub users through the github_service.py.

🤖 AI-Powered Content Generation: Leverages LongCat OpenAI-format LLM service (llm_service.py) to generate engaging LinkedIn posts and repository descriptions from GitHub data.

📰 Web Scraping Integration: Fetches latest AI/ML/tech news from multiple RSS feeds with optional Cloudflare support for JavaScript-heavy pages via scraper_service.py.

💬 Telegram-Based Approval Workflow: Implements bot-driven notification system (telegram_service.py) allowing users to review and approve generated content before posting.

🖥️ Real-Time Terminal UI: Features live log streaming and status monitoring through WebSocket connections with a retro-styled command-line interface in React (App.tsx).

💾 Persistent Data Management: Stores logs, repository tracking, todo lists, and post files using JSON/Markdown formats via dedicated storage service (storage.py).

⚡ Asynchronous Architecture: Built on FastAPI with async/await patterns for efficient concurrent task handling and real-time communication.

Architecture

The LinkedIn Agent is architected as a full-stack autonomous system with a clear separation between frontend and backend components. The FastAPI backend serves as the central orchestrator, managing agent lifecycle, real-time communication, and service coordination through asynchronous event loops. It exposes REST APIs for status monitoring and WebSocket endpoints for live log streaming. The React-based frontend provides a terminal-style interface that connects via WebSocket to display real-time agent activity, featuring auto-scrolling logs and interactive controls.

Core services include: 🤖 GitHub monitoring for repository tracking and README parsing, 🧠 LLM integration via LongCat API for content generation, 📰 RSS scraper for AI/ML news aggregation, 💾 JSON/Markdown storage for persistent data management, and 📱 Telegram bot for approval workflows and notifications. All services run asynchronously within the main agent loop, enabling concurrent operations like scraping, LLM processing, and message queuing. The architecture supports real-time updates through WebSocket connections while maintaining stateless API endpoints for external integration.

Tech Stack

This project is built using a modern, full-stack architecture combining Python for backend services and React with TypeScript for the frontend interface.

The backend leverages FastAPI for high-performance API endpoints, async HTTP handling via httpx, and real-time communication through WebSockets. It integrates with external services including Telegram bots, RSS feed scraping, GitHub API, and LLM inference via LongCat OpenAI-compatible endpoints. Data persistence is managed through JSON-based storage with Markdown support.

The frontend is a React application powered by Vite for fast development, featuring a terminal-style UI with real-time log streaming and interactive command-line aesthetics. It communicates with the backend via REST APIs and WebSocket connections for live updates.

Dependencies and Packages

The project relies on several key dependencies defined in two main files: backend/requirements.txt for the Python backend and package.json (with package-lock.json) for the React frontend.

Backend Dependencies (Python) – Defined in backend/requirements.txt:

• FastAPI – Web framework for building APIs with automatic OpenAPI documentation.
• Uvicorn – ASGI server to run FastAPI applications asynchronously.
• httpx – Async HTTP client for making requests to external services like RSS feeds and APIs.
• python-telegram-bot – Library for integrating Telegram bot functionality, including message sending and callback handling.
• feedparser – Parser for RSS and Atom feeds, used by the scraper service to fetch news content.

Frontend Dependencies (JavaScript/TypeScript) – Defined in package.json:

• React 19 – Core library for building the user interface.
• Vite – Build tool and development server optimized for fast HMR and optimized production builds.
• TypeScript – Type-safe superset of JavaScript, configured via tsconfig.json, tsconfig.app.json, and tsconfig.node.json.
• ESLint – Linting tool enforcing code quality with React, React Refresh, and TypeScript support.

These packages enable real-time terminal-style UI, agent orchestration, LLM integration, GitHub/Telegram/web scraping, and persistent storage as evidenced by the codebase structure and implementation files.

Prerequisites

Before setting up the H0NEYP0T-466/linkedin-agent, ensure your system meets the following requirements:

• Python 3.10+ is required to run the backend services (FastAPI, agent orchestration, LLM integration).
• Node.js 18+ and npm are needed for the frontend React application built with Vite.
• The project uses TypeScript across both frontend and backend components.
• A modern web browser is required to access the terminal-like UI at http://localhost:5173.

💡 No Docker or database dependencies are present in the current codebase — everything runs natively via Python virtual environments and Node.js tooling.

Installation

This project requires both Python 3.9+ for the backend and Node.js 18+ with npm for the frontend.

Backend Setup

1. Navigate to the backend directory
2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

Frontend Setup

1. Ensure you're in the project root
2. Install frontend dependencies:

   npm install

Running the Application

• Start the backend server:

  cd backend && uvicorn main:app --host 0.0.0.0 --port 8006 --reload

• Start the frontend development server:

  npm run dev

The application will be available at http://localhost:5173 (frontend) and http://localhost:8006 (backend API).

Quick Start

Get your LinkedIn Agent up and running in minutes! 🚀

First, install the frontend dependencies:

npm install

Then start the backend server:

cd backend && python -m venv venv && source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
uvicorn main:app --reload --port 8006

In a new terminal, launch the React frontend:

npm run dev

Open your browser to http://localhost:5173 to see the real-time terminal interface monitoring your agent's activities. The app automatically connects via WebSocket to stream logs and status updates.

Important: Ensure environment variables (e.g., API keys) are configured as needed in a .env file in the backend/ directory for services like Telegram bot and LLM integration to function properly.

Usage

Once the application is running, access the real-time terminal interface at http://localhost:5173 to monitor and interact with your LinkedIn Agent. The interface provides a retro-style command-line experience showing live logs, agent status, and interactive controls.

Connect via WebSocket to receive continuous updates from the backend agent. Use the REST API endpoints to check agent status, retrieve stored data, or trigger actions like fetching GitHub repositories or generating posts. The Telegram bot integration allows remote approval of generated LinkedIn content through chat commands.

The agent autonomously monitors configured GitHub repositories, scrapes relevant tech news, generates AI-powered posts using the LLM service, and notifies you via Telegram for review before posting. All activity logs stream in real-time through the terminal UI.

Key interactions include starting/stopping the agent, viewing current tasks, checking repository status, and managing post drafts — all accessible through the web interface or Telegram bot commands.

API Endpoints

The FastAPI backend exposes several RESTful endpoints and WebSocket connections for managing the LinkedIn Agent's lifecycle and retrieving data:

• POST /agent/start — Initiates the agent's autonomous workflow, triggering GitHub repository monitoring, AI-powered post generation, and Telegram-based approval notifications.
• GET /agent/status — Returns real-time status of the agent including current task, progress percentage, and active services.
• GET /posts — Retrieves generated LinkedIn post drafts stored in Markdown format, typically awaiting user approval via Telegram.
• GET /logs — Provides access to historical execution logs for debugging and monitoring purposes.
• WebSocket /ws/logs — Enables real-time streaming of live logs from the agent to the frontend terminal interface.

These endpoints support CORS-enabled communication with the React frontend running on port 8000, forming a complete autonomous content generation pipeline.

Configuration

The LinkedIn Agent is configured primarily through environment variables that control core functionality across its modular services. The system uses a centralized configuration approach where critical parameters are loaded from the environment during runtime.

Key configuration areas include:

• Telegram Integration: Requires TELEGRAM_BOT_TOKEN for bot authentication and optional proxy settings for restricted regions
• LLM Service: Needs LLM_API_KEY to authenticate with the LongCat OpenAI-format API for content generation
• GitHub Monitoring: Uses GITHUB_USERNAME to specify which user's repositories should be tracked
• Backend Port: Configured via UVICORN_PORT (default: 8006) for the FastAPI server

Environment variables are accessed throughout the backend code using standard Python methods, ensuring secure credential management. While the system includes error handling for network failures in the Telegram service, it attempts direct retries rather than implementing a full message queueing mechanism. The storage layer persists data in JSON and Markdown formats but doesn't currently support customizable retention policies.

For local development, create a .env file in the backend/ directory with the required variables before starting the application.

Environment Variables

The LinkedIn Agent backend relies on several environment variables to configure its behavior and integrations. These should be set in your environment or a .env file in the backend/ directory.

Required Variables

• TELEGRAM_BOT_TOKEN: Your bot token from @BotFather for Telegram bot authentication
• TELEGRAM_CHAT_ID: Your personal chat ID (send /start to the bot to get this)
• LONGCAT_API_KEY or OPENAI_API_KEY: API key for the LLM service (LongCat OpenAI-compatible API)
• GITHUB_USERNAME: GitHub username to monitor for repository activity

Optional Variables

• TELEGRAM_PROXY: HTTP/SOCKS5 proxy URL if Telegram is blocked in your region
• LLM_MODEL: Model name to use (default: longcat-flash-lite)
• LONGCAT_BASE_URL: Base URL for OpenAI-compatible endpoint (default: https://api.longcat.chat/openai)
• LLM_TIMEOUT_SECONDS: Request timeout in seconds (default: 60)
• DATA_DIR: Directory for all agent data (default: ./data)
• REPOS_DIR: Directory where repos are cloned (default: DATA_DIR/repos)
• PORT: Server port (default: 8006)
• CLOUDFLARE_API_TOKEN: For Cloudflare browser rendering of JS-heavy pages
• CLOUDFLARE_ACCOUNT_ID: Cloudflare account ID for browser rendering

See backend/.env.example for a complete template with all available configuration options.

Project Structure

The project follows a monorepo structure with clear separation between frontend and backend components:

Backend (backend/)

FastAPI-based microservices architecture with async/await patterns:

• main.py - Core API server with WebSocket support and CORS configuration
• agent.py - Orchestrates all services within an async event loop
• llm_service.py - Handles LLM interactions via LongCat OpenAI-format API
• scraper_service.py - Fetches AI/ML/tech news from RSS feeds with Cloudflare support
• github_service.py - Manages GitHub repository data, commits, and user events
• telegram_service.py - Telegram bot integration with message queuing and approval workflows
• storage.py - JSON/Markdown-based persistent storage system for logs, repos, and posts
• requirements.txt - Python dependencies (FastAPI, Uvicorn, httpx, python-telegram-bot, BeautifulSoup4, GitPython, pydantic, feedparser, aiofiles)
• run_commands.txt - Useful commands and scripts for development and deployment
• data/ - Persistent data directory containing:
  • pending_messages.json - Queued Telegram messages awaiting delivery
  • repos.json - Tracked GitHub repositories and metadata
  • repos.md - Repository documentation in Markdown format
  • state.json - Agent runtime state and progress tracking
  • todo.json - Task queue for autonomous operations
  • memory.md - Project memory and context notes
  • posts/ - Generated LinkedIn post drafts organized by status:
    • approved/ - Posts approved via Telegram bot workflow
    • Pending posts awaiting approval
  • repos/ - Cloned GitHub repository copies with README files for analysis
• .env.example - Environment variable template with all required configuration

Frontend (src/)

Built with React 19 and Vite, featuring a terminal-style UI:

• App.tsx - Main React component handling WebSocket connections and real-time log streaming
• main.tsx - Application entry point with StrictMode wrapper
• App.css & index.css - Terminal-inspired styling with dark theme and green monospace text
• assets/ - Static assets and images

Configuration (Root Level)

TypeScript configs, ESLint setup, and build tooling:

• package.json & package-lock.json - Frontend dependencies and scripts
• tsconfig.json, tsconfig.app.json, tsconfig.node.json - TypeScript compiler configurations
• vite.config.ts - Vite build tool and development server configuration
• eslint.config.js - Code quality and style enforcement rules
• index.html - HTML entry point with WebSocket connection setup
• public/ - Static assets served directly by the web server

Documentation & Governance

• README.md - Project overview and usage instructions
• LICENSE - MIT License terms
• CONTRIBUTING.md - Guidelines for contributors
• SECURITY.md - Security policies and reporting procedures
• CODE_OF_CONDUCT.md - Community standards
• SUPPORT.md - Support resources and troubleshooting
• you.txt - Additional project notes and information

License

This project is licensed under the MIT License — see the LICENSE file for details.

The MIT License is a permissive open-source license that allows you to freely use, modify, distribute, and sublicense the software, provided that the original copyright notice and permission notice are included in all copies or substantial portions of the code. It's ideal for projects like this LinkedIn Agent that combine web scraping, LLM integration, and real-time monitoring with a clean, maintainable tech stack.

You are welcome to use this codebase for personal or commercial purposes, contribute improvements, or integrate it into your own solutions — just give proper credit and include the license terms.

---

Made with ❤️ by H0NEYP0T-466