connector.json

Declarative specification for AI-to-AI orchestration. Where MCP defines how AI connects to tools, connector.json defines how AI coordinates with other AI.

What It Solves

MCP:             AI → tool/data (one direction, passive target)
connector.json:  AI ↔ AI ↔ AI  (multi-direction, active participants)

Every AI CLI tool (Claude Code, Codex, Gemini CLI, Aider) runs in isolation. There is no standard way to:

Route tasks to different LLMs based on cost or capability
Run multiple AI sessions in parallel with isolated environments
Define multi-phase workflows across heterogeneous AI tools
Fail over to a different provider when one goes down

connector.json is that standard.

Spec Overview

{
  "connector": "2.0",
  "name": "feature-implementation",

  "session": {
    "worktree": "feat-auth-fix",
    "sandbox": true,
    "scratchpad": true,
    "timeout_ms": 3600000
  },

  "models": {
    "primary": "claude",
    "fallback": "gemini",
    "research": "haiku",
    "implementation": "opus"
  },

  "pipeline": {
    "phases": [
      { "name": "research",   "workers": 3, "model": "research" },
      { "name": "implement",  "workers": 1, "model": "implementation" },
      { "name": "verify",     "workers": 2, "model": "primary" }
    ]
  }
}

Core Sections

`session` — Environment

How to set up each AI session. Maps to daemon-external plugins that transform PTY session configuration without modifying the terminal engine.

Field	Type	Description
`worktree`	`string`	Git worktree slug for isolated workspace
`sandbox`	`bool`	OS-level process isolation (no network, restricted writes)
`scratchpad`	`bool`	Shared knowledge directory across workers
`env`	`object`	Environment variables injected into session
`permission`	`string`	Permission policy for the session
`timeout_ms`	`number`	Session timeout in milliseconds
`resume`	`string`	Resume an existing worktree session

`models` — Routing

Which AI to use for which role. Named aliases that pipeline phases reference.

{
  "primary": "claude",
  "fallback": "gemini",
  "research": "haiku",
  "implementation": "opus",
  "review": "codex"
}

When primary is unavailable, the runtime falls back to fallback automatically. Cost-aware routing: cheap models for research, expensive models for implementation.

`pipeline` — Orchestration

Multi-phase workflow with parallel workers.

{
  "phases": [
    {
      "name": "research",
      "workers": 3,
      "model": "research",
      "session": { "sandbox": true }
    }
  ],
  "scratchpad": true,
  "mailbox": true
}

Each phase can override session settings. Workers in the same phase run in parallel. Phases execute sequentially. Results flow through scratchpad and mailbox. workers accepts either a number (N identical workers sharing the phase’s model) or an array of worker objects (each with its own model, prompt, machine).

Beyond Pipeline — Communication Topologies

Pipeline is one topology. connector.json supports all:

Type	Field	Description
Pipeline	`"pipeline": { "phases": [...] }`	Sequential phases, parallel workers within each
Dialogue	`phases[].type: "dialogue"`	Two agents in multi-round conversation
Meeting	`"type": "meeting"`	All participants hear every voice
Mesh	`"type": "mesh"`	Any agent talks to any agent directly
Recursive	Agent runs its own `connector.json`	Unlimited depth, agents spawn sub-teams

See: Bidirectional Communication, Meeting Protocol, N-to-N Topology, Recursive Teams, Dimensional Growth.

Relationship to MCP

MCP is a field inside connector.json, not a competing spec.

{
  "session": { ... },
  "models": { ... },
  "pipeline": { ... },
  "tools": {
    "mcp": ["chrome-devtools", "github", "postgres"]
  }
}

MCP = tool access protocol (AI → tool). connector.json = workflow orchestration spec (AI ↔ AI, including tools).

Relationship to OpenCLIs

OpenCLIs concept	connector.json field
`wrapper_steps`	`pipeline.phases[].steps`
`initiate_md`	`agent.flow`
`trust_domains`	`trust.domains`
MCP CLI wrapping	`tools.mcp`

connector.json unifies these into a single declarative file.

Runtime

connector.json is a spec. The runtime that executes it is the NIIA daemon + headless PTY infrastructure.

connector.json → niia daemon reads it
  → creates headless PTY sessions
  → applies session plugins (worktree, sandbox, scratchpad)
  → routes to correct LLM per phase
  → manages pipeline execution
  → collects results via mailbox
  → handles failover automatically

No code modification needed. Drop a JSON file, run niia run connector.json.

Design Principles

Declarative — describe what, not how
LLM-agnostic — any AI CLI that runs in a terminal
Infrastructure-level — orchestration in daemon, not in prompts
MCP-complementary — MCP for tools, connector.json for workflows
File is the plugin — new JSON = new workflow, no code changes

Status

Component	Status
Spec v2.0	Draft
`session.worktree`	Implemented
`session.sandbox`	Implemented (macOS)
`models` routing	Designed
`pipeline` orchestration	Designed
`niia run connector.json`	Planned

Documentation Index

​connector.json

​What It Solves

​Spec Overview

​Core Sections

​session — Environment

​models — Routing

​pipeline — Orchestration

​Beyond Pipeline — Communication Topologies

​Relationship to MCP

​Relationship to OpenCLIs

​Runtime

​Design Principles

​Status