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

Notifications You must be signed in to change notification settings

Fork 2

Star 3

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

913 Commits

913 Commits

.github/workflows

.github/workflows

api

api

app

app

assets

assets

docs

docs

npm

npm

scripts

scripts

workers

workers

.cicy_tmux.conf

.cicy_tmux.conf

.gitignore

.gitignore

.tmux.conf

.tmux.conf

LICENSE

LICENSE

Makefile

Makefile

NOTICE

NOTICE

README.md

README.md

build.sh

build.sh

dev.py

dev.py

go.work

go.work

go.work.sum

go.work.sum

versions.json

versions.json

Repository files navigation

cicy-code 是一个本地优先的多 agent 开发工作区:tmux worker + WebTTY 终端 + React 工作区 + AI 网关 + skill 市场,收在同一个仓库里,通过 npm(npx cicy-code)分发单二进制。

📸 更多截图 →

快速开始

npx cicy-code

首次运行会拉取匹配当前平台的单二进制(~30 MB),然后在本机起服务 —— 浏览器打开 http://127.0.0.1:8008 即可进入工作区。从零到指挥一支 agent 团队,大约 5 分钟。

🚀 快速开始 — 5 分钟从安装到第一支 agent 团队

📥 下载与安装 — 各平台安装包与 Docker 方式

🌐 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 # runtime 镜像 ./build.sh docker-base # 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 显示的还是旧号。

npm 分发:per-platform optionalDependencies

主包 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 [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 打的就是它

skill 生态

装/卸/列表:cicy-code skill install|remove|installed (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//)

~/cicy-ai/assets/:上传资源目录

许可证

Apache-2.0

About

CiCy — the AI-agent workspace: run, orchestrate & chat with coding agents (Claude / Codex / OpenCode / …) in tmux, manage teams, drive browser & desktop. Go server + React workspace; ships native, web/PWA & Telegram Mini App clients.

cicy-ai.com

Topics

react

tmux

golang

ide

devtools

codex

claude

cicy

ai-agent

agent-orchestration

ai-coding-agent

Resources

Readme

License

Apache-2.0 license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

3 stars

Watchers

0 watching

Forks

2 forks

Report repository

Releases 214

v2.3.260

Latest

Jul 17, 2026

+ 213 releases

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Go 57.8%

TypeScript 39.5%

Python 1.3%

Shell 1.0%

CSS 0.2%

JavaScript 0.1%

Other 0.1%