Architecture

Request flow

AI CLI (claude-code, claude-cli, ...)
  │
  │  HTTP to 127.0.0.1:3817
  ▼
┌──────────────────────────────────────────────┐
│ sotatek-proxy (Gin engine, loopback bind)    │
│                                              │
│  recoveryLogger    panic recovery            │
│  requestLogger     scrub Authorization,      │
│                    x-api-key, drop query     │
│  MiddlewareGitRemote                         │
│       │                                      │
│       ├─ extract peer port from RemoteAddr   │
│       ├─ inspect.GetPidByPeerPort  → PID     │
│       ├─ inspect.GetCwdByPid       → CWD     │
│       ├─ walk parents (≤3) for .git          │
│       ├─ cache.Get(pid) [verify CWD]         │
│       ├─ git.GetRemoteRaw(cwd)  (2s timeout) │
│       └─ inject X-Git-Remote (base64)        │
│                                              │
│  ReverseProxy (NoRoute)                      │
│       ├─ stamp User-Agent: sotatek-proxy/X   │
│       ├─ preserve original in                │
│       │  X-Forwarded-User-Agent              │
│       └─ FlushInterval=-1 (SSE-safe)         │
└────────────────────┬─────────────────────────┘
                     │  HTTP/2 (ForceAttemptHTTP2)
                     ▼
       https://bifrost.sotatek.works/anthropic/v1/*

Middleware chain

The order matters. Each layer runs in this order on the way in, reverse on the way out.

#	Middleware	Purpose
1	`recoveryLogger`	Panic recovery; never echoes request headers.
2	`requestLogger`	Compact structured log per request: method, path, status, latency, `client_ip`, `has_auth`/`has_api_key` booleans, `has_query` flag. Authorization values are never logged.
3	`MiddlewareGitRemote`	Resolves the calling PID and CWD, runs `git remote -v`, base64-encodes the result, sets `X-Git-Remote`. Strips any client-supplied `X-Git-Remote` first.
4	`ReverseProxy` (NoRoute)	Forwards to upstream 1:1, stamps `User-Agent`, streams SSE without buffering.

Process inspection (PID → CWD → git)

The proxy resolves the client’s TCP peer port (the port your CLI used to connect) back to a PID, then to a CWD, then walks up to 3 parent directories looking for .git.

OS	Implementation
macOS	`lsof -iTCP:<port> -sTCP:ESTABLISHED -F pn` (PID), `lsof -p <pid> -d cwd -F n` (CWD). 2 s exec timeout.
Linux	Reads `/proc/net/tcp[6]` to map port → inode, scans `/proc/*/fd/` for the matching socket, then reads `/proc/<pid>/cwd`. Same-user only.
Windows	`GetExtendedTcpTable` for IPv4/IPv6 connection table; PEB walk via `NtQueryInformationProcess` for CWD. 64-bit only.

Walking parents stops at common interactive shells (bash, zsh, fish, sh, dash, ksh, tcsh, csh) so the proxy never hijacks a shell’s CWD.

Cache

The PID → {cwd, git-remote} cache uses a sync.Map with a TTL (default 60 s). On every Get, the caller re-reads the current CWD and the cache entry is dropped on mismatch — this guards against PID recycling.

A background sweep every 5 minutes drops expired entries and entries whose PID is no longer alive (kill -0).

The git remote -v shell-out has a hard 2 s timeout. On timeout or no remote, the request is forwarded without the X-Git-Remote header rather than blocking.

Streaming

The proxy uses httputil.ReverseProxy with FlushInterval=-1, which forces a flush per write. SSE / chunked responses reach the client as the upstream emits them — no body buffering. Client disconnect cancels the upstream context.

Health endpoint

GET /_proxy/healthz

Returns version, commit, uptime, and (when wired) cache stats.

{
  "status": "ok",
  "version": "v0.1.0",
  "commit": "abc1234",
  "uptime": "1h23m",
  "cache": { "entries": 12, "hits": 480, "misses": 64, "hit_rate": 0.882 }
}