GitHub - JinBa1/my-time-has-come: A local CLI safety brake that instruct Claude Code to wrap up before the 5-hour usage limit runs out.

An automatic safety brake for Claude Code before your usage windows run out

Ever found yourself watching the usage bar instead of the work? Or burned through a usage window mid-task and returned to a messy, half-edited repo?

mthc gives Claude Code a two-stage stop mechanism. You set soft and hard thresholds for "wrap up as soon as you can" and "stop using tools".

At the soft threshold, mthc injects a customizable wrap-up prompt so Claude can summarize progress, stabilize the repo, and write a handoff in the style you prefer. At the hard threshold, mthc blocks further tool use through Claude Code hooks and writes a deterministic handoff report, so the next session has a clear restart point.

mthc is the emergency brake you barely notice until it matters: Install it once, then keep using Claude Code normally. It stays quiet in the background and only steps in when the time comes.

• Drop in and keep working: no alternate workflow, no new session manager.
• Claude Code native: uses Claude Code statusline and hook surfaces directly; no daemon or runtime dependency.
• Soft landing before cutoff: customizable wrap-up prompts and handoff files.
• Hard stop when needed: tool-use blocking plus a deterministic restart report.
• Local and lightweight: local state only, no daemon, no telemetry, no network calls.
• Multi-session aware: one local source of truth across concurrent sessions.

Contents

• Quick Start
  • Install
  • Configure Thresholds
  • Customize Handoffs
• How It Works
  • How Claude Responds To Soft Stop
  • How Claude Responds To Hard Stop
  • Architecture
  • Program Boundaries
• Commands
• Troubleshooting
• Roadmap
• Contributing
• License

Quick Start

Install

Requirements:

• Claude Code CLI
• Linux-style or macOS shell environment
• Node.js and npm for the preferred npm install path
• mthc available on the PATH seen by Claude Code

The preferred install path is npm.

npm install -g @jinba1/mthc
mthc install
mthc doctor
mthc status

curl -LO https://github.com/JinBa1/my-time-has-come/releases/download/v0.3.0/mthc_0.3.0_linux_amd64.tar.gz
tar -xzf mthc_0.3.0_linux_amd64.tar.gz
sudo install -m 0755 mthc /usr/local/bin/mthc
mthc install
mthc doctor

Use the archive that matches your operating system and CPU. Release packages are built for Linux and macOS targets.

Source build fallback requires Go 1.26.2.

git clone https://github.com/JinBa1/my-time-has-come.git
cd my-time-has-come
go build -o mthc .
sudo install -m 0755 mthc /usr/local/bin/mthc
mthc install
mthc doctor
mthc status

mthc install updates ~/.claude/settings.json, writes ~/.config/mthc/config.toml, and initializes ~/.config/mthc/state.json. It captures your prior Claude Code statusline command so uninstall can restore it later.

Uninstall:

• removes mthc hook/statusline entries
• restores the captured prior statusline where possible

Configure Thresholds

Show the resolved config:

Defaults:

[policy]
enabled = true # Set false to observe status but disable soft/hard interventions.

[thresholds.five_hour]  # customize your own thresholds.
enabled = true
unit = "percent" # Threshold unit; "percent" is the default when omitted.
soft = 85 # Ask Claude to wrap up when 5-hour usage reaches this value.
hard = 95 # Arm the hard-stop gate and deterministic handoff at this value.

[thresholds.seven_day]
enabled = true
soft = 90 # Weekly quota is larger.
hard = 98

[handoff]
path_template = "{cwd}/.mthc/handoff-{session_id}-{window_id}-{window_start_ts}.md" # Where handoff files are written.

[display]
mode = "silent" # Keep mthc quiet and preserve your existing Claude Code statusline.

[statusline]
refresh_interval_seconds = 10 # Session liveness interval; active sessions are tracked at about 2x this value.

[hard_stop]
enable_pretool_deny = true # Block future tool calls after the hard threshold is reached.

Change thresholds with:

mthc config set thresholds.five_hour.soft 80
mthc config set thresholds.seven_day.enabled false
mthc config set policy.enabled false
mthc config validate

config set accepts only known keys and suggests the nearest match on a typo. The legacy soft_pct/hard_pct keys are rejected; mthc doctor reports a clear diagnostic if an old config still uses them.

Config resolution is:

built-in defaults < ~/.config/mthc/config.toml < ./.mthc/config.toml

Do not hand-edit the [internal] section in ~/.config/mthc/config.toml. It is install metadata used to restore your prior Claude Code settings.

Customize Handoffs

At the soft threshold, mthc injects a wrap-up prompt through Claude Code's PostToolBatch hook. The default prompt asks the agent to summarize the task, record repository state, write a handoff document, and stop.

You can provide your own soft prompt template:

mthc config set handoff.soft_prompt_path /path/to/soft-prompt.tmpl

The soft prompt template uses Go text/template variables:

{{.WindowID}} {{.WindowLabel}}
{{.UsedPercentage}} {{.ResetsAtHuman}} {{.ResetsAtUnix}}
{{.FiveHour.UsedPercentage}} {{.FiveHour.ResetsAtHuman}} {{.FiveHour.ResetsAtUnix}} {{.FiveHour.Absent}}
{{.SevenDay.UsedPercentage}} {{.SevenDay.ResetsAtHuman}} {{.SevenDay.ResetsAtUnix}} {{.SevenDay.Absent}}
{{.SessionID}} {{.HandoffPath}} {{.CWD}} {{.ModelID}}

For custom soft prompts, .UsedPercentage, .ResetsAtHuman, and .ResetsAtUnix describe the trigger window. If an existing template hard-codes 5-hour wording, use .WindowLabel in the copy, or use .FiveHour.* / .SevenDay.* when the prompt needs specific windows.

At the hard threshold, mthc writes a deterministic Markdown handoff before denying future tool use. The handoff includes:

• session ID and model ID
• trigger window, usage percentage, and reset time
• working directory
• transcript path
• resume instructions for the next Claude Code session

The default hard-stop handoff path is:

{cwd}/.mthc/handoff-{session_id}-{window_id}-{window_start_ts}.md

How It Works

How Claude Responds To Soft Stop

The soft stop appears inside the normal Claude Code conversation. In this example, Claude finishes reading context, acknowledges the usage-window warning, and writes the requested handoff file instead of continuing with the original plan.

How Claude Responds To Hard Stop

The hard stop is more forceful. In this example, Claude tries to write another file after the gate is armed, and Claude Code reports the PreToolUse blocking error instead of allowing the edit.

Claude can still respond in text, so the final message points to the reset time and the handoff path rather than pretending the process was killed.

Architecture

                Claude Code
             ┌──────┴────────┐
             │               │
        statusLine       hooks
         command    PostToolBatch / PreToolUse
             │               │
             ▼               ▼
   ┌────────────────┐  ┌────────────────┐
   │ statusline-shim│  │   hook-shim    │
   └───────┬────────┘  └───────┬────────┘
           │                   │
           │ observes usage    │ applies policy
           │ preserves prior   │ soft prompt / deny
           │ statusline        │
           └─────────┬─────────┘
                     ▼
        ┌──────────────────────────┐
        │ ~/.config/mthc/state.json│
        │ config.toml              │
        └────────────┬─────────────┘
                     │
         ┌───────────┴───────────┐
         ▼                       ▼
 soft wrap-up prompt    hard gate + handoff

The statusline shim observes Claude Code's usage-window payload and updates local state. The hook shim applies the policy when Claude Code invokes PostToolBatch or PreToolUse.

This split matters: the hard gate is armed during statusline processing, then enforced on later tool-use hooks. That keeps a crossed threshold from being lost just because a later observation is transiently lower.

Program Boundaries

• Soft stop is advisory. The model decides whether and when to follow it.
• Hard stop blocks future tool calls. It does not kill Claude Code, interrupt an in-flight tool, erase context already loaded by the model, or prevent a final text response.
• Both controls depend on Claude Code hook opportunities.
• State is local to one machine.

Commands

Troubleshooting

mthc is designed to fail open. If a hook cannot parse input, read config, lock state, or render output, it emits an empty response so Claude Code is not blocked by a broken governor.

When something behaves strangely, you can record the hook/statusline events and replay the policy decisions without touching live Claude Code state.

Recording files can contain local paths and session metadata. Treat recordings as private unless you have inspected them.

Roadmap

• Initial release supporting Claude Code CLI
• Packaged binaries and npm distribution
• Codex CLI, GEMINI CLI and OpenCode adapters
• Smarter thresholding based on burn rate and time-to-reset
• Stronger interruption mechanisms as Claude Code control surfaces evolve

Contributing

Issues and focused pull requests are welcome.

Before opening a pull request, run:

env GOCACHE=/tmp/mthc-go-build go build ./...
env GOCACHE=/tmp/mthc-go-build go vet ./...
env GOCACHE=/tmp/mthc-go-build go test ./...
gofmt -l .

License

This project is licensed under the MIT license.