GeezerVison

binder

Call Android system services from pure Go. Provides ~14,000 type-safe Go methods across 1,500+ Android interfaces — ActivityManager, PowerManager, SurfaceFlinger, PackageManager, audio, camera and sensor HALs, and more — by speaking the Binder IPC wire protocol directly via /dev/binder ioctl syscalls. No Java, no NDK, no cgo required.

Includes a complete AIDL compiler that parses Android Interface Definition Language files and generates the Go proxies, a version-aware runtime that adapts transaction codes across Android API levels, and a CLI tool (bindercli) for interactive service discovery and invocation.

What can it do?

• Query system services — battery level, GPS location, thermal status, running processes, installed packages
• Control hardware — connect to WiFi, toggle flashlight, manage Bluetooth, configure audio
• Interact with any binder service — ActivityManager, PowerManager, SurfaceFlinger, camera/sensor HALs, and more
• No Java, no cgo — pure Go, cross-compiles to a static binary, runs on Android or any Linux with /dev/binder
• CLI tool included — bindercli for interactive service discovery, method invocation, and debugging

Quick start

Go library — go get github.com/AndroidGoLab/binder — live GPS location via binder IPC:

package main

import (
    "context"
    "fmt"
    "math"
    "os"
    "time"

    "github.com/AndroidGoLab/binder/android/location"
    androidos "github.com/AndroidGoLab/binder/android/os"
    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/binder/versionaware"
    "github.com/AndroidGoLab/binder/kernelbinder"
    "github.com/AndroidGoLab/binder/servicemanager"
)

// gpsListener receives location callbacks from the LocationManager.
type gpsListener struct{ fixCh chan location.Location }

func (l *gpsListener) OnLocationChanged(_ context.Context, locs []location.Location, _ androidos.IRemoteCallback) error {
    for _, loc := range locs { select { case l.fixCh <- loc: default: } }
    return nil
}
func (l *gpsListener) OnProviderEnabledChanged(_ context.Context, _ string, _ bool) error { return nil }
func (l *gpsListener) OnFlushComplete(_ context.Context, _ int32) error                   { return nil }

func main() {
    ctx := context.Background()
    drv, _ := kernelbinder.Open(ctx, binder.WithMapSize(128*1024))
    defer drv.Close(ctx)
    transport, _ := versionaware.NewTransport(ctx, drv, 0)
    sm := servicemanager.New(transport)

    lm, _ := location.GetLocationManager(ctx, sm)

    impl := &gpsListener{fixCh: make(chan location.Location, 1)}
    listener := location.NewLocationListenerStub(impl)

    request := location.LocationRequest{
        Provider: location.GpsProvider, IntervalMillis: 1000,
        ExpireAtRealtimeMillis: math.MaxInt64, DurationMillis: math.MaxInt64,
    }
    pkg := binder.DefaultCallerIdentity().PackageName
    _ = lm.RegisterLocationListener(ctx, location.GpsProvider, request, listener, pkg, "gps")
    defer lm.UnregisterLocationListener(ctx, listener)

    select {
    case loc := <-impl.fixCh:
        fmt.Printf("Lat: %.6f  Lon: %.6f  Alt: %.1f m  Accuracy: %.1f m\n",
            loc.LatitudeDegrees, loc.LongitudeDegrees, loc.AltitudeMeters, loc.HorizontalAccuracyMeters)
    case <-time.After(30 * time.Second):
        fmt.Fprintln(os.Stderr, "timed out")
    }
}

Full runnable example: examples/gps_location/

Or query power state:

power, _ := os.GetPowerManager(ctx, sm)
interactive, _ := power.IsInteractive(ctx)
fmt.Printf("Screen on: %v\n", interactive)

Related Projects

graph TD
    subgraph "Go application"
        GO["Go code"]
    end

    subgraph "Interface libraries"
        NDK["<b>ndk</b><br/>C API bindings via cgo"]
        JNI["<b>jni</b><br/>Java API bindings via JNI+cgo"]
        AIDL["<b>binder</b><br/>Binder IPC, pure Go"]
    end

    subgraph "Android platform"
        CAPI["NDK C libraries<br/>(libcamera2ndk, libaaudio,<br/>libEGL, libvulkan, ...)"]
        JAVA["Java SDK<br/>(android.bluetooth,<br/>android.location, ...)"]
        BINDER["/dev/binder<br/>kernel driver"]
        SYSSVCS["System services<br/>(ActivityManager,<br/>PowerManager, ...)"]
    end

    GO --> NDK
    GO --> JNI
    GO --> AIDL

    NDK -- "cgo / #include" --> CAPI
    JNI -- "cgo / JNIEnv*" --> JAVA
    AIDL -- "ioctl syscalls" --> BINDER
    BINDER --> SYSSVCS
    JAVA -. "internally uses" .-> BINDER
    CAPI -. "some use" .-> BINDER

Usage Examples

Get GPS Location

import (
    "context"
    "fmt"
    "log"

    "github.com/AndroidGoLab/binder/android/location"
    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/binder/versionaware"
    "github.com/AndroidGoLab/binder/kernelbinder"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    ctx := context.Background()

    driver, err := kernelbinder.Open(ctx, binder.WithMapSize(128*1024))
    if err != nil {
        log.Fatal(err)
    }
    defer driver.Close(ctx)

    transport, err := versionaware.NewTransport(ctx, driver, 0)
    if err != nil {
        log.Fatal(err)
    }
    sm := servicemanager.New(transport)

    lm, err := location.GetLocationManager(ctx, sm)
    if err != nil {
        log.Fatal(err)
    }

    loc, err := lm.GetLastLocation(ctx, location.FusedProvider, location.LastLocationRequest{}, binder.DefaultCallerIdentity().PackageName)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Lat: %f, Lon: %f, Alt: %f\n",
        loc.LatitudeDegrees, loc.LongitudeDegrees, loc.AltitudeMeters)
    fmt.Printf("Speed: %f m/s, Bearing: %f°\n",
        loc.SpeedMetersPerSecond, loc.BearingDegrees)

Check Power State

import (
    "context"
    "fmt"
    "log"

    genOs "github.com/AndroidGoLab/binder/android/os"
    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/binder/versionaware"
    "github.com/AndroidGoLab/binder/kernelbinder"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    ctx := context.Background()

    driver, err := kernelbinder.Open(ctx, binder.WithMapSize(128*1024))
    if err != nil {
        log.Fatal(err)
    }
    defer driver.Close(ctx)

    transport, err := versionaware.NewTransport(ctx, driver, 0)
    if err != nil {
        log.Fatal(err)
    }
    sm := servicemanager.New(transport)

    power, err := genOs.GetPowerManager(ctx, sm)
    if err != nil {
        log.Fatal(err)
    }

    interactive, _ := power.IsInteractive(ctx)
    fmt.Printf("Screen on: %v\n", interactive)

    powerSave, _ := power.IsPowerSaveMode(ctx)
    fmt.Printf("Power save: %v\n", powerSave)

List Binder Services

    sm := servicemanager.New(transport)

    services, err := sm.ListServices(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, name := range services {
        svc, err := sm.CheckService(ctx, name)
        if err == nil && svc != nil && svc.IsAlive(ctx) {
            fmt.Printf("%-60s alive\n", name)
        }
    }

Call a System Service (ActivityManager)

import (
    "github.com/AndroidGoLab/binder/android/app"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    svc, err := sm.GetService(ctx, servicemanager.ActivityService)
    if err != nil {
        log.Fatal(err)
    }
    am := app.NewActivityManagerProxy(svc)

    limit, _ := am.GetProcessLimit(ctx)
    fmt.Printf("Process limit: %d\n", limit)

    monkey, _ := am.IsUserAMonkey(ctx)
    fmt.Printf("Is monkey: %v\n", monkey)

Toggle Flashlight

Requires android.permission.CAMERA; see examples/flashlight_torch/ for the full runnable example with permission handling.

import (
    "context"

    "github.com/AndroidGoLab/binder/android/hardware"
    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/parcel"
    "github.com/AndroidGoLab/binder/servicemanager"
)

// torchToken is a minimal TransactionReceiver for SetTorchMode's client binder.
type torchToken struct{}

func (t *torchToken) Descriptor() string { return "torch.client" }

func (t *torchToken) OnTransaction(
    _ context.Context,
    _ binder.TransactionCode,
    _ *parcel.Parcel,
) (*parcel.Parcel, error) {
    return parcel.New(), nil
}

    svc, err := sm.GetService(ctx, servicemanager.MediaCameraService)
    if err != nil {
        log.Fatal(err)
    }
    camera := hardware.NewCameraServiceProxy(svc)

    // The camera service requires a non-null client binder token.
    clientToken := binder.NewStubBinder(&torchToken{})
    clientToken.RegisterWithTransport(ctx, transport)

    // Turn torch on for camera "0"
    if err := camera.SetTorchMode(ctx, "0", true, clientToken); err != nil {
        log.Fatal(err)
    }
    fmt.Println("Torch ON")

    // Turn torch off
    _ = camera.SetTorchMode(ctx, "0", false, clientToken)

List All Installed Packages

import (
    "github.com/AndroidGoLab/binder/android/content/pm"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    svc, err := sm.GetService(ctx, servicemanager.PackageService)
    if err != nil {
        log.Fatal(err)
    }
    pkgMgr := pm.NewPackageManagerProxy(svc)

    packages, err := pkgMgr.GetAllPackages(ctx)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d packages:\n", len(packages))
    for _, pkg := range packages {
        fmt.Println(" ", pkg)
    }

Handle Errors Gracefully

import (
    "errors"
    aidlerrors "github.com/AndroidGoLab/binder/errors"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    // Non-blocking service check (returns nil if not found)
    svc, err := sm.CheckService(ctx, servicemanager.MediaCameraService)
    if err != nil {
        log.Fatal(err)
    }
    if svc == nil {
        fmt.Println("Camera service not available")
        return
    }

    // Typed error inspection
    _, err = someProxy.SomeMethod(ctx)
    var status *aidlerrors.StatusError
    if errors.As(err, &status) {
        switch status.Exception {
        case aidlerrors.ExceptionSecurity:
            fmt.Printf("Permission denied: %s\n", status.Message)
        case aidlerrors.ExceptionServiceSpecific:
            fmt.Printf("Service error %d: %s\n", status.ServiceSpecificCode, status.Message)
        default:
            fmt.Printf("AIDL error: %v\n", status)
        }
    }

Query Battery Level

import (
    "github.com/AndroidGoLab/binder/android/hardware/health"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    svc, err := sm.GetService(ctx, servicemanager.ServiceName(health.DescriptorIHealth+"/default"))
    if err != nil {
        log.Fatal(err)
    }
    h := health.NewHealthProxy(svc)

    capacity, err := h.GetCapacity(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Battery level: %d%%\n", capacity)

    info, err := h.GetHealthInfo(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Status: %v, Temperature: %.1f °C\n",
        info.BatteryStatus, float64(info.BatteryTemperatureTenthsCelsius)/10)
    fmt.Printf("Voltage: %d mV, Current: %d µA\n",
        info.BatteryVoltageMillivolts, info.BatteryCurrentMicroamps)

Send a Raw Binder Transaction

import (
    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/parcel"
    "github.com/AndroidGoLab/binder/servicemanager"
)

    svc, err := sm.GetService(ctx, servicemanager.ActivityService)
    if err != nil {
        log.Fatal(err)
    }

    // Build the request parcel.
    data := parcel.New()
    defer data.Recycle()
    data.WriteInterfaceToken("android.app.IActivityManager")
    data.WriteString16("android.permission.INTERNET")
    data.WriteInt32(int32(os.Getpid()))
    data.WriteInt32(int32(os.Getuid()))

    // Resolve the method's transaction code and send.
    code, err := svc.ResolveCode(ctx, "android.app.IActivityManager", "checkPermission")
    if err != nil {
        log.Fatal(err)
    }
    reply, err := svc.Transact(ctx, code, 0, data)
    if err != nil {
        log.Fatal(err)
    }
    defer reply.Recycle()

    // Read the AIDL status header, then the return value.
    if err := binder.ReadStatus(reply); err != nil {
        log.Fatal(err)
    }
    result, _ := reply.ReadInt32()
    fmt.Printf("checkPermission returned: %d\n", result)

Register a Server-Side Service

import (
    "context"

    "github.com/AndroidGoLab/binder/binder"
    "github.com/AndroidGoLab/binder/parcel"
    "github.com/AndroidGoLab/binder/servicemanager"
)

// myService implements binder.TransactionReceiver for a simple ping service.
type myService struct{}

func (s *myService) Descriptor() string { return "com.example.IPingService" }

func (s *myService) OnTransaction(
    ctx context.Context,
    code binder.TransactionCode,
    data *parcel.Parcel,
) (*parcel.Parcel, error) {
    reply := parcel.New()
    binder.WriteStatus(reply, nil)
    reply.WriteString16("pong")
    return reply, nil
}

    // Register with ServiceManager
    err := sm.AddService(ctx, servicemanager.ServiceName("my.service"), &myService{}, false, 0)

# Find the proxy for a known AIDL interface
grep -r 'DescriptorI.*= "android.hardware.vibrator.IVibrator"' android/

    svc, err := sm.GetService(ctx, servicemanager.ServiceName(
        vibrator.DescriptorIVibrator+"/default"))
    if err != nil {
        log.Fatal(err)
    }
    proxy := vibrator.NewVibratorProxy(svc)
    caps, err := proxy.GetCapabilities(ctx)

    svc, err := sm.GetService(ctx, servicemanager.ServiceName(health.DescriptorIHealth+"/default"))

More examples: examples/

bindercli Quick Start

bindercli lets you call any Android system service from the command line — no Go code needed.

Install and deploy:

GOOS=linux GOARCH=arm64 go build -o build/bindercli ./cmd/bindercli/
adb push build/bindercli /data/local/tmp/

Try it:

# List all binder services
adb shell /data/local/tmp/bindercli service list

# Check battery level
adb shell /data/local/tmp/bindercli android.hardware.health.IHealth get-health-info

# Query ActivityManager
adb shell /data/local/tmp/bindercli android.app.IActivityManager get-process-limit

# Get GPS hardware info
adb shell /data/local/tmp/bindercli android.location.ILocationManager get-gnss-hardware-model-name

See the full bindercli reference for all subcommands and more examples.

Packages

	Package	Description	Import Path
AIDL Pipeline (tools/pkg/)
	tools/pkg/parser	Lexer and recursive-descent parser producing an AST from .aidl files	github.com/AndroidGoLab/binder/tools/pkg/parser
	tools/pkg/resolver	Import resolution across search paths with type registry and circular-import detection	github.com/AndroidGoLab/binder/tools/pkg/resolver
	tools/pkg/codegen	Go code generator for proxies, parcelables, enums, unions, and constants	github.com/AndroidGoLab/binder/tools/pkg/codegen
	tools/pkg/validate	Semantic validation: type resolution, parameter directions, oneway constraints	github.com/AndroidGoLab/binder/tools/pkg/validate
Runtime
	binder	Binder IPC abstractions: IBinder interface, Transact(), status/exception handling	github.com/AndroidGoLab/binder/binder
	parcel	Binder wire format: 4-byte aligned, little-endian serialization	github.com/AndroidGoLab/binder/parcel
	kernelbinder	Linux /dev/binder driver: open, mmap, ioctl, protocol negotiation	github.com/AndroidGoLab/binder/kernelbinder
	servicemanager	Client for android.os.IServiceManager: GetService(), ListServices(), etc.	github.com/AndroidGoLab/binder/servicemanager
	errors	AIDL exception types: ExceptionCode, StatusError	github.com/AndroidGoLab/binder/errors
Testing
	tools/pkg/testutil	Mock binder and reflection-based smoke testing for generated proxies	github.com/AndroidGoLab/binder/tools/pkg/testutil

Generated AOSP Packages

385 packages: 1513 interfaces, 2370 parcelables, 957 enums, 133 unions.

Commands and Tools

bindercli

bindercli is a unified command-line tool for interacting with Android Binder services and the AIDL compiler. It auto-generates subcommands for every AIDL interface in the project (1,500+ interfaces, 14,000+ methods), so you can call any Android system service method directly from the command line with typed flags.

Build and deploy:

GOOS=linux GOARCH=arm64 go build -o build/bindercli ./cmd/bindercli/
adb push build/bindercli /data/local/tmp/

Core subcommands:

Global flags: --format json|text|auto, --binder-device, --map-size.

Examples

Note: Transaction codes are resolved dynamically from the device's framework JARs (/system/framework/*.jar) at runtime. Compiled version tables are used as a fallback when JARs are not readable. The service subcommands and ServiceManager-level lookups work across all versions.

# List all registered binder services with alive/dead status
bindercli service list

# Inspect a specific service (show handle, descriptor, alive status)
bindercli service inspect SurfaceFlinger

# List methods available on a service with transaction codes
bindercli service methods activity

# Resolve a method name to its transaction code (or vice versa)
bindercli service resolve activity is-user-a-monkey

# Send a raw binder transaction by method name or numeric code
bindercli service transact activity is-user-a-monkey
bindercli service transact SurfaceFlinger 64

# Check if screen is on
bindercli android.os.IPowerManager is-interactive
# Example output: {"result":true}

# Check power save mode
bindercli android.os.IPowerManager is-power-save-mode
# Example output: {"result":false}

# Check if device is in Doze mode
bindercli android.os.IPowerManager is-device-idle-mode
# Example output: {"result":false}

# Get battery health info
bindercli android.hardware.health.IHealth get-health-info

# Step 1: Add a new network via the supplicant
bindercli android.hardware.wifi.supplicant.ISupplicantStaIface add-network

# Step 2: Set the SSID (pass as hex-encoded bytes; "MyNetwork" = 4d794e6574776f726b)
bindercli android.hardware.wifi.supplicant.ISupplicantStaNetwork set-ssid \
  --ssid 4d794e6574776f726b

# Step 3: Set the WPA passphrase
bindercli android.hardware.wifi.supplicant.ISupplicantStaNetwork set-psk-passphrase \
  --psk secret123

# Step 4: Set key management to WPA-PSK (bit 1 = 0x02)
bindercli android.hardware.wifi.supplicant.ISupplicantStaNetwork set-key-mgmt \
  --keyMgmtMask 2

# Step 5: Enable the network to trigger connection
bindercli android.hardware.wifi.supplicant.ISupplicantStaNetwork enable \
  --noConnect false

# Disconnect from current network
bindercli android.hardware.wifi.supplicant.ISupplicantStaIface disconnect

# List saved networks
bindercli android.hardware.wifi.supplicant.ISupplicantStaIface list-networks

# List available camera devices
bindercli android.hardware.camera.provider.ICameraProvider get-camera-id-list

# Get camera characteristics (resolution, capabilities, etc.)
bindercli android.hardware.camera.device.ICameraDevice get-camera-characteristics

# Toggle flashlight/torch mode
bindercli android.hardware.camera.provider.ICameraProvider set-torch-mode \
  --cameraDeviceName "0" --enabled true

# Get active microphones on an input stream
bindercli android.hardware.audio.core.IStreamIn get-active-microphones

# Set microphone field dimension (for directional recording)
bindercli android.hardware.audio.core.IStreamIn set-microphone-field-dimension \
  --zoom 1.0

# Set microphone direction
# 0=UNSPECIFIED, 1=FRONT, 2=BACK, 3=EXTERNAL
bindercli android.hardware.audio.core.IStreamIn set-microphone-direction \
  --direction 1

# Get current thermal status (0=none, 1=light, 2=moderate, ...)
bindercli android.os.IThermalService get-current-thermal-status
# Example output: {"result":0}

# Check if device is in power save mode
bindercli android.os.IPowerManager is-power-save-mode
# Example output: {"result":false}

# Check if device is interactive (screen on)
bindercli android.os.IPowerManager is-interactive

# Reboot the device
bindercli android.os.IPowerManager reboot \
  --confirm false --reason "cli-reboot" --wait true

# Check if a package is installed
bindercli android.content.pm.IPackageManager is-package-available \
  --packageName com.android.settings --userId 0
# Example output: {"result":true}

# Check a permission
bindercli android.content.pm.IPackageManager check-permission \
  --permName android.permission.INTERNET \
  --pkgName com.android.settings --userId 0

# Get the installer of a package
bindercli android.content.pm.IPackageManager get-installer-package-name \
  --packageName com.android.chrome

# Get display IDs
bindercli android.hardware.display.IDisplayManager get-display-ids \
  --includeDisabled false
# Example output: {"result":[0]}

# Check if clipboard has text
bindercli android.content.IClipboard has-clipboard-text \
  --callingPackage com.android.shell \
  --attributionTag "" --userId 0 --deviceId 0
# Example output: {"result":false}

# Initialize Bluetooth HCI
bindercli android.hardware.bluetooth.IBluetoothHci initialize \
  --callback <callback_service>

# Send raw HCI command (hex bytes)
bindercli android.hardware.bluetooth.IBluetoothHci send-hci-command \
  --command 01030c00

# Close Bluetooth HCI
bindercli android.hardware.bluetooth.IBluetoothHci close

# Check if user is a monkey (automated test)
bindercli android.app.IActivityManager is-user-a-monkey

# Get process memory limit
bindercli android.app.IActivityManager get-process-limit

# Check a permission for a process
bindercli android.app.IActivityManager check-permission \
  --permission android.permission.INTERNET --pid 1 --uid 0

# Force stop a package
bindercli android.app.IActivityManager force-stop-package \
  --packageName com.example.app --userId 0

# Check if app freezer is supported
bindercli android.app.IActivityManager is-app-freezer-supported

# Get active phone type (0=NONE, 1=GSM, 2=CDMA)
bindercli com.android.internal.telephony.ITelephony get-active-phone-type

# Get network country ISO
bindercli com.android.internal.telephony.ITelephony get-network-country-iso-for-phone \
  --phoneId 0

Verified Devices

Commands are tested against the following devices. The runtime uses version-aware transaction code resolution (binder/versionaware) that dynamically extracts codes from the device's framework JARs, with compiled tables as a fallback. "SM" = ServiceManager-level lookup, "Proxy" = generated proxy method with version-aware code resolution.

Architecture

The project has two major parts: a compiler that turns .aidl files into Go source code, and a runtime that implements the Binder IPC protocol for communicating with Android services.

flowchart TD
    AIDL[".aidl files"]
    AOSP["AOSP tools/pkg/3rdparty/"]

    subgraph COMPILER["Compiler Pipeline"]
        direction TB
        LEX["Lexer<br/><i>tokenizes AIDL syntax</i>"]
        PARSE["Parser<br/><i>recursive-descent → AST</i>"]
        RESOLVE["Resolver<br/><i>import resolution + type registry</i>"]
        GRAPH["Import Graph<br/><i>SCC-based cycle detection</i>"]
        GEN["Code Generator"]
    end

    subgraph GENOUT["Generated Output"]
        direction LR
        PROXY["Interface → Proxy struct<br/>+ transaction methods"]
        PARCEL_GEN["Parcelable → Go struct<br/>+ Marshal/Unmarshal"]
        ENUM["Enum → typed constants"]
        UNION["Union → tagged variant"]
    end

    subgraph RUNTIME["Binder Runtime"]
        direction TB
        KBIND["kernelbinder<br/><i>/dev/binder ioctl</i>"]
        PARCELF["parcel<br/><i>wire format serialization</i>"]
        BIND["binder<br/><i>IBinder + Transact</i>"]
        SM["servicemanager<br/><i>GetService / ListServices</i>"]
    end

    ANDROID["Android System Services<br/><i>ActivityManager, SurfaceFlinger, ...</i>"]

    AIDL --> LEX
    AOSP --> LEX
    LEX --> PARSE
    PARSE --> RESOLVE
    RESOLVE --> GRAPH
    GRAPH --> GEN
    GEN --> GENOUT

    PROXY --> BIND
    BIND --> PARCELF
    BIND --> KBIND
    SM --> BIND
    KBIND --> ANDROID

    style AIDL fill:#fff3cd,color:#000
    style AOSP fill:#fff3cd,color:#000
    style COMPILER fill:#e8eaf6,color:#000
    style GENOUT fill:#d4edda,color:#000
    style RUNTIME fill:#cce5ff,color:#000
    style ANDROID fill:#e0e0e0,color:#000

Compiler Pipeline

The compiler transforms AIDL source files into Go code through four stages:

flowchart LR
    subgraph S1["1. Lex"]
        L1["Keywords, identifiers,<br/>operators, literals"]
    end

    subgraph S2["2. Parse"]
        P1["Document AST:<br/>interfaces, parcelables,<br/>enums, unions, constants"]
    end

    subgraph S3["3. Resolve"]
        R1["Transitive imports<br/>Type registry<br/>Circular import detection"]
    end

    subgraph S4["4. Generate"]
        G1["Go source files:<br/>proxies, structs,<br/>marshal/unmarshal"]
    end

    S1 --> S2 --> S3 --> S4

Stage 1 — Lexer (tools/pkg/parser/lexer.go): Tokenizes AIDL source into keywords (interface, parcelable, oneway, ...), identifiers, operators, and literals. Handles >> splitting for nested generics like List<List<String>>.

Stage 2 — Parser (tools/pkg/parser/parser.go): Recursive-descent parser builds a typed AST. Supports the full AIDL grammar: interfaces with methods and transaction codes, parcelables with typed fields and defaults, enums with explicit or implicit values, unions, nested types, generics (List<T>, Map<K,V>), annotations (@nullable, @Backing, @utf8InCpp), and constant expressions with arithmetic/bitwise operators.

Stage 3 — Resolver (tools/pkg/resolver/resolver.go): Given search paths (-I flags), resolves AIDL imports transitively. Converts qualified names like android.os.IServiceManager to file paths, parses each imported file, and registers all definitions in a shared TypeRegistry. Detects circular imports. Supports skip-unresolved mode for bulk AOSP processing where some imports reference unavailable files.

Stage 4 — Code Generator (tools/pkg/codegen/): Produces Go source for each AIDL definition:

The code generator includes an import graph (tools/pkg/codegen/import_graph.go) that computes strongly-connected components (Tarjan's SCC algorithm) to detect and break import cycles between generated packages.

Binder Runtime

The runtime implements the Android Binder IPC protocol in pure Go:

flowchart TD
    subgraph APP["Your Go Application"]
        PROXY2["ActivityManagerProxy.GetProcessLimit(ctx)"]
    end

    subgraph MARSHAL["parcel"]
        M1["WriteInterfaceToken(descriptor)"]
        M2["WriteInt32 / WriteString16 / ..."]
        M3["ReadInt32 / ReadString16 / ..."]
    end

    subgraph BINDER["binder"]
        B1["IBinder.Transact(ctx, code, flags, data)"]
        B2["ReadStatus(reply) → check AIDL exceptions"]
    end

    subgraph KERNEL["kernelbinder"]
        K1["open(/dev/binder)"]
        K2["mmap(1MB read buffer)"]
        K3["ioctl(BINDER_WRITE_READ)"]
    end

    PROXY2 --> M1
    M1 --> M2
    M2 --> B1
    B1 --> K3
    K3 -->|reply| B2
    B2 --> M3
    M3 -->|typed result| PROXY2

kernelbinder.Driver: Opens /dev/binder, verifies the protocol version via ioctl, memory-maps the kernel buffer, and implements Transact() as a write-read ioctl. Handles transaction replies, error codes, and death notifications.

parcel.Parcel: 4-byte aligned, little-endian byte buffer implementing the Binder wire format. Writes/reads all AIDL primitive types (int32, int64, float, double, bool, byte, String as UTF-16), arrays, binder handles (flat_binder_object), and file descriptors.

binder.ProxyBinder: Client-side handle wrapping a kernel binder reference. Provides Transact(), IsAlive() (ping), and death notification registration (LinkToDeath/UnlinkToDeath).

servicemanager: Client for Android's ServiceManager, the registry of all system services. Implements GetService(), CheckService(), ListServices(), and AddService() as typed binder transactions.

Generated Code

For an AIDL interface like:

// android/app/IActivityManager.aidl
package android.app;

interface IActivityManager {
    int getProcessLimit();
    int checkPermission(in String permission, int pid, int uid);
    boolean isUserAMonkey();
    // ... 200+ more methods
}

The compiler generates:

package app

const DescriptorIActivityManager = "android.app.IActivityManager"

const (
    TransactionIActivityManagerGetProcessLimit  = binder.FirstCallTransaction + 51
    TransactionIActivityManagerCheckPermission  = binder.FirstCallTransaction + 8
    // ...
)

const (
    MethodIActivityManagerGetProcessLimit  = "getProcessLimit"
    MethodIActivityManagerCheckPermission  = "checkPermission"
    // ...
)

type IActivityManager interface {
    GetProcessLimit(ctx context.Context) (int32, error)
    CheckPermission(ctx context.Context, permission string, pid int32, uid int32) (int32, error)
    IsUserAMonkey(ctx context.Context) (bool, error)
    // ...
}

type ActivityManagerProxy struct {
    Remote binder.IBinder
}

func NewActivityManagerProxy(remote binder.IBinder) *ActivityManagerProxy {
    return &ActivityManagerProxy{Remote: remote}
}

func (p *ActivityManagerProxy) GetProcessLimit(ctx context.Context) (int32, error) {
    var _result int32
    _data := parcel.New()
    defer _data.Recycle()
    _data.WriteInterfaceToken(DescriptorIActivityManager)

    _code, _err := p.Remote.ResolveCode(ctx, DescriptorIActivityManager, MethodIActivityManagerGetProcessLimit)
    if _err != nil {
        return _result, fmt.Errorf("resolving %s.%s: %w", DescriptorIActivityManager, MethodIActivityManagerGetProcessLimit, _err)
    }

    _reply, _err := p.Remote.Transact(ctx, _code, 0, _data)
    if _err != nil {
        return _result, _err
    }
    defer _reply.Recycle()

    if _err = binder.ReadStatus(_reply); _err != nil {
        return _result, _err
    }

    _result, _err = _reply.ReadInt32()
    if _err != nil {
        return _result, _err
    }
    return _result, nil
}

Supported AIDL Constructs

Code Generation

From Individual AIDL Files

# Compile AIDL files to Go via bindercli:
bindercli aidl compile -I path/to/search/root --output gen file1.aidl file2.aidl

From AOSP (Bulk Generation)

With the AOSP submodules in tools/pkg/3rdparty/:

git submodule update --init --depth 1
go run ./tools/cmd/aidl2spec -3rdparty tools/pkg/3rdparty -output specs/
go run ./tools/cmd/spec2go -specs specs/ -output . -smoke-tests

This discovers all AIDL files across frameworks-base, frameworks-native, hardware-interfaces, and system-hardware-interfaces, infers search roots from package declarations, and generates Go proxies for all AOSP services. The current AOSP snapshot produces 5,174 Go files across 407 packages.

Transaction Code Resolution

Each binder method has a numeric transaction code that can differ between Android versions. The generated proxies call ResolveCode() at runtime to get the correct code for the device, using a multi-layer detection strategy:

1. DEX bytecode extraction (primary) — scans /system/framework/*.jar and APEX module JARs, parses DEX bytecode, and reads TRANSACTION_* constants from $Stub classes. Individual interfaces are extracted on demand (lazy), and results are cached to avoid re-scanning. This gives definitive codes for the exact firmware running on the device. This method is expected to work on all Android devices. If it fails on your platform, please open an issue.

2. Compiled version tables + ELF filtering (fallback) — pre-compiled tables from AOSP revision tags, narrowed by API level and exported symbols in libbinder.so. Used when framework JARs are not readable (e.g. non-Android host, restricted SELinux context).

3. Live transaction probing (last resort) — sends a test transaction (isUserAMonkey() on ActivityManager) with each candidate code and picks the one that returns a valid response. Used only to distinguish between AOSP revisions when ELF inspection is ambiguous.

Methods 2 and 3 exist only for environments where framework JARs are unavailable. On a standard Android device, all transaction codes are resolved dynamically from the device's own JARs.

Testing and Verification

The project is verified at four levels:

1. Unit Tests

The compiler packages (parser, codegen, resolver, binder, parcel, typesys) and tools/pkg/testutil have unit tests that run without any Android device or special environment:

go test ./tools/pkg/... ./binder/ ./parcel/

These test:

• Parser correctness: Lexing/parsing of all AIDL constructs against testdata fixtures (interfaces, parcelables, enums, unions, generics, constants, annotations)
• Code generation: Each generator (GenerateInterface, GenerateParcelable, GenerateEnum, GenerateUnion) is tested by parsing AIDL input, generating Go, and verifying the output is valid gofmt-compliant Go source that contains expected identifiers (descriptors, transaction codes, type names, method signatures)
• Import cycle detection: Verifies the SCC algorithm correctly identifies and breaks cross-package import cycles
• Marshal/unmarshal naming: Maps from AIDL types to parcel read/write expressions
• Parcel serialization: Round-trip encoding/decoding of all primitive types
• Binder status: Exception code marshaling

2. AOSP Codegen Test

Tests that code generation succeeds for the entire AOSP AIDL surface (requires tools/pkg/3rdparty/ submodules):

go test -tags aosp_codegen -v -run TestCodegenAllAOSP ./tools/pkg/codegen/

Walks all ~11,000 AIDL files, parses each, generates Go code, and verifies the output parses as valid Go. Reports per-file success/failure statistics.

3. Generated Smoke Tests

Auto-generated tests that instantiate every proxy type with a mock binder and call every method with zero-value arguments:

go run ./tools/cmd/spec2go -specs specs/ -output . -smoke-tests
go test ./tests/e2e/...  # requires /dev/binder OR mock mode

4. End-to-End Tests on Android

Full integration tests that open /dev/binder and transact with real Android system services:

# Run on Android device or emulator
go test -tags e2e -v ./tests/e2e/...

These verify:

• ServiceManager: ListServices, GetService, CheckService, service handle aliveness
• Typed transactions: Call ActivityManager.GetProcessLimit(), SurfaceFlinger.GetPhysicalDisplayIds(), etc. and validate returned types
• Exception handling: AIDL security exceptions, status codes
• Parcelable round-trip: Real service data deserialized through generated UnmarshalParcel
• Concurrency: Multiple goroutines with isolated binder drivers
• Death notifications: Registration/unregistration lifecycle
• Oneway transactions: Fire-and-forget calls
• Error handling: Invalid handles, dead processes

CI

Unit tests run automatically on every push and pull request via GitHub Actions. E2E tests require an Android device and must be run manually.

A weekly workflow checks for new AOSP revision tags, regenerates version tables and proxy code, and opens a PR automatically if anything changed.

binder-mcp

AI agents can interact with Android devices through binder-mcp, a Model Context Protocol server that exposes binder services as tools.

Device mode

# Build and push
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o build/binder-mcp ./cmd/binder-mcp/
adb push build/binder-mcp /data/local/tmp/

# Use with Claude Code (or any MCP client)
# In your MCP config, add:
# {
#   "mcpServers": {
#     "android": {
#       "command": "adb",
#       "args": ["shell", "/data/local/tmp/binder-mcp"]
#     }
#   }
# }

Remote mode (runs on host)

go run ./cmd/binder-mcp/ --mode remote
# Auto-discovers device via ADB, pushes daemon, serves MCP on stdio

Available tools

Using binder-mcp with AI Agents

Installation

# Via go install
go install github.com/AndroidGoLab/binder/cmd/binder-mcp@latest

# Via GitHub releases (pre-built binaries)
# Download from https://github.com/AndroidGoLab/binder/releases

# Via Docker (host mode)
docker run ghcr.io/androidgolab/binder-mcp

Claude Code

claude mcp add --transport stdio binder-mcp -- binder-mcp --mode remote

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "binder-mcp": {
      "command": "binder-mcp",
      "args": ["--mode", "remote"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "binder-mcp": {
      "command": "binder-mcp",
      "args": ["--mode", "remote"]
    }
  }
}

Cline

Add to Cline MCP settings:

{
  "mcpServers": {
    "binder-mcp": {
      "command": "binder-mcp",
      "args": ["--mode", "remote"],
      "alwaysAllow": ["list_services", "get_device_info", "take_screenshot"]
    }
  }
}

On-device mode (via adb)

# Build for Android
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o binder-mcp ./cmd/binder-mcp/
adb push binder-mcp /data/local/tmp/

# Configure agent to use adb transport
claude mcp add --transport stdio binder-mcp -- adb shell /data/local/tmp/binder-mcp

Interoperability

dr, _ := runner.NewDeviceRunner("SERIAL")
dr.PushBinary(ctx, "build/mybinary", "/data/local/tmp/mybinary")
result, _ := dr.Run(ctx, "/data/local/tmp/mybinary", 30*time.Second)
fmt.Println(result.Stdout)

sess, _ := proxy.NewSession(ctx, "SERIAL")
defer sess.Close(ctx)
// Session manages the daemon lifecycle and port forwarding;
// binder calls are routed through the remote transport.

gomobile bind -target android -o binder.aar ./interop/gomobile/client/

Project Layout

.
├── tools/
│   ├── cmd/
│   │   ├── aidl2spec/        AIDL-to-YAML spec compiler
│   │   ├── java2spec/        Java source info extractor (service maps, parcelables)
│   │   ├── spec2go/          Go proxy code generator from specs
│   │   ├── spec2cli/         bindercli command registry generator from specs
│   │   └── spec2readme/      README package table generator from specs
│   └── pkg/
│       ├── parser/           Lexer + recursive-descent AIDL parser
│       ├── resolver/         Import resolution and type registry
│       ├── codegen/          Go code generator
│       │   ├── codegen.go        GenerateAll orchestration, validation, import graph
│       │   ├── interface_gen.go  Interface → proxy struct + methods
│       │   ├── parcelable_gen.go Parcelable → struct + Marshal/Unmarshal
│       │   ├── enum_gen.go       Enum → typed constants
│       │   ├── marshal.go        AIDL type → parcel read/write expressions
│       │   └── import_graph.go   SCC-based import cycle detection
│       ├── spec/             YAML spec read/write
│       ├── javaparser/       Java source parser
│       ├── parcelspec/       Parcelable spec extraction
│       ├── servicemap/       Service name mapping
│       ├── validate/         Semantic validation (types, directions, oneway)
│       ├── testutil/         Mock binder, reflection-based smoke testing
│       └── 3rdparty/         AOSP submodules (frameworks-base, frameworks-native, ...)
├── binder/                   Binder IPC abstractions
│   ├── ibinder.go            IBinder interface
│   ├── proxy_binder.go       Client-side proxy: Transact, IsAlive, LinkToDeath
│   └── status.go             AIDL exception reading/writing
├── parcel/                   Wire format serialization
│   └── parcel.go             4-byte aligned little-endian buffer
├── kernelbinder/             /dev/binder kernel driver interface
│   └── driver.go             Open, mmap, ioctl BINDER_WRITE_READ
├── servicemanager/           ServiceManager client
├── errors/                   AIDL exception types (ExceptionCode, StatusError)
├── android/                  Pre-generated AOSP service proxies (5,174 files)
│   ├── app/                  ActivityManager, AlarmManager, ...
│   ├── os/                   ServiceManager, PowerManager, ...
│   ├── hardware/             HAL interfaces
│   └── ...                   407 packages total
├── com/                      AOSP com.android.* service proxies
├── interop/                  Interoperability helpers
│   ├── gadb/                 Pure-Go ADB integration
│   └── gomobile/             Android AAR via gomobile
├── examples/                 106 runnable examples
└── .github/workflows/        CI configuration