# External Agent Adapters

Builds adapters that run external agents such as Claude Code and Codex.

- Repository: https://github.com/lobehub/lobehub (83676 stars)
- Category: AI and agents
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add lobehub/lobehub --skill heterogeneous-agent -g -a claude-code -y`
Codex: `npx skills add lobehub/lobehub --skill heterogeneous-agent -g -a codex -y`
Cursor: `npx skills add lobehub/lobehub --skill heterogeneous-agent -g -a cursor -y`
Gemini CLI: `npx skills add lobehub/lobehub --skill heterogeneous-agent -g -a gemini-cli -y`

## Description

Use for external-agent launchers and execution identity, Claude Code/Codex adapters, IPC, event mapping, sessions, persistence and tool-call chains.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Heterogeneous Agent Development

Use this skill when the bug or feature lives in the external CLI agent pipeline, not the normal server-side agent runtime.

## Use This Skill For

- Adding or changing a driver under `apps/desktop/src/main/modules/heterogeneousAgent/drivers/`
- Editing an adapter under `packages/heterogeneous-agents/src/adapters/`
- Changing CLI/Desktop dispatch launchers, including OpenClaw/Hermes, or debugging task-comment authorship
- Debugging `heteroAgentRawLine` transport, `window.__HETERO_AGENT_TRACE`, or `executeHeterogeneousAgent`
- Fixing Claude Code stream-json bugs such as duplicate partial/full chunks, broken `message.id` boundaries, missing `tool_result`, TodoWrite state drift, or subagent thread routing
- Fixing Codex JSONL bugs such as mixed multi-tool messages, broken turn boundaries, or missing tool-result mapping
- Fixing step-boundary, tool persistence, subagent thread, or resume bugs in Claude Code / Codex flows
- Reproducing multi-tool mixing, orphan tool messages, or stuck tool-result loading

## Pipeline Map

1. CLI raw stdout / JSONL
2. Electron main spawns the CLI and broadcasts `heteroAgentRawLine`
3. Adapter maps raw provider events into `HeterogeneousAgentEvent`
4. `executeHeterogeneousAgent` persists assistant/tool messages and forwards stream events
5. `createGatewayEventHandler` hydrates the UI
6. Only after this path looks correct should you move on to `agent-tracing` or context-engine debugging

## Read These Files First

The rest: https://github.com/lobehub/lobehub/blob/HEAD/.agents/skills/heterogeneous-agent/SKILL.md