diff --git a/.github/release-notes/TEMPLATE.md b/.github/release-notes/TEMPLATE.md new file mode 100644 index 0000000..7b7afed --- /dev/null +++ b/.github/release-notes/TEMPLATE.md @@ -0,0 +1,26 @@ + + +## Highlights + +- **Change** — Explain what changed, why it changed, and how users benefit. + + + +## Installation or upgrade + +Explain how to install or upgrade and call out any required user action. + +## Compatibility + +Document breaking changes, migrations, known limitations, or remove this section when none apply. + +**Full Changelog**: https://github.com/nleononline/codex-context-window/compare/PREVIOUS_TAG...RELEASE_TAG diff --git a/.github/release-notes/v0.1.0.md b/.github/release-notes/v0.1.0.md new file mode 100644 index 0000000..cd87128 --- /dev/null +++ b/.github/release-notes/v0.1.0.md @@ -0,0 +1,41 @@ +Codex cannot normally see how much of its context window remains. In long conversations, compaction can arrive without warning and reduce important constraints, intermediate findings, or unfinished work before the model has a chance to preserve them. + +Codex Context Window v0.1.0 closes that blind spot. It gives the model compact, model-visible signals about its current context usage and lifecycle, so it can take approaching compaction into account while working. + +## Context awareness + +- **Live usage after prompts and tools** — `UserPromptSubmit` and `PostToolUse` report used tokens, the model context-window limit, and the percentage currently occupied. +- **Lifecycle signals** — the model is told when its session starts, its context has just been compacted or cleared, and a subagent session begins. +- **Debug mode** — setting `CODEX_CONTEXT_WINDOW_DEBUG=1` adds the originating hook to each signal and writes handler errors to `stderr`. +- **Safe fallback behavior** — missing, ambiguous, or unreadable session data produces no model-visible output instead of injecting misleading information. + +A typical signal looks like this: + +```text +YOUR CONTEXT WINDOW: 193800 / 258400 (75%) +``` + +## Lightweight and local + +The hook handler is a short-lived Rust process that reads Codex session files locally and makes no network requests. It scans the active transcript backwards in 64 KiB blocks and stops as soon as it finds the newest token-count event. + +In a 500-run reference benchmark on Apple Silicon macOS with a 7.8 MB transcript, a complete usage-hook invocation took 9.2 ms median and 12.3 ms p95, including launcher and process startup. + +Prebuilt, self-contained binaries are included for macOS, Linux, and Windows on Arm64 and x86-64. The launcher selects the correct binary automatically, so no additional runtime or dependencies are required after installation. + +## Installation + +Install the marketplace and plugin from a terminal: + +```bash +codex plugin marketplace add nleononline/codex-context-window --ref marketplace +codex plugin add codex-context-window@codex-context-window +``` + +In Codex Desktop, open the installed plugin and select **Trust all** in its hooks list. Then open a new chat or restart Codex so the hooks are loaded. + +## Compatibility + +The plugin reads Codex session files whose internal structure may change between Codex versions. If the expected token data is unavailable, the hook exits successfully without adding anything to the model context. + +**Full Changelog**: https://github.com/nleononline/codex-context-window/commits/v0.1.0 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 35c3530..a923af1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,6 +8,32 @@ permissions: contents: read jobs: + release-notes: + name: Validate release notes + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + - name: Validate versioned release notes + shell: bash + run: | + set -euo pipefail + + manifest_version="$( + python3 -c \ + 'import json; print(json.load(open(".codex-plugin/plugin.json"))["version"])' + )" + release_notes_file=".github/release-notes/v${manifest_version}.md" + + if [[ ! -s "${release_notes_file}" ]]; then + echo "release notes file ${release_notes_file} is missing or empty" >&2 + exit 1 + fi + + if grep -q "release-notes-template" "${release_notes_file}"; then + echo "release notes file ${release_notes_file} still contains the template marker" >&2 + exit 1 + fi + build: name: Build ${{ matrix.target }} runs-on: ${{ matrix.os }} @@ -74,7 +100,9 @@ jobs: publish: name: Publish marketplace if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master' - needs: build + needs: + - build + - release-notes runs-on: ubuntu-latest permissions: contents: write @@ -91,11 +119,13 @@ jobs: 'import json; print(json.load(open(".codex-plugin/plugin.json"))["version"])' )" release_tag="v${manifest_version}" + release_notes_file=".github/release-notes/${release_tag}.md" if git ls-remote --exit-code --tags origin "refs/tags/${release_tag}" >/dev/null 2>&1; then echo "tag ${release_tag} already exists" >&2 exit 1 fi echo "RELEASE_TAG=${release_tag}" >> "$GITHUB_ENV" + echo "RELEASE_NOTES_FILE=${release_notes_file}" >> "$GITHUB_ENV" - name: Stage marketplace shell: bash run: | @@ -166,4 +196,4 @@ jobs: run: >- gh release create "${RELEASE_TAG}" --target "${GITHUB_SHA}" - --generate-notes + --notes-file "${RELEASE_NOTES_FILE}" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f51376..58a5e4d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,10 @@ The local release binary is accepted by the launcher, so hooks can be tested dir ## Releasing 1. Update the version in `Cargo.toml` and `.codex-plugin/plugin.json`. -2. Run the local checks. -3. Create and push a matching tag such as `v0.1.0`. +2. Copy `.github/release-notes/TEMPLATE.md` to `.github/release-notes/vX.Y.Z.md`, remove the template marker and guidance, and write the user-facing release notes. +3. Explain the problem, the meaningful changes, and their impact. Pull requests and commits may be linked as supporting detail, but should not be the release summary. +4. Run the local checks and open a pull request. +5. Merge only after the release build matrix and release-notes validation pass. +6. Run the `Release` workflow manually from `master`. -The release workflow builds all supported targets, publishes the complete plugin marketplace to the generated `marketplace` branch, and creates a GitHub release with release notes. Do not edit the `marketplace` branch manually. +The release workflow builds all supported targets, publishes the complete plugin marketplace to the generated `marketplace` branch, creates the version tag, and uses the matching versioned file as the GitHub release description. Do not create the tag or edit the `marketplace` branch manually.