prism — HarmonyOS HTTP Debugger

Chrome DevTools–style HTTP debugging for HarmonyOS/OpenHarmony devices.
Zero CA certificate · Process-level hook · Real-time waterfall · Request override

Architecture

prism uses a dual-backend architecture. The primary backend communicates directly with the device-side hiprofilerd daemon via gRPC — the same mechanism DevEco Studio uses. This hooks into the app process before TLS, so no CA certificate is needed. A secondary mitmproxy backend is available when real-time request modification (override) is required.

The server is written in Go for high-performance binary parsing, low memory footprint, and single-binary distribution with zero runtime dependencies.

┌──────────────────────────────┐     ┌──────────────────────────────┐
│  gRPC Backend (primary)      │     │  Proxy Backend (fallback)    │
│  hiprofilerd → hdc fport     │     │  mitmproxy subprocess        │
│  No CA cert needed           │     │  Requires CA cert for HTTPS  │
│  Supports: HTTP/HTTPS capture│     │  Supports: capture + override│
└──────────────┬───────────────┘     └──────────────┬───────────────┘
               └──────────┬─────────────────────────┘
                          ▼
               ┌─────────────────────┐
               │   Go Server (Gin)   │
               │   TLV Parser        │
               │   SQLite + SSE      │
               │   Embedded Web UI   │
               └─────────┬───────────┘
                         ▼
               ┌─────────────────────┐
               │   localhost:8900    │
               └─────────────────────┘

Features

No CA certificate required — hooks the process at the network layer before TLS, just like DevEco Studio
Full HTTP detail — request/response headers, body, timing breakdown (DNS → TCP → TLS → TTFB → Download)
Real-time waterfall — Chrome DevTools–style request list with timing bars
Device log viewer — live hilog streaming with level/tag/pid filtering, search, and download
Override engine — 7 rule types: block, redirect, header modify, response status, response body, response headers, latency simulation
HAR export — standard HTTP Archive format
Log export — download filtered logs as .log files with metadata headers
Dual-theme Web UI — React + Tailwind CSS, dark/light mode with localStorage persistence
Process picker — searchable debuggable-app list with full package names
MCP server — 12 AI-agent tools for autonomous debugging (Claude Code, Cursor, etc.)
Virtual scrolling — handles 10,000+ log entries and 1,000+ requests with zero performance degradation
Single binary — ~38MB server with embedded Web UI, no Python runtime needed

Quick Start

Prerequisites

Go 1.23+ (for building from source; pre-built binaries available)
hdc (HarmonyOS Device Connector) from DevEco Studio
A HarmonyOS / OpenHarmony device connected via USB or network
For proxy mode only: Python 3.10+ with mitmproxy (pip install mitmproxy)

Build

cd prism-hos-debugger

# Build all binaries
make build

# Or build individually
make server   # bin/prism-server (HTTP/SSE server + embedded Web UI)
make cli      # bin/prism (CLI entry point)
make mcp      # bin/prism-mcp (MCP server for AI agents)

To rebuild the Web UI (already embedded in the server binary):

cd webui && npm install && npm run build && cd ..
cp -r webui/dist/* cmd/server/webui_dist/
make server

Launch

Option A: CLI (recommended)

# List connected devices
./bin/prism list-devices

# Start the server + Web UI (auto-opens browser)
./bin/prism start

# Custom web port
./bin/prism start --web-port 9000

# Start without opening browser
./bin/prism start --no-open

Open http://localhost:8900, select a device, pick a target app, and click — HTTP requests appear in real time.


A native macOS window opens with the full Web UI embedded. The app runs in the Dock with a tray icon — close the window to minimize to tray, Quit from the tray menu to stop the backend.

To package as a standalone `.app`:

```bash
# Build Go backend
make build


# Build the macOS .app bundle
cd desktop && npm run build
# Output: desktop/dist/Prism-*.dmg

Log Viewer

Switch to the Logs tab for real-time device log streaming — the same capability as DevEco Studio's Log window, but lightweight and integrated with HTTP capture.

Live hilog streaming — hdc shell hilog via subprocess, parsed in real time
Level filtering — toggle Debug / Info / Warn / Error / Fatal with color-coded badges
Tag filter — dropdown populated from unique tags in the current log set
Search — full-text search across tag, message, and domain
Download — export filtered logs as .log files with metadata headers
Virtual scrolling — handles 10,000+ entries with smooth auto-scroll
Smart follow — auto-scroll tracks new entries unless you scroll away to inspect history

MCP Server (AI Agent Integration)

prism includes an MCP server with 12 tools that let AI agents (Claude Code, Cursor, etc.) operate the debugger without touching the GUI.

./bin/prism-mcp    # Start MCP server (stdio transport)

Control tools

Tool	Description
`list_devices`	List connected HarmonyOS devices
`select_device`	Select a device for capture
`list_debuggable_apps`	List debuggable apps with PID and package name
`start_http_capture`	Start HTTP capture on target app (gRPC or proxy)
`stop_http_capture`	Stop active HTTP capture
`start_log_capture`	Start hilog capture (pid/level/tag filters)
`stop_log_capture`	Stop active log capture

Inspection tools

Tool	Description
`get_capture_status`	HTTP capture running state and backend type
`list_requests`	Paginated HTTP request list with URL/method filters
`get_request`	Full request detail: headers, body, timing (DNS/TCP/TLS/TTFB)
`list_logs`	Device log entries with level/tag/pid/search filters
`get_recent_logs_summary`	Error/warn/info counts, unique tags, recent errors

Configuration

Add to your Claude config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "prism-hos-debugger": {
      "command": "/path/to/prism-mcp"
    }
  }
}

Or use the CLI wrapper:

{
  "mcpServers": {
    "prism-hos-debugger": {
      "command": "/path/to/prism",
      "args": ["mcp"]
    }
  }
}

A Claude Code skill is bundled in the repo. Install with npx skills add . to teach the AI a 7-step autonomous debugging workflow.

⚠️ CRITICAL: App Must Be Profilable

The target app's AppScope/app.json5 MUST include "profileable": true (HarmonyOS API 24+). Without it, the system blocks all performance analysis tools — including the network-profiler — from attaching to the process. Release-signed apps default to profileable: false.
// AppScope/app.json5
{
  "app": {
    "profileable": true   // ← REQUIRED
  }
}
If you see the profiler session created but zero HTTP events, this is the most common cause.

⚠️ Request Body Capture Limitation

The gRPC profiler cannot capture POST/PUT/PATCH request bodies when the app uses @kit.NetworkKit (the legacy @ohos.net.http API). This API does not expose request payloads to the profiler. Only @kit.RemoteCommunicationKit (RCP, API 12+) with TracingConfiguration.outgoingData: true supports full request body capture.

What IS captured regardless of HTTP library: request headers, response headers, response body, timing breakdown (DNS/TCP/TLS/TTFB), and status codes.

⚠️ Boot Order Note

The profiler hooks into the process at the moment you select it in the Web UI. New HTTP connections opened after selection are captured. Pre-existing connections (keepalive sockets, connection pools established before hooking) will not appear.

For best results: kill and restart the app before selecting it, so all connections are fresh.

Capture Modes

gRPC Mode (default, recommended)

Communicates with the on-device hiprofilerd daemon via gRPC over hdc fport. The network-profiler built-in plugin intercepts HTTP calls inside the target process. No proxy configuration, no CA certificate. Fully implemented in Go with native protobuf parsing.

sequenceDiagram
    Browser->>+Go Server: POST /api/capture/start {pid}
    Go Server->>+hdc: fport 50051→50051
    Go Server->>+hiprofilerd: CreateSession(network-profiler)
    hiprofilerd-->>-Go Server: session_id
    Go Server->>+hiprofilerd: StartSession / FetchData(stream)
    loop HTTP events
        hiprofilerd-->>Go Server: ProfilerPluginData (ProtoEncoder)
        Note over Go Server: TLV binary parser (Go)
    end
    Go Server-->>Browser: SSE request stream

Proxy Mode (with overrides)

Uses mitmproxy as a subprocess for HTTP forward proxying. The Go server spawns prism_proxy_addon.py which captures flows and streams JSON lines back. Supports real-time request/response overrides, but requires CA certificate installation on the device for HTTPS interception.

Requires: pip install mitmproxy and scripts/prism_proxy_addon.py accessible from the working directory.

Override Rules

Rule	Description	Example
`block`	Drop the request	Block all `.doubleclick.net/`
`url_redirect`	Rewrite the target URL	Redirect `/v1/api` → `/v2/api`
`header_modify`	Add/remove request headers	Inject `X-Debug: 1`
`response_status`	Change HTTP status code	Return 404 for matched URLs
`response_body`	Replace response body	Return mock JSON
`response_headers`	Add/remove response headers	Strip `x-powered-by`
`latency`	Inject artificial delay	Add 500ms to simulate slow network

Rules support glob, regex, prefix, and exact URL matching with optional HTTP method filtering. Changes take effect immediately — no restart needed.

API

All endpoints are served at http://localhost:8900.

Endpoint	Description
`GET /api/health`	Health check
`GET /api/devices`	List connected devices
`POST /api/devices/select`	Select active device
`GET /api/capture/status`	Capture status (backend, running)
`GET /api/capture/apps`	List debuggable apps on device
`POST /api/capture/start`	Start capture (`{mode:"grpc"\|"proxy", pid, port}`)
`POST /api/capture/stop`	Stop active capture
`GET /api/requests`	Paginated request log
`GET /api/requests/stream`	SSE real-time request feed
`GET /api/requests/:id`	Single request detail
`DELETE /api/requests`	Clear all requests
`POST /api/requests/resend`	Resend request with modifications
`GET /api/rules`	List override rules
`POST /api/rules`	Create override rule
`PUT /api/rules/:id`	Update override rule
`DELETE /api/rules/:id`	Delete override rule
`PATCH /api/rules/:id/toggle`	Toggle rule on/off
`POST /api/rules/preview`	Preview rule matches
`GET /api/logs/status`	Log capture status
`POST /api/logs/start`	Start log capture
`POST /api/logs/stop`	Stop log capture
`GET /api/logs/stream`	SSE real-time log feed
`GET /api/logs/query`	Query log entries with filters

Project Structure

prism-hos-debugger/
├── cmd/                        # Go entry points
│   ├── server/main.go          #   HTTP/SSE server (Gin) + embedded Web UI
│   ├── prism/main.go           #   CLI (cobra)
│   └── mcp/main.go             #   MCP server (12 tools, stdio)
├── pkg/                        # Go packages
│   ├── capture/                #   gRPC client + proxy backend
│   ├── parser/                 #   TLV binary payload parser
│   ├── device/                 #   hdc CLI wrapper
│   ├── storage/                #   SQLite persistence (WAL)
│   ├── override/               #   Override rule matching engine
│   ├── log/                    #   hilog streaming parser
│   └── models/                 #   Shared data types
├── internal/sse/               # SSE event broker
├── prism/                      # Python backend (legacy, kept as reference)
│   ├── proto/                  #   Compiled protobuf stubs (_pb2.py)
│   └── ...                     #   Original Python implementation
├── prism/proto_src/            # Proto source files (from DevEco Studio)
├── prism/proto_go/             # Generated Go protobuf/gRPC code
├── scripts/
│   ├── prism_proxy_addon.py    #   mitmproxy ↔ Go bridge addon
│   └── generate-go-proto.sh   #   Proto regeneration script
├── webui/                      # React frontend (Vite + Tailwind)
├── desktop-tauri/              # Tauri desktop wrapper (experimental)
├── tests/                      # Python tests (legacy)
├── Makefile                    # Build commands
├── go.mod / go.sum             # Go module definition
└── README.md

Development

# Rebuild everything
make build

# Run tests
make test

# Regenerate Go protobuf code from .proto sources
make proto

# Format code
make fmt

# Build Web UI and re-embed into server
cd webui && npm run build && cd ..
cp -r webui/dist/* cmd/server/webui_dist/
make server

License

MIT

Navigation Menu

Repository files navigation

prism — HarmonyOS HTTP Debugger

Architecture

Features

Quick Start

Prerequisites

Build

Launch

Log Viewer

MCP Server (AI Agent Integration)

Control tools

Inspection tools

Configuration

Capture Modes

gRPC Mode (default, recommended)

Proxy Mode (with overrides)

Override Rules

API

Project Structure

Development

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
cmd		cmd
desktop-tauri		desktop-tauri
internal/sse		internal/sse
pkg		pkg
prism		prism
screenshots		screenshots
scripts		scripts
skills/prism-debugger		skills/prism-debugger
tests		tests
webui		webui
.gitignore		.gitignore
.mcp.json		.mcp.json
Makefile		Makefile
README.md		README.md
README.zh.md		README.zh.md
go.mod		go.mod
go.sum		go.sum
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

prism — HarmonyOS HTTP Debugger

Architecture

Features

Quick Start

Prerequisites

Build

Launch

Log Viewer

MCP Server (AI Agent Integration)

Control tools

Inspection tools

Configuration

Capture Modes

gRPC Mode (default, recommended)

Proxy Mode (with overrides)

Override Rules

API

Project Structure

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages