Metadata-Version: 2.4
Name: motim
Version: 0.2.0
Summary: MOTIM (Model Over Traffic — Intercept & Manage) - Proxy for capturing, querying, and replaying API traffic
Author: vaibhavk97
License-Expression: MIT
Project-URL: Homepage, https://github.com/vaibhavk97/motim
Project-URL: Repository, https://github.com/vaibhavk97/motim
Project-URL: Issues, https://github.com/vaibhavk97/motim/issues
Project-URL: Changelog, https://github.com/vaibhavk97/motim/blob/main/CHANGELOG.md
Keywords: mitm,proxy,http,api,motim,mitmproxy,httpx,traffic,intercept
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mitmproxy<12,>=10.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0.20240106; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: curl
Requires-Dist: curl_cffi>=0.14.0; extra == "curl"
Provides-Extra: linkfinder
Requires-Dist: jsbeautifier>=1.15.0; extra == "linkfinder"
Dynamic: license-file

# motim

**Model Over Traffic — Intercept & Manage**

Browse any website. motim captures every request. Now your AI agent can replay them — auth included.

```bash
pip install motim
motim init          # trust CA cert, create config
motim start         # proxy on localhost:8080
# browse normally...
motim search --host api.notion.com
motim replay 42     # exact same request, same cookies, same tokens
```

## What it does

motim runs a local MITM proxy that records full HTTP(S) exchanges — method, URL, headers, cookies, request body, response body — into a local SQLite database (`~/.motim/motim.sqlite3`).

Then you search, inspect, replay, mutate, diff, and probe those exchanges from the CLI or Python. Auth just works because motim captured the real headers your browser sent.

## Who it's for

- **AI agents** that need to call authenticated APIs without manual credential wiring
- **Security researchers** probing endpoints, diffing responses, finding hidden parameters
- **Developers** reverse-engineering undocumented APIs or debugging request flows
- **CTF players** replaying complex auth flows

## Usage

### Search and inspect

```bash
motim search --host api.example.com --status 200 --method POST
motim show 42                    # full request + response
motim cat 42                     # just the response body (pipe to jq)
motim cat 42 --request           # just the request body
motim export 42                  # as a runnable curl command
motim endpoints --service notion # discovered endpoint patterns
```

### Replay and mutate

```bash
motim replay 42                                          # as-is
motim replay 42 --set-header "x-foo=bar"                 # add/override headers
motim replay 42 --drop-header "authorization"            # strip headers
motim replay 42 --patch-json '{"page_size": 50}'         # patch JSON body
motim replay 42 --transport curl --impersonate chrome    # browser TLS fingerprint
```

### Probe (automated mutation testing)

```bash
motim probe 42 \
  --patch-json '{"admin": true}' \
  --patch-json '{"role": "superuser"}' \
  --drop-header "x-csrf-token" \
  --json
```

Replays a baseline, then each mutation. Diffs every result against the baseline.

### Timeline

```bash
motim around 42 --window 60      # exchanges ±60s from exchange 42
motim session 42 --gap 120       # session slice (gap-based splitting)
motim diff 42 43                 # diff two exchanges
motim replay-seq 10 11 12 13     # replay a sequence in order
```

### JS endpoint extraction

```bash
motim linkfinder --host app.example.com --regex '^/api/'
motim js-endpoints --service example
```

Extracts API routes from captured JavaScript bundles — finds endpoints before you click the UI path that triggers them.

### Everything else

```bash
motim services                # list captured services
motim export-yaml notion      # YAML summary export
motim rebuild-index           # rebuild derived indexes
motim doctor                  # health check
motim config show             # view config
```

## Python library

```python
from motim import get, Client, ExchangeDB

# One-liner
r = get("api_notion_com", "/v1/users/me")

# Client
client = Client("notion")
r = client.get("/v1/users/me")

# Direct DB access
with ExchangeDB("~/.motim/motim.sqlite3") as db:
    results = db.search_exchanges(host="api.notion.com", limit=10)
```

## Agent integration

motim ships a skill file so AI agents know how to use it. All commands support `--json` for machine-readable output.

```bash
motim init                  # installs to ~/.claude/skills/motim/ (Claude Code)
motim agents-md             # writes AGENTS.md for Codex, opencode, etc.
```

## Setup

`motim init` does everything: creates `~/.motim/`, generates a mitmproxy CA cert, trusts it in your system keychain, and installs the agent skill.

After `motim start`, point your browser at `localhost:8080`. Use [SwitchyOmega](https://github.com/nicerswitchy/SwitchyOmega) or set it system-wide.

Config lives at `~/.motim/config.yaml` — header profiles, timeouts, domain filters. Run `motim config show` to see it.

## Development

```bash
git clone https://github.com/vaibhavk97/motim.git
cd motim
pip install -e ".[dev]"
pytest
```

## License

MIT
