---

What is ClawCord?

ClawCord is an open-source, self-hosted AI agent that lives in your Discord DMs. It doesn't just chat — it does things. Run commands on your PC, search the web, track stocks, get news reports, and control a remote machine — all from a Discord message.

It connects to any OpenAI-compatible API (OpenAI, Ollama, LM Studio, Groq, Mistral, etc.), so you pick the model you want.

---

Features

	AI Agent with Tool Use Full agent loop with up to 25 tool rounds per message. Supports native function calling and text-based fallback for models that don't support tools (like DeepSeek). The AI decides what to do and executes it.
	PC Control Run shell commands, read/write files, open apps, list processes, kill tasks, get system info — all from Discord. The AI has full access to your machine (with safety guardrails).
	Web Search & Browsing Search the web and read full pages. Uses Ollama Cloud web search natively, with Brave Search as a fallback. The AI can research topics, read documentation, and find answers.
	News Reporter Automated journalist-style news reports delivered to your DMs. Fetches articles from NewsAPI, reads the full content, then writes a proper report with paragraphs and sources. Configurable topics, interval, and country. SQLite deduplication prevents re-sending on restart.
	Finance & Crypto Real-time stock quotes, crypto prices, and market search via Alpha Vantage. Ask "what's the price of Tesla?" and the AI knows to use the right tool.
	SyncLink — Remote PC Bridge Run the bot on a server and still control your main PC. SyncLink is a secure WebSocket bridge with HMAC-SHA256 authentication. The client is a standalone desktop app (pywebview) you give to users — no bot code needed.
	Web Dashboard A clean admin panel at localhost:5000 to configure everything: API keys, AI model, personality, news topics, security rules, SyncLink. Settings apply instantly without restarting the bot.

---

Quick Start

Prerequisites

• Python 3.10+
• A Discord bot token (create one here)
• An AI API key (OpenAI, Ollama, Groq, etc.)

Installation

git clone https://github.com/Ciel2006/ClawCord.git
cd ClawCord
pip install -r requirements.txt
python launcher.py

On first run, the web dashboard opens automatically. Configure your tokens and settings, then restart the launcher.

Configuration

All API keys are stored in .env (created automatically from .env.example):

DISCORD_TOKEN=your_token
OWNER_ID=your_discord_id
AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=your_key
AI_MODEL=gpt-4o-mini
NEWS_API_KEY=your_newsapi_key
ALPHAVANTAGE_API_KEY=your_key
SYNCLINK_SECRET=your_secret

Non-secret settings (personality, news topics, blocked commands, etc.) are in settings.json and editable from the dashboard.

---

SyncLink Setup

SyncLink lets you run ClawCord on a server while controlling your main PC remotely.

On the bot server:

1. Enable SyncLink in the dashboard
2. Set a secret key
3. Note the address shown (e.g. 10.0.0.120:8765)

On your main PC:

cd synclink
pip install -r requirements.txt
python run.py

Paste the server address and secret into the SyncLink app and hit Connect.

---

Project Structure

ClawCord/
├── launcher.py          # Entry point — starts dashboard + bot
├── bot.py               # Discord bot core
├── config.py            # Settings loader (.env + settings.json)
├── database.py          # SQLite for news deduplication
├── .env                 # API keys (auto-created, gitignored)
├── settings.json        # Non-secret configuration
├── cogs/
│   ├── chat.py          # AI agent with tool-use loop
│   ├── pc_control.py    # !run, !read, !write commands
│   ├── pc_tools.py      # Tool definitions + implementations
│   ├── web_tools.py     # Web search & fetch (Ollama/Brave)
│   ├── web_search.py    # !search command
│   └── news.py          # Automated news reporter
├── synclink/
│   ├── server.py        # WebSocket server (runs on bot machine)
│   ├── client.py        # WebSocket client (runs on user PC)
│   ├── tools.py         # Self-contained PC tool execution
│   ├── SyncLink.py      # Pywebview desktop app entry point
│   ├── run.py           # Quick launcher
│   └── ui/              # SyncLink desktop UI
├── web interface/
│   ├── app.py           # Flask dashboard
│   ├── templates/       # Dashboard HTML
│   └── static/          # CSS, JS, logo
└── svg/                 # Feature icons for README

---

Security

ClawCord gives an AI agent access to your PC. That's powerful but comes with responsibility. Here's how security is handled:

Built-in Protections

• Blocked commands — A configurable list of dangerous commands (rm -rf, format, del /s, shutdown, etc.) that are refused even if the AI requests them
• Command timeout — All shell commands have a configurable timeout (default 30s) to prevent runaway processes
• Owner-only — The bot only responds to the configured owner ID in DMs
• SyncLink HMAC-SHA256 — All messages between bot server and SyncLink client are signed and verified with a shared secret. Invalid signatures are silently dropped
• No plaintext secrets in config — API keys live in .env, which is gitignored

Reporting Vulnerabilities

If you discover a security vulnerability, please do not open a public issue. Instead:

1. Email the maintainer directly or use GitHub Security Advisories
2. Describe the vulnerability, steps to reproduce, and potential impact
3. Allow reasonable time for a fix before public disclosure

We take security seriously and will respond as quickly as possible.

Recommendations

• Use a strong, unique secret for SyncLink
• Don't expose the dashboard (port 5000) or SyncLink (port 8765) to the public internet without a VPN or firewall
• Review the blocked commands list and add anything sensitive to your setup
• Run the bot with a non-admin user account when possible
• Regularly rotate your API keys

---

Contributing

ClawCord is open source and contributions are welcome.

How to Contribute

1. Fork the repository
2. Create a branch for your feature or fix:

   git checkout -b feature/my-feature

3. Make your changes — keep commits focused and descriptive
4. Test your changes locally
5. Open a Pull Request against main with a clear description of what you changed and why

What We're Looking For

• New AI tools (integrations, APIs, automations)
• UI/UX improvements to the dashboard or SyncLink
• Bug fixes and error handling improvements
• Documentation and translations
• Security hardening
• Support for more AI providers

Guidelines

• Keep code clean and readable
• Follow the existing code style (Python, no type stubs, async where possible)
• Don't commit API keys or secrets
• Test on Windows (primary target) and Linux if possible
• Open an issue first for large changes so we can discuss the approach

---

License

This project is open source. See the LICENSE file for details.

---

_{Built with claws by Ciel}