Install the skill

The BurrowTime binary includes a small agent skill. Installing the binary does not activate tracking, and installing the skill does not start a timer. Choose the client you use:

burrowtime skill install codex
burrowtime skill install claude
burrowtime skill install cursor
burrowtime skill install gemini
burrowtime skill install opencode

To install the portable skill plus Claude Code's separate copy in one pass:

burrowtime skill install all

Check the setup

burrowtime skill doctor codex
# or check every installed target
burrowtime skill doctor all

The doctor checks the installed files, looks for an old duplicate Codex skill, and confirms that the burrowtime on yourPATH supports agent protocol 1.

Ask the agent to track

Include a BurrowTime project and a task or ticket in the request:

Track this work in BurrowTime under "client portal" +PORTAL-42.

BurrowTime creating, pausing, resuming, stopping, and reporting an owned Codex session — An owned agent session. Open the full-size demo.

The agent checks capabilities, opens one owned session, renews its lease during long work, pauses if it must wait for required input, and stops that exact session when the task ends.

No silent tracking. The bundled skill tells agents to track only after an explicit request. A normal chat or coding task does not start a timer.

What ownership protects

Mechanism	What it does
Session ID	Every later action targets the exact timer the agent started.
Idempotency key	A safe retry reuses the session instead of starting another.
Lease	An interrupted agent cannot leave an unbounded timer behind.
Pause and resume	Time spent waiting for a required answer can stay out of the total.
Manual reconciliation	You can stop the timer yourself without breaking the agent's later cleanup.

Set repository defaults

Place a .burrowtime.toml near the repository root for direct agent commands:

[agent]
project = "client portal"
task = "PORTAL-42"
repository = "portal-app"
lease = "30m"
task_from_branch = false

Set task_from_branch = true to infer ticket-shaped branch names such as PORTAL-42 when no task is configured. These defaults do not turn tracking on. The user still has to ask.

Inspect agent time

burrowtime agent status --active
burrowtime agent report --project "client portal"
burrowtime agent report --client codex --json
burrowtime agent recover

Use the protocol directly

Integrations can call the agent commands with JSON and retain the returnedsession.id. Clients with MCP support can use the bundledMCP server instead.