stalker

README

stalker

Track every AI agent interaction, forever.

Install

Install the stalker command with Go:

go install github.com/mohammad-safakhou/stalker/cmd/stalker@latest

For local development from this checkout:

make install

Make sure Go's binary directory is on your PATH. By default this is $(go env GOPATH)/bin.

Run

stalker

Defaults:

• Proxy and dashboard: http://127.0.0.1:18080
• Dashboard: http://127.0.0.1:18080/ui/
• Data directory:
  • macOS: ~/Library/Application Support/stalker/
  • Linux/Unix: ${XDG_DATA_HOME:-~/.local/share}/stalker/
  • Windows: %LOCALAPPDATA%\stalker\

For local development without installing:

make run

Configure Codex with:

openai_base_url = "http://127.0.0.1:18080/v1"

Do not set chatgpt_base_url yet. The proxy handles Codex ChatGPT-subscription routing from the OpenAI-shaped traffic by detecting ChatGPT-Account-ID or the OAuth JWT account claim.

Storage

Stalker stores request metadata in SQLite with WAL mode enabled and writes large request/response bytes through an in-memory token pipeline. Raw payloads are not retained by default. The database stores exchange metadata, per-exchange token runs, and global per-token aggregate counts.

Environment variables:

• STALKER_ADDR: listen address, default 127.0.0.1:18080
• STALKER_DATA_DIR: storage directory, default is the OS app data location
• OPENAI_BASE_URL: upstream OpenAI API base, default https://api.openai.com/v1
• CHATGPT_BACKEND_URL: upstream ChatGPT backend, default https://chatgpt.com/backend-api
• CHATGPT_CODEX_URL: upstream Codex backend, default https://chatgpt.com/backend-api/codex

Setup

Run setup after installing:

stalker install

The setup command creates the data directory and can optionally configure a service. For Codex, it writes this top-level setting to ~/.codex/config.toml:

openai_base_url = "http://127.0.0.1:18080/v1"

If you previously ran Stalker from a checkout and have data in .stalker/, move it into the app data directory with:

stalker install --migrate --service codex

If an app-data database already exists, Stalker backs that directory up before moving the old .stalker/ directory.

Upgrade to the latest version with:

stalker upgrade

Remove raw payload data retained by older versions and shrink the database with:

stalker compact --yes