MIT License

Copyright (c) 2026 Divy Srivastava

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

Intercept any app, then call it from Python like a library.

from hinge_client import Hinge

acc = Hinge() # reuses your captured session — no keys to wire up

recs = acc.get_recommendations()

acc.like(subject_id, comment="empty pools are so peaceful lol")

You never wrote `hinge_client.py`. mimic watched your own app traffic and an AI

wrote the client for you.

Every app authenticates each request with a stable bundle — a bearer token,

device ids, a session id, cookies. Capture that once from a real request **you**

made, and you can craft new calls the server can't tell apart from the real app.

The generated client is plain, editable Python on top of `mimic.App`. It gets

the ergonomic parts right — named methods, body templates, and the multi-step

chaining mobile APIs need (fetch a token here, spend it there).

sh install.sh

Installs [`uv`](https://astral.sh/uv) if you don't have it, then mimic in an

isolated tool env. No separate mitmproxy install — mimic launches it for you via

`uvx` on first `record`. (Manual: `uv tool install mimic-client`.)

mimic doctor # confirm proxy + claude are ready

mimic record # starts the proxy, prints the exact iPhone steps

`record` walks you through it and auto-fills your Mac's LAN IP:

1. iPhone → Wi-Fi → Configure Proxy → Manual → `<your-mac-ip>:8080`

2. Safari → `http://mitm.it` → install the Apple profile

3. **Settings → General → About → Certificate Trust Settings → turn on full

trust for mitmproxy** — the step everyone forgets

4. open the app, use it normally

Then:

mimic hosts # list captured hosts; pick your API host

mimic learn prod-api.hingeaws.net # see the endpoints mimic saw

mimic gen prod-api.hingeaws.net # AI writes hinge_client.py

Then `from hinge_client import Hinge; Hinge().get_recommendations()`.

Three ways to build a session by hand, if you don't want codegen:

from mimic import Session

Session.from_mitm("prod-api.hingeaws.net") # pull auth from mitmweb

Session.from_curl(open("copied.txt").read()) # paste "Copy as cURL" from devtools

Session(base_url="https://x.com", headers={...}) # explicit

`.get(path)` / `.post(path, json=...)` return parsed JSON and auto-refresh your

token from mitmweb if it rotates (a `401`/`403` triggers one re-pull + retry).

- **mitmproxy** — iOS apps (the default). mimic reads its JSON flow API and runs

it for you via `uvx`, so there's nothing extra to install.

- **cURL / paste** — anything with a web version. `Copy as cURL` in devtools →

`Session.from_curl(text)`. No proxy, no cert.

**Certificate pinning** (banking, Instagram) defeats a plain proxy, so pinned

apps aren't supported. Plenty of apps aren't pinned and just work — if

`mimic hosts` shows the app's API host, you're set.

Use it on **your own** accounts and data. It replays *your* session; it is not a

tool for accessing anyone else's. Respect each app's terms of service.

MIT — see [LICENSE](LICENSE). Provided as-is, no warranty. Use on your own

accounts and data; you are responsible for complying with each app's terms.

set -e

if ! command -v uv >/dev/null 2>&1; then

echo "installing uv…"

curl -LsSf https://astral.sh/uv/install.sh | sh

export PATH="$HOME/.local/bin:$PATH"

if [ -f "pyproject.toml" ] && grep -q 'name = "mimic-client"' pyproject.toml 2>/dev/null; then

uv tool install . --reinstall

uv tool install mimic-client --reinstall

echo "installed. next:"

echo " mimic doctor # check setup"

echo " mimic record # start capture, follow the iPhone steps"

from .session import App, Session

__all__ = ["Session", "App"]

__version__ = "0.1.0"

import argparse

import re

import shutil

import socket

import subprocess

import sys

from . import codegen

from .sources import mitm

def _mitm_and_flows():

m = mitm.Mitm()

return m, m.flows()

def _lan_ip():

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

try:

s.connect(("8.8.8.8", 80))

return s.getsockname()[0]

except OSError:

return "<this-machine-ip>"

finally:

s.close()

def _mitmweb_cmd():

"""Prefer mitmweb on PATH; otherwise run it ephemerally through uv."""

if shutil.which("mitmweb"):

return ["mitmweb"]

if shutil.which("uvx"):

return ["uvx", "--from", "mitmproxy", "mitmweb"]

return None

def cmd_record(args):

ip = _lan_ip()

print(

f"""

)

cmd = _mitmweb_cmd()

if not cmd:

sys.exit(

"no proxy available — install uv (https://astral.sh/uv) so mimic can\n"

"run mitmproxy for you, or `pipx install mitmproxy` yourself."

)

sys.stdout.flush() # show the steps before the proxy takes over the terminal

try:

subprocess.run(cmd)

except FileNotFoundError:

sys.exit("failed to launch mitmweb")

def cmd_doctor(args):

ok = True

def check(name, present, fix):

nonlocal ok

mark = "ok " if present else "MISSING"

print(f" [{mark}] {name}")

if not present:

ok = False

print(f" → {fix}")

print("mimic setup check:\n")

check("proxy (mitmweb or uvx)", _mitmweb_cmd() is not None,

"install uv: curl -LsSf https://astral.sh/uv/install.sh | sh")

check("claude CLI (for `mimic gen`)", shutil.which("claude") is not None,

"install Claude Code, or use `mimic gen --prompt-only`")

reachable = False

try:

mitm.Mitm().flows()

reachable = True

except mitm.MitmError:

pass

check("mitmweb running + reachable", reachable,

"run `mimic record` in another terminal")

print(f"\nLAN IP for the iPhone proxy: {_lan_ip()}:8080")

sys.exit(0 if ok else 1)

def cmd_hosts(args):

_, flows = _mitm_and_flows()

rows = mitm.hosts(flows)

if not rows:

sys.exit("no traffic captured yet — run `mimic record` and use the app")

print(f"{'requests':>9} host")

for host, n in rows:

print(f"{n:>9} {host}")

print("\nPick your API host (usually the one with JSON, not media/cdn).")

def cmd_learn(args):

m, flows = _mitm_and_flows()

eps = mitm.endpoints(m, flows, args.host)

if not eps:

sys.exit(f"no requests to {args.host} captured")

print(f"{args.host}: {len(eps)} endpoints\n")

for e in eps:

print(f" {e['method']:5s} {e['path']} -> {e['status']}")

def cmd_gen(args):

m, flows = _mitm_and_flows()

eps = mitm.endpoints(m, flows, args.host)

if not eps:

sys.exit(f"no requests to {args.host} captured")

if args.prompt_only:

print(codegen.build_prompt(args.host, eps))

return

out = args.out or _default_out(args.host)

print(f"asking claude to write a client from {len(eps)} endpoints…", file=sys.stderr)

source = codegen.generate(args.host, eps, model=args.model)

with open(out, "w") as f:

f.write(source)

cls = _class_name(source)

print(f"\nwrote {out}")

print(f"\n from {out[:-3]} import {cls or 'Client'}")

print(f" acc = {cls or 'Client'}()")

print(" # then call the generated methods\n")

def _default_out(host):

stem = re.sub(r"[^a-z0-9]+", "_", host.split(".")[0].lower()).strip("_")

return f"{stem or 'app'}_client.py"

def _class_name(source):

m = re.search(r"class\s+(\w+)\s*\(", source)

return m.group(1) if m else None

def main(argv=None):

p = argparse.ArgumentParser(prog="mimic", description=__doc__,

formatter_class=argparse.RawDescriptionHelpFormatter)

sub = p.add_subparsers(dest="cmd", required=True)

sub.add_parser("record", help="start the proxy + iPhone setup steps").set_defaults(func=cmd_record)

sub.add_parser("doctor", help="check your setup").set_defaults(func=cmd_doctor)

sub.add_parser("hosts", help="list captured hosts").set_defaults(func=cmd_hosts)

lp = sub.add_parser("learn", help="show endpoints for a host")

lp.add_argument("host")

lp.set_defaults(func=cmd_learn)

gp = sub.add_parser("gen", help="AI-generate a client for a host")

gp.add_argument("host")

gp.add_argument("-o", "--out", help="output .py path")

gp.add_argument("--model", default="sonnet", help="claude model (default: sonnet)")

gp.add_argument("--prompt-only", action="store_true", help="print the prompt instead of calling claude")

gp.set_defaults(func=cmd_gen)

args = p.parse_args(argv)

args.func(args)

if __name__ == "__main__":

main()