codex-statusline 0.1.0__tar.gz

codex_statusline-0.1.0/LICENSE

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

codex_statusline-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: codex-statusline
+Version: 0.1.0
+Summary: A tmux statusline for OpenAI Codex CLI: context usage, 5h and weekly quota, and session tokens at a glance. Local-only.
+Author: Zimo Xu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moviw/codex-statusline
+Project-URL: Issues, https://github.com/Moviw/codex-statusline/issues
+Project-URL: Changelog, https://github.com/Moviw/codex-statusline/blob/main/CHANGELOG.md
+Keywords: codex,codex-cli,openai,statusline,tmux,quota,tokens,terminal
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codex-statusline
+
+**See your Codex context and quota at a glance.**
+
+[![tests](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml/badge.svg)](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/codex-statusline)](https://pypi.org/project/codex-statusline/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+English | [简体中文](README.zh-CN.md)
+
+A status bar for [OpenAI Codex CLI](https://github.com/openai/codex). It shows context used, 5-hour and weekly quota left with reset times, and session tokens. You keep running `codex` exactly as before.
+
+![codex-statusline demo](docs/preview.svg)
+
+```text
+CTX USED ███░░░░░ 35% | 5h ████████░░ 78% 5:41pm | week ████░░░░░░ 39% Fri 3:41pm | tok 1.2M
+```
+
+## Why
+
+- **No more `/status` interruptions.** Quota and context sit in view while you work.
+- **Local only.** Never reads `auth.json`, never calls a quota API, never makes extra model calls.
+- **Zero new habits.** Keep typing `codex`. `codex exec`, pipes, and scripts pass straight through to the official binary.
+- **Honest numbers.** Unknown shows as `--` and stale quota shows as `refresh`. A missing value is never passed off as 0% or 100%.
+- **Fits any width.** Segments collapse, then drop, as the terminal narrows.
+
+## Install
+
+Requires macOS or Linux, [tmux](https://github.com/tmux/tmux), and Codex CLI ≥ 0.159.0. Bash, Zsh, and Fish are all detected automatically.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Moviw/codex-statusline/main/install.sh | sh
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if needed (uv also fetches Python 3.11+ for you), installs the tool, then shows you the exact shell/hook diff and asks before writing anything.
+
+Prefer to do it yourself:
+
+```sh
+uv tool install codex-statusline    # or: pipx install codex-statusline
+codex-statusline install            # add --dry-run to only preview the diff
+```
+
+Then **open a new terminal** and run `codex`. The first time, Codex asks you to review a hook: confirm it is `codex-statusline binding`.
+
+Missing tmux? `brew install tmux` or `sudo apt install tmux`.
+
+## Usage
+
+```sh
+codex                     # same as always, now with a status bar
+codex resume --last
+codex exec 'task'         # non-interactive: passed straight through, no bar
+
+codex-statusline doctor   # check versions and dependencies
+codex-statusline preview --demo --width 80   # try it without launching Codex
+codex-statusline uninstall
+```
+
+Uninstall removes only what this tool added and still matches exactly. If you edited its block, it stops instead of overwriting. Backups live in `~/.local/share/codex-statusline/`.
+
+## Configuration
+
+Optional. Create `~/.config/codex-statusline/config.toml`:
+
+```toml
+segments = ["ctx", "5h", "week", "tokens"]  # pick and reorder
+theme = "dark"     # dark | light
+ascii = false      # true for terminals without block glyphs
+warn_at = 20       # quota remaining % that turns yellow
+crit_at = 5        # quota remaining % that turns red
+```
+
+Invalid values are reported and fall back to defaults.
+
+## How it works
+
+`codex` becomes a small shell function that starts the official CLI inside a private tmux session and draws the bar at the bottom. Data comes from two places only: the terminal title Codex already emits (model, context, thread id), and the rollout log of *this* session, which a SessionStart hook pins by exact path. The official binary is not replaced or patched, and your tmux config is not touched. Details: [docs/architecture.md](docs/architecture.md).
+
+## FAQ
+
+**How do I scroll or copy?** It runs inside tmux: press `Ctrl-B` then `[` to scroll and copy. The mouse wheel may behave differently from bare Codex.
+
+**Windows?** Not supported (tmux).
+
+**Is this official?** No. It is a third-party tool built on a version-sensitive integration.

codex_statusline-0.1.0/README.md

@@ -0,0 +1,86 @@
+# codex-statusline
+
+**See your Codex context and quota at a glance.**
+
+[![tests](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml/badge.svg)](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/codex-statusline)](https://pypi.org/project/codex-statusline/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+English | [简体中文](README.zh-CN.md)
+
+A status bar for [OpenAI Codex CLI](https://github.com/openai/codex). It shows context used, 5-hour and weekly quota left with reset times, and session tokens. You keep running `codex` exactly as before.
+
+![codex-statusline demo](docs/preview.svg)
+
+```text
+CTX USED ███░░░░░ 35% | 5h ████████░░ 78% 5:41pm | week ████░░░░░░ 39% Fri 3:41pm | tok 1.2M
+```
+
+## Why
+
+- **No more `/status` interruptions.** Quota and context sit in view while you work.
+- **Local only.** Never reads `auth.json`, never calls a quota API, never makes extra model calls.
+- **Zero new habits.** Keep typing `codex`. `codex exec`, pipes, and scripts pass straight through to the official binary.
+- **Honest numbers.** Unknown shows as `--` and stale quota shows as `refresh`. A missing value is never passed off as 0% or 100%.
+- **Fits any width.** Segments collapse, then drop, as the terminal narrows.
+
+## Install
+
+Requires macOS or Linux, [tmux](https://github.com/tmux/tmux), and Codex CLI ≥ 0.159.0. Bash, Zsh, and Fish are all detected automatically.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Moviw/codex-statusline/main/install.sh | sh
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if needed (uv also fetches Python 3.11+ for you), installs the tool, then shows you the exact shell/hook diff and asks before writing anything.
+
+Prefer to do it yourself:
+
+```sh
+uv tool install codex-statusline    # or: pipx install codex-statusline
+codex-statusline install            # add --dry-run to only preview the diff
+```
+
+Then **open a new terminal** and run `codex`. The first time, Codex asks you to review a hook: confirm it is `codex-statusline binding`.
+
+Missing tmux? `brew install tmux` or `sudo apt install tmux`.
+
+## Usage
+
+```sh
+codex                     # same as always, now with a status bar
+codex resume --last
+codex exec 'task'         # non-interactive: passed straight through, no bar
+
+codex-statusline doctor   # check versions and dependencies
+codex-statusline preview --demo --width 80   # try it without launching Codex
+codex-statusline uninstall
+```
+
+Uninstall removes only what this tool added and still matches exactly. If you edited its block, it stops instead of overwriting. Backups live in `~/.local/share/codex-statusline/`.
+
+## Configuration
+
+Optional. Create `~/.config/codex-statusline/config.toml`:
+
+```toml
+segments = ["ctx", "5h", "week", "tokens"]  # pick and reorder
+theme = "dark"     # dark | light
+ascii = false      # true for terminals without block glyphs
+warn_at = 20       # quota remaining % that turns yellow
+crit_at = 5        # quota remaining % that turns red
+```
+
+Invalid values are reported and fall back to defaults.
+
+## How it works
+
+`codex` becomes a small shell function that starts the official CLI inside a private tmux session and draws the bar at the bottom. Data comes from two places only: the terminal title Codex already emits (model, context, thread id), and the rollout log of *this* session, which a SessionStart hook pins by exact path. The official binary is not replaced or patched, and your tmux config is not touched. Details: [docs/architecture.md](docs/architecture.md).
+
+## FAQ
+
+**How do I scroll or copy?** It runs inside tmux: press `Ctrl-B` then `[` to scroll and copy. The mouse wheel may behave differently from bare Codex.
+
+**Windows?** Not supported (tmux).
+
+**Is this official?** No. It is a third-party tool built on a version-sensitive integration.

codex_statusline-0.1.0/codex_statusline.egg-info/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: codex-statusline
+Version: 0.1.0
+Summary: A tmux statusline for OpenAI Codex CLI: context usage, 5h and weekly quota, and session tokens at a glance. Local-only.
+Author: Zimo Xu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moviw/codex-statusline
+Project-URL: Issues, https://github.com/Moviw/codex-statusline/issues
+Project-URL: Changelog, https://github.com/Moviw/codex-statusline/blob/main/CHANGELOG.md
+Keywords: codex,codex-cli,openai,statusline,tmux,quota,tokens,terminal
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codex-statusline
+
+**See your Codex context and quota at a glance.**
+
+[![tests](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml/badge.svg)](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/codex-statusline)](https://pypi.org/project/codex-statusline/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+English | [简体中文](README.zh-CN.md)
+
+A status bar for [OpenAI Codex CLI](https://github.com/openai/codex). It shows context used, 5-hour and weekly quota left with reset times, and session tokens. You keep running `codex` exactly as before.
+
+![codex-statusline demo](docs/preview.svg)
+
+```text
+CTX USED ███░░░░░ 35% | 5h ████████░░ 78% 5:41pm | week ████░░░░░░ 39% Fri 3:41pm | tok 1.2M
+```
+
+## Why
+
+- **No more `/status` interruptions.** Quota and context sit in view while you work.
+- **Local only.** Never reads `auth.json`, never calls a quota API, never makes extra model calls.
+- **Zero new habits.** Keep typing `codex`. `codex exec`, pipes, and scripts pass straight through to the official binary.
+- **Honest numbers.** Unknown shows as `--` and stale quota shows as `refresh`. A missing value is never passed off as 0% or 100%.
+- **Fits any width.** Segments collapse, then drop, as the terminal narrows.
+
+## Install
+
+Requires macOS or Linux, [tmux](https://github.com/tmux/tmux), and Codex CLI ≥ 0.159.0. Bash, Zsh, and Fish are all detected automatically.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Moviw/codex-statusline/main/install.sh | sh
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if needed (uv also fetches Python 3.11+ for you), installs the tool, then shows you the exact shell/hook diff and asks before writing anything.
+
+Prefer to do it yourself:
+
+```sh
+uv tool install codex-statusline    # or: pipx install codex-statusline
+codex-statusline install            # add --dry-run to only preview the diff
+```
+
+Then **open a new terminal** and run `codex`. The first time, Codex asks you to review a hook: confirm it is `codex-statusline binding`.
+
+Missing tmux? `brew install tmux` or `sudo apt install tmux`.
+
+## Usage
+
+```sh
+codex                     # same as always, now with a status bar
+codex resume --last
+codex exec 'task'         # non-interactive: passed straight through, no bar
+
+codex-statusline doctor   # check versions and dependencies
+codex-statusline preview --demo --width 80   # try it without launching Codex
+codex-statusline uninstall
+```
+
+Uninstall removes only what this tool added and still matches exactly. If you edited its block, it stops instead of overwriting. Backups live in `~/.local/share/codex-statusline/`.
+
+## Configuration
+
+Optional. Create `~/.config/codex-statusline/config.toml`:
+
+```toml
+segments = ["ctx", "5h", "week", "tokens"]  # pick and reorder
+theme = "dark"     # dark | light
+ascii = false      # true for terminals without block glyphs
+warn_at = 20       # quota remaining % that turns yellow
+crit_at = 5        # quota remaining % that turns red
+```
+
+Invalid values are reported and fall back to defaults.
+
+## How it works
+
+`codex` becomes a small shell function that starts the official CLI inside a private tmux session and draws the bar at the bottom. Data comes from two places only: the terminal title Codex already emits (model, context, thread id), and the rollout log of *this* session, which a SessionStart hook pins by exact path. The official binary is not replaced or patched, and your tmux config is not touched. Details: [docs/architecture.md](docs/architecture.md).
+
+## FAQ
+
+**How do I scroll or copy?** It runs inside tmux: press `Ctrl-B` then `[` to scroll and copy. The mouse wheel may behave differently from bare Codex.
+
+**Windows?** Not supported (tmux).
+
+**Is this official?** No. It is a third-party tool built on a version-sensitive integration.

codex_statusline-0.1.0/codex_statusline.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+codex_statusline.egg-info/PKG-INFO
+codex_statusline.egg-info/SOURCES.txt
+codex_statusline.egg-info/dependency_links.txt
+codex_statusline.egg-info/entry_points.txt
+codex_statusline.egg-info/top_level.txt
+src/__init__.py
+src/__main__.py
+src/cli.py
+src/data.py
+src/entry.py
+src/hook.py
+src/launcher.py
+src/manage.py
+src/render.py
+tests/test_auto_shells.py
+tests/test_data.py
+tests/test_fish.py
+tests/test_management.py
+tests/test_render.py
+tests/test_startup.py
+tests/test_tmux.py

codex_statusline-0.1.0/codex_statusline.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

codex_statusline-0.1.0/codex_statusline.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-statusline = src.cli:main

codex_statusline-0.1.0/codex_statusline.egg-info/top_level.txt

@@ -0,0 +1 @@
+src

codex_statusline-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "codex-statusline"
+version = "0.1.0"
+description = "A tmux statusline for OpenAI Codex CLI: context usage, 5h and weekly quota, and session tokens at a glance. Local-only."
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "Zimo Xu" }]
+keywords = ["codex", "codex-cli", "openai", "statusline", "tmux", "quota", "tokens", "terminal"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/Moviw/codex-statusline"
+Issues = "https://github.com/Moviw/codex-statusline/issues"
+Changelog = "https://github.com/Moviw/codex-statusline/blob/main/CHANGELOG.md"
+
+[project.scripts]
+codex-statusline = "src.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

codex_statusline-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_statusline-0.1.0/src/__init__.py

@@ -0,0 +1,3 @@
+"""A local-only tmux status area for the official Codex CLI."""
+
+__version__ = "0.1.0"

codex_statusline-0.1.0/src/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

codex_statusline-0.1.0/src/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import json
+import os
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+
+
+def main():
+    args = sys.argv[1:]
+    from .launcher import child, launch, official, raw, version
+
+    if args and args[0] in ("launch", "raw"):
+        try:
+            return (launch if args[0] == "launch" else raw)(args[1:])
+        except KeyboardInterrupt:
+            return 130
+    if args and args[0] == "_child":
+        return child(args[1])
+    if args and args[0] == "hook":
+        from .hook import record
+
+        record()
+        return 0
+    parser = argparse.ArgumentParser(
+        description="Third-party local tmux statusline for the official Codex CLI."
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    for name in ("install", "uninstall"):
+        s = sub.add_parser(name)
+        s.add_argument(
+            "--shell",
+            choices=["auto", "bash", "zsh", "fish", "both", "all"],
+            default="auto",
+            help="default: all supported shells found on PATH",
+        )
+        s.add_argument("--home", default=str(Path.home()), help="target home (for isolated tests)")
+        s.add_argument(
+            "--yes",
+            action="store_true",
+            help="approve printed diff without interactive prompt",
+        )
+        s.add_argument("--dry-run", action="store_true")
+    sub.add_parser("doctor")
+    p = sub.add_parser("preview")
+    p.add_argument("--width", type=int, default=120)
+    p.add_argument("--theme", choices=["dark", "light"])
+    p.add_argument("--ascii", action="store_true")
+    p.add_argument("--tmux", action="store_true", help="emit tmux style syntax, not ANSI")
+    p.add_argument("--demo", action="store_true", help="show explicitly synthetic example data")
+    ns = parser.parse_args(args)
+    try:
+        if ns.action in ("install", "uninstall"):
+            from .manage import installation
+
+            return installation(ns, ns.action == "uninstall")
+        if ns.action == "doctor":
+            path = official()
+            data = {
+                "python": sys.version.split()[0],
+                "codex": path,
+                "codex_version": ".".join(map(str, version(path))),
+                "tmux": shutil.which("tmux"),
+                "shell": os.environ.get("SHELL"),
+                "tested_codex": "0.159.0",
+                "credentials_read": False,
+            }
+            print(json.dumps(data, indent=2))
+            return 0 if data["tmux"] and version(path) >= (0, 159, 0) else 1
+        if ns.action == "preview":
+            from .render import load_config, render
+
+            cfg = load_config()
+            now = time.time()
+            state = {
+                "model": "Codex",
+                "cwd": os.getcwd(),
+                "context_used": None,
+                "quotas": {},
+            }
+            if ns.demo:
+                state.update(
+                    model="DEMO GPT-6",
+                    context_used=35,
+                    cwd="~/project",
+                    branch="main",
+                    tokens=1_234_567,
+                    quotas={
+                        "5h": {
+                            "remaining": 78,
+                            "reset_at": now + 7200,
+                            "observed_at": now,
+                        },
+                        "weekly": {
+                            "remaining": 39,
+                            "reset_at": now + 172800,
+                            "observed_at": now,
+                        },
+                    },
+                )
+            print(
+                render(
+                    state,
+                    ns.width,
+                    theme=ns.theme or cfg["theme"],
+                    ascii_only=ns.ascii or cfg["ascii"],
+                    tmux=ns.tmux,
+                    segments=cfg["segments"],
+                    warn_at=cfg["warn_at"],
+                    crit_at=cfg["crit_at"],
+                )
+            )
+            return 0
+    except (OSError, ValueError, RuntimeError, KeyError) as error:
+        print(f"codex-statusline: {error}", file=sys.stderr)
+        return 1