Pythinker Cli

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.

[](https://pypi.org/project/pythinker-code/) [](https://pepy.tech/projects/pythinker-code) [](https://github.com/Pythoughts-labs/pythinker-cli/blob/main/LICENSE)

[](https://docs.astral.sh/ruff/) [](https://pythinker.com) [](https://github.com/Pythoughts-labs/pythinker-cli/actions/workflows/ci-pythinker-cli.yml?query=branch%3Amain) [](https://github.com/Pythoughts-labs/pythinker-cli/blob/main/pyproject.toml)

🌐 Website  ·  ⚡ Quick Start  ·  ✨ Features  ·  🧩 IDE Integration  ·  🔌 MCP  ·  🔐 Privacy  ·  🛠️ Develop

---

💡 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), so it slots cleanly into ACP-aware editors like Zed and JetBrains. It loads Model Context Protocol (MCP) 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.62.0

• Updates surface during long-running sessions. Pythinker now checks periodically for newly available releases, shows each new update notice once per session, and bounds every check with a watchdog so a stalled attempt cannot prevent later retries.
• Repository-local agent workflows stay local. This checkout now treats its root .agents/ directory as local agent configuration instead of version-controlled project content.

Upgrade with pythinker update, pip install --upgrade pythinker-code==0.62.0, or use the native installer for your platform from the Releases page.

---

✨ 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 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:. Use pythinker skill list, pythinker skill lock, and pythinker skill verify-lock to inspect project skills and pin their hashes in skills-lock.json.

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

📊 Local Benchmarks

Run /benchmark to execute deterministic local coding tasks through the active Pythinker session, with replayable artifacts and verification reports.

🧪 SWE-Style Fixtures

Run trusted local JSONL fixtures with /benchmark:swe --dataset --trusted-dataset true when you want SWE-style task inputs without a hosted evaluator.

> [!NOTE] > Built-in shell commands such as cd are not yet supported in shell command mode.

---

⚡ Quick Start

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

| Platform | Recommended install | Artifact source | |---|---|---| | 🪟 Windows | irm https://pythinker.com/install.ps1 \| iex | PythinkerSetup-0.62.0.exe from Releases | | / | curl -fsSL https://pythinker.com/install.sh \| bash | native tarball from Releases | | — Homebrew | brew install Pythoughts-labs/pythinker/pythinker-code | auto-published Homebrew tap | | 🐳 Docker | docker run --rm -it ghcr.io/pythoughts-labs/pythinker-code | GHCR multi-arch image | | 🪟 Windows — Scoop | scoop bucket add pythinker https://github.com/Pythoughts-labs/scoop-pythinker && scoop install pythinker-code | auto-published Scoop bucket | | ❄️ Nix | nix run github:Pythoughts-labs/pythinker-cli | flake apps.default | | — system package | Download the .deb or .rpm for your distro below | Releases | | 🐍 Python fallback | 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:

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.62.0.exe is an Inno Setup wizard. Release builds are signed when Authenticode secrets are configured in CI; otherwise the installer ships unsigned. 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.

# One-line install (downloads the native .exe, verifies SHA-256, runs per-user)
irm https://pythinker.com/install.ps1 | iex

# Or manually download the installer + checksum from the Releases page,
# verify with Get-FileHash, then run:
.\PythinkerSetup-0.62.0.exe

# Open a fresh PowerShell
pythinker --version

Per-machine install (IT-managed boxes): .\PythinkerSetup-0.62.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 launches the Inno installer with visible progress (/SILENT /NORESTART /CURRENTUSER /CLOSEAPPLICATIONS /NORESTARTAPPLICATIONS).

Uninstall: irm https://pythinker.com/uninstall.ps1 | iex — runs the registered uninstaller, then sweeps leftover files, PATH edits (user + system), Start Menu shortcuts, and uninstall registry keys, and verifies the result. Your config/sessions in %USERPROFILE%\.pythinker are kept unless you set $env:PYTHINKER_PURGE_DATA = "1" first. Apps & Features → Pythinker Code → Uninstall works too and reverts both the files and the PATH edit.

> 🛡 First-launch SmartScreen warning — Until Authenticode secrets are > configured in CI for a release, 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.

---

— Homebrew tap

# 1. Install
brew install Pythoughts-labs/pythinker/pythinker-code
#    Homebrew ≥ 5 may refuse the untrusted tap; trust it once, then re-run:
#      brew trust pythoughts-labs/pythinker

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

Works on Apple Silicon and Intel from the same native GitHub Release tarballs used by the curl installer. 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).

> Untrusted-tap refusal — Homebrew ≥ 5 (with HOMEBREW_REQUIRE_TAP_TRUST) > refuses third-party taps until you trust them once: > brew trust pythoughts-labs/pythinker. The in-app updater detects the > refusal and offers to run it for you.

Uninstall: brew uninstall pythinker-code && brew untap Pythoughts-labs/pythinker.

> The tap repo is Pythoughts-labs/homebrew-pythinker > — auto-maintained, do not hand-edit.

---

— 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-code_0.62.0_amd64.deb
sudo apt-get install -f       # only if dpkg reports missing deps

# Debian / Ubuntu (ARM64)
sudo dpkg -i pythinker-code_0.62.0_arm64.deb

# Fedora / RHEL / openSUSE (x86_64)
curl -LO https://github.com/Pythoughts-labs/pythinker-cli/releases/download/v0.62.0/pythinker-code-0.62.0.x86_64.rpm
curl -LO https://github.com/Pythoughts-labs/pythinker-cli/releases/download/v0.62.0/pythinker-code-0.62.0.x86_64.rpm.sha256
sha256sum -c pythinker-code-0.62.0.x86_64.rpm.sha256
# Fedora / RHEL:
sudo dnf install ./pythinker-code-0.62.0.x86_64.rpm
# openSUSE:
sudo zypper install ./pythinker-code-0.62.0.x86_64.rpm

# Fedora / RHEL (aarch64)
curl -LO https://github.com/Pythoughts-labs/pythinker-cli/releases/download/v0.62.0/pythinker-code-0.62.0.aarch64.rpm
curl -LO https://github.com/Pythoughts-labs/pythinker-cli/releases/download/v0.62.0/pythinker-code-0.62.0.aarch64.rpm.sha256
sha256sum -c pythinker-code-0.62.0.aarch64.rpm.sha256
sudo dnf install ./pythinker-code-0.62.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:

sha256sum -c pythinker-code_0.62.0_amd64.deb.sha256        # Debian/Ubuntu
sha256sum -c pythinker-code-0.62.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:

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

---

/ — curl-bash native installer

For containers, fresh VMs, or any host without a system package manager. The canonical https://pythinker.com/install.sh endpoint is backed by [scripts/install-native.sh](./scripts/install-native.sh). It serves shell script content directly, detects your OS + arch, downloads the matching PyInstaller-frozen tarball, verifies its SHA-256, and lands the single binary at ~/.local/bin/pythinker.

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

# Pin a specific version
curl -fsSL https://pythinker.com/install.sh | bash -s -- --version 0.27.0

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

Host /install.sh with:

Content-Type: text/x-shellscript; charset=utf-8
Cache-Control: public, max-age=300, s-maxage=900, stale-if-error=86400

Use long immutable caching only for versioned release artifact URLs, for example Cache-Control: public, max-age=31536000, immutable on fixed-tag assets.

Supported targets:

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

The script prints PATH guidance if ~/.local/bin isn't already on your $PATH.

Uninstall: rm ~/.local/bin/pythinker.

🐍 Python fallback

Use the Python package only when a native installer is not available for your environment:

pip install pythinker-code

Native installs remain the supported path for new users and for in-app updates.

🔐 Authenticate (optional)

For hosted Pythinker models or ACP terminal auth:

pythinker login

Z.AI exposes two independent OpenAI-compatible routes. Choose the route that owns your key; both may coexist, and Pythinker never infers, migrates, falls back, or retries across them:

# Coding Plan subscription
pythinker login --z-ai-coding   # reads ZAI_CODING_API_KEY when set

# Standard pay-as-you-go API
pythinker login --z-ai-api      # reads ZAI_API_KEY when set

These create distinct z-ai-coding/* and z-ai-api/* model identities. See the [provider guide](./docs/en/configuration/providers.md#managed-zai-routes) for endpoints, curated GLM capabilities, and route-scoped /usage behavior.

💬 Try it out

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

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.

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

pythinker logout --lm-studio

Ollama

# 1. start the server in one terminal
ollama serve

# 2. pull a

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Pythoughts-labs](https://github.com/Pythoughts-labs)
- **Source:** [Pythoughts-labs/pythinker-cli](https://github.com/Pythoughts-labs/pythinker-cli)
- **License:** Apache-2.0
- **Homepage:** https://pythinker.com

Install and usage instructions live in the source repository linked above.