cliclaw 1.0.0

package/.env.example

@@ -0,0 +1,16 @@
+# Token do bot (obter no @BotFather)
+TELEGRAM_BOT_TOKEN=
+
+# ID do grupo com Forum/Topics ativado (usar /id no grupo)
+FORUM_GROUP_ID=
+
+# Anthropic API Key (opcional — o bot usa OAuth do Claude Code CLI)
+# Deixar em branco se fizer login via: claude (abre link OAuth)
+ANTHROPIC_API_KEY=
+
+# OpenAI API Key (opcional — o bot usa o Codex CLI logado)
+# Deixar em branco se já logado via: codex login
+OPENAI_API_KEY=
+
+# Pasta de dados (padrão: ~/openclaw/data)
+DATA_DIR=

package/README.md

@@ -0,0 +1,241 @@
+# 🦀 Cli-Claw
+
+> **Cli-Claw** is a Telegram bot that acts as a **direct bridge between AI CLI tools and your phone**. Each conversation lives in a dedicated Forum Topic thread — you type from anywhere, the CLI runs on your server, the answer comes back. No API keys, no per-token billing, just your own subscription plan.
+
+```
+/new  →  opens a forum topic  →  🟣 Claude or 🟢 Codex
+ └ each topic = one CLI session with full conversation memory
+```
+
+📖 **[Leia em Português →](README.pt.md)**
+
+---
+
+## Why a CLI bridge?
+
+Most Telegram AI bots call HTTP APIs. Cli-Claw is different — it drives the actual CLI binaries installed on your server:
+
+| | Cli-Claw | API-based bots |
+|---|---|---|
+| **Auth** | OAuth / ChatGPT login | API keys (paid per token) |
+| **Cost** | Your subscription plan | Metered billing |
+| **Agentic tasks** | ✅ Full tool access | ❌ Limited |
+| **Permission control** | ✅ Per session / on demand | N/A |
+| **Adds a new CLI** | Just install & restart | N/A |
+
+Because it drives real CLI processes, Cli-Claw can do anything you can do in a terminal — install software, execute code, browse files, run long agentic workflows.
+
+---
+
+## Supported agents
+
+| Agent | Status | Notes |
+|---|---|---|
+| 🟣 **Claude Code** | ✅ Available | Requires claude.ai subscription |
+| 🟢 **Codex** | ✅ Available | Requires OpenAI/ChatGPT account |
+| 🔜 **OpenCode** | Coming soon | Open-source CLI, no subscription needed |
+
+Each agent you install becomes immediately available. The bot detects which CLIs are in `PATH` on startup and shows a setup guide for anything not yet configured.
+
+---
+
+## Bot commands
+
+| English | Portuguese | Description |
+|---|---|---|
+| `/new` | `/nova` | New Claude session (creates a forum topic) |
+| `/new codex` | `/nova codex` | New Codex session |
+| `/sessions` | `/sessoes` | List all sessions |
+| `/clear` | `/limpar` | Reset current session / topic |
+| `/status` | `/status` | Active session info |
+| `/id` | `/id` | Show this chat ID |
+| `/help` | `/ajuda` | Show help message |
+
+---
+
+## Requirements
+
+- **Ubuntu 22+** (tested on Oracle Cloud ARM64)
+- **Node.js 22+**
+- **Claude Code CLI** authenticated via OAuth (`claude`) — *optional, add to unlock 🟣*
+- **Codex CLI** authenticated via ChatGPT (`codex login`) — *optional, add to unlock 🟢*
+- A Telegram **group** with **Topics enabled**, bot added as **admin**
+
+---
+
+## Installation
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/luizfeer/cliclaw.git
+cd cliclaw
+npm install
+```
+
+### 2. Install Node.js 22 (if needed)
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+npm install -g tsx pm2
+```
+
+### 3. Install AI CLIs
+
+Install at least one. You can add more later — just restart the bot.
+
+```bash
+# Set up npm global prefix (no sudo)
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+
+# 🟣 Claude Code (requires claude.ai subscription)
+npm install -g @anthropic-ai/claude-code
+claude   # opens OAuth link in your browser
+
+# 🟢 Codex (requires OpenAI/ChatGPT account)
+npm install -g @openai/codex
+codex login
+```
+
+> **Don't have either yet?** That's fine — install the bot first, then send `/start` in Telegram. The bot will show exactly what to run.
+
+### 4. Configure
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+```env
+TELEGRAM_BOT_TOKEN=   # from @BotFather → /newbot
+FORUM_GROUP_ID=       # run /id inside your group to get it
+```
+
+### 5. Choose a permission mode
+
+Add `PERMISSION_MODE` to your `.env`:
+
+| Mode | Value | Behavior |
+|---|---|---|
+| **Full auto** *(recommended)* | `auto` | Always skips all permission prompts — models run freely |
+| **Per session** | `session` | Bot asks when you run `/new`: *"Allow full auto for this session?"* |
+| **On demand** | `ask` | Restricted by default; prefix any message with `!` to grant full auto for that message only |
+
+```env
+PERMISSION_MODE=auto
+```
+
+### 6. Set up Telegram group
+
+1. Create a Telegram group
+2. **Edit group → Topics → Enable**
+3. Add your bot as **Admin** with *Manage Topics* permission
+4. Send `/id` in the group and copy the Chat ID
+5. Paste it as `FORUM_GROUP_ID` in `.env`
+
+### 7. Start
+
+```bash
+# Test run
+npx tsx index.ts
+
+# Production — auto-restarts on crash and reboot
+pm2 start ecosystem.config.js
+pm2 save && pm2 startup
+```
+
+---
+
+## How it works
+
+```
+Message in forum topic
+       ↓
+Resolve session by thread_id
+       ↓
+Lock session (prevent concurrent processes)
+       ↓
+Send "⚙️ Processing..." + typing loop every 4s
+       ↓
+Spawn CLI based on PERMISSION_MODE:
+  claude --resume <id> -p "msg" --output-format text
+  codex exec resume <thread> --json "msg"
+       ↓
+Process runs to completion (no kill timeout)
+       ↓
+Delete "Processing..." → send formatted HTML response
+```
+
+Session IDs are saved to `data/chat_<id>.json` — context survives bot restarts.
+
+---
+
+## Publishing to npm *(planned)*
+
+The goal is to make installation a single command:
+
+```bash
+npm install -g cliclaw
+cliclaw setup   # interactive wizard: bot token, group ID, permission mode
+cliclaw start
+```
+
+This requires a `cli.js` setup wizard and a compiled entry point. The CLIs (`claude`, `codex`) will still need to be authenticated manually — npm can bundle the bot code but not OAuth sessions. The wizard would guide through that step.
+
+Contributions welcome: **[github.com/luizfeer/cliclaw](https://github.com/luizfeer/cliclaw)**
+
+---
+
+## Project structure
+
+```
+cliclaw/
+├── index.ts                   # Entry point
+├── ecosystem.config.js        # PM2 config (uses tsx)
+├── src/
+│   ├── config.ts              # Loads .env + detects available CLIs
+│   ├── storage.ts             # JSON session persistence
+│   ├── agents/
+│   │   ├── claude.ts          # Claude Code CLI wrapper
+│   │   └── codex.ts           # Codex CLI wrapper
+│   ├── handlers/
+│   │   ├── commands.ts        # /new /sessions /clear etc.
+│   │   └── messages.ts        # Routes by thread_id, typing loop, lock
+│   └── utils/
+│       └── markdown.ts        # Markdown → Telegram HTML
+├── data/                      # Session JSON files (git-ignored)
+├── .env                       # Secrets (git-ignored)
+└── .env.example               # Template
+```
+
+---
+
+## Deploy to another VPS
+
+```bash
+git clone https://github.com/luizfeer/cliclaw.git
+cd cliclaw && npm install
+npm install -g tsx pm2 @anthropic-ai/claude-code @openai/codex
+claude && codex login
+cp .env.example .env && nano .env
+pm2 start ecosystem.config.js && pm2 save
+```
+
+---
+
+## Contributing
+
+Cli-Claw is an open community project. PRs welcome — especially:
+- New CLI agent adapters (OpenCode, Gemini CLI, etc.)
+- `cliclaw setup` wizard for npm distribution
+- i18n improvements
+- Better permission UX
+
+---
+
+## License
+
+MIT

package/README.pt.md

@@ -0,0 +1,241 @@
+# 🦀 Cli-Claw
+
+> **Cli-Claw** é um bot Telegram que funciona como **ponte direta entre ferramentas CLI de IA e o seu celular**. Cada conversa vive em um tópico dedicado de Fórum — você digita de qualquer lugar, o CLI roda no servidor, a resposta volta. Sem API keys, sem cobrança por token, só o seu plano de assinatura.
+
+```
+/nova  →  abre um tópico no fórum  →  🟣 Claude ou 🟢 Codex
+ └ cada tópico = uma sessão CLI com memória completa de conversa
+```
+
+📖 **[Read in English →](README.md)**
+
+---
+
+## Por que uma ponte de CLI?
+
+A maioria dos bots Telegram de IA chama APIs HTTP. O Cli-Claw é diferente — ele aciona os binários CLI instalados no seu servidor:
+
+| | Cli-Claw | Bots baseados em API |
+|---|---|---|
+| **Autenticação** | OAuth / login ChatGPT | API keys (pago por token) |
+| **Custo** | Seu plano de assinatura | Cobrança por uso |
+| **Tarefas agênticas** | ✅ Acesso completo às ferramentas | ❌ Limitado |
+| **Controle de permissões** | ✅ Por sessão / sob demanda | N/A |
+| **Adicionar novo CLI** | Instale e reinicie | N/A |
+
+Por acionar processos CLI reais, o Cli-Claw pode fazer tudo o que você faria no terminal — instalar software, executar código, navegar em arquivos, rodar workflows agênticos longos.
+
+---
+
+## Agentes disponíveis
+
+| Agente | Status | Requisito |
+|---|---|---|
+| 🟣 **Claude Code** | ✅ Disponível | Assinatura claude.ai |
+| 🟢 **Codex** | ✅ Disponível | Conta OpenAI/ChatGPT |
+| 🔜 **OpenCode** | Em breve | CLI open-source, sem assinatura |
+
+Cada agente que você instala fica disponível imediatamente. O bot detecta quais CLIs estão no `PATH` ao iniciar e exibe um guia de configuração para o que ainda não está instalado.
+
+---
+
+## Comandos do bot
+
+| Português | Inglês | Descrição |
+|---|---|---|
+| `/nova` | `/new` | Nova sessão Claude (cria tópico no fórum) |
+| `/nova codex` | `/new codex` | Nova sessão Codex |
+| `/sessoes` | `/sessions` | Listar todas as sessões |
+| `/limpar` | `/clear` | Reiniciar sessão / tópico atual |
+| `/status` | `/status` | Info da sessão ativa |
+| `/id` | `/id` | Ver ID deste chat |
+| `/ajuda` | `/help` | Exibir ajuda |
+
+---
+
+## Requisitos
+
+- **Ubuntu 22+** (testado em Oracle Cloud ARM64)
+- **Node.js 22+**
+- **Claude Code CLI** autenticado via OAuth (`claude`) — *opcional, instale para ativar 🟣*
+- **Codex CLI** autenticado via ChatGPT (`codex login`) — *opcional, instale para ativar 🟢*
+- Um **grupo** Telegram com **Tópicos ativados**, bot adicionado como **admin**
+
+---
+
+## Instalação
+
+### 1. Clonar e instalar
+
+```bash
+git clone https://github.com/luizfeer/cliclaw.git
+cd cliclaw
+npm install
+```
+
+### 2. Instalar Node.js 22 (se necessário)
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+npm install -g tsx pm2
+```
+
+### 3. Instalar os CLIs de IA
+
+Instale pelo menos um. Pode adicionar mais depois — basta reiniciar o bot.
+
+```bash
+# Configurar npm global sem sudo
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+
+# 🟣 Claude Code (requer assinatura claude.ai)
+npm install -g @anthropic-ai/claude-code
+claude   # abre link OAuth no navegador
+
+# 🟢 Codex (requer conta OpenAI/ChatGPT)
+npm install -g @openai/codex
+codex login
+```
+
+> **Ainda não tem nenhum?** Tudo bem — instale o bot primeiro, depois envie `/start` no Telegram. O bot mostrará exatamente o que executar.
+
+### 4. Configurar
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+```env
+TELEGRAM_BOT_TOKEN=   # obtido no @BotFather → /newbot
+FORUM_GROUP_ID=       # use /id dentro do grupo para obter
+```
+
+### 5. Escolher o modo de permissões
+
+Adicione `PERMISSION_MODE` ao seu `.env`:
+
+| Modo | Valor | Comportamento |
+|---|---|---|
+| **Full auto** *(recomendado)* | `auto` | Sempre pula prompts de permissão — modelos rodam livremente |
+| **Por sessão** | `session` | Bot pergunta ao criar `/nova`: *"Permitir full auto nesta sessão?"* |
+| **Sob demanda** | `ask` | Restrito por padrão; prefixe mensagens com `!` para liberar só aquele envio |
+
+```env
+PERMISSION_MODE=auto
+```
+
+### 6. Configurar o grupo Telegram
+
+1. Crie um grupo no Telegram
+2. **Editar grupo → Tópicos → Ativar**
+3. Adicione o bot como **Admin** com permissão de *Gerenciar Tópicos*
+4. Envie `/id` no grupo e copie o Chat ID
+5. Cole como `FORUM_GROUP_ID` no `.env`
+
+### 7. Iniciar
+
+```bash
+# Teste rápido
+npx tsx index.ts
+
+# Produção — reinicia automaticamente em crash e reboot
+pm2 start ecosystem.config.js
+pm2 save && pm2 startup
+```
+
+---
+
+## Como funciona
+
+```
+Mensagem no tópico do fórum
+       ↓
+Identifica sessão pelo thread_id
+       ↓
+Lock da sessão (impede processos concorrentes)
+       ↓
+Envia "⚙️ Processando..." + typing loop a cada 4s
+       ↓
+Spawn do CLI com base no PERMISSION_MODE:
+  claude --resume <id> -p "msg" --output-format text
+  codex exec resume <thread> --json "msg"
+       ↓
+Processo roda até terminar (sem timeout que mata o processo)
+       ↓
+Deleta "Processando..." → envia resposta formatada em HTML
+```
+
+Os IDs de sessão são salvos em `data/chat_<id>.json` — o contexto sobrevive a reinicializações.
+
+---
+
+## Publicar no npm *(planejado)*
+
+O objetivo é tornar a instalação um único comando:
+
+```bash
+npm install -g cliclaw
+cliclaw setup   # wizard interativo: token do bot, ID do grupo, modo de permissão
+cliclaw start
+```
+
+Isso requer um wizard `cli.js` e um entry point compilado. Os CLIs (`claude`, `codex`) ainda precisariam ser autenticados manualmente — o npm pode empacotar o código do bot mas não sessões OAuth. O wizard guiaria por esse passo.
+
+Contribuições são bem-vindas: **[github.com/luizfeer/cliclaw](https://github.com/luizfeer/cliclaw)**
+
+---
+
+## Estrutura do projeto
+
+```
+cliclaw/
+├── index.ts                   # Ponto de entrada
+├── ecosystem.config.js        # Configuração PM2 (usa tsx)
+├── src/
+│   ├── config.ts              # Carrega .env + detecta CLIs disponíveis
+│   ├── storage.ts             # Persistência de sessões em JSON
+│   ├── agents/
+│   │   ├── claude.ts          # Wrapper do CLI Claude Code
+│   │   └── codex.ts           # Wrapper do CLI Codex
+│   ├── handlers/
+│   │   ├── commands.ts        # /nova /sessoes /limpar etc.
+│   │   └── messages.ts        # Roteamento por thread_id, typing loop, lock
+│   └── utils/
+│       └── markdown.ts        # Conversor Markdown → HTML do Telegram
+├── data/                      # Arquivos JSON de sessão (ignorado pelo git)
+├── .env                       # Segredos (ignorado pelo git)
+└── .env.example               # Template de configuração
+```
+
+---
+
+## Deploy em outra VPS
+
+```bash
+git clone https://github.com/luizfeer/cliclaw.git
+cd cliclaw && npm install
+npm install -g tsx pm2 @anthropic-ai/claude-code @openai/codex
+claude && codex login
+cp .env.example .env && nano .env
+pm2 start ecosystem.config.js && pm2 save
+```
+
+---
+
+## Contribuindo
+
+Cli-Claw é um projeto aberto para a comunidade. PRs são bem-vindos — especialmente:
+- Novos adaptadores de agentes CLI (OpenCode, Gemini CLI, etc.)
+- Wizard `cliclaw setup` para distribuição via npm
+- Melhorias de i18n
+- UX de permissões mais refinada
+
+---
+
+## Licença
+
+MIT