codex-usage-widget AGENTS.md

AGENTS.md

Project

Codex Usage Widget is a local-only Windows desktop utility that displays Codex usage in a movable WPF widget and beside the Windows notification area. It targets .NET 10 and obtains rate-limit data through the locally installed Codex CLI and its official app-server protocol.

Before changing code, read README.md, docs/ARCHITECTURE.md, and the files directly involved in the requested behavior. For release work, also read docs/RELEASING.md.

Scope and decision discipline

• Implement the smallest complete change that satisfies the explicit request.
• Preserve behavior outside the requested scope.
• Do not add speculative features, configuration, compatibility layers, dependencies, or refactors for possible future needs.
• Prefer a direct implementation over a generalized system. Introduce an abstraction only when it solves a concrete current problem, protects an existing architectural boundary, or creates a necessary test seam.
• Do not turn an isolated change into a repository-wide cleanup. Mention worthwhile out-of-scope improvements separately instead of implementing them.
• Refactor only when the existing structure directly prevents a safe change. Keep the refactor proportional to the request.
• Keep one cohesive responsibility per type and file, but do not split trivial logic into extra files merely to reduce file size.
• Follow established project patterns unless the task explicitly requires changing them.
• Resolve discoverable, reversible, in-scope implementation details by inspecting the repository and following its existing patterns. Do not stop for minor choices that do not materially affect the result.
• Ask before making a choice that materially changes UX, architecture, public behavior, data handling, packaging, supported platforms, or dependencies.

Authorization and repository safety

• Treat existing uncommitted changes as user-owned. Do not overwrite, revert, reformat, stage, or include them unless they are explicitly part of the task.
• Do not commit, push, create or update a pull request, tag, publish a release, rewrite history, or otherwise change remote state unless the user explicitly requests that action.
• When the user asks for a local implementation or preview, stop after local validation and wait for approval before any Git or GitHub publishing action.
• Never use destructive Git or filesystem commands to resolve an unrelated workspace problem.
• Keep personal machine paths, usernames, credentials, tokens, and environment-specific values out of tracked files. Use repository-relative paths in documentation and configuration.