Desktop app
Best for visual setup, provider health, allocations, and protection settings.
Download from GitHub Releases ↗QuotaFence user guide
Protect shared AI quota
in a few minutes.
Install QuotaFence, sync a provider, give each project a weekly budget, then turn on protection. Your allocations and usage ledger stay on this device.
1InstallDesktop or CLI
2SyncCodex or Claude Code
3AllocateChoose folder and weekly %
4ProtectEnable the provider integration
New to QuotaFence?Start with the desktop app. Use the CLI when you want the same controls directly in your terminal.
01
Install QuotaFence
Choose the desktop app, the CLI, or both. They use the same local database, so allocations created in one appear in the other.
CLI and TUI
Best for terminal-first workflows, scripts, and managed agent launches.
npm install --global @quotafence/cliEarly release
Desktop builds may be unsigned. Download only from the official release page, verify the supplied checksum, then follow your operating system’s “Open anyway” flow. Do not disable system-wide security.
02
Sync your first provider
QuotaFence reads the allowance information already available to Codex or Claude Code on your device. It does not ask you to paste provider credentials into the app.
- 1Sign in to the provider normally
Make sure Codex or Claude Code already works on this computer.
- 2Open QuotaFence and select the provider
Choose Sync. The 5-hour and weekly windows should show their remaining percentage and reset time.
- 3Confirm the values
If a provider temporarily rate-limits refreshes, QuotaFence keeps the last successful checkpoint and shows its real age.
or from the terminal
qfence syncqfence status03
Allocate weekly quota by project
An allocation gives a local folder a percentage of the provider’s full weekly allowance. Five-hour limits remain provider-wide and are not divided between projects.
- 1Open a provider and choose Add allocation
Select the actual project folder so QuotaFence can match work to it.
- 2Choose a weekly percentage
For example, 30% reserves a project budget equal to 30 percentage points of the provider’s weekly window.
- 3Choose where quota comes from
QuotaFence uses unallocated quota first. If there is not enough, select another project to reduce.
qfence allocations add --provider codex --percent 30Run the command inside the project folder, or add --path /path/to/project. Use --provider claude for Claude Code.
04
Understand priority and Safe quota
Budget left and Safe quota answer different questions. This distinction prevents a low-priority project from spending quota promised to projects above it.
Budget left
Allocation − attributed usageHow much of this project’s own weekly budget has not been used.
Safe quota
Provider remaining − higher prioritiesHow much can be spent now without consuming quota protected for projects above it.
Priority 1 is protected first.
Drag projects in the desktop app or use Shift+K and Shift+J in qfence top. A project can have budget left but Safe quota equal to zero when higher-priority reservations consume the provider’s remaining capacity.
05
Protect Codex and Claude Code work
Protection checks the current project, provider, allocation, priority, and policy before supported work begins. A warning tells you capacity is running low; Stop blocks work that would consume protected quota.
Desktop integrations
Open Settings, choose Codex or Claude Code, and enable protection. Start a new task or conversation after enabling hooks; an already-open task cannot attach newly installed hooks. Send the first prompt, then use Check now in QuotaFence.
Managed terminal launch
Start the agent through QuotaFence so admission and reconciliation use the current folder’s allocation.
qfence codexqfence claudeIf a prompt is blocked unexpectedly
Check that the task belongs to the allocated folder, sync the provider, and inspect Safe quota—not only Budget left. Temporary provider refresh failures should not be treated as fresh data.
06
Use the desktop app
Overview
See all providers, allowance windows, sync age, and recent local activity.
Provider page
Sync 5-hour and weekly windows, review reset times, and manage that provider’s project allocations.
Allocations
Add folders, change weekly budgets, transfer quota, reorder priorities, and inspect full paths.
Settings
Configure general behavior and open provider-specific integration health and protection controls.
07
Use the CLI and terminal UI
Run qfence top for the interactive dashboard. It shows allowances, projects, and history using the same data as the desktop app.
←→Switch tabs
jkSelect a project
aAdd allocation
eEdit allocation
dDelete allocation
KJChange priority
rRefresh now
qQuit
Useful commands
qfence statusRefresh and show allowance statusqfence allocationsList project budgets and decisionsqfence historyShow basic daily usage historyqfence hereShow the project mapped to this folderqfence policyShow the effective Warn and Stop policyqfence --helpSee the complete command reference08
Review basic usage history
The desktop activity map and qfence history use a rolling local history. Provider movement that cannot be safely mapped to one project remains unattributed instead of being guessed.
qfence historyqfence history codex --days 9009
Troubleshooting
qfence is not found
Open a new terminal after npm installation. Confirm npm’s global binary directory is in your PATH, then run npm install --global @quotafence/cli again.
A provider shows stale data or a refresh warning
Wait briefly before syncing again. Providers can rate-limit repeated refreshes. QuotaFence displays the age of the last successful checkpoint rather than claiming stale data is current.
Protection says a new task is required
Create a new provider task after hooks are enabled, send its first prompt, then select Check now. Existing tasks cannot load hooks installed after they were opened.
A project has budget left but is stopped
Look at Safe quota and project priority. Higher-priority projects may reserve all currently remaining provider quota. Reorder priorities, change allocations, or wait for the weekly reset.
The wrong folder is detected
Run qfence here inside the folder. QuotaFence uses the most specific allocated ancestor. Remove or correct an unintended parent-folder allocation if necessary.
Still stuck? Open a GitHub issue ↗ without attaching prompts, source code, credentials, or the local database.
10
Privacy and local data
QuotaFence is local-first. The open-source core does not intentionally upload prompts, responses, source files, transcripts, provider credentials, or its SQLite ledger. Folder paths, allocations, policies, checkpoints, and basic history remain on your device.
What QuotaFence can see
It stores the minimum metadata needed to match a local folder to an allocation and reconcile provider-level quota movement. Provider APIs expose aggregate allowance data, so exact token usage by project is not always available.
Ready to begin?