feat(peak_usage): add peak-time indicator module

README.md

@@ -107,6 +107,7 @@ Everything in the [Claude Code status line documentation](https://code.claude.co
 | `$cship.context_window` | Context window tokens (used/total) |
 | `$cship.context_window.used_tokens` | Real token count in context with percentage (e.g. `8%(79k/1000k)`) |
 | `$cship.usage_limits` | API usage limits (5hr / 7-day) |
+| `$cship.peak_usage` | Peak-time indicator (US Pacific business hours) |
 | `$cship.agent` | Sub-agent name |
 | `$cship.session` | Session identity info |
 | `$cship.workspace` | Workspace/project directory |
@@ -199,7 +200,7 @@ critical_style     = "bold red"
 
 ### 3. 💰 Cost Guardian
 
-Shows cost, lines changed, and rolling API usage limits all at once. Colour escalates as budgets fill.
+Shows cost, lines changed, rolling API usage limits, and a peak-time indicator. Colour escalates as budgets fill.
 
 <img src="./docs/examples/05.png" alt="Cost guardian cship statusline example" width="600">
 
@@ -210,7 +211,7 @@ Shows cost, lines changed, and rolling API usage limits all at once. Colour esca
 [cship]
 lines = [
   "$cship.model $cship.cost +$cship.cost.total_lines_added -$cship.cost.total_lines_removed",
-  "$cship.context_bar $cship.usage_limits",
+  "$cship.context_bar $cship.usage_limits $cship.peak_usage",
 ]
 
 [cship.model]
@@ -238,6 +239,9 @@ warn_threshold     = 70.0
 warn_style         = "bold yellow"
 critical_threshold = 90.0
 critical_style     = "bold red"
+
+[cship.peak_usage]
+style = "bold yellow"
 ```
 
 </details>

cship.toml

@@ -1,7 +1,7 @@
 [cship]
 lines = [
   "$starship_prompt",
-  "$cship.model $cship.cost $cship.context_bar $cship.usage_limits"
+  "$cship.model $cship.cost $cship.context_bar $cship.usage_limits $cship.peak_usage"
 ]
 
 [cship.model]
@@ -33,4 +33,8 @@ separator          = " "
 warn_threshold     = 60.0
 warn_style         = "fg:#e0af68"
 critical_threshold = 80.0
-critical_style     = "bold fg:#f7768e"
+critical_style     = "bold fg:#f7768e"
+
+[cship.peak_usage]
+symbol = "⏰ "
+style  = "fg:#e0af68"

docs/configuration.md

@@ -356,6 +356,37 @@ Setting both formats to `""` effectively hides the entire module.
 
 ---
 
+## `[cship.peak_usage]` — Peak-Time Indicator
+
+Shows when Anthropic's peak-time rate limiting is likely active, based on current time relative to US Pacific business hours. Returns nothing outside peak hours so the indicator disappears entirely.
+
+The check is purely time-based (Mon–Fri, default 07:00–17:00 Pacific) — no network calls.
+
+**Token:** `$cship.peak_usage`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `disabled` | `bool` | `false` | Hide this module |
+| `style` | `string` | — | ANSI style |
+| `symbol` | `string` | `"⏰ "` | Prefix symbol |
+| `format` | `string` | `"[$symbol$value]($style)"` | Format string; `$value` = `Peak` |
+| `start_hour` | `integer` | `7` | Start of peak window in US Pacific time (0–23) |
+| `end_hour` | `integer` | `17` | End of peak window in US Pacific time, exclusive (0–24). Use `24` to mean through end of day |
+
+**Variables:** `$value` (`Peak`), `$symbol`, `$style`
+
+US Pacific DST is handled automatically — PDT (UTC−7) from the second Sunday of March to the first Sunday of November, PST (UTC−8) otherwise.
+
+```toml
+[cship.peak_usage]
+symbol     = "⏰ "
+style      = "fg:#e0af68"
+start_hour = 7
+end_hour   = 17
+```
+
+---
+
 ## `[cship.starship_prompt]` — Full Starship Prompt
 
 Renders your entire Starship-configured prompt in a single call. Unlike per-module passthrough (e.g., `$directory`, `$git_branch`), this token invokes `starship prompt` to produce the complete rendered prompt with all configured modules.

docs/faq.md

@@ -64,6 +64,24 @@ The CShip `usage_limits` module fetches data from the Anthropic API using your C
 
 ---
 
+## How does the peak-time indicator handle time zones and DST?
+
+The `peak_usage` module checks whether the current time falls within the configured peak window in **US Pacific time**. It computes the UTC→Pacific offset internally — PDT (UTC−7) from the second Sunday of March through the first Sunday of November, PST (UTC−8) the rest of the year.
+
+There are no dependencies on system locale or `TZ` environment variable; the DST boundaries are calculated from the UTC date using Tomohiko Sakamoto's day-of-week algorithm.
+
+**Defaults:** Mon–Fri, 07:00–17:00 Pacific. To customise:
+
+```toml
+[cship.peak_usage]
+start_hour = 9   # 9 AM Pacific
+end_hour   = 18  # 6 PM Pacific (exclusive)
+```
+
+Set `end_hour = 24` to mean "through end of day". Weekends always return nothing.
+
+---
+
 ## Why is my cost or context not updating?
 
 **Cost and context window** data comes from Claude Code's JSON feed, which is updated on every statusline render (every time Claude Code calls `cship`). If these values appear stuck, check:

docs/showcase.md

@@ -69,15 +69,15 @@ critical_style     = "bold red"
 
 ## 3. Cost Guardian
 
-Shows cost, lines changed, and rolling API usage limits all at once. Colour escalates as budgets fill.
+Shows cost, lines changed, rolling API usage limits, and a peak-time indicator. Colour escalates as budgets fill.
 
 ![Cost guardian cship statusline](./examples/05.png)
 
 ```toml
 [cship]
 lines = [
   "$cship.model $cship.cost +$cship.cost.total_lines_added -$cship.cost.total_lines_removed",
-  "$cship.context_bar $cship.usage_limits",
+  "$cship.context_bar $cship.usage_limits $cship.peak_usage",
 ]
 
 [cship.model]
@@ -105,6 +105,9 @@ warn_threshold     = 70.0
 warn_style         = "bold yellow"
 critical_threshold = 90.0
 critical_style     = "bold red"
+
+[cship.peak_usage]
+style = "bold yellow"
 ```
 
 ---

src/config.rs

@@ -19,6 +19,7 @@ pub struct CshipConfig {
     pub session: Option<SessionConfig>,
     pub workspace: Option<WorkspaceConfig>,
     pub usage_limits: Option<UsageLimitsConfig>,
+    pub peak_usage: Option<PeakUsageConfig>,
     pub starship_prompt: Option<StarshipPromptConfig>,
 }
 
@@ -266,6 +267,22 @@ pub struct UsageLimitsConfig {
     pub separator: Option<String>,
 }
 
+/// Configuration for `[cship.peak_usage]` — peak-time indicator.
+/// Shows when Anthropic's peak-time rate limiting is likely active
+/// based on current time relative to US Pacific business hours.
+#[derive(Debug, Deserialize, Default)]
+pub struct PeakUsageConfig {
+    pub disabled: Option<bool>,
+    pub symbol: Option<String>,
+    pub style: Option<String>,
+    pub format: Option<String>,
+    /// Start of peak window in US Pacific time (0–23). Default: 7.
+    pub start_hour: Option<u32>,
+    /// End of peak window in US Pacific time, exclusive (0–24). Default: 17.
+    /// Use 24 to mean "through end of day" (e.g., `start_hour = 0, end_hour = 24` = all day).
+    pub end_hour: Option<u32>,
+}
+
 /// Configuration for `[cship.starship_prompt]` — renders full starship prompt as a token.
 #[derive(Debug, Deserialize, Default)]
 pub struct StarshipPromptConfig {

src/modules/mod.rs

@@ -3,6 +3,7 @@ pub mod context_bar;
 pub mod context_window;
 pub mod cost;
 pub mod model;
+pub mod peak_usage;
 pub mod session;
 pub mod usage_limits;
 pub mod vim;
@@ -44,6 +45,7 @@ pub const ALL_NATIVE_MODULES: &[&str] = &[
     "cship.workspace.current_dir",
     "cship.workspace.project_dir",
     "cship.usage_limits",
+    "cship.peak_usage",
 ];
 
 /// Static dispatch registry — the ONLY file modified when adding a new native module.
@@ -109,6 +111,8 @@ pub fn render_module(
         "cship.workspace.project_dir" => workspace::render_project_dir(ctx, cfg),
         // Usage limits module — non-blocking thread dispatch for live API data
         "cship.usage_limits" => usage_limits::render(ctx, cfg),
+        // Peak usage indicator — time-based peak-hour check
+        "cship.peak_usage" => peak_usage::render(ctx, cfg),
         other => {
             tracing::warn!("cship: unknown native module '{other}' — skipping");
             None