badlogic / pi-mono

31,9073,472+355 todayTypeScript

View on GitHub

AI agent toolkit: coding agent CLI, unified LLM API, TUI & web UI libraries, Slack bot, vLLM pods

📊 Project Info

Language: TypeScript
Stars: ⭐ 31,907
Forks: 3,472
Today: +355
Ranking: #6
Collection: Overall
Trending Date: April 5, 2026
Last Push: 4/5/2026

📸 Screenshots

5分钟上手 pi-mono

快速安装并运行一个AI智能体，体验pi-mono的核心功能

🖥️ OS

macOSWindowsLinux

⚙️ Runtime

Node.js>= 18.0

🔧 Tools

Git— 克隆项目代码

📝 Steps

克隆项目

获取pi-mono源代码到本地

克隆主仓库

$ git clone https://github.com/badlogic/pi-mono.git

进入项目目录

$ cd pi-mono

✓Expected: 项目目录结构包含packages文件夹和package.json文件

💡确保网络连接正常，Git已正确安装

安装依赖

安装项目所需的所有npm包

安装项目依赖

$ npm install

✓Expected: 看到大量npm包被下载和安装，最后显示'added X packages'

💡首次安装可能需要几分钟，取决于网络速度

构建项目

编译TypeScript代码

构建所有包

$ npm run build

✓Expected: 看到编译过程输出，最后显示构建成功信息

💡如果遇到TypeScript错误，确保所有依赖已正确安装

运行编码智能体

启动交互式编码助手，这是最直观的体验方式

进入编码智能体目录

$ cd packages/coding-agent

启动编码智能体

$ npm start

✓Expected: 看到终端界面显示编码智能体的欢迎信息和交互提示

💡首次运行可能需要配置API密钥，可以按提示跳过或配置

✅ 验证成功

成功启动编码智能体并能够进行交互

✓看到终端显示编码智能体的欢迎界面
✓可以输入问题并获得AI响应
✓智能体能够理解并执行编码任务

⚡ Quick Tips

配置如果遇到API密钥错误，可以先跳过配置，体验基础功能

其他使用Ctrl+C退出智能体交互界面

配置项目使用workspace模式，所有包在根目录统一管理

🔍 Troubleshooting

❓ npm install 失败，显示权限错误

→ 使用 nvm 管理Node.js版本，或尝试 sudo npm install（不推荐）

❓ npm run build 失败，显示TypeScript错误

→ 确保先运行 npm install 安装所有依赖，然后重试

❓ 编码智能体启动后立即退出

→ 检查是否缺少必要的环境变量，尝试在根目录运行 npm run check 诊断问题

❓ 内存不足或构建缓慢

→ 可以单独构建特定包，如 cd packages/coding-agent && npm run build

🎯 Next Steps

配置API密钥

设置OpenAI、Anthropic等LLM提供商密钥以使用完整功能

探索其他包

尝试pi-tui终端UI库或pi-pods GPU部署管理工具

查看示例代码

参考packages目录下的示例了解各模块用法

Difficulty

初级

Est. Time

3-5小时

Target Audience

对AI智能体开发感兴趣的前端/Node.js开发者，具备基础的TypeScript和命令行操作能力

🎯 What You'll Learn

学会使用pi-mono项目中的核心工具，包括调用多厂商LLM API、创建简单的AI智能体，以及通过CLI管理GPU部署

📋 Prerequisites

TypeScript基础熟悉

项目使用TypeScript开发，需要能理解基本的类型定义和模块导入

Node.js与npm熟悉

需要安装Node.js环境，使用npm管理依赖和运行脚本

命令行操作了解

需要运行CLI命令和脚本

Git基础了解

需要克隆仓库和查看代码

📚 Resources

必看

项目README及各包README

最权威的使用说明和配置指南

🗺️ Learning Phases

环境准备与项目概览

⏱ 30分钟

安装开发环境

确保已安装Node.js（建议v18+）和Git，克隆项目仓库：git clone https://github.com/badlogic/pi-mono.git

💡可以使用node -v和npm -v检查版本

探索项目结构

查看根目录下的README.md和packages文件夹，了解各个子包的功能

💡重点关注@mariozechner/pi-ai（LLM API）和@mariozechner/pi-coding-agent（编码智能体）

安装依赖

在项目根目录运行npm install安装所有依赖包

💡依赖较多，可能需要一些时间

快速体验核心功能

⏱ 1小时

运行构建检查

按照README提示，先运行npm run build，然后运行npm run check

💡注意顺序：必须先build再check，因为web-ui包需要依赖的.d.ts文件

体验编码智能体

进入packages/coding-agent目录，查看其README，尝试运行基本的CLI命令

💡这是项目的亮点功能，可以先了解其基本用法，不一定需要立即配置所有API密钥

查看示例代码

在各个包的src目录中寻找示例或测试文件，了解基本API调用方式

💡从pi-ai包的测试文件开始，看如何调用不同厂商的LLM

动手实践第一个智能体

⏱ 1.5小时

配置LLM API密钥

选择一家LLM提供商（如OpenAI），获取API密钥，在代码中配置pi-ai客户端

💡可以从简单的环境变量配置开始，参考pi-ai包的文档

创建简单的对话智能体

使用pi-agent-core创建一个能调用工具（如获取天气、计算）的基础智能体

💡先实现一个简单的工具函数，让智能体学习调用它

运行并测试智能体

编写一个简单的脚本，启动智能体并进行对话测试

💡从控制台输入输出开始，逐步增加复杂度

探索高级功能与部署

⏱ 1小时

了解TUI库

查看pi-tui包的示例，了解如何创建终端用户界面

💡可以尝试运行现有的TUI示例，观察差分渲染效果

学习Pod管理

阅读pi-pods包的README，了解如何管理vLLM在GPU Pod上的部署

💡如果暂时没有GPU环境，可以先了解CLI命令结构

查看贡献指南

阅读CONTRIBUTING.md和AGENTS.md，了解项目开发规范

💡注意项目对人和AI智能体的贡献都有明确规则

⚠️ Common Mistakes

❌ 未按顺序运行npm run build和npm run check

✅ 严格按照README提示：先build生成类型定义文件，再运行check

❌ 未正确配置LLM API密钥

✅ 确保API密钥以正确的方式（环境变量或配置文件）传递给pi-ai客户端

❌ 忽略包之间的依赖关系

✅ 注意各包通过@mariozechner/前缀相互引用，修改代码时考虑依赖影响

❌ 直接修改node_modules中的代码

✅ 所有修改都应在packages目录下的对应包中进行，然后重新构建

🚀 Next Steps

深入探索pi-coding-agent的完整功能并集成到工作流中；学习使用pi-pods管理自己的LLM部署；为项目贡献代码或文档，参与开源协作；基于pi-agent-core开发更复杂的多智能体系统