pythinker-ai 0.1.0

Pythinker — an ultra-lightweight personal AI agent framework with built-in chat channels, memory, MCP, and an OpenAI-compatible API.

🐍 Pythinker is an open-source, ultra-lightweight personal-AI-agent framework. It keeps the core agent loop small and readable while still supporting chat channels, long-term memory, MCP, and practical deployment paths — so you can go from local setup to a long-running personal agent with minimal overhead.

Powered by a small, multiplexing agent loop: one Python process listens to Slack, Telegram, Discord, WhatsApp, Matrix, MS Teams, email, a WebSocket WebUI, and an OpenAI-compatible HTTP API — all backed by a single session-scoped memory layer.

💡 Key Features

• Ultra-lightweight — a small readable core. Stable long-running behavior without orchestration sprawl.
• Channel-agnostic — Slack, Telegram, Discord, WhatsApp, Matrix, MS Teams, email, WebSocket, plus an OpenAI-compatible HTTP API.
• Provider-rich — 25+ LLM providers (Anthropic, OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, Qwen/DashScope, MiniMax, VolcEngine, Moonshot, DeepSeek, StepFun, and more) behind a single interface.
• Memory that learns — a two-phase "Dream" process consolidates long-term memory into MEMORY.md / SOUL.md / USER.md, auto-versioned with pure-Python git.
• Skills & MCP — bundled skills (GitHub, cron, weather, tmux, summarize, skill-creator, …) plus first-class Model Context Protocol tool access.
• Sandboxed shell — every command is wrapped in a bubblewrap sandbox on Linux; file tools enforce workspace boundaries.
• Hackable — the Python package is ~55k LOC with zero monolithic orchestration layer. Read it, fork it, extend it.

📦 Install

[!IMPORTANT] If you want the newest features and experiments, install from source (the dev branch). If you want the most stable day-to-day experience, install from PyPI or with uv.

Install from source

git clone https://github.com/mohamed-elkholy95/Pythinker-ai.git
cd Pythinker-ai
pip install -e .

Install with uv

uv tool install pythinker-ai

Install from PyPI

pip install pythinker-ai

🚀 Quick Start

1. Initialize

pythinker onboard

The interactive wizard drops a config at ~/.pythinker/config.json and asks which provider / model you want.

2. Configure (~/.pythinker/config.json)

Configure these two parts (other options have defaults). Add or merge the blocks below into your existing config rather than replacing the whole file.

Set your API key (e.g. OpenRouter, a good default for global users):

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  }
}

Set your model (optionally pin a provider — defaults to auto-detection):

{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4-6"
    }
  }
}

3. Chat

pythinker agent

• Want different LLM providers, web search, MCP, security settings, or more config options? See Configuration.
• Want to run Pythinker in chat apps like Telegram, Discord, Slack, WhatsApp, or Matrix? See Chat Apps.
• Want Docker or Linux service deployment? See Deployment.

🧪 WebUI (Development)

[!NOTE] The WebUI development workflow currently requires a source checkout and is not yet shipped together with the official packaged release. See the WebUI README for full WebUI development docs and build steps.

1. Enable the WebSocket channel in ~/.pythinker/config.json

{ "channels": { "websocket": { "enabled": true } } }

2. Start the gateway

pythinker gateway

3. Start the WebUI dev server

cd webui
bun install
bun run dev

🏗️ Architecture

🐍 Pythinker stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.

See docs/ARCHITECTURE.md for a forensic walkthrough of the runtime.

✨ Features

📈 24/7 Real-Time Market Analysis	🚀 Full-Stack Software Engineer	📅 Smart Daily Routine Manager	📚 Personal Knowledge Assistant
Discovery • Insights • Trends	Develop • Deploy • Scale	Schedule • Automate • Organize	Learn • Memory • Reasoning

📚 Docs

Browse the repo docs for the current GitHub development version.

• Talk to Pythinker from familiar chat apps: Chat Apps
• Configure providers, web search, MCP, and runtime behavior: Configuration
• Integrate Pythinker with local tools and automations: OpenAI-Compatible API · Python SDK
• Run Pythinker with Docker or as a Linux service: Deployment
• Deeper dives: Architecture · Memory · Multiple Instances · Channel Plugin Guide

🤝 Contribute & Roadmap

PRs welcome! The codebase is intentionally small and readable. 🤗

Branching Strategy

Branch	Purpose
main	Stable releases — bug fixes and minor improvements
dev	Experimental features — new features and breaking changes

Unsure which branch to target? See CONTRIBUTING.md for details.

Roadmap — Pick an item and open a PR!

• Multi-modal — See and hear (images, voice, video)
• Long-term memory — Never forget important context
• Better reasoning — Multi-step planning and reflection
• More integrations — Calendar and more
• Self-improvement — Learn from feedback and mistakes

Contributors

🔐 Security

Found a vulnerability? Please do not open a public issue. Follow the private disclosure process in SECURITY.md.

📄 License

Pythinker is released under the MIT License. Third-party components redistributed with the project are listed in THIRD_PARTY_NOTICES.md.

⭐ Star History

Thanks for visiting ✨ Pythinker!