Package Exports

handsoff
handsoff/dist/cli/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (handsoff) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

Session Monitoring — Handsoff listens for Claude Code session start/end events and notifies you on Telegram
Permission Control — When Claude requests to execute a tool, you receive a permission prompt on Telegram with Allow/Deny buttons
Real-time Decisions — Click the button in Telegram to grant or deny the tool execution
Task Completion — Receive final notifications when tasks complete, including execution duration, token usage, and results

Claude + Telegram workflow Permission request and task completion on Telegram

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

npm install -g handsoff

Or run without installing:

npx handsoff init

Quick start

Initialize configuration:

handsoff init

Start the gateway daemon:

handsoff gateway start

Attach an agent:

handsoff attach claude

Check gateway status:

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:

Setting up your Claude Code hook server port
Configuring Telegram bot credentials
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:

[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

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