Merge pull request #100 from stephenleo/docs/add-ttl-to-readme-sample-config

docs: add ttl field to README usage_limits sample config

Author: stephenleo

.github/workflows/claude-code-review.yml

@@ -3,8 +3,6 @@ name: Claude Code Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
-  pull_request_target:
-    types: [opened, synchronize, ready_for_review, reopened]
     # Optional: Only run on specific file changes
     # paths:
     #   - "src/**/*.ts"
@@ -14,7 +12,7 @@ on:
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
+    # Skip for external contributions
     # if: |
     #   github.event.pull_request.user.login == 'external-contributor' ||
     #   github.event.pull_request.user.login == 'new-developer' ||
@@ -23,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: write
+      pull-requests: read
       issues: read
       id-token: write
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name          = "cship"
-version       = "1.1.2"
+version       = "1.2.0"
 edition       = "2024"
 description   = "Beautiful, Blazing-fast, Customizable Claude Code Statusline"
 license       = "Apache-2.0"

Cargo.toml

@@ -208,6 +208,7 @@ critical_threshold = 70.0
 critical_style     = "bold red"
 
 [cship.usage_limits]
+ttl                = 60        # cache TTL in seconds; increase if running many concurrent sessions
 five_hour_format   = "5h {pct}%"
 seven_day_format   = "7d {pct}%"
 separator          = " "

README.md

@@ -295,7 +295,7 @@ Displays the current working directory or project directory.
 
 ## `[cship.usage_limits]` — API Usage Limits
 
-Displays 5-hour and 7-day API utilization percentages with time-to-reset. Fetches from the Anthropic API using your OAuth token (stored in the OS credential store). Results are cached for 60s or until the reset window passes.
+Displays 5-hour and 7-day API utilization percentages with time-to-reset. Fetches from the Anthropic API using your OAuth token (stored in the OS credential store). Results are cached for the configured TTL (default 60s) or until the reset window passes.
 
 **Token:** `$cship.usage_limits`
 
@@ -311,11 +311,13 @@ Displays 5-hour and 7-day API utilization percentages with time-to-reset. Fetche
 | `warn_style` | `string` | `"yellow"` | Style at warn level |
 | `critical_threshold` | `float` | — | % at which style switches to `critical_style` |
 | `critical_style` | `string` | `"bold red"` | Style at critical level |
+| `ttl` | `integer` | `60` | Cache refresh interval in seconds. Increase to reduce API pressure when running multiple concurrent sessions. |
 
 **Prerequisites:** On Linux/WSL2, install `libsecret-tools` and store your OAuth token with `secret-tool`. See [FAQ](/faq#usage-limits-linux) for setup instructions.
 
 ```toml
 [cship.usage_limits]
+ttl                = 300       # 5 minutes; increase if you run many concurrent sessions
 five_hour_format   = "5h {pct}%({reset})"
 seven_day_format   = "7d {pct}%({reset})"
 separator          = " "

docs/configuration.md

@@ -75,8 +75,8 @@ The CShip `usage_limits` module fetches data from the Anthropic API using your C
 - Run `cship explain` to confirm cship is receiving a valid JSON context.
 
 **Usage limits** data is cached:
-- Cache TTL: **60 seconds**, or until the rate-limit reset window passes (whichever comes first).
-- The first call in a session always fetches fresh data; subsequent calls within 60s return the cached value.
+- Cache TTL: **configurable (default 60 seconds)**, or until the rate-limit reset window passes (whichever comes first). Set `[cship.usage_limits] ttl` to increase the cache interval if you run many concurrent sessions.
+- The first call in a session always fetches fresh data; subsequent calls within the configured TTL return the cached value.
 - If the cache seems stale, check that your OAuth token is valid (re-login to Claude Code if needed).
 
 You can see the current cache state by running `cship explain` — it shows the usage limits value being rendered and any warnings if the API call failed.

docs/faq.md

@@ -97,6 +97,7 @@ critical_threshold = 70.0
 critical_style     = "bold red"
 
 [cship.usage_limits]
+ttl                = 60        # cache TTL in seconds; increase if running many concurrent sessions
 five_hour_format   = "5h {pct}%"
 seven_day_format   = "7d {pct}%"
 separator          = " "