Content
# 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.
