Skip to main content

​
Connector Integration

MonoSurf is a CLI binary. connector.json defines how CLI binaries are invoked. They connect naturally.

​
The Pattern

┌──────────────────────────────────────────────────────────────────┐
│  connector.json (defines)                                         │
│  "To search X, run monosurf x.com search {query} --json"         │
│  "If results > 3 lines, suggest: read specific tweet"             │
│  "If write intent, require approval gate"                         │
├──────────────────────────────────────────────────────────────────┤
│  cjson runner (executes)                                          │
│  Reads connector.json → resolves variables → runs binary          │
│  Matches output → suggests next action                            │
├──────────────────────────────────────────────────────────────────┤
│  monosurf (does the work)                                         │
│  Connects to Chrome → navigates → extracts → returns              │
└──────────────────────────────────────────────────────────────────┘

​
Intent Field

connector.json v2.1 adds intent to StepDefinition: 
"search": {
  "binary": "monosurf",
  "args": ["x.com", "search", "{query}", "--json"],
  "intent": "read",
  "output": {
    "has_results": {
      "match": "lines_over:3",
      "next": ["read specific tweet", "check author timeline"]
    }
  }
},
"post": {
  "binary": "monosurf",
  "args": ["x.com", "post", "{text}"],
  "intent": "write"
}
  • intent: "read" — safe, AI can execute freely within grant
  • intent: "write" — mutates state, cjson runner prompts for confirmation
This field was added to the connector.json schema specifically for the MonoSurf use case, but applies to any tool that has read and write operations.

​
Pipeline Example

A connector.json can define a full discover → dive → engage pipeline: 
Phase 1: discover
  monosurf x.com search "AI terminal" --json
  → output matched "has_results"
  → next: "read specific tweet"

Phase 2: dive
  monosurf x.com read {selected_url} --json
  → output matched "has_thread"
  → next: "reply to tweet"

Phase 3: engage (gated)
  [APPROVAL GATE] "All write operations must be confirmed"
  → User approves
  monosurf x.com post {text}
  → "posted"
Machine executes steps 1-2 automatically. Step 3 pauses for human approval. This is the same pattern as kernel-cli’s observe → control flow.

​
Same Pattern, Every Tool

connector.json doesn’t know or care that MonoSurf uses Chrome CDP internally. It sees a CLI binary with arguments and output. The same connector.json format works for:
ToolTransportconnector.json sees
monosurfchromiumoxide CDPbinary: "monosurf"
monofetchHTTPbinary: "monofetch"
monogitGit APIbinary: "monogit"
niiaLocal CLIbinary: "niia"
One format. Any tool. The transport is the tool’s problem, not the orchestrator’s.

​
Running via cjson

# List available steps
cjson monosurf-x.connector.json --list

# Run single step
cjson monosurf-x.connector.json --step search query="rust"

# Run full pipeline
cjson monosurf-x.connector.json topic="AI agents"
The cjson runner:
  1. Loads connector.json
  2. Resolves {variables} from CLI arguments
  3. Executes binary with args
  4. Matches output against rules
  5. Suggests next actions
  6. Gates write operations with approval prompts