# ahin99/token_restart_bot architecture

> Architecture diagram of the GitHub repository ahin99/token_restart_bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahin99/token_restart_bot
- Repository: https://github.com/ahin99/token_restart_bot

## Overview

tokenbot is a macOS daemon-like utility that keeps Claude Code and Codex five-hour usage windows rolling. Its principal workflow is a one-minute launchd tick: inspect local CLI activity, determine whether a window has expired (including buffer and quiet-hour rules), send a short provider message when due, then record the outcome for later ticks and status checks. The README documents status, plan, manual ping, and install/uninstall capabilities. The sampled source is partial, so relationships for unsampled command handlers rely on README statements.

Main entry points: [`tokenbot.py`](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py) (Tick coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Scheduling and runtime"]
  node_tick["Tick coordinator<br/>[tokenbot.py]"]
  node_install["Launchd registration<br/>[tokenbot.py]"]
end

subgraph group_window["Window and provider"]
  node_activity["Activity reader<br/>[tokenbot.py]"]
  node_window_calc["Window scheduler<br/>[tokenbot.py]"]
  node_quiet["Quiet-hour rules<br/>[tokenbot.py]"]
  node_ping["Provider ping<br/>[tokenbot.py]"]
end

subgraph group_ops["Operations and state"]
  node_state[("Runtime state<br/>[tokenbot.py]")]
  node_logs["Bot log<br/>[tokenbot.py]"]
  node_status_plan["Status and plan<br/>[tokenbot.py]"]
end

node_operator(("Operator"))
node_launchd(("launchd timer"))
node_provider_clis["Claude / Codex CLI"]
node_local_logs["Provider activity logs"]

node_launchd -->|"runs each minute"| node_tick
node_operator -->|"runs tick"| node_tick
node_tick -->|"collects activity"| node_activity
node_activity -->|"reads timestamps"| node_local_logs
node_tick -->|"checks window"| node_window_calc
node_window_calc -->|"checks allowed time"| node_quiet
node_tick -->|"sends when due"| node_ping
node_ping -->|"runs CLI command"| node_provider_clis
node_tick -->|"records outcome"| node_state
node_tick -->|"writes results"| node_logs
node_operator -->|"requests status or plan"| node_status_plan
node_status_plan -->|"reads state"| node_state
node_operator -->|"registers service"| node_install
node_install -->|"configures timer"| node_launchd

click node_tick "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_activity "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_window_calc "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_quiet "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_ping "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_state "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_logs "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_status_plan "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"
click node_install "https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tick,node_install toneBlue
class node_activity,node_window_calc,node_quiet,node_ping toneAmber
class node_state,node_logs,node_status_plan toneMint
class node_operator,node_launchd,node_provider_clis,node_local_logs toneIndigo
```

## Components

### Scheduling and runtime

- [Tick coordinator](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Launchd registration](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`

### Window and provider

- [Activity reader](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Window scheduler](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Quiet-hour rules](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Provider ping](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`

### Operations and state

- [Runtime state](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Bot log](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`
- [Status and plan](https://github.com/ahin99/token_restart_bot/blob/main/tokenbot.py): `tokenbot.py`

### Other components

- **Operator**
- **launchd timer**
- **Claude / Codex CLI**
- **Provider activity logs**

## Connections

- launchd timer → Tick coordinator: runs each minute (evidence: `README.md`)
- Operator → Tick coordinator: runs tick (evidence: `README.md`)
- Tick coordinator → Activity reader: collects activity (evidence: `README.md`)
- Activity reader → Provider activity logs: reads timestamps (evidence: `README.md`)
- Tick coordinator → Window scheduler: checks window (evidence: `README.md`)
- Window scheduler → Quiet-hour rules: checks allowed time (evidence: `tokenbot.py`)
- Tick coordinator → Provider ping: sends when due (evidence: `README.md`)
- Provider ping → Claude / Codex CLI: runs CLI command (evidence: `README.md`)
- Tick coordinator → Runtime state: records outcome (evidence: `README.md`)
- Tick coordinator → Bot log: writes results (evidence: `README.md`)
- Operator → Status and plan: requests status or plan (evidence: `README.md`)
- Status and plan → Runtime state: reads state (evidence: `README.md`)
- Operator → Launchd registration: registers service (evidence: `README.md`)
- Launchd registration → launchd timer: configures timer (evidence: `README.md`)
