An intelligent agent that reads your codebase, edits files, runs shell commands, searches the web, and iterates until the job is done. Powered by Pythinker models — compatible with other LLM providers. All from the shell you already live in.
Website · Quick Start · Features · IDE Integration · MCP · Architecture · Development
Pythinker Codeis an open-source AI engineering agent that lives in your terminal. Give it a task — refactor a module, trace a bug, scaffold a feature — and it plans, executes tools, observes results, and keeps going until you are satisfied. It runs against your repo, the shell, the web, and MCP tools, with the model of your choice.
It ships with first-class subagents for focused work — coder for scoped edits, explore for codebase reconnaissance, and plan for implementation design — all dispatched in parallel, isolated contexts from a single iterative loop.
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.
**Plan · Execute · Verify · Iterate.**One agent, one shell, one workflow. No tab-switching. No context loss. No magic.
|
A purpose-built TUI tuned for long, focused agent sessions. Single-binary install, no Node.js required for end users, ready in milliseconds. |
Dispatch |
|
Run |
Add and authenticate MCP servers conversationally with |
|
Approval flows to review tool calls before they run, a granular permission model, and lifecycle hooks to gate risky calls, audit decisions, and wire automation. |
Works out of the box with Pythinker models; configurable for other compatible LLM APIs. |
|
A companion browser interface ( |
Drop screen recordings into the conversation — let the agent see what is hard to describe. |
Pythinker ships native installers— no Node.js prerequisite. Pick the row that matches your OS:
| Platform | Recommended install | Source |
|---|---|---|
  macOS / Linux |
curl -fsSL https://code.pythinker.com/pythinker-code/install.sh | bash |
code.pythinker.com |
 Homebrew |
brew install pythoughts-labs/tap/pythinker-code |
Homebrew |
 Windows (PowerShell) |
irm https://code.pythinker.com/pythinker-code/install.ps1 | iex |
code.pythinker.com |
 Nix |
nix run github:Pythoughts-labs/pythinker-code |
flake |
 npm / pnpm fallback |
npm install -g @pythoughts/pythinker-code |
requires Node.js ≥ 26.4.0 |
Note
**Windows:**install Git for Windows before first launch — Pythinker Code uses the bundled Git Bash as its shell. For a custom Git Bash location, set PYTHINKER_SHELL_PATH to the absolute path of bash.exe.
After install, open a new shell:
pythinker --version # confirm installcd your-project
pythinkerOn first launch, run /login and choose **Pythinker Code OAuth**or an API key from the console.
Take a look at this project and explain its main directories.
Find where authentication is handled and add a unit test for the token refresh path.
Refactor the error handling in src/api/ to use a shared Result type — keep the diff minimal.
| Command | Description |
|---|---|
/login |
Authenticate with OAuth or API key |
/mcp-config |
Manage MCP servers conversationally |
/skill:<name> |
Invoke an installed skill |
/help |
Built-in keyboard shortcut reference |
For upgrade, uninstall, headless/automation usage, and platform-specific notes, see the Getting Started guide.
Pythinker speaks Agent Client Protocol natively. Log in once via the CLI, then point your ACP-compatible editor at pythinker acp for a full agent session inside your IDE.
Configuration for Zed / JetBrains
Add to ~/.config/zed/settings.json:
{
"agent_servers": {
"Pythinker Code": {
"type": "custom",
"command": "pythinker",
"args": ["acp"],
"env": {}
}
}
}Open a new conversation in Zed's Agent panel. For JetBrains setup, troubleshooting, and the full capability matrix, see Using in IDEs and the pythinker acp reference.
Pythinker loads Model Context Protocol tools so the same servers your other agents use just work — stdio and HTTP transports, OAuth-backed servers, persistent config.
Inside a session, /mcp-config manages everything conversationally:
/mcp-config # add, authenticate, test, and remove MCP servers
See the configuration docs for config-file based setup.
Pythinker Code is a pnpm monorepo. The CLI consumes capabilities through the SDK and never depends directly on internal engine packages.
| Package | Role |
|---|---|
apps/pythinker-code |
CLI and terminal UI — the primary user-facing entry point |
packages/agent-core |
Unified agent engine: sessions, tools, skills, permissions, plans |
packages/kosong |
"Any LLM" — LLM and provider abstraction layer |
packages/kaos |
Execution environment and file/process abstractions |
packages/server |
Hosts agent sessions over REST + WebSocket (/api/v1) |
packages/node-sdk |
Public TypeScript SDK for embedding and automation |
Pythinker is a small, extensible runtime — not a monolith. Build on it.
| Extension Point | What it does | Where to look |
|---|---|---|
| Subagents | Delegate focused work to coder, explore, and plan agents in isolated contexts |
built-in |
| Skills | /skill:<name> loads reusable, repo-local instructions on demand |
bundled & user-defined |
| Hooks | Observe or block tool execution; integrate policy or automation | lifecycle hook events |
| Plugins | Skills, MCP servers, and data sources from the marketplace or GitHub | plugin ecosystem |
| SDK | Embed agent capabilities in your own tools | @pythoughts/pythinker-code-sdk |
| Topic | Link |
|---|---|
| Getting Started | guides/getting-started |
| Interaction & approvals | guides/interaction |
| Sessions | guides/sessions |
| IDE integration | guides/ides |
| Configuration | configuration/config-files |
| Command reference | reference/pythinker-command |
| Pythinker Code product | pythinker.com/code |
**Requirements:**Node.js ≥ 26.4.0 · pnpm 10.34.3 · Git
git clone https://github.com/Pythoughts-labs/pythinker-code.git
cd pythinker-code
pnpm install|
▶ Run & iterate pnpm dev:cli # CLI in dev mode
pnpm dev:web # browser UI
pnpm dev:server # agent server
pnpm dashboard # session dashboard |
Verify pnpm test # test suite (Vitest)
pnpm typecheck # TypeScript check
pnpm lint # lint with oxlint
pnpm build # build all packages |
pythinker-code/
├── apps/
│ ├── pythinker-code/ CLI · TUI · ACP · the primary entry point
│ ├── pythinker-web/ Companion browser UI (Vue 3)
│ └── dashboard/ Session replay & debugging
├── packages/
│ ├── agent-core/ Unified agent engine: sessions · tools · skills · permissions
│ ├── kosong/ "Any LLM" provider abstraction
│ ├── kaos/ Execution environment & file/process abstractions
│ ├── server/ REST + WebSocket session host (/api/v1)
│ └── node-sdk/ Public TypeScript SDK
└── per-package test suites (Vitest)
Contributions are warmly welcome — bug reports, PRs, plugins, skills, and docs all help.
- Start with
CONTRIBUTING.md - See
SECURITY.mdfor responsible disclosure - Discuss firstfor new features, large refactors, or API changes — open an issue before coding
- Follow Conventional Commits(
feat:,fix:,docs:, …) and include a changeset (pnpm changeset) when your PR affects release artifacts - Understand your diff— AI-assisted PRs are held to the same standard as hand-written ones
If Pythinker helps you, a on GitHub goes a long way.
Distributed under the MIT License. See LICENSE for the full text.
Our TUI is built on pi-tui — thank you to the authors for their excellent work.