Cicy-code – a local-first multi-agent coding workspace via npx

Cicy-code, a local-first multi-agent coding workspace, is now available via npx. The tool bundles a tmux worker, WebTTY terminal, React workspace, AI gateway, and skill market into a single binary distributed through npm, enabling users to set up an agent team in about five minutes.

cicy-code 是一个本地优先的多 agent 开发工作区:tmux worker + WebTTY 终端 + React 工作区 + AI 网关 + skill 市场,收在同一个仓库里,通过 npm npx cicy-code 分发单二进制。 npx cicy-code 首次运行会拉取匹配当前平台的单二进制 ~30 MB ,然后在本机起服务 —— 浏览器打开 http://127.0.0.1:8008 http://127.0.0.1:8008 即可进入工作区。从零到指挥一支 agent 团队,大约 5 分钟。 - 🚀 快速开始 https://docs.cicy-ai.com/guide/getting-started — 5 分钟从安装到第一支 agent 团队 - 📥 下载与安装 https://docs.cicy-ai.com/guide/download — 各平台安装包与 Docker 方式 - 🌐 cicy-ai.com https://cicy-ai.com — 官网与云端版 cicy-code/ ├── app/ React + Vite 前端 入口 app/src/App.tsx,主界面 Workspace.tsx ├── api/ Go 后端 + 终端层 │ ├── mgr/ 主程序与业务路由 main.go 注册路由与启动 │ ├── server/ WebTTY HTTP/WebSocket 服务 │ ├── webtty/ WebTTY 协议 │ ├── js/ 浏览器端终端资产源码 改后需 cd api && make asset │ ├── skillcmd/ cicy-code skill <… 子命令 安装/卸载/列表 │ └── resources/ 后端静态资源 ├── npm/ npm 发布包与启动器 bin/cicy-code.js + publish-all.sh + install.sh ├── scripts/ 构建/发版/测试脚本 build-image.sh / fresh-instance.sh / sync-version.py ├── workers/ Cloudflare Workers 见下「Cloudflare Workers」 ├── build.sh 标准构建入口 唯一正确的构建/测试方式 ├── dev.py 本地开发入口 ├── versions.json base 镜像 / app 资产 / ttyd 版本 └── Makefile 常用别名 主入口: - 本地开发 python3 dev.py - 构建/测试 ./build.sh - 后端 api/mgr/main.go ,前端 app/src/App.tsx ,主工作区 app/src/components/Workspace.tsx - 版本号源头 npm/package.json - cicy 状态根 ~/cicy-ai 必须走 ./build.sh,不要直接 go build / go test。 build.sh 会在编译前准备内嵌资源;裸 go build ./mgr/ 会跳过这些步骤、和真实流水线不等价,还会在仓库根丢一个 ./mgr 产物。 ./build.sh 依次: - 同步版本号 - 复制 api/resources → api/mgr/resources - 复制 .tmux.conf 、 .cicy tmux.conf → api/mgr/ - 构建 app/dist 除非 SKIP NPM=1 - 刷新 ttyd 内嵌资产 除非 SKIP TTYD ASSET=1 - 复制 app/dist → api/mgr/ui 前端嵌进二进制 - 编译 api/mgr → api/cicy-code ./build.sh build os arch 当前/指定平台构建 ./build.sh all 全平台 ./build.sh test-go Go 测试 稳定入口 ./build.sh test-go ./mgr/... 单包测试 ./build.sh docker <tag runtime 镜像 ./build.sh docker-base <tag base 镜像 cd ~/projects/cicy-code python3 dev.py 构建 + 后台起 api/cicy-code --dev --public,tail 日志 默认端口:API 8008 、Vite 8022 。前端源码改动: dev.py 默认 SKIP NPM=1 复用 app/dist ,要生效先 cd app && npm run build ,再 python3 dev.py 。 前后端分开调试: cd app && npm ci && npm run dev 前端 HMR :8022 cd api && go run ./mgr/ --dev --public 后端把非 API 请求反代到 :8022 （ --dev 仅用于本地起服务;正式产物仍必须走 ./build.sh 。） 版本号统一由 scripts/sync-version.py 写入这几处: npm/package.json 、 app/package.json 、 app/package-lock.json 、 app/src/config.ts 、 api/mgr/main.go 、 .cicy tmux.conf 。 正式发版 走 CI : python3 scripts/sync-version.py --set 2.3.NN 1 bump 所有版本文件 cd app && npm run build 2 前端 build 把 config.version 烘进 dist cd .. && git add <你的文件 && git commit ... 3 提交 共享 checkout:只 add 自己的文件 git push origin main git tag v2.3.NN && git push origin v2.3.NN 4 打 tag → 触发 .github/workflows/release.yml CI 从 tag 构建各平台二进制、发布 npm 五连包。 只更新本地 Mac 桌面 不发 npm,更快 : 桌面跑 ~/.local/bin/cicy-code symlink → 版本化二进制 。流程见项目内约定 每次必 bump 版本 → ./build.sh build darwin amd64 → 拷成版本化名 → 原子换 symlink → 同步 ~/.local/bin/.cicy-localbin.json 。 前端改动务必在 bump 之后 npm run build ,否则 SKIP NPM=1 会复用旧 dist, membership-version 显示的还是旧号。 主包 cicy-code 只是个 launcher 几 KB ,二进制按平台拆成子包,npm 按 os / cpu 只装匹配当前机器的那个 : cicy-code launcher bin/cicy-code.js → require.resolve 平台子包并 exec ├─ cicy-code-darwin-arm64 ├─ cicy-code-darwin-x64 ├─ cicy-code-linux-x64 └─ cicy-code-linux-arm64 安装: npm install -g cicy-code 海外 npm install -g cicy-code --registry=https://registry.npmmirror.com 国内 缓存二进制,不走 GitHub npx cicy-code 临时跑一次 npm/publish-all.sh <npm-version gh-tag 从对应 GitHub release 资产打包发布 4 个平台子包 + 主包 子包先发、主包后发,保证 optionalDependencies 可解析 。CI 已自动化这条链。 后端 api/mgr — main.go 注册全部路由与启动。关键文件: setup.go :环境检查、内置 worker、开机 seed dotfiles / memory 模板 / 内置 skill tmux.go :pane 生命周期、tmux send、agent 启动脚本 boot.sh 、fork chatbus.go :聊天 WebSocket、poll、client 广播 agent memory template.go :agent 记忆模板组装 见下 newtab.go : /newtab 单源浏览器起始页 chrome + electron tab 共用 skills.go / skill market .go :skill 市场 API /api/skill-market/ ai gateway .go / providers .go :各 provider 适配与 AI 网关 runtime.go / machines.go :managed runtime、机器表 ui.go :内嵌 UI 或 Vite 反代; paths.go :状态根与路径常量 终端层 — api/server HTTP/WS 、 api/webtty 协议 、 api/js 浏览器端资产,改后 make asset 。 前端 app — App.tsx 路由; Workspace.tsx 主工作区 agent stack / 团队面板 / skill 市场 / Todo / WS 状态 ; services/api.ts 统一 API 客户端; config.ts 版本号与 API base。 Cloudflare Workers workers/ 独立 wrangler deploy ,与主程序解耦 : oauth-flow → oauth-flow.cicy-ai.com :Google OAuth 授权码 无状态中继 只暂存 code,TTL 10min、一次性;永不接触 client secret / token skills-registry → skills.cicy-ai.com : public skill 注册表 API /v1/skills 、 /v1/admin/publish , skill install 打的就是它 - 装/卸/列表: cicy-code skill install|remove|installed <name api/skillcmd/ - public 注册表: workers/skills-registry skills.cicy-ai.com ,public skill 源码在独立仓库 cicy-skills ,tag 触发 /v1/admin/publish - 规范:三类 skill public / private / team 的落盘位置与发布约定见 cicy-skill-spec - 前端市场入口 /api/skill-market/ ,红点提示 public skill 有更新 cicy 状态根 ~/cicy-ai : ~/cicy-ai/global.json :全局配置 + api token ~/cicy-ai/db/ :敏感配置 email.json 、 cf.json 、 frps.toml 、 mihomo.yaml 等,chmod 600 ~/cicy-ai/memory/ :记忆模板 global.md 、 projects/ 、 agents/ ~/cicy-ai/workers/ :各 agent workspace ~/cicy-ai/skills/ :已装 skill public 扁平 / private/ / team/<team / ~/cicy-ai/assets/ :上传资源目录 Apache-2.0