English | 中文
Wombat is a plugin and local CLI for OpenAI Codex. Search conversation history, analyze Token usage, diagnose project problems, and review files for safe cleanup.
Ask in natural language to recover past decisions, resume work or investigate recurring failures. Wombat retrieves local evidence and calculates usage; Codex explains the findings, makes authorized changes and rechecks the original problem.
You: What did I work on in this project this week? Where did most of the Tokens go, and what should I do next?
Example answer: Most of this week's work involved installation fixes and additional tests. Total usage was 1.2 million Tokens, including 900,000 for installation troubleshooting.
The records show a successful macOS installation recheck and a code change following the Windows installation failure. I found no successful Windows recheck in those records. See turns 18–21 of the “Installation troubleshooting” conversation. Next, verify Windows installation under the original failure conditions to decide whether further fixes are needed.
You: We've twice discovered missing package files after publishing. How did we handle those failures, and how can we prevent another one?
Example answer: Both failures were handled by adding the missing files and rebuilding the package. Current code shows that scripts/ship.ts does not call the existing scripts/check-package.ts before uploading. Add that check before upload and stop publication if it fails.
You: Make that change, then recheck with a valid package and a package missing a required file.
Example recheck: Through the same publishing entry, the valid package passed. The package with a missing file failed the check, and the upload step did not run.
You: This work is finished. Check this project for temporary files, test outputs and build artifacts. List them first; don't delete anything yet.
Example preview: Two cleanup candidates occupy about 2.6 GB:
target/: 2.4 GB of compiler cache that can be regenerated by rebuilding..tmp/test-run-42/: a 180 MB temporary directory created by this test run. The tests have finished, and no later step needs it.
Keep source files, configuration, final test reports and the installation package awaiting delivery. Nothing has been deleted; cleanup would permanently remove the two selected directories.
You: Clean those two items, keep the reports and installation package, then recheck.
Example recheck: Both directories are absent at their original paths. Source files, configuration, final test reports and the installation package remain.
Stable: v0.6.4.
Install a version of Codex that supports native plugins, with the codex command available locally. Wombat's local analysis needs no separate API key or development tools.
On macOS or Linux, install Wombat and its plugin:
curl -fsSL https://raw.githubusercontent.com/YannByte/wombat/main/scripts/install/install.sh | sh -s -- --pluginOn Windows PowerShell:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/YannByte/wombat/main/scripts/install/install.ps1))) -Plugin- Open your project in Codex.
- Start a new conversation.
- Ask:
$wombat:wombat Show today's usage and the three tasks that used the most Tokens. Tell me whether the data is complete.
The answer uses the language of your question and includes the time range, total usage, top tasks and any missing data. For installation trouble, follow the reported recovery step; see the installation guide.
Ask with $wombat:wombat, for example:
| Task | Example request |
|---|---|
| Find a decision | Why did we choose this installation approach last time? Find the discussion and show its location in the original conversation. |
| Resume work | Where did we leave this project yesterday? Find the last confirmed results, unfinished work and next step. |
| Review the week | What did I work on in this project this week? Separate verified results from work that still needs checking. |
| Compare usage | How did this project's usage change from last week to this week? Which tasks and models account for the main differences? |
| Investigate a recurring problem | This installation problem keeps coming back. Use related records and current code to find what remains unresolved and suggest a change. |
| Verify a change | Recheck the original installation failure after this fix. What passed, and what remains unverified? |
| Free up space | Which temporary files, test outputs and build artifacts can be cleaned from this project? List them first and keep files needed for delivery. |
Use these examples as a starting point and explore questions from your own work. Add a project, time range or specific problem to narrow the scope. You can follow up with “Show the original conversation,” “Suggest the smallest change,” or “Recheck the original failure after the change.”
See the plugin guide for more uses, or the CLI guide for direct queries.
Ask $wombat:wombat for a past discussion, decision or unfinished task. Add the project, date range or words you remember. Wombat locates relevant records and returns original conversation locations.
Yes. Omit --plugin or -Plugin when installing and use the CLI directly. CLI queries support JSON output; see the CLI guide.
- CLI analysis stays local and makes no model calls. Selected Skill evidence enters the current Codex conversation and consumes Tokens; see privacy.
- Cleanup needs authorization for the selected items. It protects conversations, state, configuration and credentials; changed or unknown conditions block deletion. See the cleanup guide.
Release packages support macOS arm64/x64, Linux glibc arm64/x64, and Windows x64. Codex artifact cleanup currently targets macOS layouts. For unsupported record formats, see format recovery.
Rerun the installation command above to update Wombat and its Codex plugin. Keep any options for a specific version or custom installation directory.
See the installation guide for update options and runtime-only updates.
See the CLI guide for direct queries, JSON output and budget controls. See Contributing for source setup.
Report a problem or request. Describe what happened and the tools involved; no private logs are needed. Use the security policy for security reports.
MIT. See third-party notices for dependency licenses.