Pythinker-ai

🤖 Pythinker is an open-source tiny agent framework. It keeps the core agent loop compact 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 tiny, multiplexing agent loop: one Python process listens to Slack, Telegram, Discord, WhatsApp, Signal, Matrix, MS Teams, email, a WebSocket WebUI, and an OpenAI-compatible HTTP API — all backed by a single session-scoped memory layer.

What's new in 2.7.1 — The public command is now pythinker-ai, runtime state lives under ~/.pythinker-ai/ / .pythinker-ai/, and environment variables use the PYTHINKER_AI_ prefix so Pythinker can coexist with pythinker-code. Native installers are the canonical install path and use short URLs. Coding workflows gained structured apply_patch, long-running exec sessions (write_stdin, list_exec_sessions), and find_files; OpenAI providers can force Chat Completions vs. Responses API via providers.openai.apiType. See the changelog for details.

💡 Key Features

• Tiny agent — a compact readable core. Stable long-running behavior without orchestration sprawl.
• Channel-agnostic — Slack, Telegram, Discord, WhatsApp, Signal, Matrix, MS Teams, email, WebSocket, plus an OpenAI-compatible HTTP API.
• Full-screen TUI — pythinker-ai tui (alias chat) opens a prompt_toolkit chat with live streaming, slash-command pickers (/model, /provider, /sessions, /theme, /help, /status), fuzzy search, themable chrome (default + monochrome), and Ctrl+C cancellation of in-flight turns.
• 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.
• Provider hot-reload — edits to model / provider / API key in ~/.pythinker-ai/config.json land at the next turn boundary. No restart of the SDK or gateway. Same-signature snapshots short-circuit; broken configs are logged and swallowed so an in-flight session can't crash on a typo.
• Headless browser tool (opt-in) — drives Playwright-managed Chromium for JavaScript-rendered pages, click/form flows, screenshots, and DOM snapshots. mode="auto" launches a packaged headless Chromium without Docker; mode="cdp" connects to an external service for hardened deployments. First-use Chromium binary installs lazily, with idle eviction, per-context page caps, SSRF route handling, and turn-boundary hot reload of browser config.
• Governed-execution runtime (off by default) — opt-in RuntimeConfig wires a PolicyService (allow-lists from agent manifests, per-turn budgets, recursion depth), a ToolEgressGateway chokepoint, an AgentRegistry directory loader, RequestContext + BudgetCounters plumbing, and a pluggable TelemetrySink (loguru / JSONL / composite). When the loader is None and policy is off, the runtime follows the default lightweight path.
• Autonomous subagent tracking — spawned subagents are first-class task records with durable output under .pythinker-ai/task-results/. Pick a role at spawn time — coder (full tools), explore (read-only navigation), or plan (planning-only, no write/edit/shell) — and use /tasks, /task-output <task_id>, and to inspect or stop background work from chat.

📦 Install

Pythinker ships native installers for every platform alongside the PyPI wheel. Pick the row that matches your OS — no Python, Node, or uv prerequisite for the native paths.

✅ Status note (May 2026): native installers are now the canonical path for new installs. The short URLs below always resolve to the latest GitHub Release artifact, verify its .sha256 sidecar, and install pythinker-ai.

Platform	One-line install	Artifact
🪟 Windows	irm https://pythinker.com/ai.ps1 | iex	PythinkerSetup-<version>.exe
🍎 / 🐧 macOS / Linux	curl -fsSL https://pythinker.com/ai | bash	native tarball
🍎 macOS (Homebrew)	brew install mohamed-elkholy95/pythinker/pythinker-ai	Homebrew tap
🐧 Linux packages	.deb / .rpm from Releases	system package
🐍 Python fallback	pip install pythinker-ai	PyPI

Every artifact ships with a matching .sha256 file — verify before install on any platform with sha256sum, shasum -a 256, or Get-FileHash.

After install, on any OS:

pythinker-ai --version                # confirm install
pythinker-ai onboard                  # interactive setup wizard
pythinker-ai                          # start the interactive CLI

In-app updates — pythinker-ai update queries the GitHub Releases API and re-runs the right installer for your build with SHA-256 verification. Set PYTHINKER_AI_CLI_NO_AUTO_UPDATE=1 to disable the proactive startup check.

🪟 Windows — native installer

The short PowerShell installer downloads the latest PythinkerSetup-<version>.exe, verifies its .sha256 sidecar, and runs the Inno Setup installer silently. It installs per-user into %LOCALAPPDATA%\Programs\Pythinker, registers pythinker-ai on your user PATH (HKCU\Environment), broadcasts WM_SETTINGCHANGE so new shells see the change, and does not require UAC.

irm https://pythinker.com/ai.ps1 | iex
pythinker-ai --version

For a pinned version or an IT-managed per-machine install, download the script first and pass flags:

irm https://pythinker.com/ai.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Version 2.7.1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -AllUsers

Manual .exe downloads from Releases still work; verify them with Get-FileHash before running.

Upgrade: pythinker-ai update from inside the running app — it downloads the newest installer, verifies SHA-256, and re-runs it silently (/VERYSILENT /SUPPRESSMSGBOXES /NORESTART).

Uninstall: Apps & Features → Pythinker → Uninstall reverts both the files and the PATH edit.

🛡 First-launch SmartScreen warning — until the Authenticode cert is provisioned in CI, the installer ships unsigned and Windows shows "Windows protected your PC." Click More info → Run anyway. Use the published .sha256 as your integrity check until signing comes online.

🍎 macOS — Homebrew tap

# 1. Install — always pulls the newest pythinker-ai release on PyPI
brew install mohamed-elkholy95/pythinker/pythinker-ai

# 2. Verify
pythinker-ai --version
which pythinker-ai       # -> /opt/homebrew/bin/pythinker-ai (Apple Silicon)
                         #    or /usr/local/bin/pythinker-ai (Intel)

Works on Apple Silicon and Intel — brew picks the right Python build for you. The formula provisions a clean venv and installs pythinker-ai unpinned, so every fresh brew install resolves the newest release on PyPI; the tap also auto-republishes its url/sha256 block on every Pythinker release so brew info reflects the current version.

Upgrade: brew upgrade pythinker-ai works once the tap has refreshed for the new release. To pick up a PyPI point release immediately (between tap refreshes), brew reinstall pythinker-ai.

Uninstall: brew uninstall pythinker-ai && brew untap mohamed-elkholy95/pythinker.

The tap repo is mohamed-elkholy95/homebrew-pythinker — auto-maintained, do not hand-edit.

🐧 Linux — system packages

Native .deb and .rpm packages for both x86_64 and aarch64 are attached to every GitHub Release.

# Debian / Ubuntu (x86_64)
sudo dpkg -i pythinker-ai_2.7.1_amd64.deb
sudo apt-get install -f       # only if dpkg reports missing deps

# Debian / Ubuntu (ARM64)
sudo dpkg -i pythinker-ai_2.7.1_arm64.deb

# Fedora / RHEL / openSUSE (x86_64)
sudo rpm -i pythinker-ai-2.7.1.x86_64.rpm
# or use the package manager (preferred — handles deps):
sudo dnf install ./pythinker-ai-2.7.1.x86_64.rpm
sudo zypper install ./pythinker-ai-2.7.1.x86_64.rpm

# Fedora / RHEL (aarch64)
sudo rpm -i pythinker-ai-2.7.1.aarch64.rpm

Both packages drop a small /usr/bin/pythinker-ai launcher that execs the real binary under /usr/lib/pythinker/, so your $PATH stays tidy.

Verify before install:

sha256sum -c pythinker-ai_2.7.1_amd64.deb.sha256        # Debian/Ubuntu
sha256sum -c pythinker-ai-2.7.1.x86_64.rpm.sha256       # Fedora/RHEL

Upgrade: download the new .deb/.rpm from Releases and dpkg -i / dnf install over it. Or run pythinker-ai update from inside the running app — it'll fetch the matching new package and prompt for sudo to install.

Uninstall:

sudo dpkg -r pythinker-ai                                # Debian/Ubuntu
sudo rpm -e pythinker-ai                                 # Fedora/RHEL

🌐 macOS / Linux — curl-bash native installer

For containers, fresh VMs, or any host without a system package manager. The install-native.sh helper detects your OS + arch, downloads the matching PyInstaller-frozen tarball, verifies its SHA-256, and lands the single binary at ~/.local/bin/pythinker-ai.

# Latest release
curl -fsSL https://pythinker.com/ai | bash

# Pin a specific version
curl -fsSL https://pythinker.com/ai | bash -s -- --version 2.7.1

# Custom prefix (defaults to $HOME/.local)
curl -fsSL https://pythinker.com/ai | bash -s -- --prefix /opt/pythinker

Supported targets:

uname -s / -m	Tarball asset
Linux / x86_64	pythinker-<version>-x86_64-unknown-linux-gnu.tar.gz
Linux / aarch64	pythinker-<version>-aarch64-unknown-linux-gnu.tar.gz
Darwin / arm64	pythinker-<version>-aarch64-apple-darwin.tar.gz

The script prints PATH guidance if ~/.local/bin isn't already o