# Pythinker β€” full documentation corpus > Concatenated markdown for AI agents. Sources are also available individually at > /README.md, /README_CODE.md, /PRODUCT.md, and /pythinker-cli.md. > See /llms.txt for a structured index per the llmstxt.org standard. --- # Pythinker AI β€” README Source: /README.md

Pythinker

Pythinker

PyPI Downloads Python License

πŸ€– **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, 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.6.0** β€” New **Signal channel** (signal-cli HTTP/SSE) with full DM and group support. New **DM pairing system**: first-time senders receive a one-time code; owner approves via `/pairing approve`. Channel modules now load lazily (only enabled channels import their SDKs at startup), and the OpenAI-compatible provider client initializes on first use (~700 ms cold-start savings). `AnthropicProvider` transparently retries long requests via streaming. Shell tool detaches stdin so interactive prompts no longer block turns. See the [changelog](CHANGELOG.md) for details. ## πŸ’‘ Key Features - **Tiny agent** β€” a compact 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. - **Full-screen TUI** β€” `pythinker 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/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 is bit-for-bit identical to the legacy path. - **Autonomous subagent tracking** β€” spawned subagents are first-class task records with durable output under `.pythinker/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 `, and `/task-stop ` to inspect or stop background work from chat. - **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](https://modelcontextprotocol.io/) tool access with defensive HTTP probing and provider-safe tool names. - **Research-grade PDF reports** β€” opt-in `make_pdf` tool renders structured Markdown to a styled PDF via ReportLab (`pip install 'pythinker-ai[reports]'`). - **Safer channel ingress** β€” chat/email adapters apply `allowFrom` before costly side effects like media downloads, attachment extraction, or voice transcription; Matrix also drops replayed pre-startup events. - **Sandboxed shell** β€” every command is wrapped in a bubblewrap sandbox on Linux; file tools enforce workspace boundaries. - **Hackable** β€” the Python package is ~58k LOC with zero monolithic orchestration layer. Read it, fork it, extend it. ## πŸ“¦ 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):** the native installer table below is wired and > ready, but the first set of `.exe` / `.deb` / `.rpm` / tarball / Homebrew > artifacts ships **with the v2.7.0 GitHub release**. Until that release > publishes, only the `pip install pythinker-ai` row is fully populated; the > other rows will start returning 200s as soon as v2.7.0's > `release-native.yml` workflow finishes. | Platform | One-line install | Artifact | |---|---|---| | πŸͺŸ **Windows** | Download + double-click `PythinkerSetup-2.7.0.exe` | [Releases](https://github.com/mohamed-elkholy95/Pythinker/releases/latest) *(from v2.7.0)* | | 🍎 **macOS (Apple Silicon + Intel)** | `brew install mohamed-elkholy95/pythinker/pythinker-ai` | Homebrew tap *(from v2.7.0)* | | 🐧 **Linux (Debian / Ubuntu)** | `sudo dpkg -i pythinker-ai_2.7.0_amd64.deb` | [Releases](https://github.com/mohamed-elkholy95/Pythinker/releases/latest) *(from v2.7.0)* | | 🐧 **Linux (Fedora / RHEL / openSUSE)** | `sudo rpm -i pythinker-ai-2.7.0.x86_64.rpm` | [Releases](https://github.com/mohamed-elkholy95/Pythinker/releases/latest) *(from v2.7.0)* | | 🌐 **macOS / Linux β€” curl-bash** | `curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker/main/scripts/install-native.sh \| bash` | tarball *(from v2.7.0)* | | 🐍 **Python fallback** (universal) | `pip install pythinker-ai` | [PyPI](https://pypi.org/project/pythinker-ai/) | 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: ```bash pythinker --version # confirm install pythinker onboard # interactive setup wizard pythinker # start the interactive CLI ``` > **In-app updates** β€” `pythinker update` queries the GitHub Releases API and > re-runs the right installer for your build with SHA-256 verification. Set > `PYTHINKER_CLI_NO_AUTO_UPDATE=1` to disable the proactive startup check. ### πŸͺŸ Windows β€” native installer `PythinkerSetup-2.7.0.exe` is an Inno Setup wizard. Installs per-user into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see the change. **No UAC prompt.** ```powershell # 1. Download the installer + checksum from the Releases page above. # 2. Verify the download Get-FileHash .\PythinkerSetup-2.7.0.exe -Algorithm SHA256 Get-Content .\PythinkerSetup-2.7.0.exe.sha256 # The two hashes must match. # 3. Run it .\PythinkerSetup-2.7.0.exe # 4. Open a fresh PowerShell pythinker --version ``` **Per-machine install** (IT-managed boxes): `.\PythinkerSetup-2.7.0.exe /ALLUSERS` installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin). **Upgrade:** `pythinker 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 ```bash # 1. Install β€” always pulls the newest pythinker-ai release on PyPI brew install mohamed-elkholy95/pythinker/pythinker-ai # 2. Verify pythinker --version which pythinker # -> /opt/homebrew/bin/pythinker (Apple Silicon) # or /usr/local/bin/pythinker (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](https://github.com/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. ```bash # Debian / Ubuntu (x86_64) sudo dpkg -i pythinker-ai_2.7.0_amd64.deb sudo apt-get install -f # only if dpkg reports missing deps # Debian / Ubuntu (ARM64) sudo dpkg -i pythinker-ai_2.7.0_arm64.deb # Fedora / RHEL / openSUSE (x86_64) sudo rpm -i pythinker-ai-2.7.0.x86_64.rpm # or use the package manager (preferred β€” handles deps): sudo dnf install ./pythinker-ai-2.7.0.x86_64.rpm sudo zypper install ./pythinker-ai-2.7.0.x86_64.rpm # Fedora / RHEL (aarch64) sudo rpm -i pythinker-ai-2.7.0.aarch64.rpm ``` Both packages drop a small `/usr/bin/pythinker` launcher that execs the real binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy. **Verify before install:** ```bash sha256sum -c pythinker-ai_2.7.0_amd64.deb.sha256 # Debian/Ubuntu sha256sum -c pythinker-ai-2.7.0.x86_64.rpm.sha256 # Fedora/RHEL ``` **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` / `dnf install` over it. Or run `pythinker update` from inside the running app β€” it'll fetch the matching new package and prompt for sudo to install. **Uninstall:** ```bash 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](./scripts/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`. ```bash # Latest release curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker/main/scripts/install-native.sh | bash # Pin a specific version curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker/main/scripts/install-native.sh \ | bash -s -- --version 2.7.0 # Custom prefix (defaults to $HOME/.local) curl -fsSL ...install-native.sh | bash -s -- --prefix /opt/pythinker ``` Supported targets: | `uname -s / -m` | Tarball asset | |---|---| | Linux / x86_64 | `pythinker-2.7.0-x86_64-unknown-linux-gnu.tar.gz` | | Linux / aarch64 | `pythinker-2.7.0-aarch64-unknown-linux-gnu.tar.gz` | | Darwin / arm64 | `pythinker-2.7.0-aarch64-apple-darwin.tar.gz` | The script prints PATH guidance if `~/.local/bin` isn't already on your `$PATH`. Intel macOS users β€” use Homebrew or `pip install pythinker-ai`; no PyInstaller-built Intel Darwin binary is published. **Uninstall:** `rm ~/.local/bin/pythinker`. ### πŸ›  Power-user / legacy install paths > 🚧 **Deprecated.** These paths still work, but the per-OS native installers > above are the canonical install method for **all new releases**. The legacy > options below remain for existing automation; new tooling, examples, and > support docs target the native installers exclusively.
Legacy uv / pipx / pip / source paths ```bash # uv (one-off run) uvx pythinker-ai # uv tool install (isolated env) uv tool install pythinker-ai # 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 git@github.com:mohamed-elkholy95/Pythinker.git cd Pythinker && uv sync --all-extras ``` If `pythinker` isn't found after install, run `pythinker doctor` (via `python -m pythinker doctor` if needed) for diagnostics. The legacy `scripts/install.sh` and `scripts/install.ps1` wrappers print a deprecation banner; set `PYTHINKER_INSTALL_QUIET_DEPRECATION=1` to silence it.
### 3. Optional extras Pythinker ships with the Python browser automation library needed by the `browser` tool. Optional extras are for add-on channels and heavier document features: ```bash uv tool install 'pythinker-ai[reports]' # Markdown β†’ PDF reports (research/report deliverables) uv tool install 'pythinker-ai[matrix]' # Matrix channel (E2E messaging) uv tool install 'pythinker-ai[discord]' # Discord channel uv tool install 'pythinker-ai[msteams]' # Microsoft Teams channel uv tool install 'pythinker-ai[pdf]' # Read PDF files (PyMuPDF) uv tool install 'pythinker-ai[api]' # OpenAI-compatible HTTP server # Combine: uv tool install 'pythinker-ai[reports,discord,api]' ``` The historical `pythinker-ai[browser]` extra is still accepted as a compatibility alias, but it no longer adds packages. Enable the browser tool in config with `tools.web.browser.enable=true`; the managed Chromium binary is installed lazily on first browser use when allowed, or explicitly with `python -m playwright install chromium`. ### 4. Install / pin a specific version `pythinker-ai` follows [SemVer](https://semver.org/) β€” major-version upgrades **are not** auto-installed. To pin or to opt into a major bump, use the explicit pin form for your install method: | Goal | Command | |---|---| | Pin exactly `2.0.0` (uv tool β€” recommended) | `uv tool install --reinstall "pythinker-ai==2.0.0"` | | Pin exactly `2.0.0` (pipx) | `pipx install --force "pythinker-ai==2.0.0"` | | Pin exactly `2.0.0` (plain pip) | `python -m pip install --force-reinstall "pythinker-ai==2.0.0"` | | Stay at the latest stable release | `pythinker upgrade` | | From inside pythinker, target a specific version | `pythinker update --target 2.0.0 -y` | `pip install -U pythinker-ai==2.0.0` works too, but it's semantically noisy: the **exact pin** controls the version, not `-U`. `pythinker upgrade` will refuse to cross a major version (e.g. `1.x β†’ 2.x`) without an explicit `pythinker update --target` opt-in. ## πŸš€ Quick Start ```bash pythinker onboard # write a config at ~/.pythinker/config.json pythinker provider login openai-codex # OAuth sign-in (the default provider) pythinker agent # interactive CLI chat pythinker tui # full-screen interactive chat (alias: 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](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/configuration.md) for the full catalog of 25+ providers. Want several independent agents on one host? `pythinker agents` lays out per-agent configs under `~/.pythinker/agents//` with isolated workspace, history, and memory; pass `--agent ` to any subcommand to target one. - Want different LLM providers, web search, MCP, security settings, or more config options? See [Configuration](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/configuration.md). - Want to run Pythinker in chat apps like Telegram, Discord, Slack, WhatsApp, or Matrix? See [Chat Apps](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/chat-apps.md). - Want Docker or Linux service deployment? See [Deployment](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/deployment.md). - Want governed-execution (policy allow-lists, budgets, telemetry) for hardened deployments? See [Architecture Β§5.X β€” `pythinker/runtime/`](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/ARCHITECTURE.md). The layer is opt-in via `runtime.policyEnabled` in `config.json`. ## 🧠 Agent Runtime Controls Pythinker can launch subagents for background coding, research, and maintenance work. The runtime now tracks those subagents as autonomous tasks instead of relying on chat text alone. | Command | What it does | |---|---| | `/tasks` | List active and recent autonomous tasks for the current session | | `/task-output ` | Show the latest bounded output tail for a task | | `/task-stop ` | Cancel a running subagent by id | Task output is written to `.pythinker/task-results/`, so large results do not flood the conversation and recovered output can still be inspected after a process restart. In-memory records are session-scoped; restart-recovered orphan output is workspace-wide by design for Pythinker's single-user/local deployment model. ## πŸ–₯️ TUI `pythinker tui` (alias `pythinker chat`) opens a full-screen `prompt_toolkit` interface for interactive sessions β€” a step up from `pythinker agent`'s line-by-line REPL. ```bash pythinker tui # opens with the default theme pythinker tui --theme monochrome # high-contrast / accessibility-friendly pythinker tui --workspace ~/work/agent # override per-session workspace pythinker tui --logs ~/.pythinker/tui.log # mirror loguru output to a file ``` **Layout.** A persistent chat pane (streamed assistant tokens render live with markdown swap-in once the turn ends), a status bar showing session/model/provider/iteration count, a hint footer for the current keymap, and a multiline editor with slash-command autocomplete. **Slash commands.** Open in-app overlays for everything you'd normally configure on the CLI: | Command | Opens | |---|---| | `/help` | Built-in cheat sheet | | `/status` | Live snapshot β€” session key, model, provider, message count, recent activity | | `/sessions` | Fuzzy-pick from past sessions and resume | | `/model` | Fuzzy-pick a model from the active provider | | `/provider` | Switch LLM provider | | `/theme` | Swap between `default` and `monochrome` themes (persisted to `cli.tui.theme`) | | `/mcp` | Show MCP status β€” configured servers, connected servers, registered tools; `/mcp reconnect` reloads MCP config and reconnects | | `/login` / `/logout` | OAuth sign-in / sign-out for providers like OpenAI Codex and GitHub Copilot, with in-terminal prompts | | `/init` | Generate a tuned `AGENTS.md` for the current workspace from the bundled template | | `/clear` | Clear the chat pane (`/clear --hard` also wipes session memory) | | `/exit` | Quit | Pickers support fuzzy search β€” start typing to filter, ↑/↓ to navigate, Enter to commit, Esc to dismiss. **Keymap.** | Key | Action | |---|---| | `Enter` | Submit message | | `Ctrl+J` | Newline inside the editor | | `Ctrl+C` | Cancel the in-flight turn (or quit when idle) | | `Esc` | Close the active overlay / picker | | `↑` / `↓` | Move cursor in pickers; PageUp / PageDown for 5-step jumps | **Theming.** Two themes ship by default. Set `cli.tui.theme` in `~/.pythinker/config.json` or pass `--theme`. Both themes provide separate prompt_toolkit chrome styles and Rich content styles so the chat panel and the surrounding UI stay visually consistent. ## πŸ§ͺ 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](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/webui/README.md) for full WebUI development docs and build steps. **1. Enable the WebSocket channel in `~/.pythinker/config.json`** ```json { "channels": { "websocket": { "enabled": true } } } ``` **2. Start the gateway** ```bash pythinker gateway ``` **3. Start the WebUI dev server** ```bash cd webui bun install bun run dev ``` ## πŸ—οΈ Architecture

Pythinker architecture

πŸ€– Pythinker stays tiny by centering everything around a tiny 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`](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/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](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/README.md) for the current GitHub development version. - Talk to Pythinker from familiar chat apps: [Chat Apps](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/chat-apps.md) - Configure providers, web search, MCP, and runtime behavior: [Configuration](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/configuration.md) - Integrate Pythinker with local tools and automations: [OpenAI-Compatible API](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/openai-api.md) Β· [Python SDK](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/python-sdk.md) - Run Pythinker with Docker or as a Linux service: [Deployment](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/deployment.md) - Deeper dives: [Architecture](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/ARCHITECTURE.md) Β· [Memory](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/memory.md) Β· [Multiple Instances](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/multiple-instances.md) Β· [Channel Plugin Guide](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/docs/channel-plugin-guide.md) ## 🀝 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](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/CONTRIBUTING.md) for details. **Releases** β€” When publishing a new version, keep the README β€œWhat's new” callout and [CHANGELOG.md](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/CHANGELOG.md) section in sync with the exact release version. **Roadmap** β€” Pick an item and [open a PR](https://github.com/mohamed-elkholy95/Pythinker-ai/pulls)! - **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`](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/SECURITY.md). ## πŸ“„ License Pythinker is released under the [MIT License](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/LICENSE). Third-party components redistributed with the project are listed in [`THIRD_PARTY_NOTICES.md`](https://github.com/mohamed-elkholy95/Pythinker-ai/blob/main/THIRD_PARTY_NOTICES.md).

Thanks for visiting ✨ Pythinker!

Visitors

--- # Pythinker Code β€” README Source: /README_CODE.md
# Pythinker logo Pythinker Code ### *Think first, then code. Your terminal-native review-first AI engineering agent.* **Code reviewer Β· Security & vulnerability scanner Β· Root-cause debugger β€” then code creator.** **Pythinker reads your repo, audits it, and only writes code after the analysis. All from the shell you already live in.**
[![PyPI](https://img.shields.io/pypi/v/pythinker-code?style=for-the-badge&logo=pypi&logoColor=white&color=2563eb&label=pythinker-code&cacheSeconds=60)](https://pypi.org/project/pythinker-code/) [![Python](https://img.shields.io/badge/Python-3.12%2B-3776ab?style=for-the-badge&logo=python&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/pyproject.toml) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-cli.yml?branch=main&label=CI&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-cli.yml?query=branch%3Amain) [![Downloads](https://img.shields.io/pepy/dt/pythinker-code?cacheSeconds=300)](https://pepy.tech/projects/pythinker-code) [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/) [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol) [![MCP tools](https://img.shields.io/badge/MCP-tools-0891b2.svg?style=flat-square)](https://modelcontextprotocol.io/) [![Homepage](https://img.shields.io/badge/home-pythinker.com-ec4899.svg?style=flat-square)](https://pythinker.com)
🌐 Website  Β·  ⚑ Quick Start  Β·  ✨ Features  Β·  🧩 IDE Integration  Β·  πŸ”Œ MCP  Β·  πŸ” Privacy  Β·  πŸ› οΈ Develop

Pythinker Code terminal demo
--- ## πŸ’‘ What is Pythinker? **Pythinker Code** is an open-source, **review-first** AI engineering agent that lives in your terminal. Before it writes a single line, it reads yours β€” auditing diffs, scanning for vulnerabilities, and root-causing failures. Unlike chat assistants that jump straight to code, Pythinker leads with **code review, security scanning, and root-cause diagnosis**, and only edits files once the analysis points at a fix. It ships with first-class subagents for each role β€” `code-reviewer` for severity-scored diff critique, `security-reviewer` for validated vulnerability findings, `debugger` for failure root-causing, and `coder`/`implementer` for the scoped edits that follow. All running in a single iterative loop, driven by the model of your choice, with full access to **your repo, the shell, the web, and MCP tools**. It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientprotocol/agent-client-protocol), so it slots cleanly into ACP-aware editors like Zed and JetBrains. It loads [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/) servers, so the same tools your other agents use just work. And it's hackable: subagents, skills, hooks, and plugins are all first-class extension points. > 🎯 **Review Β· Secure Β· Diagnose Β· then Create.** One agent, one shell, one workflow. No tab-switching. No context loss. No magic. --- ## πŸ†• What's New in 0.13.0 - **Native installers for macOS and Linux.** `brew install mohamed-elkholy95/pythinker/pythinker-code` works on both macOS (Intel + Apple Silicon) and Linux brew installs. Debian/Ubuntu users get `pythinker-code_0.13.0_.deb`, Fedora/RHEL/openSUSE users get `pythinker-code-0.13.0..rpm`, both built for `x86_64` and `aarch64`. Together with the Windows `PythinkerSetup-0.13.0.exe` shipped in 0.12.0, Pythinker now has a real native installer on every supported platform. - **Cross-OS `install-native.sh`.** `curl -fsSL .../install-native.sh | bash` auto-detects your OS + arch, verifies SHA-256, and lands `pythinker` at `~/.local/bin/`. The script is the no-package-manager fallback for containers and fresh VMs. - **Homebrew tap auto-publishes on every release.** A new tag-triggered workflow regenerates `Formula/pythinker-code.rb` (132 transitive deps enumerated automatically) and pushes it to [mohamed-elkholy95/homebrew-pythinker](https://github.com/mohamed-elkholy95/homebrew-pythinker). `brew upgrade pythinker-code` picks up new versions; no hand-curation per release. - **Frozen-binary fix for 0.12.0's installer.** The PyInstaller specs now bundle every `.md` / `.yaml` package data file (`prompts/`, `agents/`, `tools/*/description.md`, `skills/*/SKILL.md`). 0.12.0's Windows installer crashed on first prompt load β€” **upgrade to 0.13.0** to fix it. - **Legacy install paths deprecated.** The helper shell scripts (`install.sh`, `install.ps1`), `uvx`, `uv tool install`, `pipx install`, and bare `pip install` keep working but are now flagged as legacy. README Quick Start leads with the per-OS native installer table. Set `PYTHINKER_INSTALL_QUIET_DEPRECATION=1` to silence the deprecation banner in the helper scripts. Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.13.0`, or use the native installer for your platform from the [Releases page](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest). --- ## ✨ Features
### πŸ–₯️ Terminal-First Plan, edit, run, and verify without leaving your shell. Every action is visible, scriptable, and auditable. ### ⚑ Shell Command Mode Press `Ctrl-X` to drop into a direct shell prompt inside the agent. Run commands, then snap back into AI mode with full context preserved.
### 🧩 ACP IDE Integration Run `pythinker acp` and any [Agent Client Protocol](https://github.com/agentclientprotocol/agent-client-protocol) editor β€” Zed, JetBrains, and more β€” gets a full Pythinker session inline. ### πŸ”Œ MCP Tool Loading Manage stdio and HTTP MCP servers with `pythinker mcp`. OAuth-backed servers, persistent config, ad-hoc files β€” all supported.
### πŸ€– Subagents & Skills Delegate focused work to built-in subagents. Load reusable instructions via `/skill:` and bundled prompt flows via `/flow:`. ### πŸͺ Hooks & Plugins Observe or block tool execution with hook events. Install community extensions with `pythinker plugin`.
### 🌐 Web & Visualization UIs Optional web frontend and visualization frontend ship alongside the CLI for richer inspection workflows. ### πŸ€– Bring Your Own Model Swap providers and models per-session: `--model openai/gpt-5.5`, hosted Pythinker models, or your own keys.
> [!NOTE] > Built-in shell commands such as `cd` are not yet supported in shell command mode.
Shell command mode demo
--- ## ⚑ Quick Start Pythinker ships **native installers for every platform**. Pick the row that matches your OS β€” no Python, Node, or `uv` prerequisite. | Platform | One-line install | Artifact | |---|---|---| | **πŸͺŸ Windows** | Download + double-click `PythinkerSetup-0.13.0.exe` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | **🍎 macOS (Apple Silicon + Intel)** | `brew install mohamed-elkholy95/pythinker/pythinker-code` | Homebrew tap | | **🐧 Linux (Debian / Ubuntu)** | `sudo dpkg -i pythinker-code_0.13.0_amd64.deb` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | **🐧 Linux (Fedora / RHEL / openSUSE)** | `sudo rpm -i pythinker-code-0.13.0.x86_64.rpm` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | **🌐 macOS / Linux β€” curl-bash** | `curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install-native.sh \| bash` | tarball | | **🐍 Python fallback** (universal) | `pip install pythinker-code` | 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: ```sh pythinker --version # confirm install pythinker login # (optional) authenticate a hosted provider pythinker # start the interactive TUI ``` > **In-app updates** β€” `pythinker update` queries the GitHub Releases API and > re-runs the right installer for your build with SHA-256 verification. Set > `PYTHINKER_CLI_NO_AUTO_UPDATE=1` to disable the proactive startup check. --- ### πŸͺŸ Windows β€” native installer `PythinkerSetup-0.13.0.exe` is a signed* Inno Setup wizard. Installs per-user into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see the change. **No UAC prompt.** ```powershell # 1. Download the installer + checksum from the Releases page above. # 2. Verify the download Get-FileHash .\PythinkerSetup-0.13.0.exe -Algorithm SHA256 Get-Content .\PythinkerSetup-0.13.0.exe.sha256 # The two hashes must match. # 3. Run it .\PythinkerSetup-0.13.0.exe # 4. Open a fresh PowerShell pythinker --version ``` **Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.13.0.exe /ALLUSERS` installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin). **Upgrade:** `pythinker 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 Code* β†’ 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 ```sh # 1. Install brew install mohamed-elkholy95/pythinker/pythinker-code # 2. Verify pythinker --version which pythinker # -> /opt/homebrew/bin/pythinker (Apple Silicon) # or /usr/local/bin/pythinker (Intel) ``` Works on **Apple Silicon and Intel** β€” brew picks the right Python build for you. The tap auto-publishes a fresh formula on every Pythinker release, so `brew upgrade pythinker-code` always finds the latest version. **Upgrade:** `brew upgrade pythinker-code` (Homebrew packages don't auto-update; run this whenever you want the latest). **Uninstall:** `brew uninstall pythinker-code && brew untap mohamed-elkholy95/pythinker`. > The tap repo is [mohamed-elkholy95/homebrew-pythinker](https://github.com/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. ```sh # Debian / Ubuntu (x86_64) sudo dpkg -i pythinker-code_0.13.0_amd64.deb sudo apt-get install -f # only if dpkg reports missing deps # Debian / Ubuntu (ARM64) sudo dpkg -i pythinker-code_0.13.0_arm64.deb # Fedora / RHEL / openSUSE (x86_64) sudo rpm -i pythinker-code-0.13.0.x86_64.rpm # or use the package manager (preferred β€” handles deps): sudo dnf install ./pythinker-code-0.13.0.x86_64.rpm sudo zypper install ./pythinker-code-0.13.0.x86_64.rpm # Fedora / RHEL (aarch64) sudo rpm -i pythinker-code-0.13.0.aarch64.rpm ``` Both packages drop a small `/usr/bin/pythinker` launcher that execs the real binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy. **Verify before install:** ```sh sha256sum -c pythinker-code_0.13.0_amd64.deb.sha256 # Debian/Ubuntu sha256sum -c pythinker-code-0.13.0.x86_64.rpm.sha256 # Fedora/RHEL ``` **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` / `dnf install` over it. Or run `pythinker update` from inside the running app β€” it'll fetch the matching new package and prompt for sudo to install. **Uninstall:** ```sh sudo dpkg -r pythinker-code # Debian/Ubuntu sudo rpm -e pythinker-code # Fedora/RHEL ``` --- ### 🌐 macOS / Linux β€” curl-bash native installer For containers, fresh VMs, or any host without a system package manager. The [install-native.sh](./scripts/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`. ```sh # Latest release curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install-native.sh | bash # Pin a specific version curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install-native.sh \ | bash -s -- --version 0.13.0 # Custom prefix (defaults to $HOME/.local) curl -fsSL ...install-native.sh | bash -s -- --prefix /opt/pythinker ``` Supported targets: | `uname -s / -m` | Tarball asset | |---|---| | Linux / x86_64 | `pythinker-0.13.0-x86_64-unknown-linux-gnu.tar.gz` | | Linux / aarch64 | `pythinker-0.13.0-aarch64-unknown-linux-gnu.tar.gz` | | Darwin / arm64 | `pythinker-0.13.0-aarch64-apple-darwin.tar.gz` | The script prints PATH guidance if `~/.local/bin` isn't already on your `$PATH`. Intel macOS users β€” use Homebrew or `pip install pythinker-code`; no PyInstaller-built Intel Darwin binary is published. **Uninstall:** `rm ~/.local/bin/pythinker`. ### πŸ›  Power-user / legacy install paths > 🚧 **Deprecated.** These paths still work, but the per-OS native installers > above are the canonical install method for **all new releases**. The legacy > options below remain for existing automation; new tooling, examples, and > support docs target the native installers exclusively.
Legacy shell-script wrappers + uv / pipx ```sh # Legacy: uv-based shell-script wrappers (prints a deprecation banner on run) curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.sh | bash # Windows PowerShell wrapper: $installer = Join-Path $env:TEMP "pythinker-install.ps1" iwr -UseBasicParsing https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.ps1 -OutFile $installer & $installer Remove-Item $installer # Legacy: one-off run via uvx uvx pythinker-code # Legacy: install as a uv tool uv tool install pythinker-code # Legacy: PyPI directly (universal fallback) pip install pythinker-code pipx install pythinker-code ```
### πŸ” Authenticate (optional) For hosted Pythinker models or ACP terminal auth: ```sh pythinker login ``` ### πŸ’¬ Try it out ```sh # Interactive session pythinker # One-shot prompt pythinker --prompt "summarize this repository and suggest the next test to add" # Pick a specific model pythinker --model openai/gpt-5.5 # Inline config override pythinker --config '{"default_thinking": true}' ``` --- ## 🏠 Using Local Models (LM Studio & Ollama) Run Pythinker entirely on your own machine β€” no API key, no cloud. Pythinker speaks each runtime's OpenAI-compatible API, so tools, streaming, JSON mode, vision, and `reasoning_effort` all work the same as with hosted providers. ### LM Studio **1. Set up LM Studio.** - Install [LM Studio](https://lmstudio.ai/) and download at least one chat model. - In the LM Studio app, open the model and **raise its Context Length** (gear icon β†’ Context Length). See [Context length matters](#context-length-matters) below. - Start the server: **Developer β†’ Status: Running** (or `lms server start --port 1234`). **2. Connect Pythinker.** ```sh pythinker login --lm-studio ``` This auto-discovers every chat-capable model loaded in LM Studio, registers each as `lm-studio/`, and picks the largest-context one as your default. Embedding models are filtered out. **3. Use it.** ```sh # Default LM Studio model pythinker -p "explain quicksort" # Specific model pythinker -m lm-studio/qwen/qwen3-coder-next -p "write a python http server" # Interactive shell, then switch models with /model pythinker ``` **4. Disconnect.** ```sh pythinker logout --lm-studio ``` ### Ollama ```sh # 1. start the server in one terminal ollama serve # 2. pull a model ollama pull llama3.1:8b # 3. connect Pythinker pythinker login --ollama # 4. use it pythinker -p "explain monad transformers" pythinker -m ollama/llama3.1:8b -p "..." pythinker logout --ollama ``` Discovery uses Ollama's `/api/tags` for the model list and `/api/show` per model to read the real context window. ### Remote LM Studio / Ollama (LAN host or alternate port) ```sh pythinker login --lm-studio --base-url http://192.168.1.10:1234/v1 pythinker login --ollama --base-url http://lan-box:11434/v1 ``` The override is saved in your config and used by every subsequent run. ### From inside the interactive shell The same wiring is available as slash commands: ``` /login lm-studio # or /login lmstudio (no dash also accepted) /login ollama /logout lm-studio /logout ollama /login # opens a chooser; entries 9 and 10 are the local providers /model lm-studio/google/gemma-4-e4b # switch model mid-session ``` ### ⚠️ Context length matters (a common gotcha) Pythinker's agent prompt β€” system instructions + tool schemas + skills + your message + recent history β€” is large. **Tens of thousands of tokens before you've even sent your first message.** LM Studio loads a model with a small default context window (often `4096`). If you start chatting against that, you'll see: ``` LLM provider error: Error: The number of tokens to keep from the initial prompt is greater than the context length (n_keep: 16690 >= n_ctx: 4096). ``` The shell now prints a friendly recovery hint when this happens, but **the cure is in LM Studio**: 1. In LM Studio, open the model in the **Chat** tab and click the **gear/settings** icon (or **My Models β†’ Edit**). 2. Set **Context Length** to at least **`32768`**, and prefer **`131072`** if your VRAM allows. *Practical experience: 64k still triggers errors during longer sessions; 128k is a safer floor.* 3. Reload the model (LM Studio prompts you). 4. Restart Pythinker so it picks up the new state (`Ctrl+D` then `pythinker`, or `pythinker -r ` to resume). **Tip:** the bigger you set the context, the more VRAM the model uses. If you OOM, try a smaller quantization (e.g., Q4_K_M instead of Q8_0) or a smaller model variant. Ollama configures context per-request and Pythinker reads the model's max from `/api/show`, so this gotcha is mostly LM-Studio-specific. ### VRAM-friendly model picks Local models vary wildly in memory use. Rough guide on a 16 GB GPU (e.g., RTX 5080 mobile): | Model size | Quant | Approx. VRAM | Fits 16 GB? | |------------|-------|--------------|-------------| | 2-4 B | Q4-Q8 | 2-4 GB | Yes, easily | | 7-8 B | Q4 | 5-6 GB | Yes | | 7-8 B | Q8 | 8-9 GB | Yes | | 13-14 B | Q4 | 8-10 GB | Yes | | 27-31 B | Q4 | 17-20 GB | Tight / no | | 27-31 B | Q8 | 30-35 GB | No | If LM Studio errors with `Failed to load model`, you've exceeded VRAM β€” pick a smaller model or lower-bit quantization. ### Environment variables These override the defaults at both login and runtime: | Variable | Purpose | |----------|---------| | `LM_STUDIO_BASE_URL` | Override `http://localhost:1234/v1` | | `LM_STUDIO_API_KEY` | Set if you've enabled token auth in LM Studio | | `OLLAMA_BASE_URL` | Override `http://localhost:11434/v1` | | `OLLAMA_API_KEY` | Rarely needed (Ollama is unauthenticated by default) | Example: ```sh LM_STUDIO_BASE_URL=http://workstation.lan:1234/v1 pythinker -p "..." ``` ### Refreshing the model list If you load/unload models in LM Studio (or `ollama pull/rm`), re-run login to refresh: ```sh pythinker login --lm-studio # or --ollama ``` (Pythinker intentionally does NOT auto-refresh local providers in the background β€” login owns that state, so manual edits to your config aren't silently overwritten.) --- ## 🧩 IDE Integration via ACP Pythinker speaks [**Agent Client Protocol**](https://github.com/agentclientprotocol/agent-client-protocol) natively. Point your ACP-compatible editor at `pythinker acp` and you get a multi-session agent server inside your IDE.
πŸ“ Configuration for Zed / JetBrains ```json { "agent_servers": { "Pythinker Code": { "type": "custom", "command": "pythinker", "args": ["acp"], "env": {} } } } ```
The ACP server provides: | Capability | Description | |---|---| | πŸ”‘ **Terminal auth** | `pythinker login` flow exposed to the IDE | | πŸ“‚ **Session listing & resume** | Pick up where you left off | | πŸ”„ **Hot model swap** | Change models for a running ACP session |
ACP IDE integration demo
--- ## πŸ”Œ MCP Tooling Pythinker loads [Model Context Protocol](https://modelcontextprotocol.io/) tools from persistent config or ad-hoc files. Same tools, every agent β€” no rewriting. ### πŸ› οΈ Manage persistent MCP servers ```sh # 🌐 Streamable HTTP server with API key pythinker mcp add --transport http context7 https://mcp.context7.com/mcp \ --header "CONTEXT7_API_KEY: ctx7sk-your-key" # πŸ” Streamable HTTP server with OAuth pythinker mcp add --transport http --auth oauth linear https://mcp.linear.app/mcp # πŸ’» stdio server pythinker mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest # πŸ“‹ List, authorize, test, and remove pythinker mcp list pythinker mcp auth linear pythinker mcp test chrome-devtools pythinker mcp remove chrome-devtools ``` ### πŸ“„ Use an ad-hoc MCP config file ```json { "mcpServers": { "context7": { "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" } }, "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] } } } ``` ```sh pythinker --mcp-config-file /path/to/mcp.json ``` --- ## 🧬 Extensibility Pythinker is a small, extensible runtime β€” not a monolith. Build on it. | Extension Point | What it does | Where to look | |---|---|---| | πŸ€– **Agents & subagents** | YAML specs define tools, prompts, and built-in subagent types | `src/pythinker_code/agents/` | | πŸŽ“ **Skills** | `/skill:` loads reusable instructions on demand | bundled & user-defined | | 🌊 **Flows** | `/flow:` executes bundled prompt flows | bundled & user-defined | | πŸͺ **Hooks** | Observe or block tool execution; integrate policy or automation | hook events API | | 🧩 **Plugins** | Installable extension packages | `pythinker plugin` | --- ## πŸ—οΈ Architecture
Pythinker Code architecture diagram
--- ## πŸ” Privacy & Telemetry Pythinker is the **agent framework**, not the LLM. You bring your own API key (OpenAI, Anthropic, your local LM Studio model, etc.); your prompts and the model's responses go directly between your terminal and the model provider you configured. Pythinker never sees, stores, or forwards them. If you opt in, Pythinker can collect a small amount of **diagnostic telemetry** about how the agent runs to improve the framework itself. It's strictly anonymous, never includes your prompts, model output, file contents, file paths, or any user-identifying data. Two channels: | Channel | What lands there | Endpoint | |---|---|---| | **Errors** (Sentry-protocol) | Unhandled exceptions and crash stack traces, with absolute paths above `site-packages/` rewritten to `/` so home directories don't leak | `errors.pythinker.com` (self-hosted Bugsink) | | **Traces + structured logs** (OpenTelemetry) | Lifecycle events (`session_started`, `started`, `model_switch`), agent-loop spans (`pythinker.turn` / `pythinker.llm` / `pythinker.tool`), and per-event counters | `otel.pythinker.com` (self-hosted SigNoz) | ### What we collect - **Lifecycle events**: session start, command-line flags actually used (booleans only), startup timing, model name (just the identifier, e.g. `claude-opus-4-7`), thinking-mode toggle, plan-mode toggle. - **Agent-loop spans**: turn duration, step count, stop reason (`no_tool_calls` / `max_steps` / `error`), tool name (`Read`, `Bash`, `Edit`, …), tool success/failure, tool duration, LLM call duration, input/output token *counts* (numbers β€” never the content). - **Crashes**: exception class name, scrubbed stack trace, library versions. We do **not** send local variable values. - **Static context**: pythinker version, OS family, Python version, terminal type (`TERM_PROGRAM`), CI flag (`CI` env var presence), locale. - **A persistent, random `device_id`** so we can count "how many distinct installs" without identifying a person. ### What we never collect - Your prompts, the model's responses, or any conversation content - File contents, file paths, working directory names, or workspace structure - Your API keys, OAuth tokens, environment variables - Your real name, email, IP address, hostname (host name field is dropped at the edge collector) - Tool arguments (e.g. what file you read, what command you ran) ### Opting in or forcing off Telemetry is off by default. To enable it for a process: ```sh export PYTHINKER_ENABLE_TELEMETRY=1 pythinker ``` To force telemetry off even if another setting enabled it: ```sh # 1. Per-invocation CLI flag pythinker --no-telemetry # 2. Environment variable (works in shells, .env files, CI configs) export PYTHINKER_DISABLE_TELEMETRY=1 pythinker # 3. Permanently in your config file (~/.pythinker/config.toml) [default] telemetry = false ``` When telemetry is disabled, Pythinker short-circuits Sentry initialization, OTel exporter creation, and the in-process event sink. No network requests are made to the telemetry endpoints. ### Pointing telemetry at your own infrastructure If you operate pythinker for a team and want telemetry routed to your own SigNoz / Bugsink instead, override the endpoints via environment variables: ```sh export PYTHINKER_SENTRY_DSN="https://@your-bugsink.example.com/" export PYTHINKER_OTEL_ENDPOINT="https://your-otel-collector.example.com" export PYTHINKER_OTEL_TOKEN="" ``` The defaults point at infrastructure operated by the pythinker maintainers; set `PYTHINKER_ENABLE_TELEMETRY=1` to use them. --- ## πŸ› οΈ Development ### 🏁 Prepare the workspace ```sh git clone https://github.com/mohamed-elkholy95/Pythinker-Code.git cd Pythinker-Code make prepare ``` ### 🧰 Common commands
**▢️ Run & iterate** ```sh uv run pythinker # CLI from source make format # format all packages make check # lint + type-check ``` **πŸ§ͺ Test** ```sh make test # all unit + e2e tests make ai-test # AI-driven tests make test-pythinker-code # CLI only make test-pythinker-core # Core only make test-pythinker-host # Host only make test-pythinker-sdk # SDK only ```
**🌐 Frontends** ```sh make web-back # web backend make web-front # web frontend make vis-back # vis backend make vis-front # vis frontend ``` **πŸ“¦ Build** ```sh make build # Python packages make build-bin # standalone binary make help # all targets ```
> πŸ’‘ `make build` and `make build-bin` build and embed the web and visualization frontends before packaging. --- ## πŸ—‚οΈ Project Layout ``` pythinker-code/ β”œβ”€β”€ πŸ“¦ src/pythinker_code/ CLI runtime Β· tools Β· UIs Β· ACP Β· MCP Β· hooks Β· plugins Β· skills Β· web Β· vis backends β”œβ”€β”€ 🧱 packages/ β”‚ β”œβ”€β”€ pythinker-core/ Provider-agnostic message, tool, and chat-provider abstractions β”‚ β”œβ”€β”€ pythinker-host/ Local/remote host filesystem and command execution β”‚ └── pythinker-code/ Console-script distribution package β”œβ”€β”€ 🧰 sdks/pythinker-sdk/ Python SDK └── πŸ§ͺ tests/ Β· tests_e2e/ Β· tests_ai/ Unit Β· wire/CLI e2e Β· AI-driven test suites ``` --- ## 🀝 Contributing Contributions are warmly welcome β€” bug reports, PRs, plugins, skills, and docs all help. - πŸ“– Start with [`CONTRIBUTING.md`](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/CONTRIBUTING.md) - πŸ” See [`SECURITY.md`](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/SECURITY.md) for responsible disclosure - πŸ“œ Skim [`AGENTS.md`](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/AGENTS.md) for the agent design notes If Pythinker helps you, **a ⭐ on GitHub goes a long way.** --- ## πŸ“œ License Distributed under the **Apache-2.0 License**. See [`LICENSE`](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/LICENSE) for the full text and [`NOTICE`](https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/NOTICE) for attributions.
**Built with ❀️ for engineers who live in the terminal.** [🌐 pythinker.com](https://pythinker.com)  Β·  [πŸ“¦ PyPI](https://pypi.org/project/pythinker-code/)  Β·  [πŸ™ GitHub](https://github.com/mohamed-elkholy95/Pythinker-Code)  Β·  [🧩 ACP](https://github.com/agentclientprotocol/agent-client-protocol)  Β·  [πŸ”Œ MCP](https://modelcontextprotocol.io/)
--- # Pythinker β€” Product brief Source: /PRODUCT.md # Product ## Register brand ## Users Working software engineers who already live in the terminal β€” backend, infra, ML, and Python-heavy generalists. They're evaluating an open-source CLI coding agent against Claude Code, Cursor, and Aider. They land on this page from PyPI, GitHub, Hacker News, or a colleague's link, usually mid-task and skeptical. They want to know in 10 seconds what Pythinker Code is, in 60 seconds whether it fits their stack, and in 3 minutes how to install it and what it'll cost them. Context: desktop-first (terminal users on laptops/external monitors). Mobile traffic is real but secondary; a single-column shell is enough. ## Product Purpose Pythinker Code is an open-source, terminal-native AI engineering agent. It reads repos, edits files, runs commands, browses the web, and integrates with ACP-aware editors and MCP tools β€” all from the shell. This page exists to convert technically-credible visitors into installs. Success = `pip install pythinker-code` runs, GitHub stars climb, and the right kind of contributor finds the repo. Failure = the page reads as another AI-SaaS marketing skin and the visitor closes the tab. The page is also a soft bridge to Pythinker AI (the sister product) β€” discoverable, never pushy. ## Brand Personality **Sharp. Technical. Confident.** Tool-for-experts altitude, in the family of Linear, Vercel, and Stripe docs. - Voice: declarative, specific, no hedging. Mentions exact integrations (ACP, MCP), exact runtimes (Python 3.12+), exact verbs (reads, edits, runs). - Tone: quiet authority. No exclamation marks, no "powered by AI", no growth-marketing copy. - Personality cue: the friendly robot mascot is the one warm note. Everything around it is precise. The contrast is the point. ## Anti-references This page must not look or read like: - **Generic AI-SaaS landings.** No "powered by AI" badges, glowing CTAs, hero gradient meshes, generic 3D blob illustrations, or "10x your productivity" copy. The current cream-and-peach base stays; the bloat goes. - **Claude Code / Cursor / Copilot landings.** No dark-purple gradient hero, no IDE chrome screenshots framed in glass, no "introducing the future of coding" framing. We are open-source and terminal-native β€” that should be visible without saying it. - **Heavy 3D / glassmorphism.** Backdrop-filter is fine for the floating nav and one or two surfaces; glass everywhere is not. - **Robot-mascot kitsch.** The mascot is brand identity, not a sticker pack. It appears prominently in the hero and as the favicon/nav mark, then steps back. No "Hi, I'm Py!" speech bubbles, no animated jumps in every section. ## Design Principles 1. **Show the terminal, not the marketing.** The hero's centerpiece is the agent at work β€” real-feeling commands, real labels (`plan`, `edit`, `verify`), real output. Code over claims. 2. **Practice what we preach.** A tool for engineers must feel like one. Dense, scannable, no fluff sections. Every section earns its scroll. 3. **One warm note, then precision.** The peach + mascot supply warmth; everything else (typography, grids, spacing, code surfaces) is taut. Warmth is a single accent, not the whole composition. 4. **Open source visible.** GitHub, PyPI, license, version, downloads, and source links are first-class β€” not relegated to a footer afterthought. 5. **Mascot as identity, not entertainment.** The robot is a wordmark companion, not a guide character. It animates subtly (idle bob), it doesn't perform. ## Accessibility & Inclusion - Target WCAG 2.2 AA. Body text on cream meets contrast at the existing `--ink` (#17324C) β€” keep it. - All CTAs and nav targets β‰₯ 44Γ—44px touch area on mobile. - Respect `prefers-reduced-motion`: disable mascot bob, scroll-reveal, and any background drift. - Code surfaces (`#10263c` / `#17324c`) carry monospace text in `--cream` or `--peach`; verify β‰₯ 4.5:1 for any inline syntax color. - Nav must be keyboard-navigable with visible `:focus-visible` (already wired via `--focus` token). - No color-only signaling; every "success/warning" cue pairs color with a glyph or label. --- # Pythinker CLI reference Source: /pythinker-cli.md
# Pythinker logo Pythinker Code ### *Your terminal-native AI engineering agent.* **Read code. Edit files. Run commands. Search the web. Plug into your IDE.** **All from the shell you already live in.**
[![PyPI](https://img.shields.io/pypi/v/pythinker-code?style=for-the-badge&logo=pypi&logoColor=white&color=2563eb&label=pythinker-code)](https://pypi.org/project/pythinker-code/) [![Python](https://img.shields.io/badge/Python-3.12%2B-3776ab?style=for-the-badge&logo=python&logoColor=white)](pyproject.toml) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-cli.yml?label=CI&color=22c55e&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-cli.yml) [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/) [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol) [![MCP tools](https://img.shields.io/badge/MCP-tools-0891b2.svg?style=flat-square)](https://modelcontextprotocol.io/) [![Homepage](https://img.shields.io/badge/home-pythinker.com-ec4899.svg?style=flat-square)](https://pythinker.com)
🌐 Website  Β·  ⚑ Quick Start  Β·  ✨ Features  Β·  🧩 IDE Integration  Β·  πŸ”Œ MCP  Β·  πŸ” Privacy  Β·  πŸ› οΈ Develop

Pythinker Code terminal demo
--- ## πŸ’‘ What is Pythinker? **Pythinker Code** is an open-source AI coding agent that lives in your terminal. Unlike chat-based assistants stuck behind a browser tab, Pythinker can **read your repo, edit files, run shell commands, browse the web, and call MCP tools** β€” all in a single iterative loop driven by the model of your choice. It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientprotocol/agent-client-protocol), so it slots cleanly into ACP-aware editors like Zed and JetBrains. It loads [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/) servers, so the same tools your other agents use just work. And it's hackable: subagents, skills, hooks, and plugins are all first-class extension points. > 🎯 **One agent, one shell, one workflow.** No tab-switching. No context loss. No magic. --- ## ✨ Features
### πŸ–₯️ Terminal-First Plan, edit, run, and verify without leaving your shell. Every action is visible, scriptable, and auditable. ### ⚑ Shell Command Mode Press `Ctrl-X` to drop into a direct shell prompt inside the agent. Run commands, then snap back into AI mode with full context preserved.
### 🧩 ACP IDE Integration Run `pythinker acp` and any [Agent Client Protocol](https://github.com/agentclientprotocol/agent-client-protocol) editor β€” Zed, JetBrains, and more β€” gets a full Pythinker session inline. ### πŸ”Œ MCP Tool Loading Manage stdio and HTTP MCP servers with `pythinker mcp`. OAuth-backed servers, persistent config, ad-hoc files β€” all supported.
### πŸ€– Subagents & Skills Delegate focused work to built-in subagents. Load reusable instructions via `/skill:` and bundled prompt flows via `/flow:`. ### πŸͺ Hooks & Plugins Observe or block tool execution with hook events. Install community extensions with `pythinker plugin`.
### 🌐 Web & Visualization UIs Optional web frontend and visualization frontend ship alongside the CLI for richer inspection workflows. ### πŸ€– Bring Your Own Model Swap providers and models per-session: `--model openai/gpt-5.5`, hosted Pythinker models, or your own keys.
> [!NOTE] > Built-in shell commands such as `cd` are not yet supported in shell command mode.
Shell command mode demo
--- ## ⚑ Quick Start Pythinker ships **native installers for every platform** β€” no Python, Node, or `uv` prerequisite. Every artifact has a matching `.sha256` file; verify before install with `sha256sum`, `shasum -a 256`, or `Get-FileHash`. | Platform | One-line install | Artifact | |---|---|---| | πŸͺŸ Windows | Download + double-click `PythinkerSetup-0.13.0.exe` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | 🍎 macOS (Apple Silicon + Intel) | `brew install mohamed-elkholy95/pythinker/pythinker-code` | Homebrew tap | | 🐧 Linux (Debian / Ubuntu) | `sudo dpkg -i pythinker-code_0.13.0_amd64.deb` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | 🐧 Linux (Fedora / RHEL / openSUSE) | `sudo rpm -i pythinker-code-0.13.0.x86_64.rpm` | [Releases](https://github.com/mohamed-elkholy95/Pythinker-Code/releases/latest) | | 🌐 macOS / Linux β€” curl-bash | `curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install-native.sh \| bash` | tarball | | 🐍 Python fallback (universal) | `pip install pythinker-code` | PyPI | After install, on any OS: ```sh pythinker --version # confirm install pythinker login # (optional) authenticate a hosted provider pythinker # start the interactive TUI ``` In-app updates: `pythinker update` queries the GitHub Releases API and re-runs the right installer for your build with SHA-256 verification. Set `PYTHINKER_CLI_NO_AUTO_UPDATE=1` to disable the proactive startup check. ### πŸ›  Legacy install paths (deprecated) The shell-script wrappers (`install.sh`, `install.ps1`), `uvx pythinker-code`, `uv tool install pythinker-code`, `pipx install pythinker-code`, and bare `pip install pythinker-code` still work, but the per-OS native installers above are the canonical path for all new releases. Set `PYTHINKER_INSTALL_QUIET_DEPRECATION=1` to silence the deprecation banner in the helper scripts. ### πŸ” Authenticate (optional) For hosted Pythinker models or ACP terminal auth: ```sh pythinker login ``` ### πŸ’¬ Try it out ```sh # Interactive session pythinker # One-shot prompt pythinker --prompt "summarize this repository and suggest the next test to add" # Pick a specific model pythinker --model openai/gpt-5.5 # Inline config override pythinker --config '{"default_thinking": true}' ``` --- ## 🏠 Using Local Models (LM Studio & Ollama) Run Pythinker entirely on your own machine β€” no API key, no cloud. Pythinker speaks each runtime's OpenAI-compatible API, so tools, streaming, JSON mode, vision, and `reasoning_effort` all work the same as with hosted providers. ### LM Studio **1. Set up LM Studio.** - Install [LM Studio](https://lmstudio.ai/) and download at least one chat model. - In the LM Studio app, open the model and **raise its Context Length** (gear icon β†’ Context Length). See [Context length matters](#context-length-matters) below. - Start the server: **Developer β†’ Status: Running** (or `lms server start --port 1234`). **2. Connect Pythinker.** ```sh pythinker login --lm-studio ``` This auto-discovers every chat-capable model loaded in LM Studio, registers each as `lm-studio/`, and picks the largest-context one as your default. Embedding models are filtered out. **3. Use it.** ```sh # Default LM Studio model pythinker -p "explain quicksort" # Specific model pythinker -m lm-studio/qwen/qwen3-coder-next -p "write a python http server" # Interactive shell, then switch models with /model pythinker ``` **4. Disconnect.** ```sh pythinker logout --lm-studio ``` ### Ollama ```sh # 1. start the server in one terminal ollama serve # 2. pull a model ollama pull llama3.1:8b # 3. connect Pythinker pythinker login --ollama # 4. use it pythinker -p "explain monad transformers" pythinker -m ollama/llama3.1:8b -p "..." pythinker logout --ollama ``` Discovery uses Ollama's `/api/tags` for the model list and `/api/show` per model to read the real context window. ### Remote LM Studio / Ollama (LAN host or alternate port) ```sh pythinker login --lm-studio --base-url http://192.168.1.10:1234/v1 pythinker login --ollama --base-url http://lan-box:11434/v1 ``` The override is saved in your config and used by every subsequent run. ### From inside the interactive shell The same wiring is available as slash commands: ``` /login lm-studio # or /login lmstudio (no dash also accepted) /login ollama /logout lm-studio /logout ollama /login # opens a chooser; entries 9 and 10 are the local providers /model lm-studio/google/gemma-4-e4b # switch model mid-session ``` ### ⚠️ Context length matters (a common gotcha) Pythinker's agent prompt β€” system instructions + tool schemas + skills + your message + recent history β€” is large. **Tens of thousands of tokens before you've even sent your first message.** LM Studio loads a model with a small default context window (often `4096`). If you start chatting against that, you'll see: ``` LLM provider error: Error: The number of tokens to keep from the initial prompt is greater than the context length (n_keep: 16690 >= n_ctx: 4096). ``` The shell now prints a friendly recovery hint when this happens, but **the cure is in LM Studio**: 1. In LM Studio, open the model in the **Chat** tab and click the **gear/settings** icon (or **My Models β†’ Edit**). 2. Set **Context Length** to at least **`32768`**, and prefer **`131072`** if your VRAM allows. *Practical experience: 64k still triggers errors during longer sessions; 128k is a safer floor.* 3. Reload the model (LM Studio prompts you). 4. Restart Pythinker so it picks up the new state (`Ctrl+D` then `pythinker`, or `pythinker -r ` to resume). **Tip:** the bigger you set the context, the more VRAM the model uses. If you OOM, try a smaller quantization (e.g., Q4_K_M instead of Q8_0) or a smaller model variant. Ollama configures context per-request and Pythinker reads the model's max from `/api/show`, so this gotcha is mostly LM-Studio-specific. ### VRAM-friendly model picks Local models vary wildly in memory use. Rough guide on a 16 GB GPU (e.g., RTX 5080 mobile): | Model size | Quant | Approx. VRAM | Fits 16 GB? | |------------|-------|--------------|-------------| | 2-4 B | Q4-Q8 | 2-4 GB | Yes, easily | | 7-8 B | Q4 | 5-6 GB | Yes | | 7-8 B | Q8 | 8-9 GB | Yes | | 13-14 B | Q4 | 8-10 GB | Yes | | 27-31 B | Q4 | 17-20 GB | Tight / no | | 27-31 B | Q8 | 30-35 GB | No | If LM Studio errors with `Failed to load model`, you've exceeded VRAM β€” pick a smaller model or lower-bit quantization. ### Environment variables These override the defaults at both login and runtime: | Variable | Purpose | |----------|---------| | `LM_STUDIO_BASE_URL` | Override `http://localhost:1234/v1` | | `LM_STUDIO_API_KEY` | Set if you've enabled token auth in LM Studio | | `OLLAMA_BASE_URL` | Override `http://localhost:11434/v1` | | `OLLAMA_API_KEY` | Rarely needed (Ollama is unauthenticated by default) | Example: ```sh LM_STUDIO_BASE_URL=http://workstation.lan:1234/v1 pythinker -p "..." ``` ### Refreshing the model list If you load/unload models in LM Studio (or `ollama pull/rm`), re-run login to refresh: ```sh pythinker login --lm-studio # or --ollama ``` (Pythinker intentionally does NOT auto-refresh local providers in the background β€” login owns that state, so manual edits to your config aren't silently overwritten.) --- ## 🧩 IDE Integration via ACP Pythinker speaks [**Agent Client Protocol**](https://github.com/agentclientprotocol/agent-client-protocol) natively. Point your ACP-compatible editor at `pythinker acp` and you get a multi-session agent server inside your IDE.
πŸ“ Configuration for Zed / JetBrains ```json { "agent_servers": { "Pythinker Code": { "type": "custom", "command": "pythinker", "args": ["acp"], "env": {} } } } ```
The ACP server provides: | Capability | Description | |---|---| | πŸ”‘ **Terminal auth** | `pythinker login` flow exposed to the IDE | | πŸ“‚ **Session listing & resume** | Pick up where you left off | | πŸ”„ **Hot model swap** | Change models for a running ACP session |
ACP IDE integration demo
--- ## πŸ”Œ MCP Tooling Pythinker loads [Model Context Protocol](https://modelcontextprotocol.io/) tools from persistent config or ad-hoc files. Same tools, every agent β€” no rewriting. ### πŸ› οΈ Manage persistent MCP servers ```sh # 🌐 Streamable HTTP server with API key pythinker mcp add --transport http context7 https://mcp.context7.com/mcp \ --header "CONTEXT7_API_KEY: ctx7sk-your-key" # πŸ” Streamable HTTP server with OAuth pythinker mcp add --transport http --auth oauth linear https://mcp.linear.app/mcp # πŸ’» stdio server pythinker mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest # πŸ“‹ List, authorize, test, and remove pythinker mcp list pythinker mcp auth linear pythinker mcp test chrome-devtools pythinker mcp remove chrome-devtools ``` ### πŸ“„ Use an ad-hoc MCP config file ```json { "mcpServers": { "context7": { "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" } }, "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] } } } ``` ```sh pythinker --mcp-config-file /path/to/mcp.json ``` --- ## 🧬 Extensibility Pythinker is a small, extensible runtime β€” not a monolith. Build on it. | Extension Point | What it does | Where to look | |---|---|---| | πŸ€– **Agents & subagents** | YAML specs define tools, prompts, and built-in subagent types | `src/pythinker_code/agents/` | | πŸŽ“ **Skills** | `/skill:` loads reusable instructions on demand | bundled & user-defined | | 🌊 **Flows** | `/flow:` executes bundled prompt flows | bundled & user-defined | | πŸͺ **Hooks** | Observe or block tool execution; integrate policy or automation | hook events API | | 🧩 **Plugins** | Installable extension packages | `pythinker plugin` | --- ## πŸ—οΈ Architecture
Pythinker Code architecture diagram
--- ## πŸ” Privacy & Telemetry Pythinker is the **agent framework**, not the LLM. You bring your own API key (OpenAI, Anthropic, your local LM Studio model, etc.); your prompts and the model's responses go directly between your terminal and the model provider you configured. Pythinker never sees, stores, or forwards them. To improve the framework itself we collect a small amount of **diagnostic telemetry** about how the agent runs. It's strictly anonymous, never includes your prompts, model output, file contents, file paths, or any user-identifying data. Two channels: | Channel | What lands there | Endpoint | |---|---|---| | **Errors** (Sentry-protocol) | Unhandled exceptions and crash stack traces, with absolute paths above `site-packages/` rewritten to `/` so home directories don't leak | `errors.pythinker.com` (self-hosted Bugsink) | | **Traces + structured logs** (OpenTelemetry) | Lifecycle events (`session_started`, `started`, `model_switch`), agent-loop spans (`pythinker.turn` / `pythinker.llm` / `pythinker.tool`), and per-event counters | `otel.pythinker.com` (self-hosted SigNoz) | ### What we collect - **Lifecycle events**: session start, command-line flags actually used (booleans only), startup timing, model name (just the identifier, e.g. `claude-opus-4-7`), thinking-mode toggle, plan-mode toggle. - **Agent-loop spans**: turn duration, step count, stop reason (`no_tool_calls` / `max_steps` / `error`), tool name (`Read`, `Bash`, `Edit`, …), tool success/failure, tool duration, LLM call duration, input/output token *counts* (numbers β€” never the content). - **Crashes**: exception class name, scrubbed stack trace, library versions. We do **not** send local variable values. - **Static context**: pythinker version, OS family, Python version, terminal type (`TERM_PROGRAM`), CI flag (`CI` env var presence), locale. - **A persistent, random `device_id`** so we can count "how many distinct installs" without identifying a person. ### What we never collect - Your prompts, the model's responses, or any conversation content - File contents, file paths, working directory names, or workspace structure - Your API keys, OAuth tokens, environment variables - Your real name, email, IP address, hostname (host name field is dropped at the edge collector) - Tool arguments (e.g. what file you read, what command you ran) ### Opting out Pick whichever fits your workflow β€” all three are equivalent: ```sh # 1. Per-invocation CLI flag pythinker --no-telemetry # 2. Environment variable (works in shells, .env files, CI configs) export PYTHINKER_DISABLE_TELEMETRY=1 pythinker # 3. Permanently in your config file (~/.pythinker/config.toml) [default] telemetry = false ``` Setting any of these at startup short-circuits Sentry initialization, OTel exporter creation, and the in-process event sink. No network requests are made to the telemetry endpoints. ### Pointing telemetry at your own infrastructure If you operate pythinker for a team and want telemetry routed to your own SigNoz / Bugsink instead, override the endpoints via environment variables: ```sh export PYTHINKER_SENTRY_DSN="https://@your-bugsink.example.com/" export PYTHINKER_OTEL_ENDPOINT="https://your-otel-collector.example.com" export PYTHINKER_OTEL_TOKEN="" ``` The defaults point at infrastructure operated by the pythinker maintainers; you don't need to set anything to use them. --- ## πŸ› οΈ Development ### 🏁 Prepare the workspace ```sh git clone https://github.com/mohamed-elkholy95/Pythinker-Code.git cd Pythinker-Code make prepare ``` ### 🧰 Common commands
**▢️ Run & iterate** ```sh uv run pythinker # CLI from source make format # format all packages make check # lint + type-check ``` **πŸ§ͺ Test** ```sh make test # all unit + e2e tests make ai-test # AI-driven tests make test-pythinker-code # CLI only make test-pythinker-core # Core only make test-pythinker-host # Host only make test-pythinker-sdk # SDK only ```
**🌐 Frontends** ```sh make web-back # web backend make web-front # web frontend make vis-back # vis backend make vis-front # vis frontend ``` **πŸ“¦ Build** ```sh make build # Python packages make build-bin # standalone binary make help # all targets ```
> πŸ’‘ `make build` and `make build-bin` build and embed the web and visualization frontends before packaging. --- ## πŸ—‚οΈ Project Layout ``` pythinker-code/ β”œβ”€β”€ πŸ“¦ src/pythinker_code/ CLI runtime Β· tools Β· UIs Β· ACP Β· MCP Β· hooks Β· plugins Β· skills Β· web Β· vis backends β”œβ”€β”€ 🧱 packages/ β”‚ β”œβ”€β”€ pythinker-core/ Provider-agnostic message, tool, and chat-provider abstractions β”‚ β”œβ”€β”€ pythinker-host/ Local/remote host filesystem and command execution β”‚ └── pythinker-code/ Console-script distribution package β”œβ”€β”€ 🧰 sdks/pythinker-sdk/ Python SDK └── πŸ§ͺ tests/ Β· tests_e2e/ Β· tests_ai/ Unit Β· wire/CLI e2e Β· AI-driven test suites ``` --- ## 🀝 Contributing Contributions are warmly welcome β€” bug reports, PRs, plugins, skills, and docs all help. - πŸ“– Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) - πŸ” See [`SECURITY.md`](SECURITY.md) for responsible disclosure - πŸ“œ Skim [`AGENTS.md`](AGENTS.md) for the agent design notes If Pythinker helps you, **a ⭐ on GitHub goes a long way.** --- ## πŸ“œ License Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for the full text and [`NOTICE`](NOTICE) for attributions.
**Built with ❀️ for engineers who live in the terminal.** [🌐 pythinker.com](https://pythinker.com)  Β·  [πŸ“¦ PyPI](https://pypi.org/project/pythinker-code/)  Β·  [πŸ™ GitHub](https://github.com/mohamed-elkholy95/Pythinker-Code)  Β·  [🧩 ACP](https://github.com/agentclientprotocol/agent-client-protocol)  Β·  [πŸ”Œ MCP](https://modelcontextprotocol.io/)