cc-claw 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "cc-claw",
+  "version": "0.1.0",
+  "description": "CC-Claw: Personal AI assistant on Telegram — multi-backend (Claude, Gemini, Codex), sub-agent orchestration, MCP management",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "cc-claw": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/cli.js start",
+    "dev": "tsx src/cli.ts start",
+    "setup": "tsx src/cli.ts setup"
+  },
+  "keywords": [
+    "claude",
+    "telegram",
+    "bot",
+    "ai",
+    "assistant",
+    "claude-code",
+    "vertex-ai",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.6.2",
+    "commander": "^14.0.3",
+    "croner": "^9.0.0",
+    "dotenv": "^16.4.7",
+    "grammy": "^1.35.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "groq-sdk": "^0.15.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^25.3.5",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  }
+}

package/skills/agent-claude.md

@@ -0,0 +1,42 @@
+---
+name: agent-claude
+description: Capability manifest for Claude Code as a CC-Claw sub-agent
+compatible_backends: all
+---
+
+# Claude Code Sub-Agent
+
+## Strengths
+- Exceptional code generation, analysis, and debugging
+- Strong planning and architectural reasoning
+- Native sub-agent support (Agent tool)
+- Session resume via --resume flag
+- Full permission mode support (yolo/safe/readonly/plan)
+- Adjustable thinking depth (auto/off/low/medium/high/extra_high)
+
+## Limitations
+- Process must be killed after receiving result (undici keep-alive holds socket for 300s)
+- Higher token cost than alternatives for simple tasks
+- GOOGLE_APPLICATION_CREDENTIALS must be removed from env
+
+## Optimal Task Types
+- Complex code generation and multi-file changes
+- Code review and architectural analysis
+- Planning and design (use planner role with plan permission mode)
+- Debugging and root cause analysis
+- Tasks requiring deep reasoning (set thinking level high)
+
+## Models
+- **opus-4.6**: Most capable, highest cost — use for complex reasoning
+- **sonnet-4.6**: Strong balance of capability and cost — default choice
+- **haiku-4.5**: Fast and cheap — use for simple, focused tasks
+
+## MCP Support
+Full MCP support. Add via: `claude mcp add <name> -- <command> [args...]`
+
+## Tips for the Orchestrating Agent
+- Use sonnet-4.6 for most tasks, opus-4.6 only when deep reasoning is needed
+- Set thinking level high for debugging, low for simple edits
+- Always kill process after result (shouldKillOnResult: true)
+- For review-only tasks, use readonly permission mode
+- Claude excels at tasks that require understanding intent and context

package/skills/agent-codex.md

@@ -0,0 +1,39 @@
+---
+name: agent-codex
+description: Capability manifest for Codex CLI as a CC-Claw sub-agent
+compatible_backends: all
+---
+
+# Codex CLI Sub-Agent
+
+## Strengths
+- GPT-5.x model family (5.4, 5.3 Codex, 5.2 Codex)
+- Strong code generation and refactoring
+- Session resume via exec resume subcommand
+- Sandbox mode for safe execution
+- Reasoning effort control (low/medium/high/extra_high)
+
+## Limitations
+- Resume uses different command pattern (exec resume <id> "prompt")
+- Fewer native tools than Claude Code
+
+## Optimal Task Types
+- Code generation and refactoring
+- Test generation
+- Code translation between languages
+- Straightforward implementation tasks
+
+## Models
+- **gpt-5.4**: Most capable — deep reasoning tasks
+- **gpt-5.3-codex**: Balanced — general coding tasks
+- **gpt-5.2-codex**: Fast — simple implementations
+
+## MCP Support
+Full MCP support. Add via: `codex mcp add <name> -- <command> [args...]`
+
+## Tips for the Orchestrating Agent
+- Good alternative to Claude for straightforward coding tasks
+- Use sandbox mode (--sandbox) for untrusted or exploratory tasks
+- Resume pattern differs: exec resume <session-id> "new prompt"
+- Set reasoning effort high for complex tasks, low for boilerplate
+- Consider for tasks where OpenAI models may have training advantages

package/skills/agent-gemini.md

@@ -0,0 +1,40 @@
+---
+name: agent-gemini
+description: Capability manifest for Gemini CLI as a CC-Claw sub-agent
+compatible_backends: all
+---
+
+# Gemini CLI Sub-Agent
+
+## Strengths
+- Excellent video and multimodal analysis
+- Strong web search and information retrieval
+- Google ecosystem integration (Drive, GCP)
+- Session resume via --resume flag
+- Large context window
+- Thinking level support (HIGH/LOW)
+
+## Limitations
+- Exits cleanly but may be slower than Claude for pure code tasks
+- Fewer permission mode options than Claude
+
+## Optimal Task Types
+- Video and image analysis (multimodal)
+- Web research and documentation lookup
+- Google Cloud Platform integration tasks
+- Tasks requiring large context windows
+- Information synthesis from multiple sources
+
+## Models
+- **gemini-3.1-pro-preview**: Most capable — use for complex multimodal tasks
+- **gemini-3-flash**: Fast and efficient — use for quick tasks
+
+## MCP Support
+Full MCP support. Add via: `gemini mcp add <name> -- <command> [args...]`
+
+## Tips for the Orchestrating Agent
+- Use Gemini for any task involving video, images, or multimodal input
+- Prefer for web research tasks over other backends
+- Use flash model for quick lookups, pro for deep analysis
+- Gemini handles large context well — good for analyzing big files
+- Consider for tasks that benefit from Google ecosystem access

package/skills/onboard-cli.md

@@ -0,0 +1,156 @@
+---
+name: onboard-cli
+description: Onboard a new coding CLI as a CC-Claw sub-agent runner. Use when user asks to add, register, or onboard a new CLI tool.
+compatible_backends: all
+---
+
+# Onboard New CLI as Sub-Agent Runner
+
+Follow this process to onboard a new coding CLI so CC-Claw can use it as a sub-agent.
+
+## Step 1: Verify Installation
+
+Check if the CLI is installed:
+```bash
+which <cli-name>
+<cli-name> --version
+```
+
+If not installed, tell the user and stop. Do NOT install software.
+
+## Step 2: Discover Capabilities
+
+Run the help command to understand flags:
+```bash
+<cli-name> --help
+<cli-name> exec --help    # or equivalent subcommand for non-interactive mode
+```
+
+Look for:
+- **Headless/non-interactive mode flag**: `-p`, `--prompt`, `exec`, etc.
+- **Output format flag**: `--output-format stream-json`, `--json`, `-o stream-json`
+- **Model selection flag**: `-m`, `--model`
+- **Working directory flag**: `-C`, `--cd`, `--cwd`
+- **Session resume flag**: `--resume`
+- **Permission/sandbox flags**: `--yolo`, `--sandbox`, `--force`, `--permission-mode`
+- **MCP management**: `<cli> mcp list`, `<cli> mcp add`, etc.
+
+## Step 3: Test NDJSON Output
+
+Run the CLI with a simple test prompt to capture its output format:
+```bash
+<cli-name> -p "Say hello and nothing else" --output-format stream-json 2>/dev/null | head -20
+```
+
+Analyze the JSON lines to understand:
+- How does `init` look? (session ID)
+- How does `text` look? (assistant responses)
+- How does `result` look? (final output)
+- How does `usage` look? (token counts)
+
+## Step 4: Confirm with User
+
+Present a summary:
+- CLI name and version
+- Detected capabilities (session resume, MCP, permissions, etc.)
+- Detected output format
+- Any limitations found
+
+Ask the user to confirm before proceeding.
+
+## Step 5: Create Runner Config
+
+Write the runner config to `~/.cc-claw/runners/<id>.json`:
+
+```json
+{
+  "id": "<cli-name>",
+  "displayName": "<Display Name>",
+  "executable": "<cli-name>",
+  "executableFallbacks": [],
+  "spawnPattern": {
+    "promptFlag": ["-p"],
+    "outputFormatFlag": ["--output-format", "stream-json"],
+    "modelFlag": ["-m"],
+    "cwdFlag": ["-C"],
+    "sessionResumeFlag": ["--resume"],
+    "extraArgs": [],
+    "permModes": {
+      "yolo": ["<yolo-flags>"],
+      "safe": ["<safe-flags>"],
+      "readonly": ["<readonly-flags>"],
+      "plan": ["<plan-flags>"]
+    }
+  },
+  "outputParsing": {
+    "preset": "generic",
+    "fieldMappings": {
+      "initMatch": {"type": "init"},
+      "initSessionIdPath": "session_id",
+      "textMatch": {"type": "text"},
+      "textPath": "text",
+      "resultMatch": {"type": "result"},
+      "resultTextPath": "result",
+      "usageMatch": {"type": "usage"},
+      "usageInputPath": "usage.input_tokens",
+      "usageOutputPath": "usage.output_tokens",
+      "usageCachePath": "usage.cache_read_input_tokens"
+    }
+  },
+  "mcpCommands": {
+    "add": ["<cli>", "mcp", "add", "{name}", "--", "{command}"],
+    "remove": ["<cli>", "mcp", "remove", "{name}"],
+    "list": ["<cli>", "mcp", "list"]
+  },
+  "mcpConfigInjection": "none",
+  "capabilities": {
+    "supportsSessionResume": true,
+    "supportsMcp": true,
+    "supportsNdjson": true,
+    "supportsPermissionModes": true,
+    "maxConcurrentSessions": 4,
+    "specialties": []
+  },
+  "shouldKillOnResult": false
+}
+```
+
+Adapt ALL fields based on what you discovered in Steps 2-3. Do NOT use placeholder values.
+
+## Step 6: Create Capability Skill
+
+Write a capability manifest to `~/.cc-claw/workspace/skills/agent-<id>.md`:
+
+```markdown
+---
+name: agent-<id>
+description: Capability manifest for <Display Name> as a CC-Claw sub-agent
+compatible_backends: all
+---
+
+# <Display Name> Sub-Agent
+
+## Strengths
+- (discovered strengths)
+
+## Limitations
+- (discovered limitations)
+
+## Optimal Task Types
+- (based on capabilities)
+
+## Tips for the Orchestrating Agent
+- (practical usage advice)
+```
+
+## Step 7: Verify
+
+Tell the user the runner has been created and they should run `/runners` to verify it appears. The new runner loads automatically — no restart needed.
+
+## Important Rules
+
+- NEVER install software. Only onboard CLIs that are already installed.
+- ALWAYS test the CLI's output format empirically — don't guess.
+- ALWAYS confirm with the user before writing config files.
+- Fill in ALL config fields based on actual discovery, not templates.
+- If the CLI doesn't support NDJSON output, it cannot be onboarded as a sub-agent runner.