@interactive-inc/claude-funnel 0.10.0 → 0.15.1

package/README.md

@@ -1,56 +1,56 @@
 [![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) and time-based triggers (cron). External events flow into subscription "channels" and arrive at Claude Code over MCP. Outbound API calls from Claude go back through the same connectors as MCP tools, so replying to a Slack thread or commenting on a GitHub issue does not need a bash subshell.
+A hub for AI coding agents. One long-running daemon owns all external connections; agents subscribe to named channels and react to events without you wiring up shell scripts and cron entries. Outbound replies travel back through the same connectors as MCP tools, so answering a message or commenting on an issue does not need a bash subshell.
 
-The command is `funnel` or its shorthand `fnl`.
+The command is `funnel` (or the shorthand `fnl`).
 
-## Why funnel
+Connectors today: Slack (Socket Mode), GitHub (poll via `gh`), Discord (Gateway), and cron schedules. Built around Claude Code; the architecture is agent-agnostic.
 
-A single Claude Code session is great at one repo at one moment. The moment you want it to react to things — a Slack mention, a new GitHub issue, a 9 AM standup — you end up gluing shell scripts, cron entries and `bash -c "claude ..."` together, and there is no single place that says "who is listening to what, and who is allowed to reply where."
+## Why funnel
 
-`funnel` is that place. You configure named subscription boxes (channels), attach connectors to them, launch Claude with a channel binding, and the daemon does the rest:
+A single agent session is great at one repository at one moment. The moment you want it to react to things — a chat mention, a new issue, a 9 AM standup — you end up gluing shell scripts, cron entries, and `bash -c "agent ..."` invocations together. There is no single place that says "who is listening to what, and who is allowed to reply where."
 
-- The gateway daemon owns the external connections. Slack Socket Mode, the Discord Gateway, GitHub polling — they connect once, from the daemon, no matter how many Claude sessions you start. Launching a second Claude does not open a second Slack socket; both sessions just subscribe to the same channel and the daemon routes events to them
-- Inbound events arrive as MCP notifications, so Claude reacts in the same session it is already running in
-- Outbound replies use MCP tools per connector, so they are essentially synchronous (no bash, no CLI cold start)
-- Listeners are supervised with health checks and auto-restart, so a flaky Slack connection or a crashed poller recovers on its own
-- Multiple Claudes can share the same channel (`fanout`) or compete for events as workers (`exclusive`) — the daemon decides who gets each event
+funnel is that place. Declare named subscription boxes (channels), attach connectors to them, launch the agent with a channel binding, and the daemon handles the rest:
 
-If you have ever wanted "Slack-driven Claude" or "cron-driven Claude" without writing a dispatcher, this is it.
+- The daemon owns the external connections. Each one connects once, no matter how many agent sessions you start. A second agent does not open a second socket; both sessions subscribe to the same channel and the daemon fans events out.
+- Inbound events arrive as MCP notifications, so the agent reacts in the session it is already running in.
+- Outbound replies use MCP tools per connector — essentially synchronous (no bash, no CLI cold start).
+- Listeners are supervised with health checks and automatic restart; a flaky connection or crashed poller recovers on its own.
+- Multiple agents can share a channel (`fanout`) or compete for events as workers (`exclusive`) — the daemon decides who gets each event.
 
 ## Concepts
 
 ```
-External sources                       Outbound calls
-(Slack / GitHub / Discord / cron)     (Claude → MCP tools per connector)
-            │                                       ▲
-            ▼                                       │
-        Channels (with nested per-type connectors)
-                    │
-                    ▼  WebSocket
-              Gateway daemon
-        (port 9742: WS /ws + listener supervisor + reply API)
-                    │
-                    ▼  MCP (stdio)
-              Claude Code
+external sources                          outbound replies
+(chat / source-control / cron)            (MCP tools per connector)
+        │                                          │
+        ▼                                          ▼
+            daemon  (port 9742)
+            routes events into channels
+            serves replies through the same connectors
+                        │
+                        ▼  WebSocket / MCP (stdio)
+                     agent  (subscribes to one channel)
 ```
 
-Channel — a named subscription box. Holds one or more connectors. Each Claude session subscribes to exactly one channel. Delivery mode is `fanout` (every subscriber sees every event; the default) or `exclusive` (round-robin one subscriber per event, for worker pools).
+Three concepts make up the model:
+
+Channel — a named subscription box. Holds one or more connectors. An agent session subscribes to exactly one channel. Delivery is `fanout` (every subscriber sees every event, the default) or `exclusive` (one event per subscriber, round-robin — for worker pools).
 
-Connector — a single attachment to an external source. Four types ship: `slack` (Socket Mode push), `gh` (GitHub poll via the `gh` CLI), `discord` (Gateway push), and `schedule` (cron tick). Connectors are nested inside their owning channel.
+Connector — a single attachment from a channel to an external source. Four types ship today: `slack`, `gh`, `discord`, `schedule`. The first three are bidirectional (events in, replies out); `schedule` is one-way (cron ticks in).
 
-Profile — a named launch preset for Claude. Bundles `{ path, sub-agent, channel }` so `fnl claude --profile cto` reproduces a known setup. The first profile in the list is the default.
+Profile — a saved launch preset for an agent. Bundles `{ path, sub-agent, channel }` so `fnl claude --profile cto` reproduces a known setup. The first profile in the list is the default.
 
-Gateway daemon — the long-running process and the sole owner of external connections. Each connector connects from here exactly once; Claude sessions never open their own. Hosts the connector listeners with auto-restart, broadcasts events to subscribed clients, and serves the outbound reply API. Runs on port 9742 by default.
+The daemon is where all external connections live. It runs on port 9742, supervises connectors with auto-restart, broadcasts events to subscribed agent sessions over WebSocket, and serves the reply API that MCP calls. Starting or stopping an agent never starts or stops external connections.
 
-MCP — the bridge into Claude Code. A thin client: subscribes to one channel over WebSocket (the daemon does the real work) and surfaces one MCP tool per callable connector so Claude can call back out. Starting or stopping a Claude session does not start or stop external connections.
+The MCP layer is a thin bridge into the agent. It subscribes to the bound channel over WebSocket (the daemon does the work) and exposes one tool per callable connector so the agent can reply back out.
 
 ## Requirements
 
 - [Bun](https://bun.sh) 1.3 or later
 - [Claude Code](https://docs.claude.com/en/docs/claude-code) CLI
-- A Slack / GitHub / Discord token or CLI, depending on which connectors you use
+- A token or CLI for whichever external service you connect (Slack app, `gh` auth, Discord bot, etc.)
 
 ## Install
 
@@ -58,11 +58,11 @@ MCP — the bridge into Claude Code. A thin client: subscribes to one channel ov
 bun add -g @interactive-inc/claude-funnel
 ```
 
-The published package already ships the built `dist/`, so `bun add -g` makes `funnel` / `fnl` available immediately — no postinstall step.
+The published package ships the built `dist/`, so `bun add -g` makes `funnel` / `fnl` available immediately — no post-install step.
 
 ## Quick start
 
-Wire Slack to Claude:
+Wire one source to one agent:
 
 ```bash
 fnl channels add ops
@@ -72,16 +72,59 @@ fnl gateway start
 fnl claude --channel ops
 ```
 
-From now on every Slack event the bot can see arrives in the running Claude session, and Claude can reply via the `my-slack` MCP tool.
+Every event the connector sees now arrives in the running agent session, and the agent can reply via the `my-slack` MCP tool.
 
 Save it as a profile for one-command launches:
 
 ```bash
 fnl profiles add cto --path=/repo/myapp --sub-agent=cto --channel=ops
-fnl claude --profile cto         # cd /repo/myapp + sub-agent + channel binding
+fnl claude --profile cto         # cd + sub-agent + channel binding in one shot
 ```
 
-Cron-driven Claude:
+Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo will use it:
+
+```json
+{
+  "$schema": "https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json",
+  "channel": "ops",
+  "options": ["--brief", "--agent", "cto"],
+  "env": {
+    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
+  },
+  "connectors": [
+    {
+      "type": "slack",
+      "name": "my-slack",
+      "env": {
+        "botToken": "SLACK_BOT_TOKEN",
+        "appToken": "SLACK_APP_TOKEN"
+      }
+    }
+  ]
+}
+```
+
+Only `channel` is required.
+
+The optional `options` array is prepended to the claude argv on every launch, before any args the user types after `fnl claude`. Use it for repo-wide claude flags (e.g. `--brief`, `--agent <name>`, `--model <name>`). User-supplied CLI args appear later in the argv so they still win on collision.
+
+The optional top-level `env` is a `Record<string, string>` of environment variables to layer under the claude process. `process.env` from the launching shell wins on collision, so funnel.json sets defaults that the user can still override one-off via the shell.
+
+The optional `connectors` array is treated as the source of truth for the declared channel: missing connectors are created, an existing connector that the spec references by token (not by name) is renamed in place, and connectors not declared in the spec are removed on launch. An absent `connectors` field leaves `~/.funnel` alone.
+
+The optional top-level `$schema` points at the hosted JSON Schema (`https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json`) so editors can validate and autocomplete the file. Local alternatives: the file ships in the npm package at `node_modules/@interactive-inc/claude-funnel/schemas/funnel.schema.json`, or generate one in-repo with `fnl schema > funnel.schema.json` and reference it via `./funnel.schema.json`.
+
+Each token field resolves in this order:
+
+- literal value at the field itself (e.g. `"botToken": "xoxb-..."`) — used as-is
+- env-var name at `env.<field>` (e.g. `"env": { "botToken": "SLACK_BOT_TOKEN" }`) — looked up in `process.env`, falling back to `./.env.local` in the cwd; fails with a clear error when neither is set
+- field omitted everywhere — `fnl claude` prompts on a TTY and writes the answer to `~/.funnel/settings.json`; on non-TTY stdin the launch fails so CI / agent-spawned-agent runs do not hang
+
+Setting both a literal and an `env.<field>` for the same field is an error (pick one).
+
+`funnel.json` itself is never written to — secrets stay in env vars, `.env.local`, or `~/.funnel`, never in the committed file.
+
+Cron-driven agent runs:
 
 ```bash
 fnl channels ops connectors add daily --type=schedule
@@ -91,14 +134,11 @@ fnl channels ops connectors daily schedules add morning \
 
 Each tick fires the prompt into the channel. If the daemon was down at 9 AM, the next start catches up the missed slot (`meta.catchup = "true"`) for up to 24 hours.
 
-Multiple Claudes on the same source — pick the delivery mode:
+Multiple agents on the same source — pick the delivery mode:
 
 ```bash
-# default: fanout — every Claude on the channel sees every event
-fnl channels add reviews
-
-# worker pool — each event is handled by exactly one Claude, round-robin
-fnl channels add ingest --delivery=exclusive
+fnl channels add reviews                       # fanout (default): every agent sees every event
+fnl channels add ingest --delivery=exclusive   # exclusive: one event per agent, round-robin
 ```
 
 ## CLI surface
@@ -138,9 +178,11 @@ fnl profiles <name> as-default               move to the front of the list
 fnl profiles rename <old> <new>
 fnl profiles remove <name>
 
-fnl claude                                   launch the default profile
+fnl claude                                   launch using ./funnel.json, or the default profile
 fnl claude --profile <name>                  launch a named profile
 fnl claude --channel <name>                  raw launch (no profile, cwd = current dir)
+fnl claude [...]                             positionals and any flag other than -p / --profile / --channel
+                                              (e.g. --agent, --resume, -c, --model) pass through to claude
 fnl mcp                                      run as an MCP server (invoked from .mcp.json)
 
 fnl gateway                                  status (default subcommand)
@@ -150,6 +192,7 @@ fnl gateway logs [-n <N>]                    tail diagnostic log
 fnl gateway listeners                        live registry (alive / dead)
 
 fnl status                                   overall status (channels / profiles / gateway / clients)
+fnl schema                                   print the JSON Schema for funnel.json (pipe to a file for editor support)
 fnl update                                   `bun i -g @interactive-inc/claude-funnel`
 fnl                                          (no args) launch the OpenTUI dashboard
 
@@ -161,7 +204,7 @@ fnl --help                                   every subcommand has --help; verb-w
 
 ## Outbound calls (MCP tools per connector)
 
-When `fnl claude` launches Claude Code, the funnel MCP server connects to the gateway and reads the channel's connectors from `~/.funnel/settings.json`. For every callable connector (`slack` / `discord` / `gh`; `schedule` is one-way and skipped), the MCP advertises one tool with the connector's name. Claude calls them like:
+When `fnl claude` launches the agent, the funnel MCP server connects to the daemon and reads the channel's connectors from `~/.funnel/settings.json`. For every callable connector (`slack` / `discord` / `gh`; `schedule` is one-way and skipped), MCP advertises one tool with the connector's name. The agent calls them like:
 
 ```jsonc
 // MCP: tools/list returns
@@ -169,7 +212,7 @@ When `fnl claude` launches Claude Code, the funnel MCP server connects to the ga
 { "name": "ops-slack", "inputSchema": { ... } }
 { "name": "gh-main",   "inputSchema": { ... } }
 
-// Claude calls
+// agent calls
 tools/call name="discord" arguments={
   "method": "POST",
   "path": "/channels/123/messages",
@@ -177,9 +220,9 @@ tools/call name="discord" arguments={
 }
 ```
 
-The MCP forwards via HTTP `POST /channels/<channel>/connectors/<connector>/call` to the gateway daemon, which dispatches through the existing `FunnelChannels.call()` adapter. No bash subshell, no CLI cold start — replies are essentially synchronous.
+MCP forwards via HTTP `POST /channels/<channel>/connectors/<connector>/call` to the daemon, which dispatches through the connector's adapter. No bash subshell, no CLI cold start — replies are essentially synchronous.
 
-If you need to invoke a connector from outside Claude, the same path is reachable as `fnl channels <ch> connectors <c> request --method=<...> [--key=value ...]`.
+To invoke a connector from outside an agent, the same path is reachable as `fnl channels <ch> connectors <c> request --method=<...> [--key=value ...]`.
 
 ## Data model
 
@@ -189,7 +232,7 @@ Channel    = { id, name, delivery, connectors[] }
         or `exclusive` (round-robin one client per event)
 
 Connector  =
-  | { type: "slack",    name, botToken, appToken }     Slack Socket Mode
+  | { type: "slack",    name, botToken, appToken }      Slack Socket Mode
   | { type: "gh",       name, pollInterval? }           GitHub (gh CLI, poll-based)
   | { type: "discord",  name, botToken }                Discord Gateway
   | { type: "schedule", name, entries[] }               cron-driven; entries = { id, cron, prompt, enabled?, catchupPolicy? }
@@ -197,6 +240,13 @@ Connector  =
 Profile    = { name, path, subAgent, channelId }
         named launch preset; the first profile in the list is the default
 
+LocalConfig = { channel, options?, env?, connectors? }
+        per-repo file (funnel.json) checked by `fnl claude` when no --profile / --channel is given
+        options[] is prepended to claude argv (user CLI args override); env merges under process.env;
+        connectors[] declares connectors to materialize on launch (each token field accepts a literal,
+        an env-var reference at `env.<field>` resolved from process.env and ./.env.local, or omission
+        for a TTY prompt persisted to ~/.funnel)
+
 Settings   = { channels[], profiles[] }                 → ~/.funnel/settings.json
 ```
 
@@ -208,7 +258,7 @@ Persistent state lives under `~/.funnel/`. Volatile logs and the event store liv
 ~/.funnel/
 ├── settings.json                                       channels[] with nested connectors, profiles[]
 ├── gateway.pid                                         daemon PID
-├── gateway.token                                       Bearer token for gateway HTTP / WS
+├── gateway.token                                       Bearer token for daemon HTTP / WS
 ├── claude/
 │   └── <profile>.pid                                   prevents double-launch of the same profile
 └── channels/
@@ -219,23 +269,23 @@ Persistent state lives under `~/.funnel/`. Volatile logs and the event store liv
 
 /tmp/funnel/
 ├── events/events.db                                    SQLite event store with replay-by-seq
-├── funnel.log                                          diagnostic log (gateway lifecycle, listener boot, connects)
+├── funnel.log                                          diagnostic log (daemon lifecycle, listener boot, connects)
 └── gateway.log                                         daemon stdout/stderr
 ```
 
-Notes
+Notes:
 
 - Connector configuration is stored inline in `settings.json` (nested under the channel), not in a per-type directory. Per-connector durable state (e.g. `lastFiredAt` for schedule catch-up) lives under `channels/<channel-id>/connectors/<connector-id>/state.json` keyed by id, so renames do not lose state.
-- `funnel gateway logs` tails `funnel.log` and renders it as YAML.
+- `fnl gateway logs` tails `funnel.log` and renders it as YAML.
 
 ## Environment variables
 
 | Variable               | Purpose                                                                                       |
 | ---------------------- | --------------------------------------------------------------------------------------------- |
 | `FUNNEL_CHANNEL_ID`    | Injected into the child process by `fnl claude`; the funnel MCP uses it to subscribe.         |
-| `FUNNEL_PORT`          | Gateway port (default 9742).                                                                  |
-| `FUNNEL_GATEWAY_URL`   | Gateway base URL used by MCP for both WS subscribe and HTTP reply (default `http://localhost:9742`). |
-| `FUNNEL_GATEWAY_TOKEN` | Bearer token for the gateway HTTP / WS. Defaults to the contents of `~/.funnel/gateway.token`. |
+| `FUNNEL_PORT`          | Daemon port (default 9742).                                                                   |
+| `FUNNEL_GATEWAY_URL`   | Daemon base URL used by MCP for both WS subscribe and HTTP reply (default `http://localhost:9742`). |
+| `FUNNEL_GATEWAY_TOKEN` | Bearer token for the daemon HTTP / WS. Defaults to the contents of `~/.funnel/gateway.token`. |
 
 ## Discord bot setup
 
@@ -293,7 +343,7 @@ await server.stop()
 unsubscribe()
 ```
 
-The gateway daemon exposes `/health`, `/status`, `/listeners*`, `/channels/:channel/connectors/:connector/call`, plus the `/ws?channel=<name>` WebSocket.
+The daemon exposes `/health`, `/status`, `/listeners*`, `/channels/:channel/connectors/:connector/call`, plus the `/ws?channel=<name>` WebSocket.
 
 ### Sandboxed Funnel
 
@@ -381,9 +431,9 @@ The published package ships a bundled library entry (`dist/index.js`) plus gener
 
 This repo ships a Claude Code skill at `.claude/skills/funnel/SKILL.md`. It briefs Claude on the architecture and command groups, and tells it to defer flag-level details to `funnel <command> --help`.
 
-Project-scoped (auto). If you run `claude` inside this repo, the skill is picked up automatically — no install step.
+Project-scoped (auto): if you run `claude` inside this repo, the skill is picked up automatically — no install step.
 
-Global (use the skill in any project). Claude Code does not currently provide a CLI to install skills from a remote URL, so copy the file into your personal skills directory:
+Global (use the skill in any project): Claude Code does not currently provide a CLI to install skills from a remote URL, so copy the file into your personal skills directory:
 
 ```bash
 # from a clone of this repo