# Pythinker Cli

> Think first, then code. Where Claude Code and Codex jump straight to writing, this stays review-first: a code reviewer, security scanner, root-cause debugger, and code generator, all in one shell-native loop.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pythoughts-labs-pythinker-cli`
- **Verified:** Pending review
- **Seller:** [Pythoughts-labs](https://agentstack.voostack.com/s/pythoughts-labs)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Pythoughts-labs](https://github.com/Pythoughts-labs)
- **Source:** https://github.com/Pythoughts-labs/pythinker-cli
- **Website:** https://pythinker.com

## Install

```sh
agentstack add mcp-pythoughts-labs-pythinker-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

#  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)**](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.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](https://github.com/Pythoughts-labs/pythinker-cli/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:`. 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](https://github.com/Pythoughts-labs/pythinker-cli/releases/latest) |
| ** / ** | `curl -fsSL https://pythinker.com/install.sh \| bash` | native tarball from [Releases](https://github.com/Pythoughts-labs/pythinker-cli/releases/latest) |
| ** — 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](https://github.com/Pythoughts-labs/pythinker-cli/releases/latest) |
| **🐍 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:

```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.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.**

```powershell
# 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

```sh
# 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](https://github.com/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.

```sh
# 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:**

```sh
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:**

```sh
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`.

```sh
# 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:

```http
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 / x86_64              | `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 / x86_64             | `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:

```sh
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:

```sh
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:

```sh
# 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

```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

…

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pythoughts-labs-pythinker-cli
- Seller: https://agentstack.voostack.com/s/pythoughts-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.