Claude Timings Wrapper

claude-timed

Track how time is spent during Claude Code sessions: how long you're idle after the agent finishes, how long you spend typing, and how long the agent works.

How it works

`claude-timed` is a Node.js PTY wrapper that sits between your terminal and the `claude` process. It uses two mechanisms to track timing:

1. Keystroke interception — The wrapper intercepts stdin in raw mode to detect when you start typing (only real text input — arrow keys, Ctrl combos, Tab, etc. are ignored).
2. Claude Code hooks — Four hooks drive transitions:
   • UserPromptSubmit — Fires when the user actually submits a prompt. Writes a timestamp to a temp file so the wrapper knows when the agent started working.
   • Stop — Fires when the agent finishes responding. Writes a timestamp so the wrapper knows when the agent completed.
   • Notification (elicitation_dialog matcher) — Fires when the agent enters plan mode and asks the user to confirm/adjust. The Stop hook doesn't fire in this case, so this ensures the wrapper correctly transitions to IDLE.
   • PreToolUse (AskUserQuestion matcher) — Fires when the agent asks the user a question, treating it as a stop point similar to Stop.

These signals drive a state machine:

INITIAL  --(first keystroke)---------> typing started
         --(UserPromptSubmit hook)---> AGENT_WORKING

AGENT_WORKING --(Stop/Notification/PreToolUse hook)--> IDLE
              --(Ctrl+C)-----------------------------> IDLE (agent_interrupt)

IDLE --(first keystroke)--------------> USER_TYPING
     --(Stop hook, no prior submit)---> IDLE (background_agent_stop, time counted as agent work)

USER_TYPING --(UserPromptSubmit hook)-> AGENT_WORKING
            --(Ctrl+C)----------------> IDLE (typing discarded)

AGENT_WORKING + typing --(UserPromptSubmit)-> steering_submit logged, stays in AGENT_WORKING

IDLE --(120 min no activity)----------> PAUSED (session_paused; stop