pythinker-ai 0.1.4

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

🐍 Pythinker

🐍 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

uv tool install pythinker-ai

This installs Pythinker into an isolated environment and puts pythinker on your PATH. uv handles Python, PATH, and upgrades for you.

Don't have uv?

# macOS / Linux / WSL:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then re-run uv tool install pythinker-ai.

Prefer pipx, plain pip, or source?

# pipx (equivalent to uv tool install, slower):
pipx install pythinker-ai

# Plain pip (last resort — you may need to add ~/.local/bin to PATH):
pip install --user pythinker-ai

# From source (contributors only):
git clone [e-mail]:mohamed-elkholy95/Pythinker-ai.git
cd Pythinker-ai && uv sync --all-extras

If pythinker isn't found after install, run pythinker doctor (via python -m pythinker doctor if needed) for diagnostics.

🚀 Quick Start

pythinker onboard                           # write a config at ~/.pythinker/config.json
pythinker provider login openai-codex       # OAuth sign-in (the default provider)
pythinker agent                             # chat

pythinker onboard ships a config preconfigured for OpenAI Codex via ChatGPT OAuth (no API key needed). To use a different provider/model, edit ~/.pythinker/config.json — see Configuration for the full catalog of 25+ providers.

• 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

🔐 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.

Thanks for visiting ✨ Pythinker!