PaiCLI Python CLI
PaiCLI Python is a terminal AI agent with ReAct and planning, an MCP client, memory, pre-edit snapshots and a Runtime API.
- 113 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent reads and writes files, runs shell commands and uses the network, and safety rests on confirmations and the path policy.
- The provider key is sent to an external model API.
Install
Manual install
git clone https://github.com/itwanger/PaiCLI-Python.gitThe first quick start command. Then `cd PaiCLI-Python` and `uv sync --extra dev`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads and writes files, runs shell commands and uses the network, and safety rests on confirmations and the path policy.
- The provider key is sent to an external model API.
This is third-party code. Review the repository files before installing.
What it does
A terminal agent in Python that reads and writes files, searches code, runs commands, searches the web and calls MCP tools. Modes: a ReAct loop, planning with a task graph (`--mode plan`) and a team of planner, workers and reviewer (`--mode team`). Dangerous actions go through human confirmation, with a path and command policy and an audit log. Memory combines a project file and long-term SQLite memory with deduplication and expiry. A snapshot is created before each agent run so you can return to it. The Runtime API stores threads, events and background tasks. PaiCLI can also serve as an MCP server, and the skill system loads skills by matching the request. DeepSeek is configured by default.
Who it is for. Developers who study how agents are built or want a terminal agent with confirmations and snapshots. The documentation is in Chinese.
Good fit when
- You want to study agent architecture: ReAct, planning, memory, MCP.
- The agent must ask for confirmation before commands and file writes.
- A snapshot is needed before an agent run so edits can be rolled back.
- The agent is called from scripts with a single `-p` prompt and JSON output.
Not a fit when
- You need a skill or plugin for an agent you already use: PaiCLI is a separate agent.
- Chinese documentation does not work for you.
- You need a mature supported product rather than a learning project.
Example request
Run `uv run paicli --mode plan -p "read the README and verify the project" --json` and show the plan and token usage.Limitations
The project is tied to the author course on agent engineering: it was built for learning and portfolios rather than as a mass product. Python 3.11 and `uv` are required, with DeepSeek configured by default through `DEEPSEEK_API_KEY`. Installation is from a repository clone, and no package registry release is stated. Chrome DevTools MCP needs Node.js 20.19 and Chrome. Configuration is read from five sources by priority, with project settings overriding user ones.
How to disable. Delete the repository clone and the `~/.paicli` directory with settings and memory. Snapshots and the audit log live in project directories, delete them by hand.
FAQ
How do I run PaiCLI?
Clone the repository, run `uv sync --extra dev`, then `uv run paicli` for interactive mode or `uv run paicli -p "prompt"` for a single prompt.
Which model provider is used?
An OpenAI-compatible streaming client, with DeepSeek configured by default through `DEEPSEEK_API_KEY`.
How do I check the environment?
`uv run paicli doctor --cwd .` checks the setup.
Are dangerous actions confirmed?
Yes: human confirmation, a command and path policy and a JSONL audit log.
What is team mode?
A planner, workers and a reviewer with dependencies, parallel workers and review retries. Run `uv run paicli --mode team --worker-mode plan -p "prompt"`.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI agent that works with project files and shell commands, lets you choose a model provider and connects external MCP tools.
A teaching terminal coding agent in Python, built as a "nanoGPT for agents": read it, take it apart and fork it
A local Python coding agent that writes every step to a log you can analyze, replay and resume.
A minimal terminal coding agent extended with skills, prompt templates and TypeScript packages
A terminal coding agent in Go: one binary with no Node or Python, diff review right in the interface and sub-agents
A personal AI agent for the terminal with shell, Python, web and local models, one of the earliest agent CLIs
README in short
The README is in Chinese: overview, a learning roadmap, a feature list, requirements, quick start, configuration priority and provider setup. Modes and the Runtime API are listed in the feature section.