Getting started

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

Before you begin

You need:

• Codex installed and signed in;
• Linux x86-64 (tested), or Linux/macOS on another architecture (untested);
• GLIBC 2.31 or newer for prebuilt Linux releases (Ubuntu 20.04 or newer);
• curl and tar.

Optional but useful during setup:

• systemctl on Linux if you want a background service;
• launchctl on macOS if you want a background service;
• Rust 1.85+ only if you want to build from source.

Quick preflight checks:

codex login status
command -v curl
command -v tar

Choose an install method

Pick one method based on what you need.

Method 1: One-line installer (recommended)

Run:

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

The installer checks your Codex sign-in, detects your platform, downloads the matching GitHub Release archive, and verifies its SHA-256 checksum. Linux x86-64 proceeds automatically. Every untested platform requires confirmation.

During install, you will see a prompt:

Install and start the LimitWise background service? [y/N]

• Enter y to enable scheduled background execution now.
• Enter n (or press Enter) to skip service setup and only install plugin + binary.

It then installs the marketplace and plugin:

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

The background service is a separate opt-in prompt. Only approval runs:

limitwise setup

This creates a systemd user service on Linux or a LaunchAgent on macOS. The macOS LaunchAgent path is untested, including on Apple Silicon. Open a new Codex conversation after installation.

Make the limitwise command available

The installer stores the binary in LimitWise’s user data directory. That directory is not normally on your shell’s PATH, so the plugin can be installed successfully while limitwise setup still reports command not found.

On Linux, make the command available through the commonly configured ~/.local/bin directory:

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

On macOS, use the same command directory but link to the macOS application-support path:

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

If the destination already exists, do not create a second link; verify the existing command with ls -l "$HOME/.local/bin/limitwise". Ensure this line is present in your shell startup file (~/.bashrc for Bash or ~/.zshrc for Zsh), then open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

Verify the command before setting up the optional service:

command -v limitwise
limitwise --version
limitwise setup

You can also run setup immediately without changing PATH:

# Linux
"${XDG_DATA_HOME:-$HOME/.local/share}/limitwise/bin/limitwise" setup

# macOS
"$HOME/Library/Application Support/LimitWise/bin/limitwise" setup

Method 2: Direct marketplace install (no prebuilt binary)

Use this if you only want the plugin registration and will handle the binary yourself:

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

This method does not install a prebuilt limitwise binary and does not set up the background service.

Method 3: Build from source

Rust 1.85 or newer is required. From plugins/limitwise:

cargo build --release
./target/release/limitwise setup

This builds a local binary using your machine toolchain, which can help when prebuilt binaries do not match your system runtime.

For another Linux or Unix-like platform, copy the locally built executable into the same user command directory and ensure that directory is on PATH:

mkdir -p "$HOME/.local/bin"
install -m 700 target/release/limitwise "$HOME/.local/bin/limitwise"
export PATH="$HOME/.local/bin:$PATH"
limitwise --version

On Windows or any operating system other than Linux and macOS, no prebuilt installer or native LimitWise background-service setup is currently supported. A successful local build can be run directly—for example, ./target/release/limitwise on Unix or .\\target\\release\\limitwise.exe in PowerShell—and its directory can be added to the user’s PATH. The limitwise setup command itself supports only Linux and macOS.

Update LimitWise

If you used the recommended one-line installer, rerun it:

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

The installer downloads and verifies the latest release, replaces the installed binary, and refreshes the plugin marketplace. If you use background scheduling, enter y at the service prompt so the service restarts with the new binary. This does not delete existing schedules, transcripts, or local usage data.

If you installed only the marketplace plugin, refresh it with:

codex plugin marketplace upgrade limitwise
codex plugin add limitwise@limitwise

Open a new Codex conversation after either update method. Existing conversations may retain the older plugin definition.

Verify installation

Run these checks after any install method:

command -v limitwise
limitwise --version
codex plugin list
codex plugin marketplace list

For service-based scheduling:

# Linux
systemctl --user status limitwise.service

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

If service setup fails with a runtime loader error (for example a GLIBC_* not found message), use Method 3 (build from source), then retry setup using the locally built binary.

Uninstall or reset

Complete cleanup depends on how you installed LimitWise. Use the method-based cleanup guide in Troubleshooting.

Run a small example

Create an empty project folder:

mkdir -p /absolute/path/to/limitwise-test

Generate an exact time about three minutes ahead:

# Linux
date -d '+3 minutes' --iso-8601=seconds

# macOS (untested, including Apple Silicon)
date -v+3M '+%Y-%m-%dT%H:%M:%S%z' | sed -E 's/([+-][0-9]{2})([0-9]{2})$/\1:\2/'

Open Codex Plan mode. Paste this request after replacing the project path, timestamp, and timezone:

Use $schedule-codex-tasks. Plan this batch, but do not schedule it yet.

Project: /absolute/path/to/limitwise-test
Timezone: Europe/Paris
Weekly cap: 1 percentage point of the full weekly limit.

Task 1 — run at <EXACT TIMESTAMP>:
Create status.txt containing exactly:
It's working
Success: status.txt exists with exactly that line.

Task 2 — run immediately after Task 1 succeeds:
Replace status.txt with exactly:
It's working
Edited by LimitWise
Success: status.txt contains exactly those two lines.

Task 3 — run immediately after Task 2 succeeds:
Replace status.txt with exactly:
It's working
Edited by LimitWise
Modified by LimitWise
Success: status.txt contains exactly those three lines.

Codex will show a proposal. Check the path, time, timezone, budget, model, and effort. Confirm it, leave Plan mode, then say:

Create this confirmed schedule.

Terse output is built into $schedule-codex-tasks; there is no separate skill to install or invoke. LimitWise replies tersely by default when the skill is active. Say normal mode for fuller prose, terse mode to return to the default, or ultra terse for the shortest safe replies. Exact paths, timestamps, task IDs, commands, JSON, errors, and quota warnings are not shortened.

When asked, allow LimitWise to set up its background service. Do not close or suspend the computer before the first task is due.

Check progress by asking:

Use $schedule-codex-tasks and list all LimitWise tasks with their status.

After all tasks show completed, status.txt should contain:

It's working
Edited by LimitWise
Modified by LimitWise

Next steps

• Schedule real work
• Use a token budget
• Add a five-hour batch cap
• Continue quota-limited work
• Change or cancel a task
• Fix a task that did not run