handsoff 0.0.1-beta.0

package/README.md

@@ -0,0 +1,217 @@
+# Handsoff
+
+> **Hands off your desk, hand off control to your phone.**
+>
+> *Leave your desk, not your code.*
+
+Handsoff is a local gateway that bridges AI programming assistants (like Claude Code) with messaging platforms (like Telegram, Feishu). It captures agent events in real-time and forwards them to your phone, letting you monitor and control your AI assistant from anywhere.
+
+---
+
+## The Problem
+
+You're running Claude Code on your workstation. It asks for permission to execute a tool. You're away from your desk—maybe grabbing coffee, in a meeting, or simply stepping out. The session sits there waiting. Time ticks away.
+
+## The Solution
+
+**Handsoff** keeps you connected to your coding sessions wherever you are:
+
+- **Monitor** — Get notified when Claude starts or finishes tasks
+- **Control** — Approve or deny tool execution requests right from your phone
+- **Stay informed** — Receive execution summaries with token usage and results
+
+No more tethering yourself to your desk. Your code doesn't stop when you step away.
+
+---
+
+## How it works
+
+### Claude Code + Telegram integration
+
+The core workflow bridges Claude Code with Telegram:
+
+1. **Session Monitoring** — Handsoff 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>
+
+---
+
+## Architecture
+
+```
++-------------------------+
+|       CLI Layer         |
+| init | attach | gateway |
++-----------+-------------+
+            |
+            v
++-------------------------+
+|   Agent Adapter Layer   |
+| ClaudeHookAdapter       |
++-----------+-------------+
+            |
+            v
++-------------------------+
+|     Gateway Layer       |
+| SessionManager          |
+| EventBus | Publisher    |
+| PermissionService       |
++-----------+-------------+
+            |
+            v
++-------------------------+
+|   Channel Adapter Layer |
+| Telegram | Feishu       |
++-------------------------+
+```
+
+- **CLI Layer**: User commands (init, attach, gateway, logs, status)
+- **Agent Adapter Layer**: Translates agent events to unified format
+- **Gateway Layer**: Core hub managing sessions, events, permissions
+- **Channel Adapter Layer**: Sends notifications to messaging platforms
+
+---
+
+## Supported platforms
+
+- CLI agent support: `claude`
+- Chat channel support: `Telegram`, `Feishu`
+
+---
+
+## Future plan
+
+- [ ] Add more agent adapters
+- [ ] Add more channel adapters
+
+---
+
+## Installation
+
+```bash
+npm install -g handsoff
+```
+
+Or run without installing:
+
+```bash
+npx handsoff init
+```
+
+---
+
+## Quick start
+
+1. Initialize configuration:
+
+```bash
+handsoff init
+```
+
+2. Start the gateway daemon:
+
+```bash
+handsoff gateway start
+```
+
+3. Attach an agent:
+
+```bash
+handsoff attach claude
+```
+
+4. Check gateway status:
+
+```bash
+handsoff gateway status
+```
+
+---
+
+## Main commands
+
+- `handsoff init` — initialize or update `~/.handsoff/config.toml`
+- `handsoff gateway start` — start or restart the gateway daemon
+- `handsoff gateway stop` — stop the gateway daemon
+- `handsoff gateway restart` — restart the gateway daemon
+- `handsoff gateway status` — show gateway health and active sessions
+- `handsoff attach <agent-type>` — attach a supported agent to the gateway
+- `handsoff status` — view CLI status
+- `handsoff logs` — inspect logs
+- `handsoff stop` — stop the daemon
+
+---
+
+## Configuration
+
+Most configuration is handled by `handsoff 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 `~/.handsoff/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 `~/.handsoff/config.toml`:
+
+```toml
+[general]
+default_agent = "claude"
+log_level = "info"
+hook_server_port = 9876
+
+[channel.telegram]
+enabled = true
+bot_token = "YOUR_BOT_TOKEN"
+allowed_users = ["123456789"]
+notify_types = ["permission_request", "finished", "session_start", "error"]
+
+[agent.claude]
+adapter = "hooks"
+binary = "claude"
+work_dir = ""
+model = ""
+permission_mode = ""
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev -- init
+npm test
+npm run build
+```
+
+---
+
+## Notes
+
+- Use `config.example.toml` as the starting point.
+- Runtime files are stored in `~/.handsoff`.
+
+MIT

package/config.example.toml

@@ -0,0 +1,29 @@
+# Handsoff configuration
+# Copy to ~/.handsoff/config.toml and fill in your credentials
+
+[general]
+default_agent = "claude"
+log_level = "info"
+hook_server_port = 9876
+
+[channel.telegram]
+enabled = true
+bot_token = "YOUR_BOT_TOKEN"
+allowed_users = [123456789]
+
+[channel.feishu]
+enabled = false
+app_id = ""
+app_secret = ""
+
+[agent.claude]
+adapter = "hooks"
+binary = "claude"
+work_dir = ""
+model = ""
+permission_mode = ""
+
+  # Agent-specific permission settings
+  [agent.claude.permission]
+  # Low-risk tools that won't trigger permission prompts
+  lowRiskTools = ["Read", "Glob", "Grep", "List", "WebSearch", "codesearch"]

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }