
agent-town
把 Codex、Claude Code 等 AI 编程任务变成一座实时运转的 3D 小镇:任务追踪、车间对话、提醒复盘与背景音乐。
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up agent-town (git-clone project) into my current project. Found on https://claudeers.com/agent-town Repo: https://github.com/3679qwerr/agent-town Homepage/docs: — Detected install method: git-clone → git clone https://github.com/3679qwerr/agent-town Category: devtools. Platforms: cli, api, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
git clone https://github.com/3679qwerr/agent-town
// compatibility
| Platforms | cli, api, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
Agent Town · Agent 小镇
把 AI 编程任务,变成一座实时运转的 3D 小镇。
Agent Town 是一个运行在本机的 AI 编程 Agent 可视化工作台。它将 Codex、Claude Code 等工具的任务、对话和执行状态映射为街区、车间、角色与传送带,让你在多个任务之间快速找到正在发生的事情。
每个 Agent 一个街区,每个项目一间车间,每次工具调用是一件包裹。读取、修改、运行命令、等待确认和本轮结束,都能在小镇里找到对应的画面和记录。
Node.js 20+ · Three.js · 原生 JavaScript · 本地运行 · MIT

文档截图均使用模拟数据。首次体验无需配置 Agent 或执行真实任务。
它能帮你做什么
- 看清任务状态:区分正在执行、明确等待、疑似等待、长时间无活动和本轮结束,集中查看需要关注的会话。
- 从场景进入对话:点击车间建筑或名牌,在中央阅读项目历史;点击角色,查看当前任务、用户指令和公开进展。
- 交接上下文:为项目保存共享记忆,把选定会话的公开消息与上一棒回复交给 Codex 或 Claude Code。
- 及时处理提醒:等待、错误和结束时弹出提醒,错误可直接定位记录;提示音与系统通知均可选择开启。
- 查看执行摘要:了解最近一轮的时长、工具调用、工具错误与结束原因,按需展开技术详情和事件时间线。
- 安排自己的工作空间:独立收起各个状态栏,调整镜头、街区、昼夜和天气,配合轻音乐作为桌面任务看板。
快速开始
需要安装 Node.js 20 或更高版本。
git clone https://github.com/3679qwerr/agent-town.git
cd agent-town
npm install
npm start
打开 http://localhost:4317。按 Ctrl+C 停止服务。
首次打开可以点击左侧 「体验演示」,约 24 秒自动展示阅读、执行、错误、等待与结束流程。也可以直接打开 演示入口。演示使用独立数据,不派发真实任务。
Windows PowerShell 如提示无法运行 npm.ps1,可使用 npm.cmd install 和 npm.cmd start。
连接本机 Agent
启动后会自动发现以下日志,无需配置密钥:
| Agent | 默认日志位置 |
|---|---|
| Codex | ~/.codex/sessions/**/*.jsonl |
| Claude Code | ~/.claude/projects/**/*.jsonl |
Windows 中,~ 对应 %USERPROFILE%。没有日志时显示空状态,打开对应 Agent 执行任务后即可看到活动。
可选安装 hooks,让等待授权、轮次结束等状态更及时:
npm run hooks:install
# 需要时卸载
npm run hooks:uninstall
安装脚本会合并已有配置,并在修改前保存 *.agent-town.bak 备份。小镇未启动时,hook 会静默跳过。
功能与交互
3D 小镇
| 场景元素 | 含义与操作 |
|---|---|
| 街区 | 每个 Agent 拥有独立街区;按住 Shift 拖动可调整位置 |
| 车间 | 每个 Agent 最近活跃的 7 个项目各占一间;点击打开项目历史对话 |
| 包裹与传送带 | 一次工具调用对应一个包裹,颜色区分读取、修改、命令、联网等类别 |
| 中转站与广场 | 展示工具结果流转、工作台与发货过程 |
| 卡通角色 | Codex 小云朵、Claude Code 小螃蟹和自定义机器人;点击查看当前任务与指令 |
| 小地图 | 查看全部街区与镜头范围,点击快速跳转 |
左键平移、右键旋转、滚轮缩放。工具栏提供全景、左右旋转、巡游、画质与名牌控制;鱼缸模式隐藏界面缓慢旋转,可按 Esc 或双击退出。
对话与当前任务
点击车间后,中央面板显示该项目的会话选择框和历史消息,可加载更早的记录。不同项目和会话分别展示,正文保留换行。
点击角色后,中央面板只列出正在执行、等待或停滞的活动会话,显示当前任务、最近用户指令、公开工具动作与回复。没有活动任务时明确提示,可转看最近会话的历史。
![]() | ![]() |
日志正文按需读取,只展示用户消息与助手公开回复;系统指令、开发者指令、内部推理和工具输出不进入对话正文。记录缺失时明确说明,不补造聊天内容。
协作台
点击工具栏 「协作台」,或在车间对话中点 「发起协作」。选择来源会话,在 「共享记忆」 中保存该项目的约定与结论。共享记忆按项目所在目录保存,同一项目下的不同 Agent 会话共用一份。
填写任务并选择接收方。可以附上来源会话的最近 6 条公开消息,单条最多 2,000 字符。点 「预览交接」 查看将发送的任务、记忆版本和上下文,再点 「确认发送」。收到回复后,可点 「接力给另一位 Agent」 继续复核,也可以摘录结论并保存到共享记忆。
真实协作会通过本机已安装并登录的 Codex 或 Claude Code 命令行启动独立会话,用于只读讨论与评审。Claude Code 需要支持受限模式的版本(2.1.248 或以上)。交接记录和共享记忆保存在本机用户目录下的 .agent-town/collaboration.json。在 「体验演示」 中可模拟两位 Agent 的交接,重新演示会清空本轮模拟记录。
状态、提醒与复盘
- 任务卡片:显示本轮目标、当前动作、状态依据与下一步建议,不显示推测的完成百分比。
- 待关注会话:集中展示明确等待和长时间无活动;疑似等待保留推测标记,执行中的工具错误不会自动成为待办。
- 错误直达:点击错误提醒,展开并定位关联记录;旧记录不可用时说明原因。
- 本轮执行摘要:展示已观测的时长、调用和错误数,区分正常结束、中断和异常;本轮结束仍需自行确认任务结果。
- 分层详情:技术参数、本轮明细和时间线默认折叠,按会话记住展开选择。
- 统计报表:按天、项目和 Agent 查看轮次、工具调用、Token 与工作分钟;支持最近 7 天和 30 天。
- 回放:以 10× / 30× / 60× 重放最近 1 小时的工具活动。

可收起面板与声音
品牌状态、统计、时间天气、会话、详情、工具栏、小地图、回放、中央面板和声音设置都能独立收起。点击右上角 「−」 收起,点击 「+ 名称」 恢复,也支持 Enter / 空格;浏览器记住你的选择,实时更新不受影响。
工具栏的 「音乐」 与 「提示音」 分别控制背景轻音乐和任务音效,「音量」 面板可独立调节两个音量并试听。正常结束播放三音提示,中断与异常使用不同音效;重复事件不重复响铃。
![]() | ![]() |
音乐和音效由 Web Audio 在本地合成,不下载媒体。首次默认关闭,开关与音量会保存;刷新后先点击页面或按键即可恢复声音。切到后台会暂停音乐,任务提示音独立工作。系统静音或浏览器后台音频限制仍可能影响出声。
天气、定时任务与派单
- 天气与昼夜:按本机时区显示时间与昼夜,默认查询北京天气,也可手动切换。使用
AT_CITY、AT_LAT、AT_LON调整天气城市。 - 定时任务:展示支持环境中的本机 crontab / launchd 用户任务;Windows 不会虚构计划任务记录。
- 派单:向已发现的项目目录发起 Codex / Claude 非交互任务,查看执行日志;需要先安装对应 CLI,可能使用该工具的账号额度。
- 自定义 Agent:可在工具栏添加名称与颜色,通过 HTTP 事件接入;内置本机工具检测入口。
本地数据与运行边界
应用监听 127.0.0.1:4317,通过本机日志、hooks 与 SSE 更新状态;任务内容不上传到云端,天气查询会联网。派单会启动对应 CLI,该 CLI 的网络行为取决于其自身配置。
项目会话选择框来自最近 7 天活跃的快照;历史对话读取已登记的源日志。每个日志缓存最多保留最近 800 条、约 400 万字符,单条最多 64,000 字符,最多缓存 6 个日志。截断、缺失或不可读取会有提示;此功能不承担永久聊天归档。
演示数据与真实会话、事件、报表分开。演示状态不接受真实派单或写入操作。
接入其他 Agent
向本地 POST /api/ingest 推送事件,即可创建街区并显示任务。以下为模拟示例:
curl -X POST http://localhost:4317/api/ingest \
-H 'Content-Type: application/json' \
-d '{
"agent": "custom", "name": "My Agent", "color": "#4aa3df",
"events": [
{ "sid": "example-1", "kind": "turnStart", "cwd": "/path/to/project", "prompt": "检查项目" },
{ "sid": "example-1", "kind": "message", "role": "user", "text": "请检查项目" },
{ "sid": "example-1", "kind": "toolStart", "toolId": "read-1", "tool": "Read", "label": "读 README.md" },
{ "sid": "example-1", "kind": "toolEnd", "toolId": "read-1" },
{ "sid": "example-1", "kind": "message", "role": "assistant", "text": "已完成公开检查记录。" },
{ "sid": "example-1", "kind": "turnEnd", "reason": "done" }
]
}'
常用事件:turnStart、toolStart、toolEnd、message、wait、turnEnd、sessionEnd。agent 使用小写字母、数字和 _.-,未指定颜色时会自动生成。
技术与开发
服务端采用 Node.js HTTP 与 SSE,前端采用原生 JavaScript 和 Three.js。模型与光照已烘焙为仓库内素材,正常运行不需要 Blender、数据库或 LLM API。
server/ 日志适配、会话状态、公开对话、SSE、报表与派单
public/ 页面、样式、3D 素材与浏览器交互
scripts/ hooks、演示和浏览器回归脚本
test/ Node.js 内置自动化测试
tools/ Blender 建模与烘焙脚本
docs/ 截图、设计和验证记录
npm test # 32 项 Node.js 自动化测试
npm run demo # 启动隔离演示流程;需先运行服务
可选浏览器回归:
npm install --no-save --package-lock=false playwright
node scripts/browser-check.js
脚本在 4318 启动隔离服务,使用临时用户目录和模拟事件,不读取真实 Agent 日志。Windows 默认使用 Edge;其他环境需准备 Playwright Chromium。
场景按需渲染:画面无变化时停止连续绘制,动态场景以较低帧率更新,操作镜头时提高刷新。模型使用烘焙贴图,不做实时阴影或重型后期;画质可在工具栏调整。
如需重新生成模型,安装 Blender,调整 package.json 中的本机 Blender 路径后运行 npm run assets。
许可
English — Agent Town is a local 3D dashboard for AI coding agents. Track Codex and Claude Code tasks through districts, workshops and parcels; open project conversations, inspect current instructions, review execution summaries, and manage alerts, collapsible panels and local background music. Run with Node.js 20+ and npm install && npm start.
// faq
What is agent-town?
把 Codex、Claude Code 等 AI 编程任务变成一座实时运转的 3D 小镇:任务追踪、车间对话、提醒复盘与背景音乐。. It is open-source on GitHub.
Is agent-town free to use?
agent-town is open-source under the MIT license, so it is free to use.
What category does agent-town belong to?
agent-town is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/agent-town)
// retro hit counter
[](https://claudeers.com/agent-town)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA



