AgentOS

Hi there👋, Welcome to the World of AI Agents

Hello Developers!!👨‍💻
AgentOS is a modular voice assistant platform with pluggable specialized agents and natural language understanding. Join us in shaping the future of AI automation!

🌟 GirlScript Summer of Code 2025 (GSSoC'25)

✨ Exciting News...

AgentOS is officially part of GirlScript Summer of Code 2025! We’re super excited to welcome contributors from all across India & beyond to collaborate, build, and grow AgentOS together.

GSSoC is India’s largest 3-month long open-source program, designed to:

• 🌱 Help developers learn, build & grow through real-world projects
• 💡 Provide mentorship & guidance at every step
• 🤝 Foster collaborative coding & teamwork
• 🎁 Reward contributors with certificates, swag, and recognition

Why join AgentOS @ GSSoC’25?

By contributing here, you’ll get to:

• ✨ Improve your AI, automation & voice assistant skills
• 🛠️ Work on modular agents & pluggable architecture
• 🏆 Showcase your contributions & get recognized
• 📜 Earn certificates & swags while learning!

💖 Call to Action

We can’t wait to welcome new contributors from GSSoC’25 into the AgentOS family!
Let’s build, learn & grow — one commit at a time.

Table of Contents🧾

• Overview📌
• Features🌟
• Technology Used🚀
• Getting Started💥
• Agent Configuration⚙️
• Directory Structure📁
• Development🔧
• Contributing Guidelines📑
• Code Of Conduct📜
• Project Admin⚡
• Contributing is fun 🧡
• Acknowledgements 🙏

Overview📌

AgentOS is a modular voice assistant platform designed for extensibility and automation. With pluggable specialized agents and natural language understanding, it serves as a comprehensive AI assistant framework. Whether you're managing tasks, controlling music, automating social media, or handling files, AgentOS provides the foundation for intelligent automation. We welcome all contributions to make this an amazing platform for developers and users alike! 🚀

Disclaimer:

Some of our agents and voice commands processing are yet to be implemented. We're actively working on these features and would love your help!

Features🌟

• 🎤 Voice & Text Interface: Conversational AI with both voice and text input capabilities for natural interaction.
• 🧩 Modular Agent Architecture: Extensible plugin system allowing developers to create custom agents for specific tasks.
• 🧠 Natural Language Understanding: Intelligent translation of user requests into actionable commands across different agents.
• 📅 Task Management: Todoist integration for comprehensive task management, reminders, and productivity tracking.
• 📁 File Management: Advanced file system navigation and manipulation capabilities for efficient file handling.
• 🎵 Music Control: Spotify integration for seamless music control, search, and playlist management.
• 🐦 Social Media Automation: Twitter bot functionality for automated posting, thread creation, and timeline monitoring.
• ✍️ Content Creation: Automated blog post generation from repositories and other content sources.
• 🔌 Desktop Integration: Electron-based UI providing a native desktop experience.
• ⚡ Real-time Processing: Fast and responsive agent communication with efficient message routing.
• 🔧 Developer-Friendly: Template-based agent creation system for rapid development and deployment.

Technology Used🚀

Getting Started💥

How to Make a Pull Request

1. Start by forking the AgentOS repository. Click on the symbol at the top right corner.

2. Clone your forked repository:

git clone https://github.com/<your-github-username>/agentOS

3. Navigate to the new project directory:

cd agentOS

4. Set upstream command:

git remote add upstream https://github.com/theagentic/agentOS

5. Create a new branch:

git checkout -b YourBranchName

or

git branch YourBranchName
git switch YourBranchName

6. Sync your fork or local repository with the origin repository:

• In your forked repository click on Fetch upstream.
• Click Fetch and merge.

Alternatively, Git CLI way to Sync forked repository with origin repository:

git fetch upstream

git merge upstream/main

Github Docs for Syncing

1. Install Requirements

# Install main requirements
pip install -r requirements.txt

# For Electron UI (optional)
pip install -r requirements-electron.txt

2. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your preferred settings
# These are system-level settings only

3. Configure Agents

Each agent has its own configuration and environment variables:

# For each agent you want to use:
cd agents/[agent_name]/
cp .env.example .env
# Edit the .env file with your API credentials

7. Make your changes to the source code.

8. Stage your changes and commit:

⚠️ Make sure not to commit sensitive configuration files like .env

⚠️ Make sure not to run the commands git add . or git add *. Instead, stage your changes for each file/folder

git add file/folder

git commit -m "<your_commit_message>"

9. Push your local commits to the remote repository:

git push origin YourBranchName

10. Create a Pull Request!

11. Run the Application

# Run the standard version
python main.py

# Or run with Electron UI (if configured)
python electron_main.py

Congratulations! You've made your first contribution! 🙌🏼

Agent Configuration⚙️

Natural Language Agent

• Functionality: Translates natural language into commands for other agents
• Requirements: Either Ollama locally installed or Gemini API key
• Configuration: agents/natural_language/.env
• See NATURAL_LANGUAGE_SETUP.md for detailed setup instructions

Todoist Agent

• Functionality: Task management, reminders, and weather information
• Requirements: Todoist API token
• Configuration: agents/datetime/.env

Spotify Agent

• Functionality: Control Spotify playback, search and play tracks/playlists
• Requirements: Spotify API credentials (Client ID and Secret)
• Configuration: agents/spotiauto/.env

Twitter Bot

• Functionality: Post tweets, create threads, monitor timelines
• Requirements: Twitter API credentials
• Configuration: agents/twitter_bot/.env

Autoblog Agent

• Functionality: Generate blog posts automatically from repositories
• Requirements: None
• Configuration: agents/autoblog/.env

File Management

• Functionality: Navigate and manipulate the file system
• Requirements: None
• Configuration: Configure allowed directories in the main .env file

Directory Structure📁

AgentOS/
├── agents/                # Agent modules
│   ├── autoblog/          # Blog automation agent
│   ├── datetime/          # Date/time and Todoist agent
│   ├── filemanage/        # File management agent
│   ├── natural_language/  # Natural language processing agent
│   ├── spotiauto/         # Spotify automation agent
│   ├── twitter_bot/       # Twitter bot agent
│   └── agent_template/    # Template for creating new agents
├── api/                   # API endpoints for external services
├── core/                  # Core system components
│   ├── agent_base.py      # Base agent class
│   ├── agent_router.py    # Routes commands to agents
│   ├── tts_engine.py      # Text-to-speech engine
│   └── voice_processor.py # Voice input processor
├── electron/              # Electron app integration
├── scripts/               # Utility scripts
├── ui/                    # User interface components
├── utils/                 # Shared utility functions
├── .env                   # Environment variables
├── config.py              # Configuration system
├── main.py                # Application entry point
├── requirements.txt       # Project dependencies
└── setup.py               # Installation script

Development🔧

Creating a New Agent

You can use the agent template to create a new agent:

# Copy the template
cp -r agents/agent_template agents/your_agent_name

# Edit the files to implement your agent's functionality

Running Tests

# Run tests for a specific agent
python -m pytest test_agent.py -v

# Run natural language agent tests
python test_nlp_agent.py

Contributing Guidelines📑

We welcome contributions from developers of all skill levels! Whether you're fixing bugs, adding new features, creating new agents, or improving documentation, your contributions help make AgentOS better for everyone.

Ways to Contribute

• 🐛 Bug Fixes: Help us identify and fix issues
• ✨ New Features: Add new functionality to existing agents
• 🤖 New Agents: Create entirely new agents for different use cases
• 📚 Documentation: Improve our docs and help others understand the project
• 🧪 Testing: Write tests to ensure code quality and reliability
• 🎨 UI/UX: Enhance the user interface and experience

Getting Started with Contributing

1. Check out our Issues page for tasks labeled good first issue
2. Read our Contributing Guidelines for detailed instructions
3. Join our community discussions and ask questions

Code Of Conduct📑

This project and everyone participating in it are governed by our [Code of Conduct](https://github.com/theagentic/agentOS/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Show some ❤️  by giving to this repository.

Project Admin⚡

Team theagentic

Ranadeep Laskar

Plans🚀

In the future, we hope to create an agentic framework so anyone can build agents for AgentOS and use them freely or, if they want, even contribute to the main project. Please feel free to reach out if you have ideas to share about this project - we'd love to discuss and get constructive criticism to make this better over time.

Contributing is fun🧡

We’re always excited to welcome new contributors! 🎉
Pick issues labeled good first issue to get started quickly.

Some ideas you could suggest or build:

• 📝 Improving AI prompt engineering for our natural-language agent
• 🧮 Adding ingredient density data or other useful datasets for agent skills
• 🎨 Enhancing UI components or responsiveness across the Electron & web interfaces
• 🧪 Adding more tests for existing agents to keep quality high
• ⚙️ Creating entirely new pluggable agents for fresh use-cases

Your creativity makes AgentOS better for everyone. 🚀

Acknowledgements

Thank you to all the amazing contributors who have made this project possible! 💝

License

This project is licensed under the MIT License.