@eximia-ventures/claude-code-toolkit 3.0.0 → 3.0.1

package/README.md

@@ -0,0 +1,426 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@eximia-ventures/claude-code-toolkit?style=flat-square&color=5B4FE5&label=npm" alt="npm version" />
+  <img src="https://img.shields.io/npm/dt/@eximia-ventures/claude-code-toolkit?style=flat-square&color=5B4FE5" alt="downloads" />
+  <img src="https://img.shields.io/github/license/eximIA-Ventures/claude-code-toolkit?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/node/v/@eximia-ventures/claude-code-toolkit?style=flat-square" alt="node" />
+</p>
+
+<h1 align="center">claude-code-toolkit</h1>
+
+<p align="center">
+  <strong>Setup completo para Claude Code em um comando.</strong><br/>
+  Statusline customizada, session continuity e AIOS integration.
+</p>
+
+<p align="center">
+  <code>npx @eximia-ventures/claude-code-toolkit</code>
+</p>
+
+---
+
+## O que faz?
+
+O `claude-code-toolkit` transforma sua experiência com o Claude Code instalando automaticamente:
+
+| Recurso | Descrição |
+|---------|-----------|
+| **Statusline** | Barra de status em tempo real com modelo, contexto, custo, tempo e git |
+| **Session Handoff** | Continuidade de sessão entre `/clear` (7 slash commands, 2 hooks) |
+| **AIOS Framework** | Integração com orquestração de agentes AI (opt-in) |
+
+---
+
+## Statusline
+
+Após instalar, sua barra de status no Claude Code fica assim:
+
+```
+🟣 Opus 4.6 | 📅 16/02/2026 | 📊 4K | ⚡ 3 | ████░░░░░░ 42% | 💰 R$0.31 | ⏱ 1m05s | 🔀 main
+```
+
+### Segmentos
+
+| Segmento | Dados | Exemplo |
+|----------|-------|---------|
+| Modelo | `model.id` | `🟣 Opus 4.6`, `🔵 Sonnet 4.5`, `🔵 Haiku 4.5` |
+| Data | Sistema | `📅 16/02/2026` |
+| Contexto | `context_window.total_*_tokens` | `📊 4K`, `📊 120K`, `📊 1.2M` |
+| Mensagens | Transcript JSONL | `⚡ 3` |
+| Progresso | `context_window.used_percentage` | `████░░░░░░ 42%` |
+| Custo | `cost.total_cost_usd` × taxa | `💰 R$0.31`, `💰 $0.05`, `💰 €0.05` |
+| Tempo | `cost.total_duration_ms` | `⏱ 1m05s`, `⏱ 32s` |
+| Git | `git branch` (cache 5s) | `🔀 main`, `🔀 feat/login` |
+
+### Cores da barra de progresso
+
+```
+██████████ 100%   🔴 Vermelho (>80%)
+██████░░░░  60%   🟡 Amarelo  (60-80%)
+████░░░░░░  40%   🟢 Verde    (<60%)
+```
+
+### Moeda configurável
+
+A moeda do custo é definida no wizard e pode ser alterada via variáveis de ambiente:
+
+```bash
+export CLAUDE_TOOLKIT_CURRENCY="R$"       # Símbolo
+export CLAUDE_TOOLKIT_CURRENCY_RATE="6.20" # Taxa USD → moeda
+```
+
+---
+
+## Instalacao
+
+### Wizard interativo (recomendado)
+
+```bash
+npx @eximia-ventures/claude-code-toolkit
+```
+
+O wizard guia você pelas opções:
+
+```
+  ╔══════════════════════════════════════╗
+  ║   claude-code-toolkit v3.0.0        ║
+  ║   Setup completo para Claude Code   ║
+  ╚══════════════════════════════════════╝
+
+  ? Selecione o que deseja instalar:
+  ◉ Statusline      — Barra de status: modelo, contexto %, custo, tempo, git
+  ◉ Session Handoff — Continuidade de sessão (via claude-code-handoff)
+
+  ─── Configuração da Statusline ───
+
+  ? Moeda para exibição de custo:
+  > BRL (R$)  — Taxa: 6.20
+    USD ($)   — Sem conversão
+    EUR (€)   — Taxa: 0.92
+    Personalizada — Definir símbolo e taxa
+
+  ─── AIOS Framework ───
+
+  ? Vai utilizar o AIOS? (s/N)
+
+  ─── Instalando... ───
+
+  ✓ Statusline instalada em ~/.claude/statusline.sh
+  ✓ settings.json atualizado com statusLine
+  ✓ claude-code-handoff instalado (7 commands, 2 hooks, 2 rules)
+  ✓ Pronto!
+```
+
+### Instalacao direta (sem wizard)
+
+```bash
+# Statusline com BRL
+npx @eximia-ventures/claude-code-toolkit install --statusline-only --currency 'R$' --currency-rate 6.20
+
+# Apenas session handoff
+npx @eximia-ventures/claude-code-toolkit install --handoff-only
+
+# Tudo exceto AIOS
+npx @eximia-ventures/claude-code-toolkit install --no-aios
+```
+
+---
+
+## Fluxo de Instalacao
+
+```mermaid
+flowchart TD
+    A["npx @eximia-ventures/claude-code-toolkit"] --> B{Wizard interativo}
+
+    B --> C["Selecionar módulos"]
+    C --> D{Statusline?}
+    C --> E{Handoff?}
+    C --> F{AIOS?}
+
+    D -->|Sim| D1["Escolher moeda\nBRL / USD / EUR / Custom"]
+    D1 --> D2["Instala ~/.claude/statusline.sh\nMerge settings.json"]
+
+    E -->|Sim| E1["npx claude-code-handoff"]
+    E1 --> E2["7 commands + 2 hooks + 2 rules\n.claude/handoffs/"]
+
+    F -->|Sim| F1{Sub-opções}
+    F1 --> F2["AIOS Core\nnpx aios-core install"]
+    F1 --> F3["Skill /aios-integrate\n.claude/commands/"]
+
+    D2 --> G["Salva manifest\n.toolkit-manifest.json"]
+    E2 --> G
+    F2 --> G
+    F3 --> G
+
+    G --> H["✓ Pronto!\nReinicie o Claude Code"]
+
+    style A fill:#5B4FE5,color:#fff,stroke:none
+    style H fill:#22c55e,color:#fff,stroke:none
+    style D1 fill:#f59e0b,color:#000,stroke:none
+    style E1 fill:#3b82f6,color:#fff,stroke:none
+    style F2 fill:#8b5cf6,color:#fff,stroke:none
+    style F3 fill:#8b5cf6,color:#fff,stroke:none
+```
+
+---
+
+## Comandos
+
+### `install` (default)
+
+```bash
+npx @eximia-ventures/claude-code-toolkit [install] [options]
+```
+
+| Flag | Descrição |
+|------|-----------|
+| `--statusline-only` | Instala apenas a statusline |
+| `--handoff-only` | Instala apenas o session handoff |
+| `--no-aios` | Pula a configuração do AIOS |
+| `--currency <symbol>` | Símbolo da moeda (`R$`, `$`, `€`) |
+| `--currency-rate <rate>` | Taxa de conversão USD → moeda |
+
+### `doctor`
+
+Verifica a integridade da instalação com 10 checks:
+
+```bash
+npx @eximia-ventures/claude-code-toolkit doctor
+```
+
+```
+  ─── Diagnóstico ───
+
+  ✓ Manifest encontrado (v3.0.0)
+  ✓ Diretório ~/.claude/ existe
+  ✓ settings.json contém statusLine
+  ✓ statusline.sh existe e é executável
+  ✓ jq instalado (jq-1.7.1)
+  ✓ git version 2.50.1
+  ✓ Node.js v25.6.0
+  ✓ Handoff commands encontrados (7 de 7)
+  ✓ AIOS Core instalado no projeto
+  ✓ Skill /aios-integrate instalada
+
+  ✓ Tudo OK! (10 verificações passaram)
+```
+
+### `uninstall`
+
+Remove tudo que foi instalado, baseado no manifest:
+
+```bash
+npx @eximia-ventures/claude-code-toolkit uninstall [--force]
+```
+
+---
+
+## Modulos
+
+### 1. Statusline
+
+A feature principal. Instala um script bash em `~/.claude/statusline.sh` que recebe JSON do Claude Code via stdin e renderiza a barra de status.
+
+**Arquivos tocados:**
+
+| Arquivo | Ação |
+|---------|------|
+| `~/.claude/statusline.sh` | Criado (bash + jq) |
+| `~/.claude/settings.json` | Merge com `statusLine.command` |
+| `~/.claude/toolkit-env.sh` | Criado (variáveis de moeda) |
+
+**Requisito:** [jq](https://jqlang.github.io/jq/) instalado (`brew install jq`)
+
+### 2. Session Handoff
+
+Instala o pacote [`claude-code-handoff`](https://www.npmjs.com/package/claude-code-handoff) no projeto, que adiciona:
+
+| Tipo | Itens |
+|------|-------|
+| Slash Commands | `/resume`, `/handoff`, `/save-handoff`, `/switch-context`, `/delete-handoff`, `/auto-handoff`, `/context-doctor` |
+| Hooks | `context-monitor.sh`, `session-cleanup.sh` |
+| Rules | `session-continuity.md`, `auto-handoff.md` |
+| Estrutura | `.claude/handoffs/` |
+
+### 3. AIOS Framework (opt-in)
+
+Para quem usa o [Synkra AIOS](https://github.com/eximIA-Ventures) — framework de orquestração de agentes AI.
+
+**AIOS Core** — Instala/atualiza o framework via `npx aios-core install`
+
+**Skill `/aios-integrate`** — Slash command para o Claude Code que funciona como gerenciador de artefatos:
+
+```mermaid
+flowchart LR
+    A["/aios-integrate"] --> B{Ação}
+    B --> C["Integrar artefato\nexterno"]
+    B --> D["Listar artefatos\ninstalados"]
+    B --> E["Exportar\nartefatos"]
+
+    C --> C1["Agent .md/.yaml"]
+    C --> C2["Squad folder"]
+
+    C1 --> F[".codex/agents/\n.antigravity/agents/\n.agent/workflows/\nagents.csv\nslash commands"]
+
+    C2 --> G["./squads/\nagents.csv\nslash commands"]
+
+    style A fill:#5B4FE5,color:#fff,stroke:none
+    style C fill:#f59e0b,color:#000,stroke:none
+    style D fill:#3b82f6,color:#fff,stroke:none
+    style E fill:#22c55e,color:#fff,stroke:none
+```
+
+---
+
+## Arquitetura
+
+```
+claude-code-toolkit/
+├── package.json
+├── bin/
+│   └── cli.js                        # Entry point
+├── src/
+│   ├── index.js                      # CLI (Commander.js)
+│   ├── installer.js                  # Wizard interativo (Inquirer)
+│   ├── modules/
+│   │   ├── index.js                  # Registry dos módulos
+│   │   ├── statusline.js             # ~/.claude/statusline.sh + settings.json
+│   │   ├── handoff.js                # npx claude-code-handoff
+│   │   └── aios.js                   # npx aios-core + skill
+│   ├── commands/
+│   │   ├── uninstall.js              # Remoção via manifest
+│   │   └── doctor.js                 # 10 checks de integridade
+│   └── utils/
+│       ├── settings-merger.js        # Deep-merge seguro (com backup)
+│       ├── file-installer.js         # Cópia com hash comparison
+│       └── logger.js                 # Output estilizado (Chalk)
+└── assets/
+    ├── statusline/
+    │   └── statusline.sh             # Script bash (jq + ANSI)
+    └── skill/
+        └── aios-integrate.md         # Slash command para Claude Code
+```
+
+---
+
+## Como funciona
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant T as Toolkit CLI
+    participant S as ~/.claude/settings.json
+    participant SH as ~/.claude/statusline.sh
+    participant CC as Claude Code
+
+    U->>T: npx @eximia-ventures/claude-code-toolkit
+    T->>T: Wizard interativo
+    T->>SH: Copia statusline.sh
+    T->>S: Deep-merge statusLine config
+    T->>T: npx claude-code-handoff
+    T->>T: Salva manifest
+
+    Note over U,CC: Após reiniciar o Claude Code
+
+    CC->>S: Lê settings.json
+    CC->>SH: Executa statusline.sh (JSON via stdin)
+    SH->>SH: Parseia com jq
+    SH->>CC: Retorna string formatada
+    CC->>U: Exibe barra de status
+```
+
+---
+
+## Seguranca
+
+- **Backup automático**: `settings.json` é salvo como `.backup` antes de qualquer merge
+- **Deep-merge seguro**: Nunca sobrescreve configurações existentes, apenas adiciona/atualiza
+- **Hash comparison**: Arquivos só são sobrescritos se o conteúdo mudou
+- **Manifest**: Tudo que é instalado fica registrado em `.toolkit-manifest.json` para uninstall preciso
+- **Idempotente**: Rodar o install múltiplas vezes é seguro
+
+---
+
+## Requisitos
+
+| Dependência | Versão | Necessário para |
+|-------------|--------|-----------------|
+| Node.js | >= 18 | CLI |
+| jq | qualquer | Statusline |
+| git | qualquer | Segmento git da statusline |
+
+---
+
+## FAQ
+
+<details>
+<summary><strong>A statusline não aparece após instalar</strong></summary>
+
+1. Reinicie o Claude Code completamente (feche e abra)
+2. Rode `npx @eximia-ventures/claude-code-toolkit doctor` para verificar
+3. Confira se `jq` está instalado: `jq --version`
+</details>
+
+<details>
+<summary><strong>Como mudar a moeda depois de instalar?</strong></summary>
+
+Adicione ao seu `~/.zshrc` ou `~/.bashrc`:
+
+```bash
+export CLAUDE_TOOLKIT_CURRENCY="€"
+export CLAUDE_TOOLKIT_CURRENCY_RATE="0.92"
+```
+
+Ou rode o toolkit novamente — ele sobrescreve com a nova config.
+</details>
+
+<details>
+<summary><strong>Posso instalar só a statusline sem o handoff?</strong></summary>
+
+Sim: `npx @eximia-ventures/claude-code-toolkit install --statusline-only`
+</details>
+
+<details>
+<summary><strong>O install quebrou meu settings.json</strong></summary>
+
+O backup fica em `~/.claude/settings.json.backup`. Restaure com:
+
+```bash
+cp ~/.claude/settings.json.backup ~/.claude/settings.json
+```
+</details>
+
+<details>
+<summary><strong>Como remover tudo?</strong></summary>
+
+```bash
+npx @eximia-ventures/claude-code-toolkit uninstall
+```
+
+Isso lê o manifest e remove apenas o que foi instalado pelo toolkit.
+</details>
+
+---
+
+## Dependencias
+
+| Pacote | Versão | Motivo |
+|--------|--------|--------|
+| [commander](https://www.npmjs.com/package/commander) | ^12.1.0 | CLI framework |
+| [inquirer](https://www.npmjs.com/package/inquirer) | ^8.2.6 | Wizard interativo (CommonJS) |
+| [chalk](https://www.npmjs.com/package/chalk) | ^4.1.2 | Output colorido (CommonJS) |
+| [fs-extra](https://www.npmjs.com/package/fs-extra) | ^11.3.0 | File operations |
+| [claude-code-handoff](https://www.npmjs.com/package/claude-code-handoff) | ^2.1.0 | Session continuity |
+
+> **Nota:** `inquirer@8` e `chalk@4` são versões CommonJS — evita problemas de ESM com npx.
+
+---
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  Made with Claude Code by <a href="https://github.com/eximIA-Ventures">eximIA Ventures</a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eximia-ventures/claude-code-toolkit",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Setup completo para Claude Code: statusline, session handoff, AIOS integration",
   "main": "src/index.js",
   "bin": {

package/src/modules/statusline.js

@@ -13,6 +13,7 @@ const STATUSLINE_SRC = path.join(__dirname, '..', '..', 'assets', 'statusline',
 
 const STATUSLINE_SETTINGS = {
   statusLine: {
+    type: 'command',
     command: `bash ${STATUSLINE_DEST}`
   }
 };