pi-charles

English | 中文

Charles Proxy analysis tools for the pi coding agent.

npm package: pi-charles

Design principle: tools only fetch, filter, and present data. Reasoning stays with the agent.

How it works

Checkpoint timeline

Each harvest_data() call:

1. Exports the current Charles session
2. Keeps only entries newer than the last harvest (by times.start millis)
3. Stores them in an in-memory ARCHIVE
4. Appends a checkpoint on the timeline
5. Clears the Charles session and restarts recording (keeps exports small)

Use load_checkpoint(n) to jump back to any historical window. All filter tools then operate on that window.

Resource placeholders

Image / JS / CSS / binary bodies are replaced with placeholders like [image/png 45.2KB]. The agent sees type and size, then calls get_raw_data only when needed.

Keyword interlock

If filter_by_keyword matches more than 30 entries, you must call check_keyword_exists first. This avoids dumping large bodies into the context window.

Prerequisites

Charles Proxy running with Web Interface enabled: Proxy → Web Interface Settings

• Enable Web interface
• Default is no user/password (anonymous). Set via /charles or CHARLES_USER/CHARLES_PASS env vars.

Install

npm (recommended)

pi install npm:pi-charles

Git

pi install git:github.com/geebos/pi-charles
pi install git:github.com/geebos/pi-charles@v1.0.0

GitHub Packages (optional)

Published as @geebos/pi-charles (scoped for the registry):

# ~/.npmrc
# @geebos:registry=https://npm.pkg.github.com
# //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

pi install npm:@geebos/pi-charles

Local development

git clone https://github.com/geebos/pi-charles.git
cd pi-charles
npm install
pi -e ./extensions/index.ts
# or
pi install ./

Configuration: /charles

Configure the Charles connection from inside pi (English UI copy):

/charles              Open settings UI (TUI)
/charles show         Show current settings
/charles test         Test Charles connection
/charles reset        Reset to defaults
/charles set user <v> Set username
/charles set pass <v> Set password
/charles set host <v> Set proxy host
/charles set port <v> Set proxy port

Setting	Default	Description
Username	(empty)	Charles Web Interface username (optional)
Password	(empty)	Charles Web Interface password (optional)
Proxy host	control.charles	Host where the Charles HTTP proxy listens
Proxy port	80	Port where the Charles HTTP proxy listens

Settings are saved to ~/.pi/agent/extensions/pi-charles/config.json and apply immediately.

Priority: environment variables > config file > defaults.

Tools

Harvest

Tool	Description
harvest_data(fresh_start?)	Incremental harvest + checkpoint. fresh_start=true inserts a reset point
load_recording(file_path)	Load a local .chlsj recording

Timeline

Tool	Description
list_checkpoints()	List all checkpoints
load_checkpoint(checkpoint_id)	Switch the visible window to a checkpoint

Overview

Tool	Description
summarize_traffic()	Host / path / status / method distribution

Filters

Tool	Description
filter_by_host(host_keyword)	Filter by host
filter_by_path(path_keyword)	Filter by URL path
filter_by_method(method)	Filter by HTTP method
filter_by_status(status_code)	Filter by HTTP status
check_keyword_exists(keyword)	Probe keyword locations; unlocks filter_by_keyword
filter_by_keyword(keyword)	Entries containing the keyword (preview)
filter_by_encryption(threshold?)	Shannon-entropy scan for likely encrypted bodies

Detail / environment

Tool	Description
get_raw_data(entry_id)	Full raw entry
set_throttling(preset?)	Enable / disable Charles throttling (auto-restored on session end)

Typical workflow

harvest_data()
summarize_traffic()
filter_by_host("api.xxx")
filter_by_encryption()
get_raw_data(entry_id)

Switch analysis target:

harvest_data({ fresh_start: true })
# trigger the target action in the app
harvest_data()

Rewind history:

list_checkpoints()
load_checkpoint({ checkpoint_id: 2 })
filter_by_keyword({ keyword: "sign" })

Environment variables

Variable	Default	Description
CHARLES_USER	pi-charles	Web Interface username
CHARLES_PASS	123456	Web Interface password
CHARLES_PROXY_HOST	127.0.0.1	Proxy host
CHARLES_PROXY_PORT	8888	Proxy port

Publishing

Pushing a version tag runs two workflows (tag-only; no double-fire with Releases):

Workflow	Registry	Package name
Publish to npm	npmjs.com	pi-charles
github-publish	GitHub Packages	@geebos/pi-charles

git tag v1.0.0
git push origin v1.0.0

Manual re-publish of an existing tag: Actions → workflow → Run workflow → enter v1.0.0.

npm Trusted Publishing (no token)

Publish to npm uses Trusted Publishing (OIDC). Do not set NPM_TOKEN.

Configure once on npmjs.com → pi-charles → Settings → Trusted Publisher:

Field	Value
Provider	GitHub Actions
Organization or user	geebos
Repository	pi-charles
Workflow filename	publish-npm.yml
Allowed actions	npm publish

Requirements: Node 24 / npm ≥ 11.5.1 (set in the workflow), permissions.id-token: write.

GitHub Packages

Uses the automatic GITHUB_TOKEN with packages: write. No extra secret.

Credits

Migrated from the Python FastMCP project tianhetonghua/Charles-mcp-server to a TypeScript pi package.

License

MIT