claudeers.
// Developer Tools

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.
// or clone
git clone https://github.com/3679qwerr/agent-town

// compatibility

Platformscli, api, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageJavaScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Agent Town · Agent 小镇

把 AI 编程任务,变成一座实时运转的 3D 小镇。

Agent Town 是一个运行在本机的 AI 编程 Agent 可视化工作台。它将 Codex、Claude Code 等工具的任务、对话和执行状态映射为街区、车间、角色与传送带,让你在多个任务之间快速找到正在发生的事情。

每个 Agent 一个街区,每个项目一间车间,每次工具调用是一件包裹。读取、修改、运行命令、等待确认和本轮结束,都能在小镇里找到对应的画面和记录。

Node.js 20+ · Three.js · 原生 JavaScript · 本地运行 · MIT

Agent 小镇:车间、传送带、角色与实时任务面板

文档截图均使用模拟数据。首次体验无需配置 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。

许可

MIT License · 第三方许可声明


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.

0 views
★ 14 stars
unclaimed
updated about 7 hours ago

// embed badge

agent-town on Claudeers
[![Claudeers](https://claudeers.com/api/badge/agent-town.svg)](https://claudeers.com/agent-town)

// retro hit counter

agent-town hit counter
[![Hits](https://claudeers.com/api/counter/agent-town.svg)](https://claudeers.com/agent-town)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

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,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how agent-town connects across the ecosystem