tabclaw 0.1.1 → 0.1.3

package/README.md

@@ -1,13 +1,30 @@
 # Tabclaw
 
-Tabclaw is a local gateway for AI assistant event hooks and notification channels. It helps connect hook-enabled agents to channels like Telegram while keeping runtime state under `~/.tabclaw`.
+Tabclaw is a local gateway that bridges AI programming assistants (like Claude Code) with chat platforms (like Telegram). It listens for agent events and forwards them to your channels in real time.
 
 ## What it does
 
-- Runs a local gateway daemon for hook-based agent integrations
-- Attaches supported agents such as `claude` to the gateway
-- Routes session events, permission requests, and status updates to configured channels
-- Provides CLI commands for daemon control, status, logs, and agent attachment
+### Overview
+
+- Runs a local HTTP gateway daemon to capture agent hook events
+- Attaches hook-enabled agents to the gateway for event streaming
+- Routes session events, permission requests, and task notifications to configured channels
+- Manages agent-initiated tool execution permissions via chat platform interactions
+
+### Claude Code + Telegram integration
+
+The core workflow bridges Claude Code with Telegram:
+
+1. **Session Monitoring** — Tabclaw listens for Claude Code session start/end events and notifies you on Telegram
+2. **Permission Control** — When Claude requests to execute a tool, you receive a permission prompt on Telegram with **Allow/Deny** buttons
+3. **Real-time Decisions** — Click the button in Telegram to grant or deny the tool execution
+4. **Task Completion** — Receive final notifications when tasks complete, including execution duration, token usage, and results
+
+<p align="center">
+  <img src="assets/image_01.jpg" width="45%" alt="Claude + Telegram workflow" />
+  &nbsp;&nbsp;
+  <img src="assets/image_02.jpg" width="45%" alt="Permission request and task completion on Telegram" />
+</p>
 
 ## Installation
 
@@ -61,9 +78,30 @@ tabclaw gateway status
 
 ## Configuration
 
-Copy `config.example.toml` to `~/.tabclaw/config.toml` and fill in your values.
+Most configuration is handled by `tabclaw init` interactive wizard, which guides you through:
+
+1. Setting up your Claude Code hook server port
+2. Configuring Telegram bot credentials
+3. Testing channel connectivity
+
+For manual setup or advanced options, edit `~/.tabclaw/config.toml`. Key sections:
+
+**General settings:**
+- `default_agent` — default agent to use (currently `claude`)
+- `hook_server_port` — local port for receiving agent hooks (default `9876`)
+- `log_level` — logging verbosity (`debug`, `info`, `warn`, `error`)
+
+**Telegram channel:**
+- `bot_token` — your Telegram bot token from BotFather
+- `allowed_users` — list of Telegram user IDs allowed to interact with the bot (e.g., `[123456789, 987654321]`)
+- `notify_types` — which event types to forward (`permission_request`, `finished`, `session_start`, `error`, etc.)
+
+**Claude agent:**
+- `adapter` — integration method (always `hooks`)
+- `binary` — Claude Code binary name
+- `permission_mode` — how to handle tool permissions
 
-Example:
+Example `~/.tabclaw/config.toml`:
 
 ```toml
 [general]
@@ -74,7 +112,8 @@ hook_server_port = 9876
 [channel.telegram]
 enabled = true
 bot_token = "YOUR_BOT_TOKEN"
-allowed_users = [123456789]
+allowed_users = ["123456789"]
+notify_types = ["permission_request", "finished", "session_start", "error"]
 
 [agent.claude]
 adapter = "hooks"

package/dist/daemon/process.js

@@ -4231,6 +4231,7 @@ var helpCommand = {
 };
 function generateStaticHelpText() {
   let output = "**TabClaw Bot Commands**\n\n";
+  output += "**/start** - Show welcome message\n\n";
   output += "**/session** - Session management\n";
   output += "  `list` [--all] - List all sessions\n";
   output += "  `status` <session-id> - Get session details\n";
@@ -4247,8 +4248,33 @@ function generateStaticHelpText() {
   return output;
 }
 
+// src/core/command/builtin/start.ts
+init_esm_shims();
+var startCommand = {
+  description: "Start the bot and show welcome message",
+  usage: "/start",
+  handler: async () => {
+    return `\u{1F44B} **Welcome to TabClaw!**
+
+I'm your Claude Code monitoring assistant. I'll notify you about:
+- \u{1F510} Permission requests that need your approval
+- \u2705 Task completions
+- \u{1F7E2} Session starts
+- \u274C Errors
+
+**Available Commands:**
+/help - Show all available commands
+/session list - List active sessions
+/system status - Check system status
+/system ping - Test connectivity
+
+Use the buttons on notifications to approve or deny permission requests.`;
+  }
+};
+
 // src/core/command/builtin/index.ts
 function registerBuiltinCommands(registry) {
+  registry.register("start", "start", startCommand);
   registry.registerGroup("session", sessionCommands);
   registry.registerGroup("system", systemCommands);
   registry.register("help", "help", helpCommand);