Troubleshooting

Compatibility warning: LimitWise has only been tested on Linux x86-64. macOS, including Apple Silicon, and other architectures are currently untested.

limitwise: command not found after installation

The one-line installer can complete successfully while the binary’s user data directory remains outside your shell’s PATH. This does not mean the Codex plugin installation failed.

Create a command link on Linux:

mkdir -p "$HOME/.local/bin"
ln -s "${XDG_DATA_HOME:-$HOME/.local/share}/limitwise/bin/limitwise" "$HOME/.local/bin/limitwise"

Create a command link on macOS:

mkdir -p "$HOME/.local/bin"
ln -s "$HOME/Library/Application Support/LimitWise/bin/limitwise" "$HOME/.local/bin/limitwise"

Ensure export PATH="$HOME/.local/bin:$PATH" is in ~/.bashrc or ~/.zshrc, open a new terminal, then verify and run setup:

command -v limitwise
limitwise --version
limitwise setup

If the link already exists, inspect it with ls -l "$HOME/.local/bin/limitwise" instead of replacing it blindly. On another operating system, build from source and add the resulting executable’s directory to the user PATH; native limitwise setup currently supports only Linux and macOS. See Make the limitwise command available for direct-path commands and platform details.

The local browser UI does not open

Run it without the browser opener and copy the printed launch URL into a browser on the same machine:

limitwise ui --no-open

Do not share that URL; its fragment is a single-use browser bootstrap. If the fragment has already been consumed, stop the process and launch a new UI session. A port collision from --port <port> is fatal; omit the flag to choose an available loopback port. The UI never binds externally, and it must not be placed behind a proxy or tunnel.

If the page reports stale or unavailable quota, run limitwise doctor and limitwise usage. Missing weekly telemetry, ambiguous telemetry, or a stale full snapshot blocks scheduling. If only five-hour telemetry is unavailable, LimitWise warns and continues with the weekly limit or token budget; its global reserve and any five-hour batch cap cannot be enforced. Browser task detail intentionally shows only a transcript path, never transcript contents.

Start with read-only diagnostics

limitwise doctor
limitwise doctor --json

Doctor does not repair or mutate anything. A warning still exits 0; a blocking failure exits 1. Common check IDs and remedies:

Codex does not see LimitWise

Check the plugin:

codex plugin list

If limitwise@limitwise is missing, add the GitHub marketplace, then reinstall:

codex plugin marketplace add aarsht7/limitwise
codex plugin add limitwise@limitwise

Open a new Codex conversation after installing or updating the plugin. Existing conversations may still use the older plugin definition.

LimitWise is outdated

For a complete installation, rerun the installer:

curl -fsSL https://raw.githubusercontent.com/aarsht7/limitwise/main/install.sh | sh

Choose y at the background-service prompt if you use scheduled execution. The installer replaces the binary, refreshes the marketplace, and restarts the service without deleting existing schedules or local data.

For a marketplace-only installation, run:

codex plugin marketplace upgrade limitwise
codex plugin add limitwise@limitwise

Then open a new Codex conversation.

The background service is not running

Install or restart it from the plugin directory:

./scripts/launch-limitwise setup

On Linux, inspect the service and recent messages:

systemctl --user status limitwise.service
journalctl --user -u limitwise.service -n 100 --no-pager

On macOS (untested, including Apple Silicon), inspect the service and recent error log:

launchctl print gui/$(id -u)/io.openai.limitwise
tail -n 100 "$HOME/Library/Application Support/LimitWise/logs/daemon.stderr.log"

If a run says quota telemetry unavailable: cannot start Codex app-server: No such file or directory (os error 2), the background service could not resolve the Codex executable from its restricted service PATH. Update LimitWise, then run confirmed service setup again. Current setup stores the resolved Codex path in the service definition, and runtime discovery also checks $HOME/.local/bin/codex plus the Codex standalone-install path.

After service setup, retry the skipped task as a new immutable attempt. Continue after quota reset is correctly rejected for this error because no valid quota snapshot was captured.

Stop or retry a running task

Open Operations, select the running task, and confirm Stop running task. Stop is cooperative: the daemon receives the request, interrupts Codex, records cancelled, then exposes Retry as new run with a fresh budget and future time. Pause is unavailable because Codex exec has no safe persistent pause/resume contract.

A task says missed

LimitWise allows five minutes of delay. If the computer was asleep, offline, or the service was stopped for longer, the task is marked missed instead of running late.

Create a new schedule with a future exact time. A missed task is not deferred automatically.

A task says quota_skipped

The task did not start because the five-hour reserve, weekly quota, or selected batch budget was exhausted. Ask Codex:

Use $schedule-codex-tasks. Show my current quota and the full status of task TASK_ID.

LimitWise does not silently downgrade ordinary quota-short work. Open the task detail and use Continue after quota reset, or ask for preview_retry_task with a fresh budget before explicitly confirming retry_task. Only quota_skipped and quota_interrupted tasks with valid recorded five-hour reset metadata can use quota resume.

A task says quota_interrupted

Codex started, but a quota threshold was reached while it was running. Check the task transcript and repository state, then use the task detail’s Continue after quota reset preview and explicitly confirm the new attempt. LimitWise never creates the follow-up automatically and never overwrites the interrupted task or its run history.

A continuation remains scheduled

The provider five-hour window reset, but global usage was still at or above the 90% threshold. LimitWise moved the same continuation to the next reported reset rather than failing it. Inspect current quota and task status before changing it.

Quota is unavailable

LimitWise needs unambiguous five-hour and weekly quota data from Codex. Confirm that the Codex CLI is installed and signed in:

codex login
./scripts/launch-limitwise usage

If quota data is still unavailable, LimitWise will not launch scheduled Codex work. This is intentional.

View token history

Ask Codex:

Use $schedule-codex-tasks and show my LimitWise token stats for the last year, month, week, and each of the last seven days.

You can also view the local JSON output:

./scripts/launch-limitwise stats

Runs stopped before Codex starts use zero tokens. If Codex started but did not report its final usage, LimitWise shows the token count as unavailable instead of guessing.

Remove LimitWise (complete cleanup)

Use the flow that matches your install method.

Before removing anything, close active Codex conversations that are currently using LimitWise.

Method A: Installed with the one-line installer (curl ... | sh)

1. Run uninstall with purge using the installed binary.

# Linux
${XDG_DATA_HOME:-$HOME/.local/share}/limitwise/bin/limitwise uninstall --purge

# macOS (untested, including Apple Silicon)
"$HOME/Library/Application Support/LimitWise/bin/limitwise" uninstall --purge

1. Remove Codex plugin registration.

codex plugin remove limitwise

1. Remove the marketplace source installed by the installer.

codex plugin marketplace remove limitwise

If your marketplace entry was saved with the full source name, remove that too:

codex plugin marketplace remove aarsht7/limitwise

1. Optional: remove plugin cache leftovers.

rm -rf ~/.codex/plugins/cache/limitwise
rm -rf ~/.codex/plugins/limitwise

Method B: Installed only with marketplace commands

If you installed with:

codex plugin marketplace add aarsht7/limitwise
codex plugin add limitwise@limitwise

Then remove:

codex plugin remove limitwise
codex plugin marketplace remove limitwise

No prebuilt binary cleanup is needed unless you manually installed one.

If codex plugin marketplace remove limitwise fails, run codex plugin marketplace list and remove the exact entry name shown there.

Method C: Running from source checkout

If you used ./scripts/launch-limitwise, run from plugins/limitwise:

./scripts/launch-limitwise uninstall --purge
codex plugin remove limitwise
codex plugin marketplace remove limitwise

Optional: delete build artifacts and local repo checkout:

rm -rf target
# Optional if you want to remove the local clone entirely:
# rm -rf /path/to/LimitWise-codex-plugin

Emergency cleanup if uninstall command cannot run

Use this when the installed binary fails to start (for example GLIBC_* not found).

# Linux service cleanup
systemctl --user disable --now limitwise.service 2>/dev/null || true
rm -f ~/.config/systemd/user/limitwise.service
systemctl --user daemon-reload 2>/dev/null || true

# macOS service cleanup (untested, including Apple Silicon)
launchctl bootout gui/$(id -u)/io.openai.limitwise 2>/dev/null || true
rm -f "$HOME/Library/LaunchAgents/io.openai.limitwise.plist"

# Data and binary cleanup
rm -rf ~/.local/share/limitwise
[ -n "${XDG_DATA_HOME:-}" ] && rm -rf "$XDG_DATA_HOME/limitwise"
[ -n "${LIMITWISE_HOME:-}" ] && rm -rf "$LIMITWISE_HOME/.local/share/limitwise"
rm -rf "$HOME/Library/Application Support/LimitWise"

# Plugin and marketplace cleanup
codex plugin remove limitwise 2>/dev/null || true
codex plugin marketplace remove limitwise 2>/dev/null || true
codex plugin marketplace remove aarsht7/limitwise 2>/dev/null || true

# Optional cache cleanup
rm -rf ~/.codex/plugins/cache/limitwise
rm -rf ~/.codex/plugins/limitwise

Verify cleanup

codex plugin list
codex plugin marketplace list

# Linux
systemctl --user status limitwise.service

# macOS (untested, including Apple Silicon)
launchctl print gui/$(id -u)/io.openai.limitwise

Expected result:

• no limitwise@limitwise in codex plugin list;
• no LimitWise marketplace entry;
• no active LimitWise user service.

--purge permanently deletes schedules, transcripts, and local usage history. This action cannot be undone.