yls-app

# Tool List Native macOS desktop application for monitoring [YLS Codex](https://ylscode.com) / AGI package quotas, usage, usage records, and local MCP snapshot data. The application provides a status bar entry, desktop dashboard, package source switching, theme skinning, status bar style configuration, and local HTTP MCP service, making it convenient for users and AI Agents to obtain the current account status. ## Application Display <p align="center"> <img src="images/yls_logo_1024.png" alt="YLS Monitor Assistant Logo" width="120" /> </p> <p align="center"> <img src="images/light_image.png" alt="YLS Monitor Assistant Light Screenshot" width="360" /> <img src="images/dark_image.png" alt="YLS Monitor Assistant Dark Screenshot" width="360" /> </p> ## Feature Overview - Codex Package Monitoring: balance, daily quota, weekly quota, request times, token consumption, cost statistics, and package expiration information. - AGI Package Monitoring: package byte total, remaining bytes, used bytes, usage progress, and recent expiration packages. - Usage Records: paginated display of Codex usage logs, including time, model, token, cost, and detailed entries. - Status Bar Display: supports multiple menu bar display styles, including balance, used percentage, remaining percentage, double rows, and ring styles. - Multiple Data Sources: supports Codex and AGI packages, single display / double display statistical modes. - Settings: API Key, polling interval, startup, status bar text color, MCP service port. - Personalized Skin: official theme, system follow-up, light / dark theme, custom color skinning. - Local MCP Service: exposes account snapshots to local AI Agents, supporting HTTP snapshot interfaces and MCP JSON-RPC style interfaces. - Automatic Refresh: polls interfaces according to configuration cycles, also supports manual immediate refresh. ## System Requirements - macOS 13.0 or later - Xcode / Command Line Tools - Swift 6.1 or later Check environment: ```bash swift --version xcode-select -p ``` ## Project Structure ```text . ├── Package.swift ├── README.md ├── Sources/yls-app │ ├── App/ # AppDelegate, window, status bar entry │ ├── Core/ # models, state management, UserDefaults configuration │ ├── MCP/ # local MCP / HTTP snapshot service │ ├── Networking/ # Codex / AGI network requests │ ├── Resources/ # application resources │ └── UI/ # SwiftUI dashboard and settings interface ├── images/ # README screenshots, logo, DMG background └── scripts/ └── build_macos_app.sh # local .app / .dmg packaging script ``` ## Running ### Command Line Running ```bash swift run yls-app ``` After running, the application window will open, and the macOS status bar entry will be displayed. The API Key needs to be filled in the settings for the first use. ### Xcode Running 1. Open Xcode. 2. Select `File -> Open...`, open the project root directory. 3. Select `yls-app` executable target. 4. Click `Run`. ### Common Development Commands ```bash # Debug build swift build # Release build swift build -c release # Clean build cache swift package clean ``` ## Configuration Description The application configuration is saved in the current macOS user's `UserDefaults`, and the main configurations include: - Codex API Key - AGI API Key - Current package source - Statistical display mode - Polling interval - Status bar display style - Status bar text color - MCP enablement - MCP port - Startup - Skin theme and custom color AGI Key also supports initialization through environment variables: ```bash export YLS_AGI_KEY="your AGI Token" swift run yls-app ``` API Key input only needs to fill in the token body, and the application will automatically request the interface in the form of `Authorization: Bearer <token>`. ## Remote Interface ### Codex Package Information ```http GET https://code.ylsagi.com/codex/info Authorization: Bearer <codex_api_key> ``` Purpose: - Get Codex balance - Get package usage - Get daily / weekly quota - Get package expiration information ### Codex Usage Logs ```http GET https://code.ylsagi.com/codex/logs Authorization: Bearer <codex_api_key> ``` Purpose: - Get Codex usage records - Display model, token, cost, detailed link, and other data - Support paginated display in the application ### AGI Package Information ```http GET https://api.ylsagi.com/user/package Authorization: Bearer <agi_api_key> ``` Purpose: - Get AGI package list - Summarize total bytes, remaining bytes, used bytes - Calculate AGI usage progress and recent expiration time ## Local MCP Service The application can start the HTTP service on the local machine, default address: ```text http://127.0.0.1:8765 ``` The MCP service can be enabled / disabled in the application settings, and the port can be modified. ### HTTP Endpoints - `GET /health` - `GET /snapshot` - `GET /mcp/snapshot` - `POST /mcp` Example: ```bash curl http://127.0.0.1:8765/mcp/snapshot ``` The snapshot content includes: - Current status - Last update time - Current package source - Codex / AGI Key configuration status - Balance, usage, progress, renewal / expiration time - Codex usage statistics and log summary - MCP service status - Current polling interval - Status bar display style ### MCP JSON-RPC Capability Supported methods: - `initialize` - `notifications/initialized` - `tools/list` - `tools/call` - `resources/list` - `resources/read` Built-in objects: - Tool: `get_codex_monitor_snapshot` - Resource: `yls://codex-monitor/snapshot` Call Tool example: ```bash curl -X POST http://127.0.0.1:8765/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_codex_monitor_snapshot" } }' ``` Read Resource example: ```bash curl -X POST http://127.0.0.1:8765/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "resources/read", "params": { "uri": "yls://codex-monitor/snapshot" } }' ``` ## Local Packaging The project provides macOS `.app` and `.dmg` packaging scripts: ```bash scripts/build_macos_app.sh ``` Default output: ```text dist/YLS Monitor Assistant.dmg ``` The script will execute: 1. `swift build -c release` 2. Generate `.app` directory structure 3. Generate `Info.plist` 4. Generate application `.icns` from `images/yls_logo_1024.png`, and use `images/yls_logo.png` as the small size icon for the DMG installation interface 5. Execute ad-hoc codesign 6. Generate DMG with background image Default build universal binary: ```bash BUILD_ARCHS="arm64 x86_64" scripts/build_macos_app.sh ``` Build single architecture only: ```bash BUILD_ARCHS="arm64" scripts/build_macos_app.sh BUILD_ARCHS="x86_64" scripts/build_macos_app.sh ``` Common configurable environment variables: ```bash APP_VERSION="0.2.0" \ APP_BUILD="12" \ BUNDLE_ID="com.yls.codex-monitor" \ APP_DISPLAY_NAME="YLS Monitor Assistant" \ scripts/build_macos_app.sh ``` ## Release Process If the repository has enabled GitHub Actions workflow, automatic build and release can be triggered through version tags: ```bash git tag v0.1.0 git push origin v0.1.0 ``` Expected products: - `YLS Monitor Assistant.dmg` - `.app` application package - `arm64 + x86_64` universal binary ## Frequently Asked Questions ### Prompt for unconfigured Key after running Configure Codex API Key and AGI API Key in the application settings. Only fill in the token body, no need to fill in the `Bearer` prefix. ### MCP port startup failure Check if the port is occupied: ```bash lsof -i :8765 ``` If occupied, modify the MCP port in the application settings. ### SwiftPM cache permission issue during command line build If the sandbox or permission restriction causes SwiftPM to be unable to write cache, clean and rebuild, or specify the writable cache directory: ```bash swift package clean CLANG_MODULE_CACHE_PATH=/tmp/yls-clang-cache swift build ``` ### Application cannot be opened after packaging The current script uses ad-hoc signature, suitable for local testing. Formal distribution requires using Apple Developer certificate signature and completing notarization. ## Development Notes - UI implemented using SwiftUI. - Status bar, window, and system capabilities managed by AppKit. - Network layer centralized in `Sources/yls-app/Networking`. - State management and data conversion centralized in `Sources/yls-app/Core`. - MCP service is a local HTTP service, only listening to `127.0.0.1`. - Do not submit real API Key to the repository.