{"id":46609674,"url":"https://github.com/xiaotonng/codeclaw","last_synced_at":"2026-03-13T08:01:10.725Z","repository":{"id":342625300,"uuid":"1174597358","full_name":"xiaotonng/codeclaw","owner":"xiaotonng","description":"The best IM-driven remote coding experience. Bridge AI coding agents to any IM.","archived":false,"fork":false,"pushed_at":"2026-03-11T02:38:18.000Z","size":1010,"stargazers_count":28,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-11T10:07:16.832Z","etag":null,"topics":["ai","claude","cli","codex","coding","nodejs","npx","telegram"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaotonng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T16:15:17.000Z","updated_at":"2026-03-11T08:59:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xiaotonng/codeclaw","commit_stats":null,"previous_names":["xiaotonng/codeclaw"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/xiaotonng/codeclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotonng%2Fcodeclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotonng%2Fcodeclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotonng%2Fcodeclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotonng%2Fcodeclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaotonng","download_url":"https://codeload.github.com/xiaotonng/codeclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotonng%2Fcodeclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30417685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T06:40:58.731Z","status":"ssl_error","status_checked_at":"2026-03-12T06:40:40.296Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","cli","codex","coding","nodejs","npx","telegram"],"created_at":"2026-03-07T18:07:12.690Z","updated_at":"2026-03-12T07:01:24.374Z","avatar_url":"https://github.com/xiaotonng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# codeclaw\n\n**The best IM-driven remote coding experience. Period.**\n\nIM 交互体验最好的远程编程工具。没有之一。\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org)\n[![npm](https://img.shields.io/npm/v/codeclaw)](https://www.npmjs.com/package/codeclaw)\n\n[English](#english) | [中文](#中文)\n\n\u003c/div\u003e\n\n---\n\n\u003ca id=\"english\"\u003e\u003c/a\u003e\n\n## Why codeclaw?\n\nMost \"AI + IM\" bridges just forward messages. codeclaw is built from scratch for **the best possible remote coding experience over instant messaging**:\n\n- **Real-time streaming** — token-by-token output via Telegram message edits; you see the AI thinking live, not a wall of text after 2 minutes\n- **System-level keep-alive** — triggers OS-level power assertions to prevent your laptop from sleeping, so long-running tasks finish even when you walk away\n- **Multi-agent hot-switch** — Claude Code + Codex CLI, switch with a single `/agents` command\n- **True multi-session** — named sessions with persistent thread IDs; restart codeclaw, resume exactly where you left off\n- **One command** — `npx codeclaw` and you're running\n\n```\nTelegram (your phone / desktop)\n  ↕ long poll\ncodeclaw (your machine, your project dir)\n  ↕ subprocess\nclaude / codex CLI\n  ↕ reads \u0026 writes\nyour codebase\n```\n\nNo server. No Docker. No config files. Just one process bridging Telegram to your local AI agent.\n\n## Features\n\n- **Multi-agent** — Claude Code + Codex CLI, hot-switch via `/agents` inline keyboard\n- **Streaming** — real-time token-by-token output via Telegram message edits\n- **Multi-session** — per-chat session management with named sessions, pagination, and resume\n- **Keep-alive** — OS-level sleep prevention (macOS `caffeinate`, Linux `systemd-inhibit`)\n- **Directory browser** — switch working directory interactively via `/switch` with inline navigation\n- **Image input** — send photos to the bot for visual context (screenshots, diagrams)\n- **Quick replies** — auto-detects yes/no questions and numbered options, shows inline buttons\n- **Long output** — responses exceeding Telegram limits are split with a full `.md` file attachment\n- **Thinking display** — shows agent thinking/reasoning process in collapsible blocks\n- **Token tracking** — per-turn and cumulative input/output/cached token counts\n- **Access control** — restrict by chat/user ID whitelist\n- **Startup notice** — sends online status to all known chats on startup\n- **Full access / safe mode** — let the agent run freely, or require confirmation before destructive actions\n\n## Quick Start\n\n### Using npx (recommended)\n\n```bash\ncd your-project/\nnpx codeclaw -t YOUR_BOT_TOKEN\n```\n\n### Global install\n\n```bash\nnpm install -g codeclaw\ncd your-project/\ncodeclaw -t YOUR_BOT_TOKEN\n```\n\n\u003e **Prerequisites:** Node.js 18+, `claude` CLI and/or `codex` CLI installed, a Telegram Bot Token from [@BotFather](https://t.me/BotFather).\n\n## CLI Options\n\n```\ncodeclaw [options]\n```\n\n### Core\n\n| Flag | Env | Default | Description |\n|------|-----|---------|-------------|\n| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM channel: `telegram` (feishu, whatsapp planned) |\n| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token (or channel-specific env below) |\n| `-a, --agent` | `DEFAULT_AGENT` | `claude` | AI agent: `claude` or `codex` |\n| `-m, --model` | — | `claude-opus-4-6` / `gpt-5.4` | Model override (maps to agent-specific env) |\n| `-w, --workdir` | `CODECLAW_WORKDIR` | `.` | Working directory for the agent |\n\n### Access Control\n\n| Flag | Env | Default | Description |\n|------|-----|---------|-------------|\n| `--full-access` | `CODECLAW_FULL_ACCESS` | `true` | Agent can read/write/execute without confirmation |\n| `--safe-mode` | — | `false` | Require confirmation before destructive operations |\n| `--allowed-ids` | `TELEGRAM_ALLOWED_CHAT_IDS` | — | Comma-separated chat/user ID whitelist |\n| `--timeout` | `CODECLAW_TIMEOUT` | `300` | Max seconds per agent request |\n\n### Channel-specific Environment Variables\n\n| Env | Description |\n|-----|-------------|\n| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) |\n| `TELEGRAM_ALLOWED_CHAT_IDS` | Comma-separated allowed Telegram chat IDs |\n\n### Agent-specific Environment Variables\n\n| Env | Default | Description |\n|-----|---------|-------------|\n| `CLAUDE_MODEL` | `claude-opus-4-6` | Claude model name |\n| `CLAUDE_PERMISSION_MODE` | `bypassPermissions` | `bypassPermissions` or `default` |\n| `CLAUDE_EXTRA_ARGS` | — | Extra CLI args passed to `claude` |\n| `CODEX_MODEL` | `gpt-5.4` | Codex model name |\n| `CODEX_REASONING_EFFORT` | `xhigh` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |\n| `CODEX_FULL_ACCESS` | `true` | Bypass sandbox and approval prompts |\n| `CODEX_EXTRA_ARGS` | — | Extra CLI args passed to `codex` |\n\n### Examples\n\n```bash\n# Basic: Telegram + Claude Code, full access\nnpx codeclaw -t $BOT_TOKEN\n\n# Codex agent, safe mode, restricted users\nnpx codeclaw -t $BOT_TOKEN -a codex --safe-mode --allowed-ids 123456,789012\n\n# Custom model, custom working directory\nnpx codeclaw -t $BOT_TOKEN -m sonnet -w ~/projects/my-app\n\n# Using environment variables\nTELEGRAM_BOT_TOKEN=xxx CODEX_MODEL=o3 npx codeclaw -a codex\n```\n\n## Bot Commands\n\nOnce running, these commands are available in Telegram:\n\n| Command | Description |\n|---------|-------------|\n| `/sessions` | List, switch, or create sessions (paginated inline keyboard) |\n| `/agents` | List installed agents, switch between them |\n| `/switch` | Browse and change working directory (interactive file browser) |\n| `/status` | Bot status: uptime, memory, agent, session, token usage |\n| `/host` | Host machine info: CPU, memory, disk, top processes |\n| `/start` | Welcome message with command list |\n\n\u003e In private chats, just send text directly — no command prefix needed. Any unrecognized `/command` is forwarded to the agent as a prompt.\n\n## Development\n\n```bash\n# 1. Install dependencies\nnpm install\n\n# 2. Create .env file with your tokens\necho \"TELEGRAM_BOT_TOKEN=your_token_here\" \u003e .env\n\n# 3. Run locally\nset -a \u0026\u0026 source .env \u0026\u0026 npx tsx src/cli.ts\n\n# 4. Run tests\nnpm test\n```\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for the layered design:\n\n```\ncli.ts → bot-telegram.ts → bot.ts → code-agent.ts\n                ↓\n         channel-telegram.ts\n```\n\n- **bot.ts** — channel-agnostic business logic, state, streaming bridge\n- **bot-telegram.ts** — Telegram-specific rendering, keyboards, callbacks\n- **channel-telegram.ts** — pure Telegram API transport (polling, sending, file download)\n- **code-agent.ts** — AI agent abstraction (spawn CLI, parse JSONL stream)\n\nAdding a new IM channel means creating `channel-xxx.ts` + `bot-xxx.ts` without touching shared logic.\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003ca id=\"中文\"\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# codeclaw\n\n**IM 交互体验最好的远程编程工具。没有之一。**\n\n\u003c/div\u003e\n\n## 为什么选 codeclaw？\n\n大多数「AI + IM」桥接工具只是转发消息。codeclaw 从零开始为 **即时通讯上最好的远程编程体验** 而构建：\n\n- **实时流式输出** — 通过 Telegram 消息编辑逐 token 推送；你能实时看到 AI 的思考过程，而不是等 2 分钟后收到一大段文字\n- **系统级保活** — 触发操作系统级电源断言，防止笔记本休眠，确保长时间任务在你离开后依然完整执行\n- **多 Agent 热切换** — Claude Code + Codex CLI，一条 `/agents` 命令即可切换\n- **真正的多会话** — 命名会话 + 持久化线程 ID；重启 codeclaw 后可以无缝恢复之前的对话\n- **一条命令启动** — `npx codeclaw` 即可运行\n\n```\nTelegram（手机 / 桌面端）\n  ↕ 长轮询\ncodeclaw（你的机器，你的项目目录）\n  ↕ 子进程\nclaude / codex CLI\n  ↕ 读写\n你的代码库\n```\n\n不需要服务器，不需要 Docker，不需要配置文件。一个进程把 Telegram 桥接到你本地的 AI 编程助手。\n\n## 功能特性\n\n- **多 Agent** — Claude Code + Codex CLI，通过 `/agents` 内联键盘热切换\n- **流式输出** — 通过 Telegram 消息编辑实时逐 token 输出\n- **多会话** — 每个聊天支持命名会话管理、分页浏览和线程恢复\n- **系统保活** — 操作系统级防休眠（macOS `caffeinate`、Linux `systemd-inhibit`）\n- **目录浏览器** — 通过 `/switch` 交互式切换工作目录，内联导航\n- **图片输入** — 向机器人发送图片提供视觉上下文（截图、设计图）\n- **快捷回复** — 自动检测是/否问题和编号选项，显示内联按钮\n- **长文本处理** — 超出 Telegram 限制的回复自动拆分，并附带完整 `.md` 文件\n- **思考展示** — 在可折叠区块中显示 Agent 的思考/推理过程\n- **Token 统计** — 每轮和累计的输入/输出/缓存 token 计数\n- **访问控制** — 按聊天/用户 ID 白名单限制\n- **启动通知** — 启动时向所有已知聊天发送在线状态\n- **完全访问 / 安全模式** — 让 AI 自由运行，或限制危险操作需确认\n\n## 快速开始\n\n### 使用 npx（推荐）\n\n```bash\ncd your-project/\nnpx codeclaw -t YOUR_BOT_TOKEN\n```\n\n### 全局安装\n\n```bash\nnpm install -g codeclaw\ncd your-project/\ncodeclaw -t YOUR_BOT_TOKEN\n```\n\n\u003e **前置条件：** Node.js 18+，`claude` CLI 和/或 `codex` CLI 已安装，从 [@BotFather](https://t.me/BotFather) 获取 Telegram Bot Token。\n\n## 命令行选项\n\n```\ncodeclaw [选项]\n```\n\n### 核心参数\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|---------|--------|------|\n| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM 渠道：`telegram`（feishu、whatsapp 规划中） |\n| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token（或下方渠道专属环境变量） |\n| `-a, --agent` | `DEFAULT_AGENT` | `claude` | AI Agent：`claude` 或 `codex` |\n| `-m, --model` | — | `claude-opus-4-6` / `gpt-5.4` | 模型覆盖（映射到 Agent 专属环境变量） |\n| `-w, --workdir` | `CODECLAW_WORKDIR` | `.` | 工作目录 |\n\n### 访问控制\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|---------|--------|------|\n| `--full-access` | `CODECLAW_FULL_ACCESS` | `true` | Agent 可以无需确认地读写执行 |\n| `--safe-mode` | — | `false` | 执行危险操作前需确认 |\n| `--allowed-ids` | `TELEGRAM_ALLOWED_CHAT_IDS` | — | 允许交互的聊天/用户 ID，逗号分隔 |\n| `--timeout` | `CODECLAW_TIMEOUT` | `300` | 每次请求最大秒数 |\n\n### 渠道专属环境变量\n\n| 环境变量 | 说明 |\n|---------|------|\n| `TELEGRAM_BOT_TOKEN` | Telegram Bot Token（来自 @BotFather） |\n| `TELEGRAM_ALLOWED_CHAT_IDS` | 允许的 Telegram 聊天 ID，逗号分隔 |\n\n### Agent 专属环境变量\n\n| 环境变量 | 默认值 | 说明 |\n|---------|--------|------|\n| `CLAUDE_MODEL` | `claude-opus-4-6` | Claude 模型名 |\n| `CLAUDE_PERMISSION_MODE` | `bypassPermissions` | `bypassPermissions` 或 `default` |\n| `CLAUDE_EXTRA_ARGS` | — | 传递给 `claude` CLI 的额外参数 |\n| `CODEX_MODEL` | `gpt-5.4` | Codex 模型名 |\n| `CODEX_REASONING_EFFORT` | `xhigh` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |\n| `CODEX_FULL_ACCESS` | `true` | 跳过沙箱和确认提示 |\n| `CODEX_EXTRA_ARGS` | — | 传递给 `codex` CLI 的额外参数 |\n\n### 使用示例\n\n```bash\n# 基本用法：Telegram + Claude Code，完全访问\nnpx codeclaw -t $BOT_TOKEN\n\n# Codex Agent，安全模式，限制用户\nnpx codeclaw -t $BOT_TOKEN -a codex --safe-mode --allowed-ids 123456,789012\n\n# 自定义模型和工作目录\nnpx codeclaw -t $BOT_TOKEN -m sonnet -w ~/projects/my-app\n\n# 使用环境变量\nTELEGRAM_BOT_TOKEN=xxx CODEX_MODEL=o3 npx codeclaw -a codex\n```\n\n## 机器人命令\n\n运行后，以下命令可在 Telegram 中使用：\n\n| 命令 | 说明 |\n|------|------|\n| `/sessions` | 列出、切换或创建会话（分页内联键盘） |\n| `/agents` | 列出已安装的 Agent，切换使用 |\n| `/switch` | 浏览和切换工作目录（交互式文件浏览器） |\n| `/status` | 机器人状态：运行时间、内存、Agent、会话、Token 用量 |\n| `/host` | 宿主机信息：CPU、内存、磁盘、进程排行 |\n| `/start` | 欢迎消息和命令列表 |\n\n\u003e 在私聊中直接发送文字即可，无需命令前缀。未识别的 `/命令` 会作为 prompt 转发给 Agent。\n\n## 本地开发\n\n```bash\n# 1. 安装依赖\nnpm install\n\n# 2. 创建 .env 文件写入 token\necho \"TELEGRAM_BOT_TOKEN=your_token_here\" \u003e .env\n\n# 3. 本地运行\nset -a \u0026\u0026 source .env \u0026\u0026 npx tsx src/cli.ts\n\n# 4. 运行测试\nnpm test\n```\n\n## 架构\n\n详见 [ARCHITECTURE.md](ARCHITECTURE.md)：\n\n```\ncli.ts → bot-telegram.ts → bot.ts → code-agent.ts\n                ↓\n         channel-telegram.ts\n```\n\n- **bot.ts** — 渠道无关的业务逻辑、状态管理、流式桥接\n- **bot-telegram.ts** — Telegram 专属渲染、键盘、回调处理\n- **channel-telegram.ts** — 纯 Telegram API 传输层（轮询、发送、文件下载）\n- **code-agent.ts** — AI Agent 抽象（启动 CLI 子进程、解析 JSONL 流）\n\n添加新 IM 渠道只需创建 `channel-xxx.ts` + `bot-xxx.ts`，无需修改共享逻辑。\n\n## 许可证\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaotonng%2Fcodeclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaotonng%2Fcodeclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaotonng%2Fcodeclaw/lists"}