httpmon

Terminal-native HTTP/HTTPS debugging proxy. Intercept, inspect, and filter traffic — all from your terminal with vim-style navigation.

Think Proxyman or Charles, but in your terminal.

Features

• MITM proxy — Intercept HTTP and HTTPS traffic with auto-generated CA certificates
• Live flow list — Watch requests stream in real-time with color-coded methods and status codes
• Tree view — Group flows by host, expand/collapse, focus on a single host
• Detail inspector — Headers, syntax-highlighted bodies, collapsible sections, image preview
• Action menu — Press Space for a context-aware command popup — no memorization needed
• Quick filter — / to filter by host, path, method, status code, or content type
• HAR export — Export all flows or a single flow to HAR format
• Request tools — Compose new requests, repeat captured ones, copy as cURL
• Diff view — Mark two flows and compare request/response side-by-side
• Host filtering — Block or allow hosts at the proxy layer with wildcard patterns
• Scripting — JavaScript hooks to modify requests/responses on the fly
• Bandwidth throttling — Simulate 3G/4G/WiFi network conditions
• Map Local — Serve local files instead of upstream responses
• Keyboard-driven — Vim-style navigation throughout — no mouse required

Quick Start

Homebrew (macOS/Linux)

brew install kostyay/tap/httpmon

Install from source

go install github.com/kostyay/httpmon/cmd/httpmon@latest

Build locally

git clone https://github.com/kostyay/httpmon.git
cd httpmon
make build
./httpmon

Usage

httpmon                          # Start proxy on :8080
httpmon --port 9090              # Custom port
httpmon --block "*.ads.com"      # Block hosts matching pattern
httpmon --allow "api.example.*"  # Only intercept matching hosts
httpmon --throttle 3g            # Simulate 3G network (750 kbps)
httpmon --throttle 4g            # Simulate 4G network (4 Mbps)
httpmon --latency 100ms          # Add 100ms latency to responses
httpmon --maplocal rules.json    # Serve local files for matching URLs
httpmon --install-ca             # Install CA cert into system trust store (needs sudo)
httpmon --version                # Print version

Then configure your browser or app to use http://localhost:8080 as its HTTP proxy.

Trust the CA certificate

The easiest way — run once with sudo:

sudo httpmon --install-ca

This generates the CA cert (if it doesn't exist yet) and adds it to your system trust store. Supports macOS and Linux.

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.httpmon/mitmproxy-ca-cert.pem

sudo cp ~/.httpmon/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/httpmon.crt
sudo update-ca-certificates

Scripting

Scripts are JavaScript files stored in ~/.httpmon/scripts/. Each script has a YAML frontmatter header and exports onRequest and/or onResponse hooks.

Script format

// ---
// name: Add Auth Header
// match:
//   - "*://api.example.com/*"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.headers["Authorization"] = "Bearer my-token";
}

function onResponse(ctx) {
  // ctx.status, ctx.headers, ctx.body
}

Header fields

Hooks

onRequest(ctx) — runs before the request is sent upstream.

onResponse(ctx) — runs before the response reaches the client.

Managing scripts

Press S in the TUI to open the scripts manager. From there:

• Space — Toggle a script on/off
• n — Create a new script from template
• d — Delete a script (with confirmation)

Scripts are reloaded each time the manager opens.

Throttle

Simulate slow network conditions. Throttling applies to all response bodies.

Presets

CLI

httpmon --throttle 3g             # Apply 3G preset
httpmon --throttle wifi --latency 200ms  # WiFi bandwidth + custom latency

TUI

Press T to open the throttle modal. Select a preset with j/k and press Enter to apply. The active preset shows in the status bar.

Map Local

Serve local files instead of fetching from upstream. Matched requests return the local file's content with the appropriate content type.

Rules JSON format

[
  {
    "pattern": "api.example.com/config",
    "local_path": "/path/to/config.json",
    "status_code": 200
  },
  {
    "pattern": "*.example.com/styles/*",
    "local_path": "/path/to/override.css"
  }
]

pattern supports * wildcards. status_code defaults to 200 if omitted.

CLI

httpmon --maplocal rules.json

TUI

Press M to open the Map Local manager:

• n — Add a new rule (pattern + local path, Tab to switch fields)
• d — Delete a rule (with confirmation)
• Esc — Close

Changes auto-save back to the rules file.

Flows served from local files show a [L] indicator in the flow list.

Keyboard Shortcuts

Press ? anywhere for the full help overlay, or Space for a context-aware action menu.

Flow List

Detail View

Global

Architecture

cmd/httpmon/          CLI entry point, flag parsing, wiring
internal/proxy/       MITM proxy engine (go-mitmproxy wrapper)
internal/store/       Thread-safe ring buffer for captured flows
internal/tui/         Bubble Tea terminal UI (list, detail, menu, compose, diff, export)
internal/filter/      Quick filter + advanced filter expressions
internal/hostfilter/  Wildcard-based host block/allow at proxy layer
internal/har/         HAR 1.2 export
internal/diff/        Flow diff engine
internal/highlight/   Syntax highlighting for response/request bodies
internal/certutil/    CA certificate generation and system trust installation
internal/throttle/    Bandwidth throttling (wraps io.Reader with rate limiting)
internal/maplocal/    Map remote URLs to local files (wildcard pattern matching)
internal/scripting/   JavaScript scripting hooks (goja runtime, YAML frontmatter)

Built with go-mitmproxy and Bubble Tea.

Contributing

make all        # lint + test + build
make test       # tests with race detection
make lint       # golangci-lint
make security   # gosec, govulncheck, gitleaks, trufflehog

License

MIT