mimic: capture an app's traffic and call it from Python

The problem mimic solves: private APIs with stable auth bundles

Most mobile apps have no public API. The endpoints exist, the app calls them constantly, but there is no documented way in. Writing a client by hand means reading proxied traffic, guessing which headers matter, and rebuilding the same request shape for every endpoint you care about.

mimic's premise is that authentication for these apps is boring. The README puts it plainly: most apps sign every request with the same bundle of values, a bearer token, some device ids, a session id, cookies, and that bundle is stable across calls. If that is true, you capture it once from a real request and replay it on new requests to the same host.

The audience is narrow on purpose. This is for someone automating their own account, not for building a product on top of someone else's service. The README's ethics section says to use it on your own accounts and data and to respect each app's terms of service. That constraint shapes everything else: there is no multi-tenant story, no credential vault, no rate-limit governor. It replays your session, and that is the whole design.

The pipeline: mitmproxy in, Claude-generated Python out

The README draws the flow as three stages: capture traffic with mitmproxy, extract auth with mimic.Session, generate a client that Claude writes after reading the captured endpoints.

Capture is the part with the most moving pieces. On iOS, mimic starts mitmproxy, prints your Mac's LAN IP, and walks you through pointing the phone's Wi-Fi proxy at that address on port 8080, installing the Apple profile from http://mitm.it, and then enabling full trust under Certificate Trust Settings. The README calls that last step out as easy to miss and notes nothing works without it. That is accurate in practice for any mitmproxy-based workflow, and it is the first place a new user gets stuck.

Once traffic is flowing, mimic reads mitmproxy's JSON flow API. It does not vendor mitmproxy; the README says mimic launches it via uvx on first record, so there is nothing extra to install. From the captured flows you get a host list, an endpoint listing, and then a generated file. The output is plain Python on top of mimic.App, which matters more than it sounds: you are expected to open hinge_client.py and edit it. The generator gives you named methods and body templates, plus the multi-step chaining that mobile APIs need when one call fetches a token and the next spends it.

Three capture backends exist, and they are not equally demanding. mitmproxy is the iOS default and needs the proxy and the certificate. cURL paste needs neither: copy a request as cURL from devtools and feed the text to Session.from_curl. HAR files cover anything you can capture in a browser, saved from the Network tab, and work with mimic hosts --har and mimic gen --har. If your target has a web version, the HAR path skips the entire certificate dance.

Installing mimic and generating your first client

The install script bootstraps uv if it is missing and then installs mimic in an isolated tool environment. The README gives the manual equivalent as uv tool install mimic-client.

sh install.sh

After that, doctor is the readiness check. It confirms the proxy and claude are available, which is worth running before you touch a phone.

mimic doctor

Recording starts the proxy and prints the iPhone setup steps with your Mac's LAN IP already filled in.

mimic record

With the phone configured and the app used normally, list what was captured. This is the checkpoint the README itself names: if mimic hosts shows the app's API host, you are good.

mimic hosts
mimic learn prod-api.hingeaws.net
mimic gen   prod-api.hingeaws.net

The learn command lists the endpoints mimic saw for that host, and gen writes hinge_client.py. From there the usage is ordinary Python: import the generated class, instantiate it, and call the methods.

from hinge_client import Hinge

acc = Hinge()
recs = acc.get_recommendations()
acc.like(subject_id, comment="hi lol")

If you would rather skip codegen, the library exposes three constructors. Session.from_mitm pulls auth from mitmweb, Session.from_curl parses pasted devtools output, and the explicit form takes a base_url and headers. The verb helpers return parsed JSON and raise requests.HTTPError on failed responses. Token rotation is handled narrowly: a 401 on an idempotent request triggers one re-pull from mitmweb and a retry, while non-idempotent requests are not retried unless you pass refresh=True. That asymmetry is deliberate and you should respect it, since a retried POST that already succeeded is a duplicate action on a real account.

Certificate pinning is a capture problem; DPoP is a replay problem

The README separates two auth schemes that break mimic, and the distinction is the most useful thing in the document.

Certificate pinning, used by banking apps and Instagram, means the app rejects the mitmproxy certificate. The proxy sees no traffic and mimic hosts stays empty. The README is explicit that this blocks capture, not replay: get past the pin and the rest works normally. mimic unpin takes an ipa or a bundle id and sets up a Frida-based bypass, with details in docs/pinning.md. That is a real escape hatch, but it moves you from "run a proxy" to "instrument the app," which is a different level of effort and a different risk profile.

DPoP is worse, and the README says so without hedging. Sender-constrained tokens carry a fresh proof signed by a private key that never leaves the device. Captured requests do not replay, so the core model fails rather than just the capture step. There is no clean workaround, and docs/dpop.md is where the project says to look. If your target uses DPoP, mimic is the wrong tool and no amount of configuration changes that.

A third limitation is quieter: the whole approach assumes the auth bundle is stable across calls. Apps that rotate tokens aggressively, bind requests to a nonce, or fingerprint the TLS client will degrade the generated client in ways the README does not enumerate. The 401 retry path covers token expiry. It does not cover request signing.

How mimic differs from mitmproxy and from hand-written clients

mitmproxy is the obvious comparison, and mimic does not replace it. mitmproxy is a proxy and an inspection tool: you watch traffic, write addons, and script flows. mimic uses mitmproxy as a capture backend and then does something mitmproxy does not attempt, which is turning the observed endpoints into a typed, editable Python client with named methods and body templates. If your goal is to understand what an app sends, mitmproxy alone is the better answer. If your goal is to call those endpoints from a script next week, the codegen step is the part that saves work.

The other alternative is writing the client yourself with requests. That is entirely viable for one or two endpoints, and it gives you full control over retries, backoff, and error handling. mimic's value shows up when the API has many endpoints or multi-step chaining, where hand-writing each call is repetitive and the generator has already read the captured set. The trade-off is that generated code is a starting point, not a finished library. You still own the file. Nothing in the README suggests the generator understands your domain, so treat its output as a scaffold you will read line by line before trusting it with a write operation.

Maintenance, licence, and what the repository does not say

The last push to the repository was on 2026-07-26, which is recent enough that the project is not abandoned, though the README does not describe a release cadence and no releases were retrieved. The version in pyproject.toml is 0.1.0, so treat the API surface as pre-1.0 and expect generated files to need regeneration if the client format changes.

The dependency footprint is small: requests at 2.28 or newer, with mitmproxy 10 or newer as an optional capture extra. Python 3.9 is the floor. That is a light install, and the uvx launch of mitmproxy means proxy upgrades are not your problem.

Licensing is MIT, declared in pyproject.toml with a LICENSE file at the repository root, and the README states the software is provided as-is with no warranty, with responsibility for complying with each app's terms falling on you. MIT covers the code. It does not cover what you do with a captured session, and the README's ethics section is the project's own position on that boundary rather than a legal one. What the README does not document is rollback: there is no described way to undo mimic unpin on a device, and no migration notes for regenerating clients across versions.

Editorial conclusion

Adopt mimic if you are automating your own account on an app whose API is not public, and you can accept that the client is generated code you will read and edit. Do not adopt it for banking apps or anything using DPoP sender-constrained tokens, because the README states captured requests do not replay. Before writing any code, run mimic doctor and then mimic hosts; if your target's API host never appears in that list, the rest of the pipeline has nothing to work on.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. littledivy/mimic on GitHub
4. README