@interactive-inc/claude-funnel 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Interactive Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @interactive-inc/claude-funnel
+
+[![npm](https://img.shields.io/npm/v/@interactive-inc/claude-funnel.svg)](https://www.npmjs.com/package/@interactive-inc/claude-funnel)
+[![license](https://img.shields.io/npm/l/@interactive-inc/claude-funnel.svg)](./LICENSE)
+
+A hub CLI that connects multiple Claude Code agents to external services (Slack / GitHub / Discord). External events flow through subscription "channels" into Claude Code sessions, and outbound API calls from Claude are funneled through the same connectors.
+
+The command is `funnel` or its shorthand `fnl`.
+
+## Overview
+
+```
+Slack/others         Connectors      Channels                Claude Code
+(external APIs) ─→   (funnel)  ─→    (subscription router) ──WS/MCP─→   (received as <channel> tags)
+                                                           ↑
+                                               funnel MCP server (funnel mcp)
+```
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.3 or later (runtime)
+- [Claude Code](https://docs.claude.com/en/docs/claude-code) CLI
+- A Slack / GitHub / Discord token or CLI, depending on which connectors you use
+
+## Install
+
+```bash
+bun add -g @interactive-inc/claude-funnel
+```
+
+After install, `funnel` and `fnl` are available globally.
+
+## Quick start
+
+```bash
+# Register an external connection (Connector)
+fnl connectors add my-slack --type slack --bot-token xoxb-... --app-token xapp-...
+
+# Create a subscription box (Channel) and attach the connector
+fnl channels add my-inbox
+fnl channels my-inbox connectors attach my-slack
+
+# Start the gateway (connects to Slack Socket Mode)
+fnl gateway start
+
+# Launch Claude (funnel is auto-registered in the current directory's .mcp.json)
+fnl claude --channel my-inbox
+```
+
+## Commands
+
+```
+fnl connectors                              list
+fnl connectors add <name> --type <t> --bot-token <t> --app-token <t>
+fnl connectors <name>                       show details
+fnl connectors <name> set [--bot-token ...] [--app-token ...]
+fnl connectors rename <old> <new>
+fnl connectors remove <name>
+fnl connectors <name> <method> <path> [body]   call API (get/post/put/delete/...)
+
+fnl channels                                list
+fnl channels add <name>
+fnl channels <name>                         show details
+fnl channels <name> connectors attach <connector>
+fnl channels <name> connectors detach <connector>
+fnl channels rename <old> <new>
+fnl channels remove <name>
+
+fnl agents                                  list agent presets (extra)
+fnl agents add <name> --channel <c> [--repo <r>] [--sub-agent <s>] [--env-file <f>]
+fnl agents <name>                           launch (sugar for fnl claude)
+fnl agents <name> set [--channel ...] [--repo ...] [--sub-agent ...] [--env-file ...]
+fnl agents rename <old> <new>
+fnl agents remove <name>
+
+fnl repos                                   list repositories (extra)
+fnl repos add <name> --path <path>          register funnel MCP into .mcp.json
+fnl repos <name>                            show details
+fnl repos <name> set [--path <path>]
+fnl repos rename <old> <new>
+fnl repos remove <name>
+
+fnl claude --channel <c> [--repo <r>] [--sub-agent <s>] [--env-file <f>]
+                                            launch Claude Code
+fnl mcp                                     run as an MCP server (invoked from .mcp.json)
+
+fnl gateway                                 running status
+fnl gateway start / stop / restart / run / logs
+fnl status                                  overall status (connectors / channels / agents / repos / gateway)
+
+fnl --version
+fnl --help        (every subcommand has --help)
+```
+
+## Data model
+
+```
+Connector =
+  | { type: "slack",   name, botToken, appToken }          Slack Socket Mode
+  | { type: "gh",      name, pollInterval? }                GitHub (gh CLI)
+  | { type: "discord", name, botToken }                     Discord Gateway
+
+Channel    = { name, connectors[] }                        subscription box
+Repository = { name, path }                                 extra
+Agent      = { name, channel, repo?, subAgent?, envFiles? } preset (extra)
+
+Settings = { connectors[], channels[], repositories[], agents[] }
+         → ~/.funnel/settings.json
+```
+
+## Discord bot setup
+
+- Create a bot in the Discord Developer Portal and obtain its token
+- Enable `Message Content Intent` under Privileged Gateway Intents
+- Invite the bot via OAuth2 → URL Generator with the `bot` scope and `View Channels` / `Send Messages` / `Read Message History` permissions
+
+## Environment variables
+
+| Variable             | Purpose                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `FUNNEL_CHANNEL_ID`  | Injected into the child process by `fnl claude`; funnel MCP uses it to subscribe.       |
+| `FUNNEL_PORT`        | Gateway port (default 9742).                                                            |
+| `FUNNEL_GATEWAY_URL` | Gateway WebSocket URL used by MCP (default `ws://localhost:9742/ws`).                   |
+
+## File layout
+
+- Config: `~/.funnel/settings.json`
+- PID: `~/.funnel/gateway.pid`
+- Event log: `/tmp/funnel/events/*.jsonl` (auto-deleted after 30 days)
+- Process log: `/tmp/funnel/gateway.log`
+
+## Links
+
+- [GitHub](https://github.com/interactive-inc/claude-funnel)
+- [Issues](https://github.com/interactive-inc/claude-funnel/issues)
+- Coding rules and design principles: [CLAUDE.md](https://github.com/interactive-inc/claude-funnel/blob/main/CLAUDE.md)
+- Design notes: [`.docs/`](https://github.com/interactive-inc/claude-funnel/tree/main/.docs)
+
+## Development
+
+```bash
+git clone https://github.com/interactive-inc/claude-funnel.git
+cd claude-funnel
+bun install
+bun link            # register funnel / fnl globally
+bun test            # run tests
+bunx tsc -b         # type check
+```
+
+## License
+
+MIT © Interactive Inc.

package/lib/factory.ts

@@ -0,0 +1,10 @@
+import { createFactory } from "hono/factory"
+import type { Funnel } from "@/funnel"
+
+export type Env = {
+  Variables: {
+    funnel: Funnel
+  }
+}
+
+export const factory = createFactory<Env>()

package/lib/funnel.ts

@@ -0,0 +1,51 @@
+import { FunnelAgents } from "@/modules/agents/funnel-agents"
+import { FunnelChannels } from "@/modules/channels/funnel-channels"
+import { FunnelClaude } from "@/modules/claude/funnel-claude"
+import { FunnelConnectors } from "@/modules/connectors/funnel-connectors"
+import { FunnelGateway } from "@/modules/gateway/funnel-gateway"
+import { FunnelMcp } from "@/modules/mcp/funnel-mcp"
+import { FunnelRepositories } from "@/modules/repos/funnel-repositories"
+import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+
+type Props = {
+  store: FunnelSettingsReader
+}
+
+export class Funnel {
+  constructor(private readonly props: Props) {
+    Object.freeze(this)
+  }
+
+  get connectors(): FunnelConnectors {
+    return new FunnelConnectors({ store: this.props.store })
+  }
+
+  get channels(): FunnelChannels {
+    return new FunnelChannels({ store: this.props.store })
+  }
+
+  get agents(): FunnelAgents {
+    return new FunnelAgents({ store: this.props.store })
+  }
+
+  get repositories(): FunnelRepositories {
+    return new FunnelRepositories({ store: this.props.store, mcp: this.mcp })
+  }
+
+  get claude(): FunnelClaude {
+    return new FunnelClaude({
+      channels: this.channels,
+      repositories: this.repositories,
+      mcp: this.mcp,
+      gateway: this.gateway,
+    })
+  }
+
+  get gateway(): FunnelGateway {
+    return new FunnelGateway()
+  }
+
+  get mcp(): FunnelMcp {
+    return new FunnelMcp()
+  }
+}

package/lib/index.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+import pkg from "../package.json" with { type: "json" }
+import { startChannelServer } from "@/modules/mcp/channel-server"
+import { toRequest } from "@/modules/router/to-request"
+import { launchTui } from "@/modules/tui/tui"
+import { app } from "@/routes"
+
+process.title = "funnel"
+
+const HELP = `funnel — Open Claude Funnel
+
+usage: funnel [command]
+
+commands:
+  (none)                launch TUI
+  claude --channel <c>  launch Claude Code
+  connectors            manage external connections (Slack, etc.)
+  channels              manage subscription boxes
+  agents                manage agent presets (extra)
+  repos                 manage repositories (extra)
+  gateway               manage the gateway
+  status                show overall connection status
+  mcp                   run as an MCP server (invoked from .mcp.json)
+
+options:
+  --help, -h            show help
+  --version, -v         show version
+
+more: funnel <command> --help`
+
+const args = process.argv.slice(2)
+
+if (args.length === 0) {
+  await launchTui()
+  process.exit(0)
+}
+
+if (args[0] === "--version" || args[0] === "-v") {
+  process.stdout.write(`${pkg.version}\n`)
+  process.exit(0)
+}
+
+if (args[0] === "mcp") {
+  await startChannelServer()
+} else {
+  const { method, url } = toRequest(args)
+
+  const parsed = new URL(url)
+
+  if (parsed.searchParams.has("help")) {
+    if (parsed.pathname === "/") {
+      process.stdout.write(`${HELP}\n`)
+      process.exit(0)
+    }
+
+    let res = await app.request(url, { method })
+
+    if (!res.ok && method !== "GET") {
+      res = await app.request(url, { method: "GET" })
+    }
+
+    if (!res.ok) {
+      const group = parsed.pathname.split("/").filter(Boolean)[0]
+
+      if (group) {
+        res = await app.request(`http://localhost/${group}?help=true`, { method: "GET" })
+      }
+    }
+
+    const text = res.ok ? await res.text() : HELP
+    process.stdout.write(`${text}\n`)
+    process.exit(0)
+  }
+
+  const res = await app.request(url, { method })
+
+  if (!res.ok) {
+    const text = await res.text()
+    if (text) process.stderr.write(`${text}\n`)
+    process.exit(1)
+  }
+
+  const body = await res.text()
+
+  if (body) process.stdout.write(`${body}\n`)
+}

package/lib/modules/agents/funnel-agents.ts

@@ -0,0 +1,105 @@
+import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import type { AgentConfig } from "@/modules/settings/settings-schema"
+
+type Deps = {
+  store: FunnelSettingsReader
+}
+
+export class FunnelAgents {
+  private readonly store: FunnelSettingsReader
+
+  constructor(deps: Deps) {
+    this.store = deps.store
+    Object.freeze(this)
+  }
+
+  list(): AgentConfig[] {
+    return this.store.read().agents
+  }
+
+  get(name: string): AgentConfig | null {
+    return this.list().find((a) => a.name === name) ?? null
+  }
+
+  add(config: AgentConfig): void {
+    const settings = this.store.read()
+
+    if (settings.agents.some((a) => a.name === config.name)) {
+      throw new Error(`agent "${config.name}" already exists`)
+    }
+
+    if (!settings.channels.some((c) => c.name === config.channel)) {
+      throw new Error(`channel "${config.channel}" not found`)
+    }
+
+    if (config.repo && !settings.repositories.some((r) => r.name === config.repo)) {
+      throw new Error(`repo "${config.repo}" not found`)
+    }
+
+    settings.agents.push(config)
+
+    this.store.write(settings)
+  }
+
+  remove(name: string): void {
+    const settings = this.store.read()
+
+    const index = settings.agents.findIndex((a) => a.name === name)
+
+    if (index < 0) throw new Error(`agent "${name}" not found`)
+
+    settings.agents.splice(index, 1)
+
+    this.store.write(settings)
+  }
+
+  rename(oldName: string, newName: string): void {
+    const settings = this.store.read()
+
+    const agent = settings.agents.find((a) => a.name === oldName)
+
+    if (!agent) throw new Error(`agent "${oldName}" not found`)
+
+    if (settings.agents.some((a) => a.name === newName)) {
+      throw new Error(`agent "${newName}" already exists`)
+    }
+
+    agent.name = newName
+
+    this.store.write(settings)
+  }
+
+  update(name: string, fields: Partial<Omit<AgentConfig, "name">>): void {
+    const settings = this.store.read()
+
+    const agent = settings.agents.find((a) => a.name === name)
+
+    if (!agent) throw new Error(`agent "${name}" not found`)
+
+    if (fields.channel !== undefined) {
+      if (!settings.channels.some((c) => c.name === fields.channel)) {
+        throw new Error(`channel "${fields.channel}" not found`)
+      }
+
+      agent.channel = fields.channel
+    }
+
+    if (fields.repo !== undefined) {
+      if (fields.repo && !settings.repositories.some((r) => r.name === fields.repo)) {
+        throw new Error(`repo "${fields.repo}" not found`)
+      }
+
+      agent.repo = fields.repo || undefined
+    }
+
+    if (fields.subAgent !== undefined) {
+      agent.subAgent = fields.subAgent || undefined
+    }
+
+    if (fields.envFiles !== undefined) {
+      agent.envFiles = fields.envFiles
+    }
+
+    this.store.write(settings)
+  }
+}

package/lib/modules/channels/funnel-channels.ts

@@ -0,0 +1,113 @@
+import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import type { ChannelConfig } from "@/modules/settings/settings-schema"
+
+type Deps = {
+  store: FunnelSettingsReader
+}
+
+export class FunnelChannels {
+  private readonly store: FunnelSettingsReader
+
+  constructor(deps: Deps) {
+    this.store = deps.store
+    Object.freeze(this)
+  }
+
+  list(): ChannelConfig[] {
+    return this.store.read().channels
+  }
+
+  get(name: string): ChannelConfig | null {
+    return this.list().find((c) => c.name === name) ?? null
+  }
+
+  add(config: ChannelConfig): void {
+    const settings = this.store.read()
+
+    if (settings.channels.some((c) => c.name === config.name)) {
+      throw new Error(`channel "${config.name}" already exists`)
+    }
+
+    for (const connectorName of config.connectors) {
+      if (!settings.connectors.some((c) => c.name === connectorName)) {
+        throw new Error(`connector "${connectorName}" not found`)
+      }
+    }
+
+    settings.channels.push(config)
+
+    this.store.write(settings)
+  }
+
+  remove(name: string): void {
+    const settings = this.store.read()
+
+    const index = settings.channels.findIndex((c) => c.name === name)
+
+    if (index < 0) throw new Error(`channel "${name}" not found`)
+
+    if (settings.agents.some((a) => a.channel === name)) {
+      throw new Error(`channel "${name}" is referenced by an agent`)
+    }
+
+    settings.channels.splice(index, 1)
+
+    this.store.write(settings)
+  }
+
+  rename(oldName: string, newName: string): void {
+    const settings = this.store.read()
+
+    const channel = settings.channels.find((c) => c.name === oldName)
+
+    if (!channel) throw new Error(`channel "${oldName}" not found`)
+
+    if (settings.channels.some((c) => c.name === newName)) {
+      throw new Error(`channel "${newName}" already exists`)
+    }
+
+    channel.name = newName
+
+    for (const agent of settings.agents) {
+      if (agent.channel === oldName) agent.channel = newName
+    }
+
+    this.store.write(settings)
+  }
+
+  attachConnector(name: string, connectorName: string): void {
+    const settings = this.store.read()
+
+    const channel = settings.channels.find((c) => c.name === name)
+
+    if (!channel) throw new Error(`channel "${name}" not found`)
+
+    if (!settings.connectors.some((c) => c.name === connectorName)) {
+      throw new Error(`connector "${connectorName}" not found`)
+    }
+
+    if (channel.connectors.includes(connectorName)) {
+      throw new Error(`connector "${connectorName}" is already attached`)
+    }
+
+    channel.connectors.push(connectorName)
+
+    this.store.write(settings)
+  }
+
+  detachConnector(name: string, connectorName: string): void {
+    const settings = this.store.read()
+
+    const channel = settings.channels.find((c) => c.name === name)
+
+    if (!channel) throw new Error(`channel "${name}" not found`)
+
+    const index = channel.connectors.indexOf(connectorName)
+
+    if (index < 0) throw new Error(`connector "${connectorName}" is not attached`)
+
+    channel.connectors.splice(index, 1)
+
+    this.store.write(settings)
+  }
+}

package/lib/modules/claude/funnel-claude.ts

@@ -0,0 +1,136 @@
+import type { FunnelChannels } from "@/modules/channels/funnel-channels"
+import { FunnelFileSystem } from "@/modules/fs/funnel-file-system"
+import { NodeFunnelFileSystem } from "@/modules/fs/node-funnel-file-system"
+import type { FunnelGateway } from "@/modules/gateway/funnel-gateway"
+import { logger } from "@/modules/logger"
+import type { FunnelMcp } from "@/modules/mcp/funnel-mcp"
+import { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
+import { NodeFunnelProcessRunner } from "@/modules/process/node-funnel-process-runner"
+import type { FunnelRepositories } from "@/modules/repos/funnel-repositories"
+
+export type LaunchOptions = {
+  channel: string
+  repo?: string
+  subAgent?: string
+  envFiles?: string[]
+  userArgs?: string[]
+}
+
+type Deps = {
+  channels: FunnelChannels
+  repositories: FunnelRepositories
+  mcp: FunnelMcp
+  gateway: FunnelGateway
+  process?: FunnelProcessRunner
+  fs?: FunnelFileSystem
+}
+
+const defaultProcess = new NodeFunnelProcessRunner()
+const defaultFs = new NodeFunnelFileSystem()
+
+export class FunnelClaude {
+  private readonly channels: FunnelChannels
+  private readonly repositories: FunnelRepositories
+  private readonly mcp: FunnelMcp
+  private readonly gateway: FunnelGateway
+  private readonly process: FunnelProcessRunner
+  private readonly fs: FunnelFileSystem
+
+  constructor(deps: Deps) {
+    this.channels = deps.channels
+    this.repositories = deps.repositories
+    this.mcp = deps.mcp
+    this.gateway = deps.gateway
+    this.process = deps.process ?? defaultProcess
+    this.fs = deps.fs ?? defaultFs
+    Object.freeze(this)
+  }
+
+  async launch(options: LaunchOptions): Promise<number> {
+    const channel = this.channels.get(options.channel)
+
+    if (!channel) {
+      throw new Error(`channel "${options.channel}" not found`)
+    }
+
+    const cwd = options.repo
+      ? this.repositories.resolvePath(options.repo)
+      : globalThis.process.cwd()
+
+    if (!this.mcp.findInstalledName(cwd)) {
+      this.mcp.install(cwd)
+
+      logger.info(`added funnel MCP to .mcp.json`, { cwd })
+    }
+
+    if (!this.gateway.isRunning()) {
+      logger.info(`starting gateway automatically`)
+      await this.gateway.start()
+    }
+
+    const claudeArgs = this.buildArgs(options, cwd)
+    const env = this.buildEnv(options, cwd)
+
+    logger.info(`claude launch`, {
+      channel: options.channel,
+      repo: options.repo,
+      subAgent: options.subAgent,
+      cwd,
+    })
+
+    return await this.process.attach(["claude", ...claudeArgs], { cwd, env })
+  }
+
+  private buildArgs(options: LaunchOptions, cwd: string): string[] {
+    const result = [...(options.userArgs ?? [])]
+
+    const mcpName = this.mcp.findInstalledName(cwd)
+
+    if (
+      mcpName &&
+      !result.includes("--dangerously-load-development-channels") &&
+      !result.includes("--channels")
+    ) {
+      result.push("--dangerously-load-development-channels", `server:${mcpName}`)
+    }
+
+    if (!result.includes("--agent") && options.subAgent) {
+      result.push("--agent", options.subAgent)
+    }
+
+    return result
+  }
+
+  private buildEnv(options: LaunchOptions, cwd: string): Record<string, string> {
+    const env: Record<string, string> = { ...globalThis.process.env } as Record<string, string>
+
+    if (options.envFiles) {
+      for (const file of options.envFiles) {
+        const filePath = `${cwd}/${file}`
+
+        if (!this.fs.existsSync(filePath)) continue
+
+        const content = this.fs.readFileSync(filePath)
+
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim()
+
+          if (!trimmed || trimmed.startsWith("#")) continue
+
+          const eqIndex = trimmed.indexOf("=")
+
+          if (eqIndex < 0) continue
+
+          const key = trimmed.slice(0, eqIndex)
+          const value = trimmed.slice(eqIndex + 1).replace(/^["']|["']$/g, "")
+
+          env[key] = value
+        }
+      }
+    }
+
+    env.FUNNEL_CHANNEL_ID = options.channel
+
+    return env
+  }
+}

package/lib/modules/connectors/funnel-connector-adapter.ts

@@ -0,0 +1,9 @@
+export type CallInput = {
+  method: string
+  path: string
+  body?: unknown
+}
+
+export abstract class FunnelConnectorAdapter {
+  abstract call(input: CallInput): Promise<unknown>
+}

package/lib/modules/connectors/funnel-connector-listener.ts

@@ -0,0 +1,5 @@
+export type NotifyFn = (content: string, meta?: Record<string, string>) => Promise<void>
+
+export abstract class FunnelConnectorListener {
+  abstract start(notify: NotifyFn): Promise<void>
+}