Why? AI agents run long tasks and need your input. LINE Hive lets you check status or reply from your phone — no editor watching required.

Features

• 📱 Check from anywhere — query agent status from LINE with ?, get instant updates
• 💬 Two-way conversation — agents ask you questions, you reply from your phone
• 🤖 Multi-agent — multiple editors share one bot; select by number
• ↩️ Quote-reply routing — quote an agent's message to auto-switch targeting
• 🆓 Free tier friendly — status queries use reply tokens (free), not push quota
• 📎 File exchange — send images, PDFs, and documents; agents read content on demand
• 🔍 PDF intelligence — text extraction, scanned PDF→image rendering, per-page navigation
• 🌐 Multi-language — English and Japanese, auto-detected from LINE profile
• 🔧 Zero config tunnel — built-in ngrok management (or bring your own tunnel)
• 🛡️ Security hardened — workspace-scoped file access, path containment, sandboxed PDF parsing
• � Interactive file browser — agents send browsable file/folder links; view code with syntax highlighting and rendered Markdown in LINE's in-app browser
• �🔐 Access control — first user is auto-registered as primary admin; restricted mode activates on follow or status check, blocking other users by default

Contents

• Features
• Companion: Doc Hive
• Quick Start
• How It Works
• Prerequisites
• Setup — LINE Account · Webhook Tunnel · Install
• Your First Message
• Updating
• MCP Tools
• LINE Commands
• Language Support
• Limitations
• Development
• Contributing
• Troubleshooting
• Architecture
• License

Companion: Doc Hive

LINE Hive handles communication — Doc Hive handles documents. Together, your agents can generate polished spreadsheets, slide decks, and Word documents, then deliver them straight to your phone via LINE.

%%{init: {"theme": "default"}}%%
flowchart TB
    subgraph Generate["📄 Doc Hive"]
        direction LR
        XLSX["create_xlsx"] ~~~ DOCX["create_docx"] ~~~ PPTX["create_pptx"]
    end
    subgraph Deliver["🐝 LINE Hive"]
        direction LR
      Ask["line_ask"] ~~~ Status["line_set_status"]
    end
    Agent["🤖 Agent"] --> Generate
    Generate -.-> File["💾 Files"]
    File -.-> Deliver
    Agent --> Deliver
    Deliver --> Phone["📱 LINE"]

    style Generate fill:#e3f2fd,stroke:#1565c0
    style Deliver fill:#f3e5f5,stroke:#7b1fa2
    classDef output fill:#e8f5e9,stroke:#2e7d32
    class Phone output

Doc Hive is a standalone MCP server — use it with or without LINE Hive. Install both for the full pipeline:

npx @zoulabo/line-hive init    # LINE messaging
npx doc-hive init               # Document generation

See the Doc Hive README for full documentation.

Quick Start

npx @zoulabo/line-hive init       # Interactive setup
# Restart your editor — MCP server starts automatically

You'll need a LINE Official Account and a webhook tunnel first. Optionally verify your connection:

npx @zoulabo/line-hive test

How It Works

Agents report status. You check from LINE when you want. No push spam — all status replies use LINE's free replyToken.

sequenceDiagram
    participant You as 📱 You
    participant Hive as 🐝 LINE Hive
    participant Agent as 🤖 Agent

    Agent->>Hive: set_status("running tests")
    Note over Agent: keeps working...

    You->>Hive: ?
    Hive-->>You: 🟡 Running tests

    Agent->>Hive: ask("3 tests failed. Fix?")
    You->>Hive: ?
    Hive-->>You: 🔴 3 tests failed. Fix?
    You->>Hive: yes, fix them
    Hive->>Agent: "yes, fix them"

    Agent->>Hive: set_status("applying fixes")
    Note over Agent: done
    Agent->>Hive: set_status(idle)

Key concepts:

• Pull, not push — agents set status, you check with ? when convenient
• Free — status queries use LINE replyTokens, not push quota
• Multi-agent — multiple editors share one bot; select by number
• Conversational — line_ask blocks until you reply, then returns your answer to the agent

Prerequisites

• A LINE Official Account with Messaging API enabled
• A webhook tunnel to localhost:19780 (ngrok recommended)
• Node.js 18+

Setup

1. Create a LINE Official Account

~5 minutes. Needs a browser + LINE app.

1. LINE Developers Console → Create Provider → Create Messaging API channel
2. Copy Channel Secret (Basic settings) and Channel Access Token (Messaging API → Issue)
3. Add the bot as a friend (scan QR in Messaging API → Bot information)
4. Disable auto-reply: Messaging API → Auto-reply messages → Edit → turn off both

Webhook URL — set after configuring your tunnel. Format: https://YOUR-TUNNEL/webhook

2. Set Up a Webhook Tunnel

LINE needs a public HTTPS URL. ngrok is recommended — the MCP server auto-manages it.

1. Sign up at ngrok.com (free tier works) and install:

   brew install ngrok                              # macOS
   ngrok config add-authtoken YOUR_AUTH_TOKEN       # authenticate

2. Claim a free stable domain at dashboard.ngrok.com/domains → Create Domain
3. In LINE Developers Console → Messaging API → set Webhook URL to https://YOUR-DOMAIN.ngrok-free.dev/webhook → toggle Use webhook On

Any tunnel that forwards to localhost:19780 works. Start it manually and skip setting NGROK_DOMAIN.

| Tool | Stable URL? | Setup | |------|-------------|-------| | VS Code Ports | Yes (devtunnels) | Built-in — Ports panel → Forward Port 19780 | | cloudflared (quick) | No (random URL) | cloudflared tunnel --url http://localhost:19780 | | cloudflared (named) | Yes (own domain) | Requires Cloudflare domain | | localtunnel | No | npx localtunnel --port 19780 | | localhost.run | No | ssh -R 80:localhost:19780 localhost.run |

3. Install LINE Hive in Your Project

npx @zoulabo/line-hive init                  # interactive
npx @zoulabo/line-hive init --editor cursor  # or: claude-code, claude-desktop

The wizard generates editor-specific config and installs an instruction file that teaches your AI agent the LINE tools.

| Editor | Config File | Secrets | |--------|------------|---------| | VS Code / Cursor | .vscode/mcp.json | Prompted at startup | | Claude Code | .mcp.json | ${VAR} env expansion | | Claude Desktop | ~/...Claude/claude_desktop_config.json | Hardcoded in config |

Claude Code as VS Code/Cursor extension? Use --editor claude-code (not --editor vscode).

Restart your editor after init. You'll be prompted for your LINE credentials and ngrok domain.

Manual Configuration (without init wizard)

If you prefer manual setup or use a different MCP client:

Create .mcp.json in your project root:

{
  "mcpServers": {
    "line-hive": {
      "command": "npx",
      "args": ["@zoulabo/line-hive"],
      "env": {
        "LINE_CHANNEL_ACCESS_TOKEN": "${LINE_CHANNEL_ACCESS_TOKEN}",
        "LINE_CHANNEL_SECRET": "${LINE_CHANNEL_SECRET}",
        "NGROK_DOMAIN": "${NGROK_DOMAIN:-}",
        "WORKSPACE_PATH": "/path/to/your/project"
      }
    }
  }
}

Set credentials in your shell profile, or use claude mcp add for secure storage:

claude mcp add --transport stdio \
  --env LINE_CHANNEL_ACCESS_TOKEN=your-token \
  --env LINE_CHANNEL_SECRET=your-secret \
  --env NGROK_DOMAIN=your-domain.ngrok-free.dev \
  --env WORKSPACE_PATH=/path/to/your/project \
  line-hive -- npx @zoulabo/line-hive

Also install instructions: copy templates/line-notification.instructions.md to .claude/rules/line-notification.md.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "line-hive": {
      "command": "npx",
      "args": ["@zoulabo/line-hive"],
      "env": {
        "LINE_CHANNEL_ACCESS_TOKEN": "your-token",
        "LINE_CHANNEL_SECRET": "your-secret",
        "NGROK_DOMAIN": "your-domain.ngrok-free.dev",
        "WORKSPACE_PATH": "/path/to/your/project"
      }
    }
  }
}

The server uses stdio transport (stdin/stdout for MCP JSON-RPC). Configure your client to run:

npx @zoulabo/line-hive

With these environment variables:

• LINE_CHANNEL_ACCESS_TOKEN — required
• LINE_CHANNEL_SECRET — required
• WORKSPACE_PATH — recommended (for agent naming)
• NGROK_DOMAIN — optional (enables webhook tunnel)

Your First Message

1. Restart your editor
2. Send ? to your bot in LINE → you'll see: 1. 🟢 your-project — Idle
3. Tell your agent: "Set your LINE status to hello world"
4. Send ? again → status updated

Not working? Run npx @zoulabo/line-hive test.

Updating

Instruction files are auto-updated on server startup — no manual step needed after upgrading.

Need to change your editor type or reconfigure from scratch? Use init:

npx @zoulabo/line-hive init                  # full interactive setup
npx @zoulabo/line-hive init --editor cursor  # switch editor type

MCP Tools

| Tool | Purpose | Blocking | |------|---------|----------| | line_set_status | Set agent description + name (status auto-derived) | No | | line_ask | Send message + wait for reply. Supports messages[] with text, file: paths, and images. | Yes | | line_check_messages | Fetch unclaimed inbound messages | No | | line_list_agents | List all active agents across editor windows | No | | line_read_file | Read content from a received file (PDF text, scanned PDF→image, image resize, text decode) | No | | line_render_markdown | Convert Markdown → HTML with auto-injected CDN (Mermaid, highlight.js, KaTeX, Chart.js). TTL-managed. | No |

File Browser

Agents can send browsable file and folder links via the file: prefix in line_ask messages. Users can also send . to browse the project root. Files open in LINE's in-app browser with:

• Syntax highlighting for code files (any text file viewable)
• Rendered Markdown with Mermaid diagrams, KaTeX math, and syntax highlighting
• Inline images (PNG, JPG, GIF, WebP, SVG)
• Directory listings with auto-appended README
• Breadcrumb navigation between files and directories
• Cross-workspace relay — browse files from other open editors

Recommended Pattern

1. line_ask({ messages: ["3 tests failed. Fix?"], agentName: "Nova", statusDescription: "Running tests", progress: "60%" })  → auto-status: needs_input
  → user replies                                                                                                              → auto-status: working
2. line_ask({ messages: ["Applying fixes now"], agentName: "Nova", statusDescription: "Applying fixes", progress: "80%" })
3. line_set_status({ agentName: "Nova" })  → idle (only when no outgoing line_ask is appropriate)

Auto-status values: idle | working | needs_input | error — the status parameter is not user-settable.

LINE Commands

Send these to your LINE bot:

| Command | Action | |---------|--------| | ? / s | Show all agents with status | | q | Show message queue with per-agent counts | | . | Browse project root in LINE's in-app browser | | Any other text | Route to targeted/waiting agent | | ✅ Continue (button) | Send a reply token to keep the conversation going | | 📊 Status (button) | Same as ? | | 📬 Queue (button) | Same as q | | 🗑️ Delete (button) | Delete a queued message (shown when queue has messages) | | 📬 N more (button) | Pop all queued messages to the agent at once | | 1️⃣ 2️⃣ ... (buttons) | Switch between agents (shown when 2+ agents active) | | Quote-reply | Quote an agent's message to auto-target that agent |

Language Support

Auto-detected from the user's LINE profile. Currently English (default) and Japanese. All bot messages, buttons, and errors are localized. Agents can override via line_set_status({ language: "ja" }). New users see a welcome message with available triggers, buttons, and a language hint.

Limitations

• 0 push policy — LINE delivery is reply-token only (no push fallback).
• Reply token expiry — ~15 min. If token pool is empty, line_ask blocks (up to 60s) then returns no_reply_token.
• Token priming — send ? then tap ✅ Continue to save a fresh reusable token before long sessions.
• Files — receive images & files (stored on disk in .line-hive-tmp/incoming/, 24h TTL). Send via messages[] (line_ask). Served files have a configurable TTL (default 2h, max 24h) with auto-cleanup. Stickers are currently ignored; video and audio are stored as files.
• Single user — designed for one primary user (admin) per LINE channel. The first follow or status check auto-activates restricted mode; additional users require manual allowlisting via store methods.
• Single webhook URL — all agent instances share one tunnel endpoint.
• Multi-workspace — only the first editor claims the webhook port/tunnel. Others piggyback via shared SQLite.
• Claude Code — line_ask can block up to 2 hours; ensure MCP_TOOL_TIMEOUT is not too short. Always use --editor claude-code for init.

Development

git clone https://github.com/zoulabo/line-hive && cd line-hive
npm install && npm run build && npm test
cp .vscode/mcp.json.example .vscode/mcp.json   # MCP dev config

| Command | Purpose | |---------|---------| | npm run build | Compile TypeScript | | npm run watch | Watch mode | | npm test | Run tests (vitest) | | npm start | Start standalone server | | npx @zoulabo/line-hive init | Full interactive setup | | npx @zoulabo/line-hive test | Test LINE API connection |

Optional Dependencies

| Feature | Package | Install | Fallback | |---------|---------|---------|----------| | PDF text extraction | pdfjs-dist | npm install pdfjs-dist | No PDF text extraction | | Image resizing + SVG→PNG | sharp | npm install sharp | Image resizing returns original size; SVG files served as download links instead of inline images | | Scanned PDF images | poppler CLI | brew install poppler (macOS) / apt install poppler-utils (Linux) | Returns install hint |

SVG support: LINE cannot display SVG files inline. When sharp is installed, SVG files sent via line_ask are automatically converted to PNG for inline preview. Without sharp, SVGs are served as download links.

Environment Variables

For standalone npm start:

| Variable | Required | Default | |----------|----------|---------| | LINE_CHANNEL_ACCESS_TOKEN | Yes | — | | LINE_CHANNEL_SECRET | Yes | — | | NGROK_DOMAIN | No | — (enables auto-managed tunnel) | | WEBHOOK_PORT | No | 19780 | | SQLITE_PATH | No | ~/.line-hive/line-hive.db | | SERVE_DIR | No | ~/.line-hive/served | | DEV_SERVER | No | — (forcibly claims webhook port) | | MAX_INCOMING_FILE_BYTES | No | 52428800 (50MB) | | MAX_OUTGOING_FILE_BYTES | No | 209715200 (200MB) |

Contributing

Designed for AI-agent-driven development. The repo includes skill files (.github/skills/) that teach agents the codebase. Point your agent at the repo and let it work.

• npm test must pass (~475 tests, <1s)
• npx tsc --noEmit must be clean
• Let the agents read skills first, then write the code

Troubleshooting

Run npx @zoulabo/line-hive test to diagnose. Common causes:

• Missing credentials — LINE_CHANNEL_ACCESS_TOKEN or LINE_CHANNEL_SECRET not set. VS Code/Cursor prompt at startup; Claude Code needs env vars.
• Port 19780 in use — Another process is using the webhook port. Kill it: lsof -ti :19780 | xargs kill
• Node.js < 18 — Requires Node.js 18+.

1. Run npx @zoulabo/line-hive test to verify API connection
2. Check that the webhook URL is set in LINE Developers Console → Messaging API → Webhook URL
3. Verify Use webhook is toggled On
4. Make sure auto-reply is disabled: Messaging API → Auto-reply messages → Edit → turn off both responses
5. Ensure the MCP server is running (check your editor's MCP status)

Use --editor claude-code whether you're running Claude Code as:

• A standalone CLI tool
• A VS Code extension
• A Cursor extension

Don't use --editor vscode — that's for GitHub Copilot.

1. Confirm ngrok is installed: ngrok version
2. Check auth: ngrok config check
3. Set NGROK_DOMAIN env var to your stable domain
4. The tunnel auto-starts with the MCP server — only one instance can run the tunnel.

Architecture

• SQLite (WAL mode) shared across all agent instances at ~/.line-hive/line-hive.db
• Heartbeat every 10s — dead agents auto-cleaned after 2 min
• Reply token pooling — webhook saves tokens for reply-only delivery (0 push quota)
• TTL-managed file serving — images, HTML, and documents served from disk with configurable TTL (default 2h, max 24h); expired files auto-cleaned every 60s
• Session correlation — line_ask creates a session, webhook fulfills it on reply
• Multi-agent routing — user selects agent via quick reply buttons, or auto-routes to needs_input agent
• Embedded tunnel — ngrok auto-managed as child process (optional; any tunnel to localhost:19780 works)
• Cross-platform — works on macOS, Linux, and Windows

License

MIT