upfront 0.1.0__tar.gz

upfront-0.1.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml,md}]
+indent_size = 2

upfront-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,16 @@
+name: Bug report
+description: Something doesn't work as documented
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes: {label: What happened, description: Command you ran and the output}
+    validations: {required: true}
+  - type: textarea
+    id: expected
+    attributes: {label: What you expected}
+    validations: {required: true}
+  - type: input
+    id: version
+    attributes: {label: Version, description: "`upfront --version`, OS, Python version"}
+    validations: {required: true}

upfront-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,14 @@
+name: Feature request
+description: Suggest an idea
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes: {label: The problem, description: "What are you trying to do, and what gets in the way?"}
+    validations: {required: true}
+  - type: textarea
+    id: proposal
+    attributes: {label: Proposed solution}
+  - type: textarea
+    id: links
+    attributes: {label: Related issues or threads elsewhere}

upfront-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## What and why
+
+## How tested
+- [ ] `pre-commit run --all-files`
+- [ ] `uv run pytest --cov`
+
+## Checklist
+- [ ] CHANGELOG.md updated under `[Unreleased]`
+- [ ] Docs updated if behaviour changed

upfront-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: {interval: weekly}
+    groups: {actions: {patterns: ["*"]}}
+  - package-ecosystem: uv
+    directory: /
+    schedule: {interval: weekly}
+    groups: {python: {patterns: ["*"]}}

upfront-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy --strict src
+      - run: uv run python scripts/gen_api_docs.py --check
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run pytest --cov --cov-report=xml --cov-fail-under=85
+      - if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          use_oidc: true
+          fail_ci_if_error: false
+    permissions:
+      contents: read
+      id-token: write  # codecov tokenless upload via OIDC
+
+  example:
+    # Runs the README example as a user would. Replace with the project's real 10-line demo.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv sync --locked
+      - name: README demo output still matches
+        run: |
+          HOME="$(mktemp -d)" uv run upfront examples/demo --yes --top 2 | tee out.txt
+          grep -F "claude-code                                      ≈ 6,786  before your first prompt" out.txt
+          grep -F "mcp filesystem (14 tools, project)             ≈ 2,751" out.txt
+          grep -F "[openai-tool-name]" out.txt
+      - name: Examples named after the issues still run
+        run: for f in examples/*.py; do uv run python "$f"; done

upfront-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - name: Tag matches package version
+        run: test "${GITHUB_REF_NAME#v}" = "$(uv version --short)"
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/upfront
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: Create release from CHANGELOG section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          awk -v v="${GITHUB_REF_NAME#v}" '$0 ~ "^## \\[" v "\\]" {f=1; next} /^## \[/ {f=0} f' CHANGELOG.md > notes.md
+          gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --notes-file notes.md

upfront-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store
+.tiktoken-cache/

upfront-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy --strict
+        entry: uv run mypy --strict src
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: pytest
+        name: pytest (pre-push)
+        entry: uv run pytest -q -x
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

upfront-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

upfront-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+
+### Added
+
+- `upfront [PATH]`: reports, per coding agent, the estimated tokens loaded before the first
+  prompt by MCP tool definitions, skill metadata and instruction files.
+- Config discovery for Claude Code (`.mcp.json`, `~/.claude.json` user and local scope),
+  Codex (`.codex/config.toml`, `~/.codex/config.toml`), Gemini CLI (`.gemini/settings.json`)
+  and OpenCode (`opencode.json[c]`), with skills folders and AGENTS/CLAUDE/GEMINI.md.
+- `tools/list` over stdio, Streamable HTTP and SSE via the official MCP SDK, with pagination,
+  per-server timeouts and per-server errors (including "auth required" and the server's last
+  stderr line).
+- Compatibility findings that cite their source: OpenAI, Anthropic and Gemini tool-name rules,
+  `$ref` parameters in Claude Code (claude-code#18260), non-standard formats in OpenCode
+  (opencode#15161), and Codex's skills-list budget.
+- `--json`, `--budget`, `--strict`, `--tools-file`, `--top`, `--timeout`, `-H/--harness`.
+- Servers are started only with consent (interactive prompt or `--yes`).
+- Library API: `upfront.profile()` and `upfront.profile_tools_file()`.
+- Examples reproducing codex#19679, opencode#11995 and claude-code#18260, and a demo project
+  with tools/list snapshots of three official MCP reference servers.
+
+[Unreleased]: https://github.com/thanatchon36/upfront/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/thanatchon36/upfront/releases/tag/v0.1.0

upfront-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the maintainer (@thanatchon36) privately, using this repository's "Report a vulnerability" form under the Security tab, which only maintainers can read. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

upfront-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for helping. Bug reports with a config that reproduces the problem are the most useful
+contribution: say which agent, which config file, and paste the relevant `upfront --json` output.
+
+## Setup
+
+You need [uv](https://docs.astral.sh/uv/). Python 3.11+ is installed by uv if missing.
+
+```bash
+git clone https://github.com/thanatchon36/upfront && cd upfront
+uv sync
+uv run pre-commit install
+```
+
+## Checks (the same ones CI runs)
+
+```bash
+uv run pre-commit run --all-files     # ruff check, ruff format, mypy --strict
+uv run pytest --cov --cov-fail-under=85
+```
+
+Tests start real MCP servers from `examples/servers/replay_server.py`, so they need no network
+except the tokenizer download on first run.
+
+## Adding a compatibility rule
+
+Rules live in `src/upfront/compat.py`. Every rule must link the public issue or documentation
+it comes from and needs a test with a tool that triggers it and one that doesn't. Rules that
+can't cite a source won't be merged: a false "this breaks in X" is worse than no warning.
+
+## Adding a harness
+
+Add a reader in `src/upfront/discover.py`, a fixture config under `tests/fixtures/`, and link
+the harness's documentation for the config format in the reader's docstring.
+
+## Commits and pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+- One logical change per pull request, with tests. Add a line under `[Unreleased]` in CHANGELOG.md.

upfront-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thanatchon
+
+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.

upfront-0.1.0/MISSION.md

@@ -0,0 +1,91 @@
+# upfront — Mission
+
+> See how many tokens each MCP server, skill and instruction file costs your coding agent before you type a word, and which tools will break in Claude Code, Codex, Gemini CLI or OpenCode.
+
+Status: in development (v0.1.0 target)
+
+## Problem
+
+Coding agents load a lot before your first prompt: every connected MCP server's tool schemas, the name and description of every installed skill, and every AGENTS.md / CLAUDE.md / GEMINI.md. Users notice it as a usage meter that climbs too fast or tools that silently disappear. The harnesses show little of it: Claude Code has `/context`, but only for itself, and OpenCode declined to build a breakdown. When the same MCP server moves between agents, schemas that work in one client fail in another.
+
+- [HN: Claude Code sends 33k tokens before reading the prompt; OpenCode sends 7k](https://news.ycombinator.com/item?id=48883275) — 706 points, 2026-07-12. Users had to put a logging proxy in front of the agent to find out.
+- [openai/codex#19679 — Make skills metadata context budget configurable instead of hardcoded 2%](https://github.com/openai/codex/issues/19679) — 👍40, open. Skill descriptions are shortened or dropped once the list passes 2% of the window, and users can't see when that happens.
+- [openai/codex#44308 — Agent Plugin MCP tools are silently hidden after the global schema budget is exhausted](https://github.com/openai/codex/issues/44308) — 👍6, open.
+- [anomalyco/opencode#11995 — Tool descriptions consume excessive tokens in system prompt](https://github.com/anomalyco/opencode/issues/11995) — 👍17, closed *not planned*.
+- [openai/codex#26234 — Flatten MCP namespace tools for non-OpenAI Responses API providers](https://github.com/openai/codex/issues/26234) — 👍49, open.
+- [anthropics/claude-code#18260 — MCP tool parameters with $ref schemas are incorrectly serialized as string](https://github.com/anthropics/claude-code/issues/18260) — 👍9, open.
+
+The full evidence and gap check are in the pain-point report and `decision.md` in the research workspace.
+
+## Target user
+
+A developer who uses one or more coding agents (Claude Code, Codex CLI, Gemini CLI, OpenCode) with several MCP servers and skills installed. They hit usage limits sooner than expected, or see tools go missing, and want to know which server or skill to cut. A second user is the **MCP server author** who wants to know what their server costs agents and whether its schemas work in every client, from CI.
+
+## Before / after
+
+**Before:** route the agent through a logging proxy (mitmproxy or a custom one), capture the first request, and count tokens by hand. Or install and remove servers one at a time and watch the usage meter. For schema compatibility: connect the server to each agent and wait for a 400.
+
+**After** (illustrative; real output is in the README):
+```console
+$ upfront --yes
+claude-code   ≈ 24,180 tokens before your first prompt
+  mcp  github        41 tools   ≈ 18,920
+  mcp  playwright    21 tools   ≈  3,140
+  skills  12 (metadata)          ≈  1,320   (bodies ≈ 21,400, loaded on demand)
+  CLAUDE.md                      ≈    800
+compat  ⚠ gemini-cli  github.create_issue  uses $ref/$defs   (gemini-cli#13326)
+```
+
+## Non-goals (v0.1)
+
+- **Measuring the harness's own system prompt.** It's vendor-internal and changes every release. upfront measures only what *you* add (servers, skills, instruction files).
+- **Exact token counts for every model.** v0.1 uses one tokenizer (`o200k_base`) as a stated estimate. Calling vendor token-count APIs would need keys and network, so it's on the roadmap.
+- **Rewriting schemas (a "fix" proxy).** v0.1 reports problems and doesn't change traffic.
+- **Runtime token usage of conversations.** That's already solved by ccusage, codeburn and others.
+- **OAuth flows for remote servers.** Servers that need auth are reported as "auth required, not measured".
+- **Cursor, Windsurf and other IDE agents.** Four CLI harnesses first.
+
+## Architecture
+
+```text
+configs on disk ──► discover ──► [Server specs, skills, instruction files]
+                                        │
+                          (consent) ──► fetch  ──► tools/list via MCP SDK (stdio / Streamable HTTP)
+                                        │
+                                        ▼
+                        tokens (o200k_base) + compat rules
+                                        │
+                                        ▼
+                         Report ──► plain-text table / JSON / exit code
+```
+
+- `upfront/discover.py` — reads Claude Code (`.mcp.json`, `~/.claude.json`), Codex (`.codex/config.toml`, `~/.codex/config.toml`), Gemini CLI (`.gemini/settings.json`, `~/.gemini/settings.json`) and OpenCode (`opencode.json[c]`, `~/.config/opencode/opencode.json`). Also finds skills dirs and instruction files.
+- `upfront/fetch.py` — launches or connects to each server with the official `mcp` SDK, with a per-server timeout, and paginates `tools/list`. Failures are recorded, never raised.
+- `upfront/tokens.py` — counts tokens for each tool's wire JSON (name, description, input/output schema), each skill's metadata and body, and each instruction file. Falls back to a chars/4 estimate if the tokenizer can't load offline.
+- `upfront/compat.py` — static rules, each linked to the public issue it comes from.
+- `upfront/report.py` + `upfront/cli.py` — rendering, JSON, budget exit codes.
+
+External deps: `mcp` (official SDK), `tiktoken` (tokenizer), `typer` (CLI). No LLM calls, no API keys.
+
+**Safety:** project-level config files can name arbitrary commands, so upfront only launches servers after confirmation (`--yes` for non-interactive use). Without consent it reports static data only.
+
+## MVP features → acceptance tests
+
+| # | Feature | Acceptance test | Closes use case in |
+|---|---|---|---|
+| F1 | Discover MCP servers, skills and instruction files for 4 harnesses, project + user scope | `tests/test_discover.py::test_discovers_all_four_harnesses` — a fixture project with all four config formats yields the expected servers, skills and files per harness | HN 33k-tokens thread |
+| F2 | Fetch every tool from stdio and Streamable HTTP servers (paginated, timeout, failures recorded) | `tests/test_fetch.py::test_fetches_paginated_tools_over_stdio_and_http` + `::test_failing_server_is_recorded_not_raised` | codex#44308 |
+| F3 | Count tokens per tool, server, skill (metadata vs body) and instruction file | `tests/test_tokens.py::test_counts_scale_with_schema_and_skill_metadata_is_separate_from_body` | opencode#11995, codex#19679 |
+| F4 | Compatibility rules per client, each linked to its source issue, plus the Codex 2% skills-list budget | `tests/test_compat.py::test_flags_each_known_breaker_and_passes_clean_tools` | codex#26234, claude-code#18260, codex#19679 |
+| F5 | CLI: ranked table, `--json`, `--budget N` exit code, `--tools-file` offline mode, launch only with consent | `tests/test_cli.py::test_budget_exit_code_and_json_and_consent` | CI use for server authors |
+
+## Success metrics
+
+- Each cited issue's scenario reproduces as a passing example in `examples/` (yes/no per link): codex#19679, opencode#11995, codex#26234 / claude-code#18260.
+- CI green on Python 3.11–3.13 × Linux/macOS, and coverage ≥ 85%.
+- In 30 days: at least one issue or PR from someone other than the author, and one MCP server repo using `upfront --budget` in CI. Stars don't count as a goal.
+
+## Roadmap
+
+- **v0.2** — exact counts via vendor token-count endpoints (opt-in, with key); `--fix` stdio proxy that rewrites schemas per client (inline `$ref`, shorten names), from report theme #1; Cursor/Windsurf configs.
+- **v0.3** — diff mode (`upfront diff main..HEAD` for MCP server PRs); a GitHub Action wrapper; per-model tokenizers.

upfront-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: upfront
+Version: 0.1.0
+Summary: See how many tokens your MCP servers, skills and instruction files cost a coding agent before your first prompt, and which tools break in which client.
+Project-URL: Homepage, https://github.com/thanatchon36/upfront
+Project-URL: Issues, https://github.com/thanatchon36/upfront/issues
+Project-URL: Changelog, https://github.com/thanatchon36/upfront/blob/main/CHANGELOG.md
+Author: Thanatchon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,context-window,gemini-cli,llm,mcp,model-context-protocol,opencode,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp>=2.3.0
+Requires-Dist: tiktoken>=0.14.0
+Requires-Dist: typer>=0.27.3
+Description-Content-Type: text/markdown
+
+# upfront
+
+[![ci](https://github.com/thanatchon36/upfront/actions/workflows/ci.yml/badge.svg)](https://github.com/thanatchon36/upfront/actions/workflows/ci.yml)
+[![coverage](https://codecov.io/gh/thanatchon36/upfront/graph/badge.svg)](https://codecov.io/gh/thanatchon36/upfront)
+[![PyPI](https://img.shields.io/pypi/v/upfront)](https://pypi.org/project/upfront/)
+[![Python](https://img.shields.io/pypi/pyversions/upfront)](https://pypi.org/project/upfront/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/thanatchon36/upfront/blob/main/LICENSE)
+
+See how many tokens your MCP servers, skills and instruction files cost a coding agent before
+you type a word, and which tools will break in Claude Code, Codex, Gemini CLI or OpenCode.
+
+## The problem
+
+> "Claude Code sends 33k tokens before reading the prompt; OpenCode sends 7k"
+> — [Hacker News, 706 points](https://news.ycombinator.com/item?id=48883275); finding out took a logging proxy.
+
+Every connected MCP server puts all of its tool schemas into the context, every skill adds its
+description, and AGENTS.md / CLAUDE.md ride along on every request. Usage limits arrive early,
+and Codex starts dropping skills ([codex#19679](https://github.com/openai/codex/issues/19679))
+and MCP tools ([codex#44308](https://github.com/openai/codex/issues/44308)) once budgets run
+out. Claude Code's `/context` shows this for Claude Code only; OpenCode closed the request as
+[not planned](https://github.com/anomalyco/opencode/issues/11995).
+
+## Demo
+
+![upfront measuring a demo project with three official MCP servers](https://raw.githubusercontent.com/thanatchon36/upfront/main/docs/demo.gif)
+
+```console
+$ uv run upfront examples/demo --yes --top 2      # in a clone of this repository
+upfront 0.1.0 · examples/demo · tokens o200k_base
+
+claude-code                                      ≈ 6,786  before your first prompt
+  mcp filesystem (14 tools, project)             ≈ 2,751
+      read_media_file                              ≈ 285
+      read_text_file                               ≈ 251
+  mcp memory (9 tools, project)                  ≈ 2,365
+      create_entities                              ≈ 349
+      search_nodes                                 ≈ 320
+  mcp everything (13 tools, project)             ≈ 1,602
+      gzip-file-as-resource                        ≈ 239
+      get-structured-content                       ≈ 186
+  skills (2, name + description)                    ≈ 33  bodies ≈ 48 load on demand
+  CLAUDE.md                                         ≈ 35
+...
+compatibility
+  error   codex       issue-scenarios.files.read: 'files.read' (10 chars) is not a valid OpenAI function name
+          [openai-tool-name] https://github.com/openai/openai-python/blob/main/src/openai/types/shared_params/function_definition.py
+```
+
+The demo's servers replay `tools/list` snapshots of the official
+[filesystem, memory and everything](https://github.com/modelcontextprotocol/servers) reference
+servers (1.0.0), so the numbers above are what those servers really cost.
+
+## Install
+
+```bash
+uvx --from git+https://github.com/thanatchon36/upfront upfront    # run from your project, no install
+pip install upfront                                               # once v0.1.0 is on PyPI
+```
+
+Python 3.11+. Then, in a project:
+
+```bash
+upfront          # skills, instruction files and the list of servers; starts nothing
+upfront --yes    # also start/connect to each MCP server and count its tools
+```
+
+## Features
+
+- **Four harnesses, both scopes.** Reads Claude Code, Codex, Gemini CLI and OpenCode configs from the project and your home directory, including `${VAR:-default}` expansion and JSONC.
+- **Real tool lists.** Talks to every stdio, Streamable HTTP and SSE server with the official MCP SDK, follows pagination, and reports failures (missing command, timeout, "auth required") per server instead of crashing.
+- **Where the tokens go.** Per server and per tool, skill metadata separately from skill bodies, and every instruction file.
+- **Compatibility checks with sources.** Tool names against OpenAI, Anthropic and Gemini rules, `$ref` parameters in Claude Code, non-standard formats in OpenCode, and Codex's skills budget. Every finding links the documentation or open issue it comes from.
+- **CI-friendly.** `--json`, `--budget N` and `--strict` exit codes, and `--tools-file` to check a saved `tools/list` without starting anything.
+- **Safe by default.** Nothing is launched without consent: it asks in a terminal and needs `--yes` elsewhere. It only ever calls `tools/list`.
+
+## How it compares
+
+| | upfront | Claude Code [`/context`](https://code.claude.com/docs/en/commands) | [mcp-assert](https://github.com/blackwell-systems/mcp-assert) | [ccusage](https://github.com/ccusage/ccusage) |
+|---|---|---|---|---|
+| Up-front cost of MCP tools, skills, instruction files | yes, per harness | yes, Claude Code only | no | no |
+| Works for Codex, Gemini CLI, OpenCode | yes | no | n/a | n/a |
+| Per-client schema compatibility | yes, 6 sourced rules | no | no; 24 usability lint rules (descriptions, nesting) | no |
+| Tests tool *behaviour* | no | no | yes (assertions, fuzzing) | no |
+| Actual spend from past sessions | no | `/usage` | no | yes |
+
+Use `/context` inside Claude Code, mcp-assert to test what your tools do, and
+ccusage to see what you've already spent. upfront answers "what will each agent load, and what
+breaks where" before you start.
+
+## How it works
+
+1. **Discover**: parse each harness's documented config files ([concepts](https://github.com/thanatchon36/upfront/blob/main/docs/concepts.md#where-upfront-looks)).
+2. **Fetch**: with consent, start each distinct server once (from the project directory, like the agent) and page through `tools/list`.
+3. **Count**: tokenize each tool's wire JSON with `o200k_base`; skill metadata and bodies separately; instruction files whole.
+4. **Check**: run the per-client rules ([table](https://github.com/thanatchon36/upfront/blob/main/docs/api.md#compatibility-rules)).
+
+More: [quickstart](https://github.com/thanatchon36/upfront/blob/main/docs/quickstart.md) · [concepts](https://github.com/thanatchon36/upfront/blob/main/docs/concepts.md) · [FAQ](https://github.com/thanatchon36/upfront/blob/main/docs/faq.md) · [API](https://github.com/thanatchon36/upfront/blob/main/docs/api.md) · [decisions](https://github.com/thanatchon36/upfront/blob/main/docs/decisions/)
+
+## Limitations
+
+- **Estimates.** One tokenizer for every model; vendors' counts differ, and clients add their own framing around tools ([ADR-0003](https://github.com/thanatchon36/upfront/blob/main/docs/decisions/ADR-0003-tokenizer.md)).
+- **Not the vendor's system prompt.** Only what you add is measured.
+- **Lazy loading isn't modelled.** Claude Code's tool search and OpenCode's lazy MCP loading defer some definitions; upfront reports their full cost.
+- **No OAuth.** Remote servers that need a login show "auth required; not measured". Headers from your config are sent; OAuth flows are not run.
+- **Root-level instruction files only**, and only the four CLI harnesses above (no Cursor or Windsurf yet).
+- **Codex's 2% skills budget** depends on the model's window; upfront checks the documented 8,000-character fallback.
+
+## Roadmap
+
+- **v0.2**: exact counts via vendor token-count APIs (opt-in), a `--fix` proxy that rewrites schemas per client, Cursor and Windsurf configs.
+- **v0.3**: `upfront diff` between git refs for MCP server pull requests, and a GitHub Action.
+
+## Contributing
+
+Bug reports with a config that reproduces the problem help most. See
+[CONTRIBUTING.md](https://github.com/thanatchon36/upfront/blob/main/CONTRIBUTING.md); compatibility rules need a public source.
+
+## License
+
+[MIT](https://github.com/thanatchon36/upfront/blob/main/LICENSE)