@interactive-inc/claude-funnel 0.15.2 → 0.17.0

package/README.md

@@ -87,8 +87,8 @@ Every event the connector sees now arrives in the running agent session, and the
 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 + sub-agent + channel binding in one shot
+fnl profiles add cto --path=/repo/myapp --channel=ops
+fnl claude --profile cto         # cd + channel binding in one shot
 ```
 
 Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo will use it:
@@ -96,31 +96,39 @@ Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo w
 ```json
 {
   "$schema": "./node_modules/@interactive-inc/claude-funnel/funnel.schema.json",
-  "channel": "ops",
-  "options": ["--brief", "--agent", "cto"],
-  "env": {
-    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
-  },
-  "connectors": [
+  "channels": [
     {
-      "type": "slack",
-      "name": "my-slack",
+      "name": "ops",
+      "options": ["--brief", "--agent", "pm"],
       "env": {
-        "botToken": "SLACK_BOT_TOKEN",
-        "appToken": "SLACK_APP_TOKEN"
-      }
+        "ANTHROPIC_MODEL": "claude-sonnet-4-6"
+      },
+      "connectors": [
+        {
+          "type": "slack",
+          "name": "my-slack",
+          "env": {
+            "botToken": "SLACK_BOT_TOKEN",
+            "appToken": "SLACK_APP_TOKEN"
+          }
+        }
+      ]
+    },
+    {
+      "name": "review",
+      "options": ["--agent", "reviewer"]
     }
   ]
 }
 ```
 
-Only `channel` is required.
+`channels[]` is required and the first entry is the default. `fnl claude --channel review` picks one by name; `fnl claude` with no `--channel` uses the first.
 
-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.
+Each channel has its own `options` (prepended to the claude argv before user-supplied CLI args, which still come last — use it for per-channel flags like `--brief`, `--agent <name>`, `--model <name>`) and `env` (layered under the launched 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 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 on a channel is the source of truth for that channel: missing connectors are created, an existing connector matched by token under a different name is renamed in place, and connectors not declared are removed on launch. An absent `connectors` field leaves `~/.funnel` alone.
 
-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.
+On launch, the chosen channel's `options` / `env` / `connectors` are also materialized into the global `~/.funnel/settings.json` Channel entry. Raw launches (`fnl claude --channel <name>` without funnel.json) and profile launches read the same fields from there, so funnel.json and settings.json share one Channel data model.
 
 The optional top-level `$schema` points at the JSON Schema so editors can validate and autocomplete the file. The recommended reference for repos with a local install is `./node_modules/@interactive-inc/claude-funnel/funnel.schema.json` — it works without a network round-trip and editors do not need to prompt for trust. The same file is also published at `https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json` (editors usually require explicit trust on first use), and `fnl schema > funnel.schema.json` regenerates a local copy on demand.
 
@@ -180,17 +188,17 @@ fnl channels <ch> connectors <c> schedules add <id> --cron="<expr>" --prompt="<t
 fnl channels <ch> connectors <c> schedules remove <id>
 
 fnl profiles                                 list (first entry is the default)
-fnl profiles add <name> --path=<dir> --sub-agent=<agent> --channel=<channel-name>
+fnl profiles add <name> --path=<dir> --channel=<channel-name>
 fnl profiles <name>                          launch (alias for `<name> run`)
 fnl profiles <name> run                      launch (sugar for `fnl claude --profile <name>`)
-fnl profiles <name> set [--path=...] [--sub-agent=...] [--channel=...]
+fnl profiles <name> set [--path=...] [--channel=...]
 fnl profiles <name> as-default               move to the front of the list
 fnl profiles rename <old> <new>
 fnl profiles remove <name>
 
-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                                   launch the first channel from ./funnel.json, or the default profile
+fnl claude --channel <name>                  with funnel.json: pick that channel; without: raw launch
+fnl claude --profile <name>                  launch a named profile (ignores funnel.json)
 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)
@@ -237,9 +245,10 @@ To invoke a connector from outside an agent, the same path is reachable as `fnl
 ## Data model
 
 ```
-Channel    = { id, name, delivery, connectors[] }
-        subscription box; delivery is `fanout` (every WS client sees every event)
-        or `exclusive` (round-robin one client per event)
+Channel    = { id, name, delivery, options[], env, connectors[] }
+        subscription box plus launch settings. delivery is `fanout` (every WS client sees every event)
+        or `exclusive` (round-robin one client per event). options[] prepends to the claude argv on
+        launch; env layers under the launched process (process.env wins on collision)
 
 Connector  =
   | { type: "slack",    name, botToken, appToken }      Slack Socket Mode
@@ -247,15 +256,17 @@ Connector  =
   | { type: "discord",  name, botToken }                Discord Gateway
   | { type: "schedule", name, entries[] }               cron-driven; entries = { id, cron, prompt, enabled?, catchupPolicy? }
 
-Profile    = { name, path, subAgent, channelId }
-        named launch preset; the first profile in the list is the default
+Profile    = { name, path, channelId }
+        named launch preset (just where to launch a channel from); the first profile is the default
+
+LocalConfig = { channels: ChannelSpec[] }
+        per-repo file (funnel.json). channels[] required; first entry is default, --channel selects.
 
-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)
+ChannelSpec = { name, options?, env?, connectors? }
+        mirrors Channel above (no id, since funnel.json declares by name). options/env/connectors
+        materialize into the matching Channel in ~/.funnel/settings.json on launch. Connector token
+        fields accept 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
 ```