chump-server

The backend hosts ChumpAgent instances over ai-query's built-in agent server routes.

Run

uv sync
uv run chump-server

Install

End-user Chump release archives bundle a platform-specific chump-server binary next to the CLI. The PyPI package remains useful for development, debugging, and direct backend runs:

uv run chump-server

During repository development, uv uses the released ai-query version pinned in pyproject.toml and uv.lock.

Build a local standalone backend binary:

python scripts/build_binary.py

The output is written to dist/bin/chump-server-<platform>. Use python scripts/build_binary.py --mode onedir --archive to produce the release archive at dist/bin/chump-server-<platform>.tar.gz.

Release

chump-server versions come from git tags through hatch-vcs.

git tag chump-server-v0.1.0
git push origin chump-server-v0.1.0

Pushing a chump-server-v* tag runs the PyPI job and creates a GitHub Release in .github/workflows/release.yml. The same release also gets platform-specific standalone backend runtime archives named chump-server-<platform>.tar.gz attached for sandbox/server-only deployments. Legacy onefile assets named chump-server-<platform> are also attached so older clients can update across the runtime archive transition.

Environment

CHUMP_HOST: default 127.0.0.1
CHUMP_PORT: default 8080
CHUMP_WORKSPACE_ROOT: defaults to the parent directory of server/
CHUMP_STATE_DIR: optional override for the workspace state directory; defaults to a per-workspace path under the user's OS state/data directory
CHUMP_PROVIDER: default chump_cloud; also supports codex, github_copilot, openai, google, anthropic, workers_ai, deepseek, openrouter, groq, xai, opencode, opencode_go, and zenmux
CHUMP_MODEL: provider-specific default
CHUMP_CLOUD_BASE_URL: optional OpenAI-compatible base URL for the chump_cloud provider
CHUMP_MAX_STEPS: default 250
CHUMP_RETRY_MAX_ATTEMPTS: provider-call retry attempts; default 3, set 1 to disable
CHUMP_RETRY_INITIAL_DELAY: initial retry delay in seconds; default 0.5
CHUMP_RETRY_MAX_DELAY: max retry delay in seconds; default 8
CHUMP_RETRY_BACKOFF: retry delay multiplier; default 2
CHUMP_RETRY_JITTER: enable retry jitter; default 1
CHUMP_COMMAND_TIMEOUT: default 120
CHUMP_MANAGED_SERVER_IDLE_TIMEOUT: optional process idle shutdown timeout in seconds
CHUMP_REASONING_EFFORT: optional OpenAI-compatible reasoning effort
CHUMP_REASONING_BUDGET: optional Gemini-compatible thinking budget
CHUMP_VERBOSE: default 1

Prompt-cache benchmark

Chump persists provider-reported token usage for every model step. Report the observed cache hit rate across local sessions, grouped by provider and model:

uv run --project server python server/scripts/benchmark_prompt_cache.py

The report includes two different rates:

Request hit: model calls where cached_tokens > 0.
Token hit: cached input tokens divided by all input tokens.

Use --provider google (repeatable), --min-calls 10, --json, or --state-root <path> to filter or automate the report. This benchmark reads local telemetry without making model requests or spending provider credits.

Metadata

Release files for chump-server 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chump-server 0.3.0
File	Size	Uploaded
chump_server-0.3.0.tar.gz	216.0 kB	Aug 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for chump-server 0.3.0
File	Interpreter	ABI	Platform	Reset
chump_server-0.3.0-py3-none-any.whl 107.3 kB Aug 24, 2026	Python 3	none	any	Details

Total release size: 323.3 kB

Release files / chump_server-0.3.0.tar.gz

Download URL	chump_server-0.3.0.tar.gz
Size	216.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`08f6b30e17c1b1d667fd9fa402b6a1d70cb013fe09eee38acf09b87409ca8a18`
BLAKE2b-256 checksum How to use checksums	`60f7752f4fc6468227a66cac49ac2554a88cd73e80b228bf04078aeeff668cb4`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abdulmumin1/chump
Publishing commit: github.com/Abdulmumin1/chump/tree/9522959f2328986ce40f9a96adf96aa685c1f6ea

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/9522959f2328986ce40f9a96adf96aa685c1f6ea/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32781974254/attempts/1

Artifact

Subject: chump_server-0.3.0.tar.gz
SHA-256 checksum: 08f6b30e17c1b1d667fd9fa402b6a1d70cb013fe09eee38acf09b87409ca8a18 Verifying attestations

Release files / chump_server-0.3.0-py3-none-any.whl

Download URL	chump_server-0.3.0-py3-none-any.whl
Size	107.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`85d3736a6a630587687b050998e09612343178c6b19f8180f7e5762f0ccbfdec`
BLAKE2b-256 checksum How to use checksums	`f3b1f4a0497558a9e90fd0b4127d9b991513bf07a075c43a19a594d5b4010f0f`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abdulmumin1/chump
Publishing commit: github.com/Abdulmumin1/chump/tree/9522959f2328986ce40f9a96adf96aa685c1f6ea

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/9522959f2328986ce40f9a96adf96aa685c1f6ea/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32781974254/attempts/1

Artifact

Subject: chump_server-0.3.0-py3-none-any.whl
SHA-256 checksum: 85d3736a6a630587687b050998e09612343178c6b19f8180f7e5762f0ccbfdec Verifying attestations