openclacky 1.1.2 → 1.1.3

data/docs/session-management-redesign.md

@@ -1,202 +0,0 @@
-# Session Management Redesign
-
-> Status: Design finalized, pending implementation
-> Date: 2026-03-22
-
----
-
-## Background
-
-Current session management has several problems:
-
-| Problem | Detail |
-|---------|--------|
-| **Delete bug (P0)** | `DELETE /api/sessions/:id` only removes from in-memory registry, disk JSON file is never deleted |
-| **Retention too small** | `cleanup_by_count(keep: 10)` — floods quickly with cron + channel sessions |
-| **Only 5 sessions restored on startup** | Misses most cron/channel history |
-| **No agent type selection in WebUI** | Always creates `general` profile, no UI to choose |
-| **No session source tracking** | No `source` field — can't distinguish manual vs cron vs channel |
-| **No agent profile tracking** | No `agent_profile` field in session JSON |
-
----
-
-## UI Design
-
-### Sidebar Layout
-
-```
-┌─────────────────────────────────┐
-│  Sessions          [+ ▾]        │
-├─────────────────────────────────┤
-│  Manual  Scheduled  Channel     │  ← tab 切换
-├─────────────────────────────────┤
-│                                  │
-│  ● Session 3        2t  $0.02   │
-│  ○ Session 2        5t  $0.08   │
-│  ○ Session 1        1t  $0.01   │
-│                                  │
-├─────────────────────────────────┤
-│  👨‍💻 Coding                       │  ← 固定区域，不参与 tab
-├─────────────────────────────────┤
-│  ● 重构 auth 模块   3t  $0.05   │
-│  ○ 接口联调         1t  $0.02   │
-└─────────────────────────────────┘
-```
-
-**Upper area — General Agent sessions:**
-- Three tabs: `Manual` / `Scheduled` / `Channel`
-- Default tab: `Manual`
-- Each tab shows sessions filtered by `source` field AND `agent_profile = general`
-- Scheduled and Channel tabs show sessions where `agent_profile = general` AND `source = cron/channel`
-
-**Lower area — Coding Agent (and future agents):**
-- Fixed section, always visible, does not participate in tab switching
-- Shows all sessions where `agent_profile = coding`, regardless of source
-- Future custom agents each get their own section below Coding
-
----
-
-### New Session Button: `[+ ▾]`
-
-```
-┌─────────────────────────────────┐
-│  Sessions          [+ ▾]        │
-└─────────────────────────────────┘
-```
-
-- **Click `+`** → immediately create a new General session (zero friction, most common action)
-- **Click `▾`** → dropdown appears:
-
-```
-                    ┌──────────────────┐
-                    │ ✦ General        │
-                    │ 👨‍💻 Coding         │
-                    │ ──────────────── │
-                    │ + Create Agent   │  ← future
-                    └──────────────────┘
-```
-
-- Selecting an agent from the dropdown creates a new session with that `agent_profile`
-- `Create Agent` is a placeholder for future custom agent creation UI
-
----
-
-## Data Layer Changes
-
-### Session JSON — new fields
-
-```json
-{
-  "session_id": "...",
-  "source": "manual",
-  "agent_profile": "general",
-  ...
-}
-```
-
-**`source` values:** `manual` | `cron` | `channel`
-**`agent_profile` values:** `general` | `coding` | `<custom-name>`
-
-### `build_session` signature update
-
-```ruby
-build_session(
-  name:,
-  working_dir:,
-  source: :manual,          # :manual | :cron | :channel
-  profile: "general",       # agent profile name
-  permission_mode: :confirm_all
-)
-```
-
-Both `source` and `agent_profile` must be serialized into the session JSON and restored on `from_session`.
-
----
-
-## New API Endpoints
-
-### `GET /api/agents`
-
-Returns all available agent profiles (built-in + user custom).
-
-Scan order:
-1. `~/.clacky/agents/<name>/profile.yml` (user override / custom)
-2. `<gem>/lib/clacky/default_agents/<name>/profile.yml` (built-in)
-
-Response:
-```json
-{
-  "agents": [
-    { "name": "general", "description": "A versatile digital employee living on your computer", "builtin": true },
-    { "name": "coding",  "description": "AI coding assistant and technical co-founder", "builtin": true },
-    { "name": "my-pm",   "description": "Product manager assistant", "builtin": false }
-  ]
-}
-```
-
-### `POST /api/sessions` — updated body
-
-```json
-{
-  "name": "Session 4",
-  "agent_profile": "coding"
-}
-```
-
-`source` is always `manual` for API-created sessions. `agent_profile` defaults to `"general"` if omitted.
-
-### `DELETE /api/sessions/:id` — fix
-
-Must delete the disk JSON file in addition to removing from registry:
-
-```ruby
-def api_delete_session(session_id, res)
-  if @registry.delete(session_id)
-    @session_manager.delete(session_id)   # ← ADD THIS
-    broadcast(session_id, { type: "session_deleted", session_id: session_id })
-    unsubscribe_all(session_id)
-    json_response(res, 200, { ok: true })
-  else
-    json_response(res, 404, { error: "Session not found" })
-  end
-end
-```
-
-`SessionManager` needs a `delete(session_id)` method that finds and removes the file by session_id prefix.
-
----
-
-## Persistence Strategy Changes
-
-| Setting | Current | New |
-|---------|---------|-----|
-| Count limit | `keep: 10` | `keep: 200` |
-| Time-based cleanup | None | Delete sessions not accessed in **90 days** |
-| Cleanup timing | On every save | On server startup + every 24h |
-| Sessions restored on startup | 5 (current dir only) | 20 (current dir) |
-
----
-
-## Implementation Order
-
-1. **Fix DELETE bug** — `api_delete_session` + `SessionManager#delete` by session_id
-2. **Data fields** — add `source` + `agent_profile` to `build_session`, `to_session_data`, `restore_session`
-3. **Channel/Cron tagging** — pass `source: :channel` / `source: :cron` when `ChannelManager` and cron create sessions
-4. **Persistence upgrade** — `keep: 200`, 90-day cleanup, restore 20 on startup
-5. **`GET /api/agents`** — scan both dirs, merge, return list
-6. **Frontend — sidebar redesign** — Manual/Scheduled/Channel tabs + Coding fixed section
-7. **Frontend — `[+ ▾]` button** — split button with agent dropdown
-
----
-
-## File Locations
-
-| File | Change |
-|------|--------|
-| `lib/clacky/session_manager.rb` | Add `delete(session_id)`, change keep to 200, add 90-day cleanup |
-| `lib/clacky/agent/session_serializer.rb` | Serialize/restore `source` + `agent_profile` |
-| `lib/clacky/server/http_server.rb` | Fix `api_delete_session`, add `GET /api/agents`, update `build_session`, restore 20 sessions |
-| `lib/clacky/server/session_registry.rb` | Expose `agent_profile` + `source` in `session_summary` |
-| `lib/clacky/server/channel/channel_manager.rb` | Pass `source: :channel` to `build_session` |
-| `lib/clacky/web/sessions.js` | Tab switching, Coding section, `[+ ▾]` button |
-| CSS / HTML template | New sidebar layout, tab styles, split button |

data/docs/system-skill-authoring-guide.md

@@ -1,47 +0,0 @@
-# System Skill Authoring Guide
-
-Guidelines for writing built-in (system-level) skills under `lib/clacky/default_skills/`.
-
----
-
-## 1. Communicating with the Clacky server
-
-Always use environment variables — never hardcode the port.
-
-```bash
-curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/xxx
-```
-
-`http_server.rb` injects `CLACKY_SERVER_HOST` and `CLACKY_SERVER_PORT` at startup.
-
----
-
-## 2. Read state via API, not config files
-
-Skills must not read local config files directly.
-
-- ❌ `cat ~/.clacky/browser.yml`
-- ✅ `curl http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/status`
-
-Exception: lightweight `enable` / `disable` operations may read/write yml directly (see `channel-manager`).
-
----
-
-## 3. Running supporting scripts
-
-If a skill includes supporting scripts, instruct the AI to run them directly using the full path — **do not describe how to discover the path**. The LLM context already contains the full paths of all files in the skill directory (injected via supporting files at invoke time).
-
-Write it simply as:
-
-```
-Run the setup script:
-ruby SKILL_DIR/scripts/feishu_setup.rb
-```
-
-or for Python:
-
-```
-python3 SKILL_DIR/scripts/setup.py
-```
-
-No `Gem.find_files`, no `find` fallback, no path-discovery logic needed.

data/docs/why-developer.md

@@ -1,371 +0,0 @@
-# Why Clacky for Professional Developers
-
-## Executive Summary
-
-Clacky is an open-source, CLI-first AI development assistant designed specifically for professional developers. It addresses critical pain points in existing AI coding tools while providing enterprise-grade features including multi-model support, automated safety mechanisms, and cost-optimized architecture.
-
-**Key Results:**
-- **50% lower cost** compared to Claude Code
-- **Zero vendor lock-in** with multi-model support
-- **Fully automated** with confirm_safe and auto_approve modes
-- **Production validated** - used to self-iterate Clacky for 3 weeks
-
----
-
-## The Problem
-
-Professional developers face three critical pain points with existing AI coding tools:
-
-### 1. Performance & Reliability Issues
-
-| Issue | Impact |
-|-------|--------|
-| **Slow response** | Interrupted workflow, reduced productivity |
-| **API blocking/banning** | Business continuity risk, especially for non-US developers |
-| **Region restrictions** | Limited access to premium models |
-
-### 2. High Costs
-
-| Tool | Monthly Cost | Pain Point |
-|------|--------------|------------|
-| Claude Code | $17-200/seat | Expensive for teams |
-| Cursor Pro | $20+/month | Addictive pricing model |
-| GitHub Copilot | $10-100/seat | Accumulated costs |
-
-**Problem**: Most tools lock you into expensive APIs without transparency on cost drivers.
-
-### 3. Lack of Safe Automation
-
-Current AI coding tools require constant vigilance:
-
-```
-❌ Every command requires manual confirmation
-❌ No automatic risk detection and mitigation
-❌ "Watch mode" fatigue - developers must stare at screens
-❌ Cannot run unattended for complete tasks
-❌ Dangerous commands (rm, curl | sh) require manual review
-```
-
----
-
-## The Solution: Clacky
-
-Clacky addresses all three pain points with a developer-first approach.
-
-### 1. Multi-Model Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Clacky Multi-Model Support               │
-├─────────────────────────────────────────────────────────────┤
-│ ✅ OpenRouter           │ Unified access to 100+ models      │
-│ ✅ OpenAI               │ GPT-4, GPT-4o compatibility       │
-│ ✅ Anthropic Config     │ Claude Code configuration compat  │
-│ ✅ DeepSeek             │ 95% cheaper than OpenAI           │
-│ ✅ M2.1 Support         │ Latest model versions             │
-│ ✅ Custom Endpoints     │ Bring your own API server         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Benefits:**
-- No single point of failure
-- Choose the best model for each task
-- Significant cost savings with alternative providers
-- Bypass regional restrictions
-
-### 2. Smart Automation Modes
-
-#### confirm_safe Mode
-
-Automatically approves low-risk operations while keeping you in control:
-
-| Operation | Behavior |
-|-----------|----------|
-| File reads | ✅ Auto-approved |
-| Directory listing | ✅ Auto-approved |
-| Search operations | ✅ Auto-approved |
-| Safe shell commands | ✅ Auto-approved |
-| Dangerous commands | ⚠️ Replaced with safe alternatives |
-| File edits | 🔒 Confirmation required |
-| File deletions | 🔒 Confirmation required |
-
-**Result**: ~70% of commands run automatically, dramatically reducing watch mode fatigue.
-
-#### auto_approve Mode
-
-Complete hands-off operation for batch tasks:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                  auto_approve Mode                          │
-├─────────────────────────────────────────────────────────────┤
-│ • Execute complete requirements without interruption       │
-│ • Dangerous operations automatically replaced              │
-│ • No file edit confirmations required                      │
-│ • Ideal for: refactoring, testing, batch processing         │
-│ • Risk level: Low (with SafeShell protection)              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-#### SafeShell Protection
-
-Clacky's SafeShell automatically:
-
-1. **Detects dangerous commands**: `rm -rf`, `curl | sh`, `sudo`
-2. **Replaces with safe alternatives**:
-   - `rm` → Moves to trash (recoverable)
-   - `curl | sh` → Blocks and warns
-   - Dangerous git operations → Confirmed first
-3. **Enforces project boundaries**: Cannot escape project directory
-4. **Logs all operations**: Audit trail for security review
-
-### 3. Cost-Optimized Architecture
-
-#### Real-Time Cost Transparency
-
-Every request displays:
-```
-💰 Cost: $0.0042 (Claude 3.5 Sonnet)
-📊 Tokens: 1,250 in / 850 out
-🗜️ Compression saved: 60%
-```
-
-#### Advanced Context Management
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│               Cost Optimization Pipeline                    │
-├─────────────────────────────────────────────────────────────┤
-│ 1. Request received                                        │
-│           ↓                                                │
-│ 2. Context compression (60% reduction typical)             │
-│           ↓                                                │
-│ 3. Tool call pre-filtering                                 │
-│    • Expensive operations identified early                 │
-│    • Smart caching for repeated operations                │
-│           ↓                                                │
-│ 4. Model selection optimization                            │
-│    • Use cheaper models for simple tasks                  │
-│    • Reserve expensive models for complex reasoning       │
-│           ↓                                                │
-│ 5. Response generation                                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Measured Results:**
-- **50% lower cost** vs Claude Code
-- **60% context compression** on average
-- **Early tool filtering** eliminates unnecessary expensive calls
-
----
-
-## Validation: Production-Proven
-
-### Self-Iteration Test (3 Weeks)
-
-Clacky was used to develop and iterate on itself for three consecutive weeks:
-
-| Metric | Result |
-|--------|--------|
-| Self-contained development | ✅ Complete |
-| Feature parity with Claude Code | ✅ Achieved |
-| Code quality | ✅ Production-ready |
-| External research tasks | ✅ webfetch outperformed Claude Code |
-
-### WebFetch Advantage
-
-For tasks requiring external web resources:
-- Clacky's webfetch tool is more reliable
-- Better handling of dynamic content
-- Faster response times
-
-### Team Validation
-
-- **Internal team**: 100% adoption for daily development
-- **Production deployments**: Zero critical incidents
-- **Developer satisfaction**: "Cannot go back to Claude Code"
-
----
-
-## Feature Comparison
-
-| Feature | **Clacky** | Claude Code | Cursor | Lovable |
-|---------|------------|-------------|--------|---------|
-| **Multi-Model Support** | ✅ Full | ❌ Anthropic only | ❌ OpenAI only | ⚠️ Limited |
-| **Self-Hosted** | ✅ Yes | ❌ No | ❌ No | ❌ No |
-| **confirm_safe Mode** | ✅ Yes | ❌ No | ❌ No | ❌ No |
-| **auto_approve Mode** | ✅ Yes | ❌ No | ❌ No | ❌ No |
-| **SafeShell Protection** | ✅ Auto | ⚠️ Manual | ⚠️ Manual | N/A |
-| **Real-Time Cost** | ✅ Full | ⚠️ Limited | ⚠️ Limited | ❌ No |
-| **Cost Reduction** | ✅ 50% | Baseline | +20% | +25% |
-| **Session Persistence** | ✅ Full | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited |
-| **Open Source** | ✅ MIT | ❌ Closed | ❌ Closed | ❌ Closed |
-| **Skills/Plugins** | ✅ Extensible | ❌ No | ⚠️ Limited | ❌ No |
-
----
-
-## Technical Architecture
-
-### Tool System
-
-Clacky uses a modular tool architecture:
-
-```
-Clacky::Tools::Base
-├── FileTool (read, write, edit, glob)
-├── ShellTool (safe execution with protection)
-├── WebTool (fetch, search)
-├── GitTool (status, commit, branch)
-├── CodeTool (run, test, lint)
-└── Custom Tools (user-defined)
-```
-
-### Agent Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   React-Based Agent                         │
-├─────────────────────────────────────────────────────────────┤
-│ 1. REASON   → Analyze task and context                     │
-│ 2. ACT      → Execute tools (with safety filters)          │
-│ 3. OBSERVE  → Process results and plan next step           │
-│                                                            │
-│ Loop until task completion or max iterations               │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Configuration
-
-Clacky is compatible with Claude Code's configuration format:
-
-```yaml
-# ~/.clacky/config.yml
-api:
-  provider: openrouter  # or openai, anthropic, deepseek
-  model: claude-3-5-sonnet
-  api_key: ${OPENROUTER_API_KEY}
-
-automation:
-  mode: confirm_safe  # or auto_approve, manual
-  safe_shell: true
-  cost_alert: 0.10
-
-models:
-  default: claude-3-5-sonnet
-  cheap: deepseek-chat
-  reasoning: claude-3-opus
-```
-
----
-
-## Cost Analysis
-
-### Monthly Cost Comparison (Individual Developer)
-
-| Tool | API Cost | Tool Cost | **Total** |
-|------|----------|-----------|-----------|
-| Claude Code | $17-200 | Included | $17-200 |
-| Cursor Pro | $20 | + API costs | $40-100 |
-| **Clacky + DeepSeek** | ~$5 | Free | **$5** |
-| **Clacky + OpenRouter** | ~$10 | Free | **$10** |
-
-### Annual Savings
-
-| Team Size | Claude Code | Clacky | **Annual Savings** |
-|-----------|-------------|--------|-------------------|
-| 5 developers | $1,020 | $600 | **$420 (41%)** |
-| 10 developers | $2,040 | $1,200 | **$840 (41%)** |
-| 50 developers | $10,200 | $6,000 | **$4,200 (41%)** |
-
----
-
-## Quick Start
-
-### Installation
-
-```bash
-# One-line installation (macOS/Linux)
-curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh | bash
-
-# Or via Ruby gem
-gem install openclacky
-```
-
-### Configuration
-
-```bash
-# Interactive configuration wizard
-clacky config set
-
-# Or set API key directly
-export OPENROUTER_API_KEY=your-api-key
-```
-
-### Usage
-
-```bash
-# Start interactive agent
-clacky agent
-
-# Run with confirm_safe (recommended for daily use)
-clacky agent --mode confirm_safe "Refactor the authentication module"
-
-# Run fully automated for complete tasks
-clacky agent --mode auto_approve "Write integration tests for all controllers"
-
-# Attach to existing session
-clacky agent -c
-
-# List available tools
-clacky tools
-```
-
----
-
-## Why Professional Developers Choose Clacky
-
-### Performance
-- Faster response with multi-model failover
-- No more watching for API blocks
-- Production-validated reliability
-
-### Cost Control
-- Transparent, real-time cost visibility
-- 50% lower operational costs
-- No vendor lock-in
-
-### Automation
-- reclaim hours of watch time each week
-- Complete unattended task execution
-- Smart safety without friction
-
-### Flexibility
-- Open source and self-hostable
-- Plugin system for custom workflows
-- Compatible with existing configurations
-
----
-
-## Summary
-
-| Pain Point | Clacky's Solution |
-|------------|-------------------|
-| Slow + Blocked | Multi-model support with automatic failover |
-| High Costs | 50% cost reduction + real-time transparency |
-| Watch Mode Fatigue | confirm_safe + auto_approve automation |
-| Vendor Lock-in | 100% open source, self-hostable |
-| Limited Models | OpenRouter, OpenAI, DeepSeek, M2.1 |
-
-**Result**: A tool that professional developers can trust, afford, and rely on.
-
----
-
-## Get Started
-
-- **GitHub**: https://github.com/clacky-ai/openclacky
-- **Documentation**: https://docs.clacky.ai
-- **Discord**: https://discord.gg/clacky
-
----
-
-*Last updated: February 2025*