LoongSuite Pilot

English | 简体中文

Quick Start | Documentation | Agent Onboarding | License

LoongSuite Pilot is a local telemetry collector for AI coding agents. It discovers supported agents on a developer machine, installs the required hooks or plugins, normalizes activity into a shared GenAI event schema, and exports logs or traces to your chosen backends.

Local dashboard — multi-agent collection status, token usage, and reporting health at a glance.

Why LoongSuite Pilot?

Development teams often use more than one AI coding agent, and each agent records activity in a different local format. Pilot gives teams one local collector that can discover those agents, collect their activity, normalize the data, and send it to destinations that are useful for analysis, audit, and observability.

Pilot is designed to answer practical questions:

• Which agents are being used?
• What model, session, turn, and tool activity happened?
• How much token usage is available from each agent?
• Where should the data be exported: local files, SLS, HTTP, or traces?
• How should sensitive prompts, tool arguments, and secrets be controlled before export?

Core Capabilities

Supported Agents

OpenClaw integration requires OpenClaw 2026.5.12 or later.

Documented Windows Agent Support

The table above describes Pilot's general integration capabilities; it does not imply that every agent is supported on every operating system. The following agents are currently explicitly documented as supported on Windows:

Agents omitted from this Windows table do not currently have an explicit Windows support statement; omission does not necessarily mean that the agent cannot run on Windows. See the Alibaba Cloud AI Coding Agent access guide for the source support matrix and Installation for Windows prerequisites and setup.

Agent definitions live in agents.d/. You can add new agents without changing the deployment framework; see Agent Onboarding.

Quick Start

Prerequisites:

• Node.js 18 or later
• npm
• curl or wget
• PowerShell 5.1 or later on Windows

Install from the public package on Linux or macOS:

curl -fsSL https://loongcollector-community-edition.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh -o /tmp/loongsuite-pilot-installer.sh && bash /tmp/loongsuite-pilot-installer.sh install

Install from the public package on Windows:

$installer = "$env:TEMP\loongsuite-pilot-installer.ps1"
Invoke-WebRequest `
  -Uri "https://loongcollector-community-edition.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.ps1" `
  -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer install

Verify the service:

loongsuite-pilot status
loongsuite-pilot info

Local JSONL output is enabled by default under ~/.loongsuite-pilot/logs/output/ on Linux/macOS and %USERPROFILE%\.loongsuite-pilot\logs\output\ on Windows.

For installer options, uninstall commands, and source builds, see Installation.

Configure Pilot

Configuration is loaded in this order: environment variables, then ~/.loongsuite-pilot/config.json, then built-in defaults.

Start with the guide that matches what you want to change:

Upstream Trace Linking (optional)

Link collected agent spans to an upstream trace so each turn's span tree reparents under the upstream span. Disabled by default, and fully fail-open (never affects normal collection/reporting).

When enabled, the upstream traceparent reaches Pilot via one of two schemes and is stamped onto collected records (trace_id on the turn, parent_span_id on the user-input event):

• Correlation file (per-turn): the caller writes {sessionId, contentHash, contentPrefix, traceparent} to ~/.loongsuite-pilot/acp-correlate/<sessionId>.jsonl when it sends a prompt. Linking is protocol-agnostic — the only requirement is that sessionId matches the gen_ai.session.id Pilot collects for that turn, and the content (hash or prefix) matches the collected user text. ACP clients satisfy this naturally (the session/new id flows into collection), so ACP is the primary case.
• Environment (TRACEPARENT on the agent process): applied to the session's first turn, via the agent's hook. Use this when the caller cannot obtain a per-turn sessionId up front.

For Claude Code, enabling both upstream linking and propagateToTools also passes the first turn's context into main-agent Bash calls. Pilot's PreToolUse(Bash) hook reserves the TOOL span id, prepends TRACEPARENT (and valid TRACESTATE, when present) to the Bash command, then reuses that id when the Stop hook builds the TOOL span. The downstream CLI must read these environment variables and configure its own trace exporter. This initial scope is fail-open and does not cover subagents, PowerShell, MCP tools, later turns, or resumed sessions with a newly supplied context.

Output Data

LoongSuite Pilot emits a normalized GenAI event schema across all supported agents. See Output Event Schema for event names, field definitions, provider values, finish reasons, and sensitivity notes for opt-in content fields.

Operate Pilot

Use the loongsuite-pilot command after installation:

loongsuite-pilot start
loongsuite-pilot stop
loongsuite-pilot restart
loongsuite-pilot status
loongsuite-pilot info
loongsuite-pilot token-usage
loongsuite-pilot rollback

Optional local dashboard:

loongsuite-pilot monitor start

Then open http://127.0.0.1:8765/.

macOS menu bar app:

On macOS, Pilot automatically runs a menu bar app after installation — no extra command needed. It shows live token, session, request, and tool counts, plus per-agent and per-provider breakdowns, so you can keep an eye on activity without opening the dashboard.

To disable it, set LOONGSUITE_PILOT_ENABLE_STATUS_BAR_APP=false or add "enableStatusBarApp": false to ~/.loongsuite-pilot/config.json.

Documentation

User Manual - Complete guide to installing, configuring, operating, and extending Pilot

Installation Guide - Install from package, verify service, uninstall, and run from source

Configuration Reference - Global config loading, runtime switches, retention, and links to output and privacy setup

Output Schema - Normalized event names, fields, provider values, and finish reasons

Developer Guide - Add support for a new AI coding agent

Build From Source

git clone https://github.com/alibaba/loongsuite-pilot.git
cd loongsuite-pilot
npm install
npm run build
node scripts/postinstall.js
node dist/index.js

For local development:

npm install
npm run build
npm run typecheck
npm test

For packaging and service installation from a local build, see Installation.

Community

We are looking forward to your feedback and suggestions. Scan the QR code below to join the LoongSuite Pilot DingTalk group.

LoongSuite Pilot SIG

Related Projects

• LoongCollector - Universal node agent for log, metric and eBPF-based collection
• LoongSuite JS - OpenTelemetry instrumentation plugins for JS-based AI coding agents
• LoongSuite Python - Process agent for Python applications
• LoongSuite Go - Process agent for Golang with compile-time instrumentation
• LoongSuite Java - GenAI telemetry utility library for Java applications

License

Apache License 2.0 - see LICENSE for details.