skills.rest
SmallAi-API
SmallAi-APICOMMUNITY
Explore all skills by this author →
WebsiteGitHub

heterogeneous-agent

Diagnose and fix Claude Code and Codex adapter, transport, and tool-persistence bugs.

Updated Jan 27, 2026
Search Tags:#debugging#claude code#codex#electron#adapter#stream-json#tool persistence
One-click install
npx skills add https://github.com/SmallAi-API/smaihub --skill heterogeneous-agent-smallai-api
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: heterogeneous-agent
Source: https://github.com/SmallAi-API/smaihub/tree/main/.agents/skills/heterogeneous-agent
Command: npx skills add https://github.com/SmallAi-API/smaihub --skill heterogeneous-agent-smallai-api

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Debugging external CLI agent integrations (Claude Code, Codex) is hard because bugs can live anywhere in the pipeline from raw CLI stdout through adapters, persistence, and UI hydration. This Skill provides a structured debug order, critical invariants, and known bug patterns so you fix the right layer first instead of guessing at UI code. ## Core Features & Use Cases - Layered Debug Workflow: Verify raw CLI traces first, then adapted events, then step boundaries and tool persistence, before touching UI rendering. - Provider-Specific Invariants: Documents Claude Code semantics (message.id step boundaries, tool_result in user events, partial deltas, subagent thread scoping) and Codex JSONL turn boundaries. - Trace Capture & Focused Tests: Explains how to read recorded live traces under .heerogeneous-tracing/ and run targeted vitest suites for adapters and the executor. - Use Case: When Claude Code duplicates text or Codex collapses multiple tools into one assistant message, follow the pipeline map to isolate whether the fault is in raw output, the adapter, or persistence, then add a regression test. ## Quick Start Ask the agent to debug why Claude Code tool results never appear in the chat UI using the heterogeneous-agent debug workflow.

Frequently Asked Questions about heterogeneous-agent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug Claude Code stream-json duplicate text or thinking?▼

Check whether partial content_block_delta events and the later full assistant block are both being emitted. Compare the raw NDJSON trace with adapted events via window.__HETERO_AGENT_TRACE, then fix the adapter so partial text is emitted only once.

Why do multiple Codex tools collapse into one assistant message?▼

The executor only cuts a new assistant message when it receives a step-boundary signal. Check whether the Codex adapter emits stream_start with newStep or an equivalent turn-change signal derived from turn.started and turn.completed events.

Why do Claude Code tool results never appear in the UI?▼

In Claude Code, tool_result blocks arrive in type: 'user' events, not assistant events. Verify the adapter processes user events and that persistToolResult resolves the call through toolMsgIdByCallId without 'unknown toolCallId' warnings.

How do I capture a raw CLI trace for debugging?▼

The app records every spawned CLI session automatically in dev builds. Read the most recent session via cat .heerogeneous-tracing/.last-live-trace, then inspect meta.json for spawn args and stdout.jsonl for the raw provider events.

When should I not start debugging at the UI layer?▼

Only debug UI hydration after raw CLI output, adapter events, and persistence are proven correct. The workflow requires starting at the leftmost broken pipeline layer, since most symptoms originate in transport or adapter code.

Related Skills

Explore More Software Engineering Skills→
adriandarianadriandarian

trace-operations

Capture, replay, and export 3Lens traces via CLI for debugging and regression testing.

Community
Intermediate
namhoanggnamhoangg

run-smoke-tests

Automate end-to-end smoke tests and diagnose failures with traces and logs.

Community
Intermediate
ejoongseokejoongseok
8

pitfall

Capture session trial-and-error mistakes as five-field pitfall records.

Community
Advanced
mDevsLabsmDevsLabs
1

heterogeneous-agent

Diagnose heterogeneous-agent pipeline failures across CLI adapters, IPC, and tool chains.

Community
Advanced