# Lynx — Local AI Agent Orchestration

Lynx is a local orchestration layer that coordinates coding agents and MCP clients around real developer workspaces. Instead of replacing the AI tools a developer already uses, Lynx connects them, assigns roles, routes tasks, exposes activity, and keeps workspace access under explicit local control.

## 1. High-Level Architecture

```mermaid
graph TD
    User["Developer"] --> Lynx["Lynx"]
    Clients["ChatGPT / Gemini / IDE / MCP clients"] --> Gateway["MCP Gateway"]
    Gateway --> Lynx
    Lynx --> Workspace["Selected local workspace"]
    Lynx --> Orchestrator["Agent Orchestrator"]
    Orchestrator --> Thinker["Thinker"]
    Thinker --> Planner["Planner"]
    Planner --> Implementer["Implementer"]
    Implementer --> Tester["Tester"]
    Tester --> Reviewer["Reviewer"]
    Reviewer -->|Revision loop| Planner
```

## 2. Bring Your Own CLI

Lynx uses coding CLIs that are already installed and authenticated on the developer's machine. The account and provider stay owned by the CLI while Lynx provides the orchestration layer around them.

```mermaid
graph LR
    Installed["Installed coding CLI"] --> Detect["Detect + readiness"]
    Detect --> Assign["Assign a role"]
    Assign --> Run["Run task"]
    Run --> Events["Normalized agent events"]
    Events --> UI["Live task visualization"]
```

Optimized adapters can work with tools such as Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro CLI, GitHub Copilot CLI, and Antigravity CLI. Compatible custom CLIs can also be automated through capability-based adaptation.

## 3. Role-Based Orchestration

A task can move through specialized roles instead of relying on one long opaque agent session:

- **Thinker** — understands the objective and constraints.
- **Planner** — turns the objective into executable steps.
- **Implementer** — performs the code changes.
- **Tester** — validates behavior and catches regressions.
- **Reviewer** — evaluates the result and can send it back through a revision loop.

The UI exposes this as a live node graph so the developer can see which role is active, where work is being routed, and which CLI is assigned to each node.

## 4. Normalized Runtime

Different CLIs expose different transports and output formats. Lynx converts these into one event model before the UI consumes them.

```mermaid
graph TD
    Headless["Headless CLI"] --> Normalize["AgentEvent normalization"]
    StdIO["stdin / stdout"] --> Normalize
    PTY["PTY + callback"] --> Normalize
    Fallback["Interactive fallback"] --> Normalize
    Normalize --> Timeline["Task timeline"]
    Normalize --> Graph["Live orchestration graph"]
    Normalize --> Files["Changed-file visibility"]
```

This keeps the interface decoupled from any one provider and lets the same task visualization work across different coding agents.

## 5. Local Workspace Gateway

Lynx can also act as an MCP gateway between external AI clients and selected local workspaces. Workspace permissions and review controls determine what each connected client can read or change.

```mermaid
graph LR
    Client["Connected AI client"] --> Auth["Connection + permissions"]
    Auth --> MCP["Lynx MCP gateway"]
    MCP --> Tools["Files / search / commands / Git"]
    Tools --> Workspace["Approved workspace"]
    Workspace --> Audit["Activity + audit trail"]
```

## 6. Design Goal

The central idea is visibility. Orchestration should not feel like a black box: developers should be able to see prompts being routed, active roles, terminal activity, changed files, approval requests, and the final result as one connected workflow.

## Demo

Watch the orchestration demo at **video.doms.dev/lynx**.