pxcCapture proxy & team collaboration
A capture proxy benchmarked against Proxyman that turns debugging sessions into a shared team asset. The only contract between the Go kernel pxc-core and the platform shells is a /v1 HTTP/WS API: macOS Swift, Windows WinUI and Flutter all share the same kernel.
01$ pxc sessions --host api.github.com --status 500 --limit 2002[ { "id": 42, "method": "POST", "path": "/v1/pay", "status": 500 } ]0304$ pxc bp respond 7 --status 201 --body '{"ok":true}'05{ "released": true, "mode": "mock" }Capturing traffic is not the goal — a reproducible debugging session is.
Design decisions
Why this tool is built the way it is, and what that buys.
The kernel exposes only the /v1 API; every client (Swift / WinUI / Flutter / CLI) is an equal consumer, so cross-platform behaviour is consistent by construction.
pxc status / sessions / body / curl all emit structured output, so AI can read the traffic and locate problems — no screenshots needed.
One rule line holds the target traffic; inspect the body live and choose to release, mock or abort — rewriting and replaying without scripts.
A capture scene exports to HAR and cURL; attach it to an issue and it reproduces — no more “try it again on your side”.
Capabilities at a glance
- Go kernel with replaceable platform shells; /v1 HTTP/WS is the only contract
- The pxc CLI is built for agents: JSON output by default, semantic exit codes, automatic token resolution
- Server-side filtering and full-text search: locate by host, status code or body keyword
- Breakpoint debugging: suspend traffic, change method / URL / headers / body, then release
- Fault injection and mocking: answer without hitting upstream to construct error branches
- Full HAR 1.2 export and cURL replay — share a debugging session with a colleague in one click
Design metrics
Each one maps to a concrete decision in the implementation.
macOS Swift / Windows WinUI / Flutter, with a replaceable UI
E2E acceptance coverage of the kernel — the precondition for identical behaviour across shells
Rules take effect within one second of saving, with no kernel restart
success / failure / usage error — easy for scripts and agents to judge
Full-text search; locate by body keyword instead of scrolling by eye
Full export + cURL replay; the debugging session is shareable
Platform support
With kernel and shell separated, support levels can advance independently per platform.
The Swift desktop shell, talking to the kernel over /v1 HTTP/WS
The WinUI desktop shell, sharing the same Go kernel
JSON output by default, semantic exit codes, automatic token resolution
On-device capture and viewing on mobile; bindings live in kernel/bindings
The kernel ships its own web UI build for inspecting traffic in the browser
How it differs from the common approach
The difference usually is not in the feature table — it is in where the boundary is drawn.
Commands at a glance
For the full manual, see the CLI reference page. All commands output structured results by default.
pxc statusKernel status, listening ports and license info
--jsonpxc sessionsSearch captured traffic with combined filters
--host--status--method--limit--qpxc body <id>Read the full request and response bodies of a session
--req--res--rawpxc curl <id>Export as a replayable cURL command
--no-headersActual output
01$ pxc sessions --host api.github.com --status 500 --limit 2002[ { "id": 42, "method": "POST", "path": "/v1/pay", "status": 500 } ]0304$ pxc bp respond 7 --status 201 --body '{"ok":true}'05{ "released": true, "mode": "mock" }Modules
3 groups, 15 modules — all from the repository’s real directory structure.
Go · Swift · WinUI · Flutter · WebSocket · HAR · FTSpxc-core, written in Go, is the single source of truth.
internal/engineTraffic capture and the proxy engine; the executor behind breakpoint suspension and release
kernel/internal/engineinternal/storeTraffic persistence and search; FTS full-text search locates by body keyword
kernel/internal/storeinternal/rulesThe rules engine: text DSL rules, hot-reloaded within 1s of saving
kernel/internal/rulesinternal/apiThe /v1 HTTP + WebSocket contract — the kernel’s only outward interface
kernel/internal/apiinternal/scriptingScripted extension capability
kernel/internal/scriptinginternal/pairing / discoveryDevice pairing and instance discovery, enabling collaborative debugging across clients
kernel/internal/{pairing,discovery}internal/license / instanceLicensing and instance management
kernel/internal/{license,instance}The kernel speaks only /v1; every client is an equal consumer.
cmd/pxcCLI: JSON output by default, semantic exit codes (0/1/2), automatic token resolution
kernel/cmd/pxccmd/pxc-coreThe kernel service process
kernel/cmd/pxc-corecmd/pxc-mobile / pxc-licenseMobile and licensing commands
kernel/cmd/apps/desktopDesktop shells (macOS Swift / Windows WinUI)
apps/desktopapps/mobile / webuiThe Flutter mobile app and Web UI
apps/{mobile,webui}What keeps cross-platform behaviour identical.
shared/api-specThe /v1 API spec; the kernel and every client align on it
shared/api-speckernel/bindingsThe mobile bindings layer
kernel/bindingskernel/webThe web UI build shipped with the kernel
kernel/webUsage
4 typical scenarios, each broken into steps you can follow.
No client-side logging needed — look at the real request and response.
- 1filter with pxc sessions --host api.example.com --status 500
- 2pxc body <id> to read the error stack in the response body
- 3when needed, pxc curl <id> to replay and reproduce locally
- 4pxc export to export a HAR and attach it to the issue
Hold the target traffic, rewrite it, release — no scripts.
- 1write one matching line in the rules file
- 2the rule hot-reloads within 1s of saving
- 3the target request suspends; inspect method / url / header / body live
- 4release after rewriting, or answer with a mock directly
Return the status code and body you need without touching the upstream.
- 1specify the response with pxc bp respond <id> --status 503 --body
- 2the client receives the constructed failure
- 3validate the front end’s degradation and fault-tolerance logic
- 4no changes to the server or the upstream
AI reads structured traffic directly; no human screenshots required.
- 1the agent calls pxc status to confirm the kernel is up
- 2filter suspicious sessions by host and status code
- 3read the body for the real error message
- 4structured output feeds straight into the analysis pipeline
Data boundary and security
Much of the value of this kind of tool is in what it does not do. Every item below notes where it is implemented.
The capture kernel runs on the local machine; traffic data never passes through third-party services.
cmd/pxc-coreDevice pairing and instance discovery; unpaired instances cannot connect.
internal/pairing · discoveryThe CLI discovers and resolves the local token automatically — no credentials passed in plaintext on the command line.
cmd/pxcRules are a local text DSL; the file location and content are auditable, with 1s hot reload.
~/.pxc/project/rules.txtLicenses bind to instances, so teams can manage and revoke them centrally.
internal/license · instanceHAR and cURL exports fire only on user action; nothing is sent out automatically.
export moduleRelease cadence
Shipped items state what was delivered; in-progress items state what is being built.
v0.3ReleasedKernel- The Go capture and proxy engine
- The /v1 HTTP + WebSocket contract
- FTS full-text search
- The rules engine with hot reload
v0.6ReleasedDebugging & multi-platform- Breakpoint suspension and release after rewriting
- Fault injection and mock responses
- The macOS Swift desktop shell
- HAR 1.2 export and cURL replay
v0.8In developmentCollaboration & agents- Completing structured output across the pxc CLI
- The Windows WinUI desktop shell
- Flutter mobile capture
- Team-shared sessions and permissions
v1.0PlannedEcosystem- Opening scripted extensions
- Protocol extensions (gRPC / WebSocket enhancements)
- CI integration and automated assertions
- Team workspaces and auditing
FAQ
Because capture must span platforms. The kernel exposes only /v1 HTTP/WS; macOS Swift, Windows WinUI, Flutter and the CLI are all equal consumers — cross-platform consistency is guaranteed by the contract, not by reimplementing capture on every platform.
Modules
3 groups, 15 modules. Paths map directly to repository directories, so engineers can locate code fast.
pxc-core, written in Go, is the single source of truth.
internal/engineTraffic capture and the proxy engine; the executor behind breakpoint suspension and release
kernel/internal/engineinternal/storeTraffic persistence and search; FTS full-text search locates by body keyword
kernel/internal/storeinternal/rulesThe rules engine: text DSL rules, hot-reloaded within 1s of saving
kernel/internal/rulesinternal/apiThe /v1 HTTP + WebSocket contract — the kernel’s only outward interface
kernel/internal/apiinternal/scriptingScripted extension capability
kernel/internal/scriptinginternal/pairing / discoveryDevice pairing and instance discovery, enabling collaborative debugging across clients
kernel/internal/{pairing,discovery}internal/license / instanceLicensing and instance management
kernel/internal/{license,instance}The kernel speaks only /v1; every client is an equal consumer.
cmd/pxcCLI: JSON output by default, semantic exit codes (0/1/2), automatic token resolution
kernel/cmd/pxccmd/pxc-coreThe kernel service process
kernel/cmd/pxc-corecmd/pxc-mobile / pxc-licenseMobile and licensing commands
kernel/cmd/apps/desktopDesktop shells (macOS Swift / Windows WinUI)
apps/desktopapps/mobile / webuiThe Flutter mobile app and Web UI
apps/{mobile,webui}What keeps cross-platform behaviour identical.
shared/api-specThe /v1 API spec; the kernel and every client align on it
shared/api-speckernel/bindingsThe mobile bindings layer
kernel/bindingskernel/webThe web UI build shipped with the kernel
kernel/webTech stack
Layered design
From kernel to shell — what each layer owns and what it is built with. The core design of these tools is separating kernel from shell.
Go pxc-core: traffic capture, FTS search, breakpoints and the rules engine
/v1 HTTP + WebSocket — the only interface between the kernel and every client
macOS Swift / Windows WinUI / Flutter
cmd/pxc with JSON output, exit codes 0/1/2 and automatic token discovery
a text DSL at ~/.pxc/project/rules.txt with 1s hot reload on save
full HAR 1.2 export and replayable cURL commands
Multi-platform support
One kernel; a different platform is just a different shell. Support levels can advance per platform.
The Swift desktop shell, talking to the kernel over /v1 HTTP/WS
The WinUI desktop shell, sharing the same Go kernel
JSON output by default, semantic exit codes, automatic token resolution
On-device capture and viewing on mobile; bindings live in kernel/bindings
The kernel ships its own web UI build for inspecting traffic in the browser
Tech stack
Command reference
8 commands. Design premises: structured output and semantic exit codes, so both scripts and AI agents can consume them reliably.
pxc statusKernel status, listening ports and license info
--jsonpxc sessionsSearch captured traffic with combined filters
--host--status--method--limit--qpxc body <id>Read the full request and response bodies of a session
--req--res--rawpxc curl <id>Export as a replayable cURL command
--no-headerspxc exportExport full HAR 1.2 records matching the filters
--out--host--sincepxc bp respond <id>Answer a suspended request directly (mock mode)
--status--body--headerpxc rules reloadHot-reload the rules file without restarting the kernel
--filepxc discoveryDiscover pairable instances and devices on the LAN
--jsonOutput conventions
The CLI is an interface for programs; humans being able to read it is a side effect.
JSON by default, with stable field names. Human-readable formatting is the caller’s decision, not something the CLI guesses.
Success, failure and usage errors return distinct exit codes, so scripts and agents branch on the code instead of parsing text.
Local token files are discovered automatically, avoiding plaintext credentials on the command line (which would land in shell history and process lists).
One real invocation
01$ pxc sessions --host api.github.com --status 500 --limit 2002[ { "id": 42, "method": "POST", "path": "/v1/pay", "status": 500 } ]0304$ pxc bp respond 7 --status 201 --body '{"ok":true}'05{ "released": true, "mode": "mock" }Hand the complexity of identity, agents and private domain to one governable kernel
Whether you are replacing an existing IAM, building an agent platform, or trying to make private-domain operations actually work — start with a 30-minute architecture call. We will first judge whether this is the kind of problem we are good at, and say so plainly if it is not.