ctxfire 0.1.0__tar.gz

ctxfire-0.1.0/.github/ISSUE_TEMPLATE/adapter.yml

@@ -0,0 +1,28 @@
+name: Adapter request or correction
+description: Propose loading semantics backed by an official source
+labels: [adapter]
+body:
+  - type: input
+    id: engine
+    attributes:
+      label: Engine and version
+    validations:
+      required: true
+  - type: input
+    id: source
+    attributes:
+      label: Official documentation URL
+    validations:
+      required: true
+  - type: textarea
+    id: semantics
+    attributes:
+      label: Loading rule and uncertainty
+    validations:
+      required: true
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Minimal fixture layout
+    validations:
+      required: true

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

@@ -0,0 +1,34 @@
+name: Bug report
+description: Report a reproducible scanner, adapter, or output problem
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not paste private repository paths or content. Redact reports first.
+  - type: input
+    id: version
+    attributes:
+      label: ctxfire version
+      placeholder: ctxfire 0.1.0
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include a small public fixture or synthetic file tree and config.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected versus actual behavior
+    validations:
+      required: true
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options: [Linux, macOS, Windows, Other]
+    validations:
+      required: true

ctxfire-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/korovin-aa97/ctxfire/security/advisories/new
+    about: Report security issues privately

ctxfire-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly

ctxfire-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What changed
+
+## Contract impact
+
+- [ ] Adapter semantics unchanged or versioned/documented
+- [ ] Report schema unchanged or versioned/documented
+- [ ] Default output remains metadata-only and repository-relative
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `mypy src`
+- [ ] `pytest`
+- [ ] `python -m build`

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

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest
+      - run: |
+          ctxfire scan --config examples/demo/before.toml --format json --output before.json
+          ctxfire scan --config examples/demo/after.toml --format json --output after.json
+          ctxfire diff before.json after.json
+          python scripts/validate_report_schema.py before.json
+          python scripts/validate_report_schema.py after.json
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install '.[tokenizers]'
+      - run: python -m unittest discover -s tests -v
+      - run: ctxfire --version
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/

ctxfire-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: pypi-distributions
+          path: dist/
+
+  publish:
+    if: ${{ vars.PYPI_PUBLISH == 'true' }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ctxfire/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: pypi-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

ctxfire-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+validation-repos/

ctxfire-0.1.0/AGENTS.md

@@ -0,0 +1,95 @@
+# ctxfire — Agent Bootstrap
+
+Last updated: 2026-08-29. Repository status: **v0.1.0 initial public release**.
+
+Read this file first, followed by `README.md`, `ctxfire.example.toml`, the
+source, and `docs/PUBLIC_RELEASE_PLAN.md`.
+
+## Product in one sentence
+
+`ctxfire` maps the context each versioned adapter attributes to a coding agent,
+how often that agent fires, and the estimated token and API-equivalent cost per
+fire and per day.
+
+## Positioning
+
+This is a static cost analyzer for multi-agent context graphs. It is not a live
+token meter, agent package manager, skill recommender, generic context manager,
+or exact subscription bill calculator.
+
+The product's useful graph is:
+
+`agent -> definition -> rules/skills/memory -> schedule -> estimated daily cost`
+
+File paths and byte counts can be exact. Token counts, cache behaviour, prices,
+and daily cost are estimates and must always expose their assumptions.
+
+## Current state
+
+- Version `0.1.0`; renamed from the colliding private draft name before launch.
+- Versioned explicit, AGENTS.md, Codex, and Claude Code adapters.
+- Git-index discovery plus narrow exact probes for ignored engine instructions.
+- `scan`, `explain`, `diff`, and `check`; human, JSON 1.0, and SARIF 2.1.0.
+- Dependency-free byte estimates and an opt-in local tiktoken backend.
+- MIT license, community/security docs, CI, release workflow, fixtures, schema,
+  demo, and a dated 18-repository validation report.
+
+## Non-negotiable boundaries
+
+- Never present estimates as actual vendor bills or measured prompt-cache hits.
+- Reports must separate exact facts from estimates and include model,
+  tokenizer, price date, cache assumption, and adapter version.
+- Do not collect or upload repository contents. The OSS scanner is local-only
+  and telemetry-free by default.
+- Do not absorb package management or runtime orchestration into this tool.
+- Keep adapters explicit and versioned because engine loading semantics change.
+- Use git-index and ignore semantics so worktrees, caches, generated copies, and
+  vendored trees do not silently inflate results.
+- Keep the extraction clean-room: no internal hosts, agent names, schedules,
+  budgets, customer data, or private fleet topology.
+
+## Next work, in order
+
+1. Keep adapter semantics aligned with their dated official sources.
+2. Preserve report schema 1.0 compatibility through the 0.1 line.
+3. Triage real user reports before expanding engine or tokenizer scope.
+4. Treat runtime measurement, package management, and scheduling as out of scope.
+
+## v0.1 definition of done
+
+- Loading rules are documented and pinned per adapter version.
+- Discovery agrees with each supported engine on representative fixtures.
+- Exact bytes, estimated tokens, schedules, cache assumptions, and prices are
+  distinguishable in both human and machine-readable reports.
+- `explain` shows why every file is included; `diff` attributes cost changes;
+  `check` provides stable CI thresholds.
+- The scanner handles ignored files, nested worktrees, symlinks, missing files,
+  cycles, shared dependencies, and generated content deterministically.
+- Results are manually checked on 10–20 third-party repositories before launch.
+- Clean installs, documentation, community files, security policy, changelog,
+  packaging, release workflow, and public demo are ready.
+
+## Working rules for future agents
+
+- Use Python 3.11+ and type all public interfaces.
+- Treat adapter semantics and report schemas as public APIs.
+- Add a regression fixture for every loading rule or parser quirk.
+- Avoid reading file contents when metadata is enough; never print sensitive
+  contents in default reports.
+- No hidden network calls or telemetry.
+- Date and source every price or competitor claim.
+- Before each release, repeat direct checks of GitHub, PyPI/npm, and competitor sites;
+  young tools and bot-blocked sites are easy to miss in search indexes.
+
+## Success criterion
+
+Before announcement: correct scans on 10–20 external repositories. Within 30
+days after launch: at least three external users run it repeatedly or keep its
+CI integration. Use voluntary adopter notes or interviews, not embedded
+telemetry.
+
+## Release authority
+
+Agents may prepare and rehearse everything. Repository visibility changes,
+package publication, public releases, directory submissions, and public launch
+posts require explicit owner authorization in the active session.

ctxfire-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/) and
+this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-08-29
+
+### Added
+
+- Versioned `explicit@1`, `agents-md@1`, `codex@1`, and `claude-code@1` adapters.
+- Git-index discovery with standard ignores and safe symlink/submodule handling.
+- `scan`, `explain`, `diff`, and `check` commands.
+- Human, JSON schema 1.0, and SARIF 2.1.0 output.
+- Explicit token, schedule, conditional-activation, cache, price, and model assumptions.
+- Reproducible fixtures, external-repository validation, packaging, and CI.
+
+[0.1.0]: https://github.com/korovin-aa97/ctxfire/releases/tag/v0.1.0

ctxfire-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+We pledge to make participation in this project welcoming and harassment-free,
+regardless of background, identity, experience, or viewpoint.
+
+Be respectful, assume good intent, criticize ideas rather than people, and do
+not publish another person's private information. Maintainers may edit, remove,
+or reject contributions and comments that violate these expectations.
+
+Report conduct concerns privately to the repository owner through the contact
+method on their GitHub profile. Reports will be reviewed promptly and kept as
+confidential as practical.
+
+This compact policy is inspired by the Contributor Covenant 2.1.

ctxfire-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+Thank you for helping make agent context costs explainable.
+
+1. Open an issue for a loading-semantics change before implementing it.
+2. Keep runtime code dependency-free unless a dependency has a clear accuracy
+   or security benefit.
+3. Add a regression fixture for every adapter/discovery quirk.
+4. Keep reports metadata-only and repository-relative by default.
+5. Run `ruff check .`, `mypy src`, `pytest`, and `python -m build`.
+
+Adapters and report schemas are public APIs. A changed engine behavior needs an
+official source link, an uncertainty note, and either a compatible adapter
+patch or a new adapter version. Do not silently change existing semantics.
+
+By participating you agree to the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

ctxfire-0.1.0/LICENSE

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

ctxfire-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: ctxfire
+Version: 0.1.0
+Summary: Explain and budget static context graphs for coding agents
+Project-URL: Homepage, https://github.com/korovin-aa97/ctxfire
+Project-URL: Documentation, https://github.com/korovin-aa97/ctxfire#readme
+Project-URL: Issues, https://github.com/korovin-aa97/ctxfire/issues
+Project-URL: Changelog, https://github.com/korovin-aa97/ctxfire/blob/main/CHANGELOG.md
+Author: Alexander Korovin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,context-window,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
+Requires-Dist: mypy<2,>=1.11; extra == 'dev'
+Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.6; extra == 'dev'
+Requires-Dist: tiktoken<1,>=0.7; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Provides-Extra: tokenizers
+Requires-Dist: tiktoken<1,>=0.7; extra == 'tokenizers'
+Description-Content-Type: text/markdown
+
+# ctxfire
+
+**See what every coding agent loads, why it loads, and what that repeated
+context could cost.**
+
+![ctxfire context graph preview](docs/assets/social-preview.png)
+
+`ctxfire` is a local, telemetry-free static analyzer for multi-agent context
+graphs. It connects agent definitions to repository instructions, rules, and
+skills; multiplies the estimated input by each agent's schedule; and keeps every
+assumption visible.
+
+```text
+implementer [codex@1]
+  context candidates: 3 files, 18120 exact bytes/fire
+  estimate: 3810 tokens/fire × 8/day = 30480 tokens/day
+reviewer [claude-code@1]
+  context candidates: 4 files, 22644 exact bytes/fire
+  estimate: 4725 tokens/fire × 8/day = 37800 tokens/day
+
+TOTAL estimated tokens/day: 68280
+```
+
+This is not a runtime meter or an invoice calculator. File sizes are exact;
+tokens, conditional activation, cache behavior, schedules, and API-equivalent
+prices are estimates recorded in every report.
+
+## Why another context-cost tool?
+
+Most repository analyzers ask, “How large is this codebase?” Runtime meters ask,
+“What did this one session consume?” `ctxfire` asks a different question:
+
+> What is the transitive instruction surface of each agent, and what happens
+> when the team loads it repeatedly every day?
+
+The unit of analysis is `agent → loading rule → context file → schedule`, not a
+flat repository walk.
+
+## Quickstart
+
+Python 3.11+ and Git are the only requirements.
+
+```bash
+pipx install git+https://github.com/korovin-aa97/ctxfire.git@v0.1.0
+ctxfire --version
+cp ctxfire.example.toml ctxfire.toml
+ctxfire scan
+```
+
+Or run without a persistent install:
+
+```bash
+uvx --from git+https://github.com/korovin-aa97/ctxfire.git@v0.1.0 ctxfire scan
+```
+
+Start from [`ctxfire.example.toml`](ctxfire.example.toml):
+
+```toml
+schema_version = "1"
+
+[project]
+name = "my-agent-team"
+root = "."
+bytes_per_token = 4.0
+tokenizer = "byte-estimate"
+model = "unspecified"
+price_date = "unspecified"
+cache_assumption = "no-cache-credit"
+conditional_activation_rate = 0.25
+
+[[agents]]
+name = "implementer"
+adapter = "codex@1"
+working_directory = "."
+fires_per_day = 8
+include = ["docs/product-rules.md"]
+conditional = ["docs/playbooks/**/*.md"]
+```
+
+`usd_per_million_input_tokens` is optional. Add it only with a model and a
+dated price you have verified. `ctxfire` deliberately ships no silently aging
+vendor price table.
+
+## Commands
+
+```bash
+# Human report
+ctxfire scan --config ctxfire.toml
+
+# Stable schema 1.0 snapshot
+ctxfire scan --format json --output before.json
+
+# Why is each edge present?
+ctxfire explain --agent implementer
+ctxfire explain --file AGENTS.md
+
+# Attribute change between snapshots
+ctxfire diff before.json after.json
+
+# CI: exit 2 only when a budget is exceeded
+ctxfire check --max-tokens-per-day 75000
+
+# GitHub-compatible SARIF
+ctxfire check --max-tokens-per-day 75000 --format sarif --output ctxfire.sarif
+```
+
+Exit codes are stable: `0` success/pass, `1` invalid input or operational error,
+and `2` a valid scan that exceeded a `check` budget.
+
+## Exact versus estimated
+
+| Field | Kind | Meaning |
+|---|---|---|
+| relative path, file presence, byte size | Exact | Facts from the local working tree |
+| adapter and inclusion reason | Declared model | Versioned loading semantics used for the graph |
+| tokens | Estimated | `ceil(bytes / bytes_per_token)` by default, or an opt-in local tokenizer count |
+| conditional activation | Estimated | User-provided rate from 0 to 1 |
+| fires/day | Assumption | Planning input; `ctxfire` is not a scheduler |
+| USD/day | Estimated equivalence | Dated input-token price × estimated tokens; not a bill |
+| cache | Assumption | Stated in the report; v0.1 does not observe cache hits |
+
+The default estimator never reads file contents. This makes it reproducible and
+privacy-safe, but less accurate than a model-specific tokenizer—especially for
+non-English text and code-heavy files.
+
+For an opt-in local tokenizer:
+
+```bash
+pipx install 'ctxfire[tokenizers]'
+```
+
+Then set `tokenizer = "tiktoken:cl100k_base"` (or another explicit tiktoken
+encoding). The report records the installed tokenizer version and changes
+`discovery.content_access` to `matched-file-content-local`. Matched bytes are
+read only in memory; they are never printed, stored, or uploaded.
+
+## Supported adapters
+
+| Adapter | Always-on context | Conditional candidates |
+|---|---|---|
+| `explicit@1` | `include` patterns | `conditional` patterns |
+| `agents-md@1` | ancestor `AGENTS.md` chain for `working_directory` | configured patterns |
+| `codex@1` | precedence-selected ancestor instruction chain, under a declared byte cap | ancestor `.agents/skills/*/SKILL.md` bodies |
+| `claude-code@1` | ancestor project memory and conservative project rules | descendant memory and project skill bodies |
+
+Adapters are conservative static models, not claims that every candidate is
+loaded on every invocation. Details, source links, and known uncertainty are in
+[`docs/ADAPTER_SPEC.md`](docs/ADAPTER_SPEC.md).
+
+## Git-aware and private by default
+
+- Uses `git ls-files --cached --others --exclude-standard` at a Git top-level.
+- Includes tracked files and non-ignored untracked files; ignored build output
+  does not silently inflate the graph.
+- Probes only known exact engine instruction paths and exact configured paths
+  outside that universe, so an ignored `CLAUDE.local.md` is still counted and
+  clearly warned without opening arbitrary ignored trees.
+- Skips symlinks rather than following them outside the repository.
+- Skips submodule gitlinks and missing/non-regular paths with a warning.
+- Emits repository-relative paths, never an absolute workstation path.
+- Default byte mode reads file metadata only. The optional tokenizer reads only
+  matched files locally; neither mode makes network calls, emits telemetry,
+  uploads content, or invokes a model.
+
+For non-Git directories, a clearly reported conservative filesystem fallback is
+used. See [`docs/PRIVACY.md`](docs/PRIVACY.md) and
+[`docs/DISCOVERY.md`](docs/DISCOVERY.md).
+
+## CI example
+
+```yaml
+- name: Enforce agent context budget
+  run: |
+    pipx install git+https://github.com/korovin-aa97/ctxfire.git@v0.1.0
+    ctxfire check --max-tokens-per-day 75000 \
+      --format sarif --output ctxfire.sarif
+```
+
+Pin a release tag or commit in CI. `ctxfire diff` also lets reviewers see
+whether a context-cost increase came from a new file, a removed file, or a size
+change.
+
+## Current limitations
+
+- The default byte-ratio estimator is intentionally approximate. The optional
+  tiktoken backend is more repeatable for a named encoding but still does not
+  prove which tokenizer a hosted agent runtime used.
+- Claude rule frontmatter is not parsed by the v0.1 adapter. Rules are counted
+  as always-on by default; set `claude_rules_activation =
+  "conditional"` only when that is a justified project-wide approximation.
+- User-level/global engine instructions are outside the project root and are
+  intentionally not scanned.
+- Imports referenced inside Markdown are not inferred. Add them explicitly.
+- Submodule contents and symlink targets are not traversed.
+- Subscription quotas, tool output, conversation history, cached-token billing,
+  output tokens, and runtime prompt construction are outside scope.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check .
+mypy src
+pytest
+python -m build
+```
+
+The report contract is public API. Schema changes require a new schema version,
+fixture updates, and a changelog entry.
+
+See the [deterministic before/after demo](docs/DEMO.md) for a small, inspectable
+`diff` walkthrough.
+
+Questions about bills, privacy, shared files, rules, symlinks, or prices are
+answered in the [FAQ](docs/FAQ.md).
+
+The default package has no runtime dependencies; the optional tokenizer stack
+and its licenses are recorded in the [dependency review](docs/DEPENDENCIES.md).
+
+## Project status
+
+`v0.1.0` is an intentionally small first release. It was exercised against 18
+unrelated public repositories; the dated methodology and results live in
+[`docs/VALIDATION.md`](docs/VALIDATION.md). Contributions are welcome—see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) and the extension guide.
+
+Built from operating a mixed Claude/Codex production fleet. The analyzer is a
+clean, generic extraction: no private fleet configuration or telemetry is
+included.
+
+MIT © 2026 Alexander Korovin.