> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# connector.json

> Cross-AI orchestration spec — declare multi-LLM workflows across pipeline, dialogue, meeting, mesh, and recursive-team topologies in a single JSON file.

# 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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/openclis/specs/connector-json/bidirectional), [Meeting Protocol](/openclis/specs/connector-json/meeting-protocol), [N-to-N Topology](/openclis/specs/connector-json/n2n-topology), [Recursive Teams](/openclis/specs/connector-json/recursive-teams), [Dimensional Growth](/openclis/specs/connector-json/dimensional-growth).

## Relationship to MCP

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

```json theme={null}
{
  "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

1. **Declarative** — describe what, not how
2. **LLM-agnostic** — any AI CLI that runs in a terminal
3. **Infrastructure-level** — orchestration in daemon, not in prompts
4. **MCP-complementary** — MCP for tools, connector.json for workflows
5. **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             |