### Manual package and launch Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Packages the app, kills existing instances, and launches the app in a new instance. ```bash ./Scripts/package_app.sh pkill -x CodexBar || pkill -f CodexBar.app || true open -n CodexBar.app ``` -------------------------------- ### Build and install CodexBar Linux from repository root Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Builds the Linux app with qmake6 and installs it per user. Requires Linux, C++17, make, qmake6, and Qt 6.4 or newer with Base, Declarative/Quick, Quick Controls, Network, D-Bus, and SVG icon support. Install Qt's Wayland plugin for Wayland sessions. Add --omarchy to install the compact Omarchy adapter, or --no-autostart to disable starting at login. Installation preserves settings and backs up existing preferences before changes. ```sh mkdir -p .local/linux-build cd .local/linux-build qmake6 ../../Integrations/Linux/codexbar-linux.pro make -j4 cd ../.. python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar ~/.local/bin/codexbar-linux --settings ``` -------------------------------- ### Selective Cherry-Pick Commands with Example Output Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Review upstream commits, identify which to sync (marked ✅) and which to skip (marked ❌), then cherry-pick the good ones. ```bash # Review upstream commits git log --oneline main..upstream/main # Example output: # 001019c style: fix swiftformat violations ✅ SYNC # e4f1e4c feat(vertex): add token cost tracking ✅ SYNC # 202efde fix(vertex): disable double-counting ✅ SYNC # 0c2f888 docs: add Vertex AI documentation ✅ SYNC # 3c4ca30 feat(vertexai): token cost tracking ✅ SYNC # abc123d refactor: remove Augment provider ❌ SKIP # Cherry-pick the good ones git cherry-pick 001019c git cherry-pick e4f1e4c git cherry-pick 202efde git cherry-pick 0c2f888 git cherry-pick 3c4ca30 # Skip abc123d (Augment removal) ``` -------------------------------- ### Run all tests with make test Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Runs the full test suite for the project. Use this to verify changes before committing. ```bash # Run all tests make test ``` -------------------------------- ### Quick build without tests Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Builds the release binary and packages the app without running tests. ```bash swift build -c release ./Scripts/package_app.sh ``` -------------------------------- ### Development Commands Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Commands for building, testing, formatting, packaging, and restarting the CodexBar app during development. ```bash # Build and run (kills old instances, builds, tests, packages, relaunches) ./Scripts/compile_and_run.sh # Quick build swift build # Run tests make test # Format code swiftformat Sources Tests swiftlint --strict # Package app ./Scripts/package_app.sh # Restart app after rebuild pkill -x CodexBar || pkill -f CodexBar.app || true cd /Users/steipete/Projects/codexbar && open -n /Users/steipete/Projects/codexbar/CodexBar.app ``` -------------------------------- ### Run tests only Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Runs the test suite via make. ```bash make test ``` -------------------------------- ### Build and test with compile_and_run.sh --test Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Builds the app and runs tests together. This is the main development script for verifying changes. ```bash # Build and test together ./Scripts/compile_and_run.sh --test ``` -------------------------------- ### Debug build Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Builds a debug binary and packages the app with the debug configuration. ```bash swift build # defaults to debug ./Scripts/package_app.sh debug ``` -------------------------------- ### Analyze Quotio Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Run the analysis script for quotio, then edit the documentation file. ```bash ./Scripts/analyze_quotio.sh # Then edit docs/QUOTIO_ANALYSIS.md ``` -------------------------------- ### Configure Git Remotes for CodexBar Fork Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md One-time setup to add upstream (steipete/CodexBar) and quotio (nguyenphutrong/quotio) remotes to your fork, then fetch all and verify. Expect origin to be git@github.com:topoffunnel/CodexBar.git. ```bash # Verify your fork is origin git remote -v # Should show: origin git@github.com:topoffunnel/CodexBar.git # Add upstream (steipete's original) git remote add upstream https://github.com/steipete/CodexBar.git # Add quotio (inspiration source) git remote add quotio https://github.com/nguyenphutrong/quotio.git # Fetch all remotes git fetch --all # Verify setup git remote -v # Should show: # origin git@github.com:topoffunnel/CodexBar.git (fetch/push) # upstream https://github.com/steipete/CodexBar.git (fetch/push) # quotio https://github.com/nguyenphutrong/quotio.git (fetch/push) ``` -------------------------------- ### Install CodexBar CLI Source: https://github.com/steipete/codexbar/blob/main/README.md Installs the CodexBar CLI after installing CodexBar.app in /Applications. ```bash # after installing CodexBar.app in /Applications ./bin/install-codexbar-cli.sh ``` -------------------------------- ### Analyze Quotio Repository with analyze_quotio.sh Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Run the quotio analysis script, which creates quotio-analysis-YYYYMMDD.md for reviewing interesting patterns. ```bash # Analyze quotio repository ./Scripts/analyze_quotio.sh # Creates: quotio-analysis-YYYYMMDD.md # Review the file for interesting patterns ``` -------------------------------- ### Weekly Quotio Review Commands Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Recommended Thursday routine: analyze quotio changes, review specific files, and document patterns. ```bash # Analyze recent quotio changes ./Scripts/analyze_quotio.sh # Review specific files of interest git show quotio/main:path/to/interesting/file.swift # Document patterns in docs/QUOTIO_ANALYSIS.md ``` -------------------------------- ### Setup: Symlink mimo-usage.py into PATH Source: https://github.com/steipete/codexbar/blob/main/docs/mimo.md Creates a symlink to the shipped Scripts/mimo-usage.py in ~/.local/bin and makes it executable. Required before running mimo-usage --update. ```bash ln -sf "$(pwd)/Scripts/mimo-usage.py" ~/.local/bin/mimo-usage chmod +x ~/.local/bin/mimo-usage ``` -------------------------------- ### codexbar serve Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Starts the CodexBar HTTP server. It exposes usage, cost, and dashboard endpoints, with authentication required on non-loopback hosts. ```APIDOC ## [GET] / ``` -------------------------------- ### Clean build and lint checks Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Run when build errors occur. Cleans the Swift package, builds, then checks formatting with swiftformat and linting with swiftlint. ```bash # Clean build swift package clean swift build # Check for format issues swiftformat Sources Tests --lint swiftlint --strict ``` -------------------------------- ### Install and run CodexBar for Omarchy Source: https://github.com/steipete/codexbar/blob/main/Integrations/Omarchy/README.md Build the Linux desktop app first, then run these commands from the repository root. The installer migrates old widget settings to ~/.config/codexbar/linux.json, backs up shell.json, and archives the old plugin. Provider authentication remains with the installed Linux CLI. ```sh python3 Integrations/Linux/install.py --omarchy --cli /absolute/path/to/codexbar ~/.local/bin/codexbar-linux --background omarchy restart shell ``` -------------------------------- ### codexbar serve Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Starts a foreground HTTP server for usage and cost JSON, a token-gated dashboard snapshot, and a built-in web UI at `/`. It also keeps the existing `/usage` behavior and supports various configuration flags. ```APIDOC ## codexbar serve ### Description Starts a foreground HTTP server for usage and cost JSON, a token-gated dashboard snapshot, and a built-in web UI at `/`. It also keeps the existing `/usage` behavior and supports various configuration flags. ### Method N/A (CLI command) ### Endpoint N/A (CLI command) ### Parameters #### Command-Line Arguments - `--all-accounts` (boolean) - Optional - Expands visible Codex profiles and configured token accounts in dashboard snapshots, with neutral numbered labels, no identity and generic errors by default. - `--identity` (string) - Optional - Sets identity mode: `full` includes identifying details, `redacted` exposes only masked emails/plan labels. Defaults to app's "Hide personal information" setting if not provided. - `--host` (string) - Optional - Accepts `localhost` or an IPv4 address, defaults to `127.0.0.1`. Binding a non-loopback host requires a dashboard token and `--allow-plain-http`. - `--port` (integer) - Optional - Defaults to `8080`. - `--refresh-interval` (integer) - Optional - Defaults to `60` seconds, controls the in-memory response cache TTL. - `--request-timeout` (integer) - Optional - Defaults to `30` seconds, bounds each request before returning `504 Gateway Timeout`; use `0` to keep waiting indefinitely. - `--dashboard-token` (string) - Optional - Sets the static bearer token for `GET /dashboard/v1/snapshot`. Prefer the `CODEXBAR_DASHBOARD_TOKEN` environment variable (it wins over the flag). Empty or whitespace-only tokens are startup errors. ### Response #### Success Response (200) - HTTP server starts and serves usage/cost JSON, dashboard snapshot, and web UI. #### Error Response (401) - Without a token, the snapshot route fails closed with `401`. #### Error Response (504) - Returns `504 Gateway Timeout` when a request exceeds `--request-timeout`. ``` -------------------------------- ### Sample text output from codexbar Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Example terminal output showing per-provider usage summaries for Codex, Claude Code, and Kilo. Includes session and weekly progress bars, pace/deficit info, reset times, credit counts, and account/plan details. Useful for verifying expected text formatting when running codexbar without --json. ```text == Codex 0.6.0 (codex-cli) == Session: 72% left [========----] Pace: 12% in deficit | Expected 16% used | Projected empty in 2h 30m Resets today at 2:15 PM Weekly: 41% left [====--------] Pace: 6% in reserve | Expected 47% used | Lasts until reset Resets Fri at 9:00 AM Credits: 112.4 left == Claude Code 2.0.58 (web) == Session: 88% left [==========--] Pace: On pace | Expected 13% used | Lasts until reset Resets tomorrow at 1:00 AM Weekly: 63% left [=======-----] Pace: On pace | Expected 37% used | Runs out in 4d Resets Sat at 6:00 AM Sonnet: 95% left [===========-] Account: user@example.com Plan: Pro == Kilo (cli) == Credits: 60% left [=======-----] 40/100 credits Plan: Kilo Pass Pro Activity: Auto top-up: visa Note: Using CLI fallback ``` -------------------------------- ### Review Upstream Changes Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Run the review script to check upstream changes. This is part of the verification checklist and next steps. ```bash ./Scripts/review_upstream.sh upstream ``` -------------------------------- ### codexbar-linux CLI commands Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Commands for the Linux adapter covering UI actions, snapshot, configuration, autostart, and quit. Snapshot, refresh, configure, autostart, and quit require an existing process; UI commands start one when needed. IPC clients load no GUI plugin, and --cli PATH and --no-tray apply when starting a new instance. ```sh codexbar-linux --background codexbar-linux --usage codexbar-linux --quick-view codexbar-linux --settings codexbar-linux --spending codexbar-linux --refresh codexbar-linux --snapshot codexbar-linux --snapshot --with-spending codexbar-linux --configure '{"provider":"both","refreshSeconds":300}' codexbar-linux --autostart status # also enable or disable codexbar-linux --quit ``` -------------------------------- ### Install CodexBar CLI via Homebrew tap Source: https://github.com/steipete/codexbar/blob/main/README.md Installs the CLI from the steipete/tap Homebrew formula (Linux today). ```bash brew install steipete/tap/codexbar ``` -------------------------------- ### Build and sign diagnostic bundle for production identity comparison Source: https://github.com/steipete/codexbar/blob/main/docs/status-item-diagnostics.md Build a debug-only diagnostic bundle from the diagnostic commit, then stage a copy of the installed app and replace its executable and resources. The recipe requires the maintainer's signing identity and uses the Developer ID 'Developer ID Application: Peter Steinberger (Y5PE65HELJ)'. It does not launch or overwrite the installed app. ```sh swift build --configuration debug --jobs 2 --product CodexBar diagnostic_bin_dir="$(swift build --configuration debug --show-bin-path)" mkdir -p .build/control-center-diagnostic codesign -d --entitlements :- /Applications/CodexBar.app \ > .build/control-center-diagnostic/entitlements.plist 2>/dev/null ditto /Applications/CodexBar.app .build/control-center-diagnostic/CodexBar.app cp "$diagnostic_bin_dir/CodexBar" .build/control-center-diagnostic/CodexBar.app/Contents/MacOS/CodexBar install_name_tool -add_rpath '@executable_path/../Frameworks' \ .build/control-center-diagnostic/CodexBar.app/Contents/MacOS/CodexBar for bundle in "$diagnostic_bin_dir"/*.bundle; do ditto "$bundle" ".build/control-center-diagnostic/CodexBar.app/Contents/Resources/$(basename "$bundle")" done /usr/libexec/PlistBuddy -c "Set :CodexGitCommit $(git rev-parse HEAD)" \ .build/control-center-diagnostic/CodexBar.app/Contents/Info.plist codesign --force --timestamp --options runtime \ --entitlements .build/control-center-diagnostic/entitlements.plist \ --sign 'Developer ID Application: Peter Steinberger (Y5PE65HELJ)' \ .build/control-center-diagnostic/CodexBar.app codesign --verify --deep --strict .build/control-center-diagnostic/CodexBar.app ``` -------------------------------- ### Install CodexBar Linux from release archive with Omarchy adapter Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Installs a CodexBar Linux release from an extracted CodexBarDesktop archive. Add --omarchy to install the compact Omarchy adapter. Installation is per user, preserves settings, and backs up existing preferences before changes. Reinstallation preserves disabled autostart. ```sh # Inside an extracted CodexBarDesktop archive: python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar --omarchy ``` -------------------------------- ### Initial Upstream Review with check_upstreams.sh and review_upstream.sh Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Check what's new in upstream and review changes in detail. review_upstream.sh creates a review branch named upstream-sync/upstream-YYYYMMDD. ```bash # Check what's new in upstream ./Scripts/check_upstreams.sh upstream # Review changes in detail ./Scripts/review_upstream.sh upstream # This creates a review branch: upstream-sync/upstream-YYYYMMDD ``` -------------------------------- ### Run CodexBar with Poe provider Source: https://github.com/steipete/codexbar/blob/main/docs/poe.md Starts CodexBar using the Poe provider. ```bash codexbar --provider poe ``` -------------------------------- ### Download, verify, and install CodexBar CLI and desktop app Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Run in sh or bash (from fish, enter bash first). Selects the latest stable GitHub release, downloads both matching archives, and stops on any download or checksum failure. The subshell leaves the current directory and shell options unchanged, uses a fresh temporary directory, and keeps the CLI and resource bundle together under ~/.local/lib/codexbar-cli. Add --omarchy only on Omarchy, or --no-autostart to disable starting at login. ```sh ( set -eu arch=$(uname -m) case "$arch" in x86_64|aarch64) ;; *) echo "Unsupported architecture: $arch" >&2; exit 1 ;; esac work=$(mktemp -d) trap 'rm -rf "$work"' EXIT cd "$work" api=https://api.github.com/repos/steipete/CodexBar/releases/latest curl -fsSL "$api" -o release.json version=$(python3 -c 'import json; print(json.load(open("release.json"))["tag_name"])') base="https://github.com/steipete/CodexBar/releases/download/$version" cli="CodexBarCLI-$version-linux-$arch.tar.gz" desktop="CodexBarDesktop-$version-linux-$arch.tar.gz" for archive in "$cli" "$desktop"; do curl -fSL "$base/$archive" -o "$archive" curl -fSL "$base/$archive.sha256" -o "$archive.sha256" sha256sum -c "$archive.sha256" done # Neither archive is extracted until both checksums have passed. cli_dir="$HOME/.local/lib/codexbar-cli" mkdir -p "$cli_dir" "$HOME/.local/bin" tar -xzf "$cli" -C "$cli_dir" ln -sfn "$cli_dir/codexbar" "$HOME/.local/bin/codexbar" "$HOME/.local/bin/codexbar" --version tar -xzf "$desktop" cd "${desktop%.tar.gz}" python3 Integrations/Linux/install.py --cli "$HOME/.local/bin/codexbar" ) ``` -------------------------------- ### Open CodexBar settings after installation Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Opens the installed CodexBar desktop app settings. Run after the installation block completes. ```sh ~/.local/bin/codexbar-linux --settings ``` -------------------------------- ### Example CLI output for coderabbit usage Source: https://github.com/steipete/codexbar/blob/main/docs/coderabbit.md Shows the expected output format of the `coderabbit usage` command, including organization, billing state, user, review count, and period reset date. ```text CodeRabbit Usage — current billing period Organization : Example Org Usage billing : inactive User : example-user Your reviews : 25 Period resets : 2026-09-30 ``` -------------------------------- ### Upstream Augment Removal Commit Summary Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Shows the files changed when upstream removed the Augment provider. Use this to identify commits to avoid when syncing. ```text Files changed: .../Providers/Augment/AugmentStatusProbe.swift | 627 deletions Tests/CodexBarTests/AugmentStatusProbeTests.swift | 88 deletions ``` -------------------------------- ### Install runtime packages on Arch (including Omarchy) Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Install required runtime packages for Arch-based distributions using pacman. Includes curl, python, and Qt 6 modules (qt6-base, qt6-declarative, qt6-svg, qt6-wayland). ```sh sudo pacman -S --needed curl python qt6-base qt6-declarative qt6-svg qt6-wayland ``` -------------------------------- ### codexbar-linux --autostart Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Manages autostart status. This command requires an existing process. ```APIDOC ## [CLI] codexbar-linux --autostart ### Description Manages autostart status. Use `status` to check, or `enable`/`disable` to change. ### Method CLI ### Command `codexbar-linux --autostart status` ### Parameters #### Path Parameters - **action** (string) - Required - `status`, `enable`, or `disable` ### Response No response body. ``` -------------------------------- ### codexbar-linux --background Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Starts the codexbar-linux process in the background. This is a UI command that starts a new instance when needed. ```APIDOC ## [CLI] codexbar-linux --background ### Description Starts the codexbar-linux process in the background. ### Method CLI ### Command `codexbar-linux --background` ### Parameters None ### Response No response body. ``` -------------------------------- ### Manual Trigger for Upstream Monitor Workflow Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Comment in the GitHub Actions workflow file to manually trigger the 'Monitor Upstream Changes' workflow via the GitHub UI. ```bash # Via GitHub UI: Actions → Monitor Upstream Changes → Run workflow ``` -------------------------------- ### Dev loop: compile and run Source: https://github.com/steipete/codexbar/blob/main/README.md Compiles and runs the app. Use `--test` to also run the sharded test suite before packaging/relaunching. `make check` runs SwiftFormat + SwiftLint, and `make docs-list` lists docs with frontmatter summaries. ```bash ./Scripts/compile_and_run.sh ./Scripts/compile_and_run.sh --test # also run the sharded test suite before packaging/relaunching make check # SwiftFormat + SwiftLint make docs-list # list docs with frontmatter summaries ``` -------------------------------- ### Quotio Pattern Learning Analysis Workflow Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Bash workflow for analyzing quotio's architecture without copying code. Steps include fetching the latest quotio, running the analysis script, reviewing specific files, documenting patterns, implementing independently on a feature branch, and committing with attribution. ```bash # 1. Fetch latest quotio git fetch quotio # 2. Analyze structure ./Scripts/analyze_quotio.sh # 3. Review specific areas git show quotio/main:path/to/AccountManager.swift # 4. Document patterns (not code!) # Edit docs/QUOTIO_ANALYSIS.md # 5. Implement independently # Create feature branch git checkout -b quotio-inspired/multi-account # 6. Commit with attribution git commit -m "feat: multi-account management Inspired by quotio's account switching pattern: https://github.com/nguyenphutrong/quotio/... Implemented independently using CodexBar architecture." ``` -------------------------------- ### codexbar-linux --spending Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Displays spending information. This is a UI command that starts a new instance when needed. ```APIDOC ## [CLI] codexbar-linux --spending ### Description Displays spending information. ### Method CLI ### Command `codexbar-linux --spending` ### Parameters None ### Response No response body. ``` -------------------------------- ### Weekly Upstream Check and Merge Workflow Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Recommended Monday routine: check upstream changes, review, cherry-pick valuable commits (skip Augment removal), test, and merge to main. ```bash # Check for new changes ./Scripts/check_upstreams.sh # If changes found, review them ./Scripts/review_upstream.sh upstream # Cherry-pick valuable commits (skip Augment removal) git cherry-pick # Test ./Scripts/compile_and_run.sh # Merge to main git checkout main git merge upstream-sync/upstream-$(date +%Y%m%d) ``` -------------------------------- ### Build script: package_app.sh Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Bundles CodexBarCLI into CodexBar.app/Contents/Helpers/CodexBarCLI. Use this script to create the app bundle. ```bash ./Scripts/package_app.sh ``` -------------------------------- ### codexbar-linux --settings Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Opens the settings interface. This is a UI command that starts a new instance when needed. ```APIDOC ## [CLI] codexbar-linux --settings ### Description Opens the settings interface. ### Method CLI ### Command `codexbar-linux --settings` ### Parameters None ### Response No response body. ``` -------------------------------- ### Make Scripts Executable and Test Upstream Monitoring Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Prepare the automation scripts and run check_upstreams.sh to see new commits in upstream and quotio plus a file change summary. Requires Scripts/*.sh to be executable. ```bash # Make scripts executable (if not already) chmod +x Scripts/*.sh # Test upstream monitoring ./Scripts/check_upstreams.sh # Should show: # - Number of new commits in upstream # - Number of new commits in quotio # - File change summary ``` -------------------------------- ### Check ai& usage via CLI Source: https://github.com/steipete/codexbar/blob/main/docs/aiand.md Displays the last 30 days of organization spend for the ai& provider. The `ai&` and `ai-and` aliases also work. ```bash codexbar usage --provider aiand ``` -------------------------------- ### Build and verify with swift build Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Builds the project and shows the last 10 lines of output. Expected to succeed; if type mismatches occur, follow them and align signatures. ```bash swift build 2>&1 | tail -10 ``` -------------------------------- ### Set Kimi Code API key via environment variable Source: https://github.com/steipete/codexbar/blob/main/docs/kimi.md Provides the Kimi Code API key through the environment. CodexBar calls GET https://api.kimi.com/coding/v1/usages with this key. ```bash export KIMI_CODE_API_KEY="kimi-code-api-key-here" ``` -------------------------------- ### codexbar-linux --quick-view Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Shows a quick view of the current status. This is a UI command that starts a new instance when needed. ```APIDOC ## [CLI] codexbar-linux --quick-view ### Description Shows a quick view of the current status. ### Method CLI ### Command `codexbar-linux --quick-view` ### Parameters None ### Response No response body. ``` -------------------------------- ### codexbar-linux --usage Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Displays usage information for the codexbar-linux command. This is a UI command that starts a new instance when needed. ```APIDOC ## [CLI] codexbar-linux --usage ### Description Displays usage information for the codexbar-linux command. ### Method CLI ### Command `codexbar-linux --usage` ### Parameters None ### Response No response body. ``` -------------------------------- ### Kill running CodexBar instances Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Force-kills any running CodexBar processes. Used when the compile_and_run script fails to kill old instances. ```bash pkill -x CodexBar || pkill -f CodexBar.app || true ``` -------------------------------- ### Learning from Quotio: Analyze, review, document, implement with attribution Source: https://github.com/steipete/codexbar/blob/main/docs/UPSTREAM_STRATEGY.md Use this workflow to analyze quotio for patterns, review specific implementations, document findings, and implement independently with proper attribution in the commit message. ```bash # Analyze quotio ./Scripts/analyze_quotio.sh # Review their multi-account implementation git show quotio/main:path/to/AccountManager.swift # Document patterns in docs/QUOTIO_ANALYSIS.md # Then implement independently in your fork # Commit with attribution git commit -m "feat: implement multi-account management Inspired by quotio's account switching pattern: https://github.com/nguyenphutrong/quotio/... Implemented independently using CodexBar's architecture." ``` -------------------------------- ### GET /dashboard/v1/snapshot Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Returns a dashboard-v1 JSON snapshot. Requires a static bearer token set via `--dashboard-token` or the `CODEXBAR_DASHBOARD_TOKEN` environment variable. ```APIDOC ## GET /dashboard/v1/snapshot ### Description Returns a dashboard-v1 JSON snapshot. Requires a static bearer token set via `--dashboard-token` or the `CODEXBAR_DASHBOARD_TOKEN` environment variable. ### Method GET ### Endpoint /dashboard/v1/snapshot ### Parameters #### Authentication - Bearer token required. Without a token, the route fails closed with `401`. ### Response #### Success Response (200) - Returns the dashboard snapshot JSON document. #### Error Response (401) - Returns `401` if no valid token is provided. ``` -------------------------------- ### Kill CodexBar processes and rebuild Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Use when the app won't launch. Kills all CodexBar instances and rebuilds via the compile_and_run script. ```bash # Kill all instances pkill -x CodexBar || pkill -f CodexBar.app || true # Rebuild and relaunch ./Scripts/compile_and_run.sh ``` -------------------------------- ### Build to confirm wiring compiles Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Runs swift build and shows the last 15 lines of output. Expected to succeed; if `UsageSnapshot.replacingIdentityOrganization` clashes with an existing extension, rename to `withAccountOrganization` and update the call site. ```bash swift build 2>&1 | tail -15 ``` -------------------------------- ### Git Workflow Commands Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Commands for checking status, creating a feature branch, committing changes, and pushing to the fork. Sync with upstream is marked as TBD. ```bash # Check status git status # Create feature branch git checkout -b feature/my-feature # Commit changes git add -A git commit -m "feat: description" # Push to fork git push origin feature/my-feature # Sync with upstream (TBD - see docs/FORK_ROADMAP.md Phase 4) ``` -------------------------------- ### Clean up old CodexBar app bundles Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md Removes all numbered CodexBar app bundles (e.g., 'CodexBar 2.app') from the project directory. The .gitignore already excludes these patterns. ```bash rm -rf "CodexBar "*.app ``` -------------------------------- ### PlugInKit registration (pkd) - check and force-add Source: https://github.com/steipete/codexbar/blob/main/docs/widgets.md Checks PlugInKit registration for the widget extension. The first command lists all widget extensions and greps for CodexBar; the second shows details for the specific widget ID. If missing or ignored, force-add and re-elect. Use -D to check for duplicates. ```shell pluginkit -m -p com.apple.widgetkit-extension -v | grep -i codexbar || true pluginkit -m -p com.apple.widgetkit-extension -i "$WIDGET_ID" -vv ``` ```shell pluginkit -a "$WAPPEX" pluginkit -e use -p com.apple.widgetkit-extension -i "$WIDGET_ID" ``` ```shell pluginkit -m -D -p com.apple.widgetkit-extension -i "$WIDGET_ID" -vv ``` -------------------------------- ### Minimal Provider Descriptor and Fetch Strategy (ExampleProviderDescriptor) Source: https://github.com/steipete/codexbar/blob/main/docs/provider.md Copy-paste template for adding a new provider. Defines the descriptor with metadata, branding, token cost, fetch plan, and CLI config, plus a basic fetch strategy that returns an empty usage snapshot. The strategy is marked as always available and never falls back. ```swift import Foundation public enum ExampleProviderDescriptor { public static let descriptor: ProviderDescriptor = Self.makeDescriptor() static func makeDescriptor() -> ProviderDescriptor { ProviderDescriptor( id: .example, metadata: ProviderMetadata( id: .example, displayName: "Example", sessionLabel: "Session", weeklyLabel: "Weekly", opusLabel: nil, supportsOpus: false, supportsCredits: false, creditsHint: "", toggleTitle: "Show Example usage", cliName: "example", defaultEnabled: false, isPrimaryProvider: false, usesAccountFallback: false, dashboardURL: nil, statusPageURL: nil), branding: ProviderBranding( iconStyle: .init(provider: .example), iconResourceName: "ProviderIcon-example", color: ProviderColor(red: 0.2, green: 0.6, blue: 0.8), confettiPalette: [ ProviderColor(hex: 0x3399CC), ProviderColor(hex: 0x66C2FF), ]), tokenCost: ProviderTokenCostConfig( supportsTokenCost: false, noDataMessage: { "Example cost summary is not supported." }), fetchPlan: ProviderFetchPlan( sourceModes: [.auto, .cli], pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [ExampleFetchStrategy()] })), cli: ProviderCLIConfig( name: "example", versionDetector: nil)) } } struct ExampleFetchStrategy: ProviderFetchStrategy { let id: String = "example.cli" let kind: ProviderFetchKind = .cli func isAvailable(_: ProviderFetchContext) async -> Bool { true } func fetch(_: ProviderFetchContext) async throws -> ProviderFetchResult { let usage = UsageSnapshot( primary: .init(usedPercent: 0, windowMinutes: nil, resetsAt: nil, resetDescription: nil), secondary: nil, updatedAt: Date(), identity: nil) return self.makeResult(usage: usage, sourceLabel: "cli") } func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool { false } } ``` -------------------------------- ### GET /accounts/ Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Discovers a specific saved provider token account or managed Codex account by its stable opaque ID, without fetching usage or exporting credentials. ```APIDOC ## GET /accounts/ ### Description Discovers a specific saved provider token account or managed Codex account by its stable opaque ID, without fetching usage or exporting credentials. ### Method GET ### Endpoint /accounts/ ### Parameters #### Path Parameters - `id` (string) - Required - The stable opaque lookup key for the account. #### Authentication - Requires bearer authentication on non-loopback binds. ### Response #### Success Response (200) - Returns the account details with its stable opaque ID and `active` flag. ``` -------------------------------- ### Build to verify schema compiles Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Runs swift build and shows the last 5 lines of output. Expected result: build succeeds. ```bash swift build 2>&1 | tail -5 ``` -------------------------------- ### GET /api/governance/virtual-keys/quota Source: https://github.com/steipete/codexbar/blob/main/docs/bifrost.md Retrieves quota and rate limit information for the calling virtual key. This self-service endpoint is scoped to the virtual key and does not require admin middleware. ```APIDOC ## [GET] /api/governance/virtual-keys/quota ### Description Retrieves quota and rate limit information for the calling virtual key. This self-service endpoint is scoped to the virtual key and does not require admin middleware. ### Method GET ### Endpoint {baseURL}/api/governance/virtual-keys/quota ### Parameters #### Headers - **x-bf-vk** (string) - Required - The virtual key used for authentication and scoping. ### Response #### Success Response (200) - **budgets** (array) - Ordered by shortest reset cycle; the shortest is the primary window, the next is the secondary window, and any further budgets appear as additional named windows. - **rate_limits** (array) - Contains components, each supplying its own token/request windows and usage. - **rate_limit** (object) - Bifrost's tightest-per-dimension compatibility merge of rate_limits components; used only when the component list is absent, null, or empty. - **is_active** (boolean) - Indicates whether the key is active; a disabled key keeps showing remaining budgets and rate limits with an inactive-key marker. - **per_model_usage** (array) - Per-model spend for the primary key-wide budget, shown when Bifrost's request logging provides it. - **override_amount** (number) - Determines the effective budget limit. - **override_mode** (string) - Determines the effective budget limit. - **override_cycles_remaining** (number) - Determines the effective budget limit. - **last_reset** (string) - Timestamp of the last reset; may be present for unused dimensions. - **max_limit** (number) - If 0, indicates an unlimited budget; reported spend remains visible as an API-spend row without inventing a quota window. ``` -------------------------------- ### Login command for Copilot: codexbar config login --provider copilot Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Advertised by Copilot's descriptor as an existing setup route. Use this to initiate login for the Copilot provider. ```bash codexbar config login --provider copilot ``` -------------------------------- ### UI/UX Patterns Commands Source: https://github.com/steipete/codexbar/blob/main/docs/QUOTIO_ANALYSIS.md Commands to find UI files and review the MenuBarView layout. ```bash # Find UI files git ls-tree -r --name-only quotio/main | grep -iE '(view|menu|ui)' # Review layouts git show quotio/main:path/to/MenuBarView.swift ``` -------------------------------- ### Quick build/test commands Source: https://github.com/steipete/codexbar/blob/main/AGENTS.md Use swift build for debug, swift build -c release for release, and make test for the sharded full suite. ```bash swift build ``` ```bash swift build -c release ``` ```bash make test ``` -------------------------------- ### GET virtual-keys quota endpoint Source: https://github.com/steipete/codexbar/blob/main/docs/bifrost.md Self-service endpoint scoped to the calling virtual key. No admin middleware required. CodexBar never requests or stores a Bifrost admin/master key. ```http GET {baseURL}/api/governance/virtual-keys/quota x-bf-vk: ``` -------------------------------- ### Run specific test with swift test --filter AugmentTests Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md Runs only the AugmentTests test case. Useful for debugging Augment provider issues without running the entire suite. ```bash # Run specific test swift test --filter AugmentTests ``` -------------------------------- ### Run CLI snapshot tests Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Run the CLI renderer and menu card model tests to verify existing tests continue to pass. ```bash swift test --filter CLIRendererTests 2>&1 | tail -15 ``` ```bash swift test --filter MenuCardModelTests 2>&1 | tail -15 ``` -------------------------------- ### Upstream Contribution Workflow Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md Bash workflow for preparing a clean branch from upstream, cherry-picking a fix without fork branding, reviewing, testing, pushing, and creating a PR on GitHub. Includes steps to link the originating issue in the PR body. ```bash # 1. Prepare clean branch from upstream ./Scripts/prepare_upstream_pr.sh fix-cursor-bonus # 2. Cherry-pick your fix (without fork branding) git cherry-pick # 3. Review - ensure no fork-specific code git diff upstream/main # 4. Test make test # 5. Push to your fork git push origin upstream-pr/fix-cursor-bonus # 6. Create PR on GitHub # Go to: https://github.com/steipete/CodexBar # Click "New Pull Request" # Select: base: steipete:main <- compare: topoffunnel:upstream-pr/fix-cursor-bonus # 7. Link the originating issue in the PR body (see below) ``` -------------------------------- ### GET /accounts Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md Discovers saved provider token accounts and managed Codex accounts without fetching usage or exporting credentials. IDs are stable opaque lookup keys; `active` means the configured selection. ```APIDOC ## GET /accounts ### Description Discovers saved provider token accounts and managed Codex accounts without fetching usage or exporting credentials. IDs are stable opaque lookup keys; `active` means the configured selection. ### Method GET ### Endpoint /accounts ### Parameters #### Authentication - Requires bearer authentication on non-loopback binds. ### Response #### Success Response (200) - Returns a list of discovered accounts with stable opaque IDs and `active` flags. ``` -------------------------------- ### Repository Overview Commands Source: https://github.com/steipete/codexbar/blob/main/docs/QUOTIO_ANALYSIS.md Commands to fetch the latest Quotio code, review file structure, and check recent activity. ```bash # Fetch latest quotio ./Scripts/analyze_quotio.sh # Review file structure git ls-tree -r --name-only quotio/main | grep -E '\.(swift|md)$' # Check recent activity git log --oneline --graph quotio/main --since="30 days ago" ``` -------------------------------- ### Quotio Pattern Adaptation Commands Source: https://github.com/steipete/codexbar/blob/main/docs/UPSTREAM_STRATEGY.md Creates an inspiration branch, views quotio implementation read-only, and commits with attribution. Emphasizes writing your own code rather than copying, and includes a commit message template with attribution link. ```bash # Create inspiration branch git checkout -b quotio-inspired/feature-name # View quotio implementation (read-only) git show quotio/main:path/to/file.swift # Implement similar pattern in your codebase # (write your own code, don't copy) # Commit with attribution git commit -m "feat: implement feature inspired by quotio Inspired by quotio's approach to [feature]: https://github.com/nguyenphutrong/quotio/commit/abc123 Implemented independently with CodexBar-specific patterns." ``` -------------------------------- ### LLM Proxy provider configuration with enterpriseHost Source: https://github.com/steipete/codexbar/blob/main/docs/llm-proxy.md Example provider configuration for LLM Proxy. Set the base URL via LLM_PROXY_BASE_URL or add enterpriseHost to the provider config. The base URL may point at the service root or /v1; CodexBar normalizes both to /v1/quota-stats. HTTPS is required unless the host is loopback, private-network, or .local mDNS. ```json { "id": "llmproxy", "enabled": true, "apiKey": "", "enterpriseHost": "https://proxy.example.com" } ``` -------------------------------- ### Install runtime packages on Fedora Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Install required runtime packages for Fedora using dnf. Includes curl, python3, and Qt 6 modules (qt6-qtbase, qt6-qtdeclarative, qt6-qtsvg, qt6-qtwayland). ```sh sudo dnf install curl python3 qt6-qtbase qt6-qtdeclarative qt6-qtsvg qt6-qtwayland ``` -------------------------------- ### Restart the right daemons (killall pkd, chronod, Dock, NotificationCenter) Source: https://github.com/steipete/codexbar/blob/main/docs/widgets.md Restarts pkd, chronod, Dock, and NotificationCenter. NotificationCenter alone is not enough. Requires sudo for chronod. ```shell killall -9 pkd || true sudo killall -9 chronod || true killall Dock NotificationCenter || true ``` -------------------------------- ### Build, package, and launch scripts Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT.md Run the full build, package, and launch workflow. Use --test to also run the sharded test suite before packaging. package_app.sh builds without tests, and launch.sh launches the existing app without rebuilding. ```bash # Full build, package, and launch (recommended) ./Scripts/compile_and_run.sh # Also run the sharded test suite before packaging/relaunching ./Scripts/compile_and_run.sh --test # Just build and package (no tests) ./Scripts/package_app.sh # Launch existing app (no rebuild) ./Scripts/launch.sh ``` -------------------------------- ### Install runtime packages on Debian 13 (Trixie) Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Install required runtime packages for Debian 13 using apt. Includes curl, python3, QML modules, and Qt 6 libraries. ```sh sudo apt update sudo apt install curl python3 qml6-module-qtquick qml6-module-qtquick-controls \ qml6-module-qtquick-layouts qml6-module-qtquick-templates qml6-module-qtquick-window \ qml6-module-qtqml-workerscript libqt6widgets6 libqt6svg6 qt6-wayland ``` -------------------------------- ### Install runtime packages on Ubuntu 24.04 (Noble) Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md Install required runtime packages for Ubuntu 24.04 using apt. Includes curl, python3, QML modules, and Qt 6 libraries. ```sh sudo apt update sudo apt install curl python3 qml6-module-qtquick qml6-module-qtquick-controls \ qml6-module-qtquick-layouts qml6-module-qtquick-templates qml6-module-qtquick-window \ qml6-module-qtqml-workerscript libqt6widgets6t64 libqt6svg6 qt6-wayland ``` -------------------------------- ### Run tests to verify failure Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Run the test suite filtered to `KiloUsageFetcherTests`. Expected: compile error because `_buildRequestForTesting` is not yet defined. ```bash swift test --filter KiloUsageFetcherTests 2>&1 | tail -15 ``` -------------------------------- ### Install CodexBar CLI via AUR Source: https://github.com/steipete/codexbar/blob/main/README.md Installs the CLI package from the Arch Linux AUR using yay. ```bash yay -S codexbar-cli ``` -------------------------------- ### Run make check Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md Runs swiftformat and swiftlint via make check, showing the last 30 lines. Expected: clean; fix reported issues by applying suggestions inline and re-running. ```bash make check 2>&1 | tail -30 ``` -------------------------------- ### Install CodexBar via Homebrew cask Source: https://github.com/steipete/codexbar/blob/main/README.md Installs the macOS app using Homebrew. Requires macOS 14+ (Sonoma). ```bash brew install --cask codexbar ``` -------------------------------- ### ctx.settings.get(key) Source: https://github.com/steipete/codexbar/blob/main/docs/plugin-prototype.md Reads a declared plain setting. Kind mismatches and undeclared keys throw. ```APIDOC ## GET ### Description Reads a declared plain setting. ### Method GET ### Endpoint `ctx.settings.get(key)` ### Parameters #### Path Parameters - **key** (string) - Required - The setting key. ### Response #### Success Response - **value** (any) - The setting value. ``` -------------------------------- ### Run focused plugin tests with swift test and script Source: https://github.com/steipete/codexbar/blob/main/docs/plugin-prototype.md Run the focused proof for plugin runtime, parity, details parity, and engine tests. The parity suites send canned responses through an injected ProviderHTTPTransport. ```shell swift test --filter ProviderPluginRuntimeTests swift test --filter ProviderPluginParityTests swift test --filter ProviderPluginDetailsParityTests ./Scripts/test-plugin-engines.sh ```