# Pomodoro Timer Extension for pi

A Pomodoro technique timer extension for the [pi coding agent](https://github.com/badlogic/pi-mono).

## Features

- **Live activity recap**: Shows the current agent task and elapsed run time in the footer
- **Previous-task recap**: Keeps the last completed task and duration visible while idle
- **Configurable timer**: Set work, break, and long break durations
- **Focus tracking**: Set focus when starting or mid-session
- **Visual status**: Combines activity and Pomodoro information in Pi’s footer
- **Commands**: Use `/pomodoro` for quick actions
- **Agent tools**: The AI agent can start/stop/check the timer directly
- **Persistence**: Timer state and completed activity recaps survive session reloads
- **Notifications**: Alerts when sessions complete
- **System prompt integration**: Timer status injected into LLM context
- **Auto-run**: On new sessions, prompts to start a pomodoro

## Installation

```bash
pi install npm:pi-pomodoro
```

## Usage

### Activity Recap

The footer updates automatically from Pi’s agent lifecycle:

- While the agent works: `● Implement activity recap · 1m 05s`
- When the agent is idle: `✓ Implement activity recap · 1m 05s`

Task prompts are normalized and shortened for a compact footer. Each completed
activity is stored as session-local extension data, providing a foundation for a
future task-history overlay.

### Commands

| Command | Description |
|---------|-------------|
| `/pomodoro start [focus]` | Start timer, optional focus task |
| `/pomodoro stop` | Pause timer |
| `/pomodoro reset` | Reset to work session |
| `/pomodoro status` | Show current status |
| `/pomodoro focus <task>` | Set/update current focus |
| `/pomodoro set <work> <break> <long>` | Configure durations (minutes, max 180 each) |
| `/pomodoro help` | Show usage information |

### Examples

```bash
# Start with default 25min work session
/pomodoro start

# Start with focus task
/pomodoro start Write API documentation

# Start with focus and default work session
/pomodoro start Fix authentication bug

# Change focus mid-session
/pomodoro focus Review PR #456

# Check current status
/pomodoro status

# Pause timer
/pomodoro stop

# Reset timer
/pomodoro reset

# Configure custom durations
/pomodoro set 30 10 20  # 30min work, 10min break, 20min long break
```

### Agent Tools

The AI agent can control the timer directly without user intervention:

| Tool | Description |
|------|-------------|
| `pomodoro_start` | Start the timer (optional `focus` param) |
| `pomodoro_stop` | Pause the timer |
| `pomodoro_reset` | Reset to work session |
| `pomodoro_status` | Get current status |
| `pomodoro_focus` | Set/update focus task |

Just ask: *"start a pomodoro session"* or *"check pomodoro status"*.

### Keyboard Shortcut

- `Ctrl+Shift+P` - Toggle timer start/stop

### Auto-Run Behavior

The extension automatically:
- Injects timer status into the system prompt so the LLM always knows the current session
- Suggests starting a pomodoro on fresh sessions
- Reminds about breaks when work sessions complete

The LLM can control the timer without user intervention - just say "start a pomodoro" or "check timer status".

## Default Settings

- **Work duration**: 25 minutes
- **Break duration**: 5 minutes
- **Long break**: 15 minutes (after 4 work sessions)

## Files

- `pomodoro.ts` - The extension source
- `pomodoro.test.ts` - Core logic unit tests
- `pomodoro.integration.test.ts` - Integration tests
- `pomodoro.security.test.ts` - Security tests
- `README.md` - This documentation

## Known Limitations

- **Timer precision**: Uses `setInterval` with 1-second ticks. Over long sessions, small drift may accumulate (typically negligible for 25-minute sessions).

## Testing

```bash
bun test
```

The test suite covers all three test files:
- `pomodoro.test.ts` — Core logic unit tests (time formatting, tick logic, session transitions)
- `pomodoro.integration.test.ts` — Integration tests (commands, state restoration, edge cases)
- `pomodoro.security.test.ts` — Security tests (prototype pollution, input validation, type confusion)

## Publishing to npm

This repo publishes automatically from GitHub Actions when a version tag matching
`v*` is pushed. Authentication uses npm Trusted Publishing (OIDC), so no npm
token is stored in GitHub.

### One-time setup

In the npm package settings, configure a GitHub Actions trusted publisher for
`lmn451/pi-pomodoro`, workflow filename `publish.yml`, with `npm publish` allowed.

### Release a new version

```bash
npm version patch
git push
git push --tags
```

You can also use `minor` or `major` instead of `patch`.