CLI: Agent Mode

When running inside an AI agent environment, the CLI automatically detects the agent context and sets the source field to "agent".

Auto-Detection

The CLI checks for these environment variables:

Variable	Agent Platform	Sets agent_type to
`CLAUDE_SESSION_ID`	Claude Code	`claude-code`
`CODEX_SESSION_ID`	Codex	`codex`
`OPENCLAW_AGENT_ID`	OpenClaw	`openclaw`
`CURSOR_AGENT`	Cursor	`cursor`

When detected, the CLI automatically:

Sets source: "agent" on all entries.
Populates metadata.agent_type from the environment.
Uses the session ID as metadata.session_id.

Zero-Config Example (inside Claude Code)

# These are auto-detected — no flags needed
keito time start --project acme --task development
# ... agent works ...
keito time stop --notes "Implemented OAuth flow"
keito expense log --project acme --quantity 45 \
  --notes "claude-opus-4-6: 30k input + 15k output tokens"

The resulting time entry:

{
  "source": "agent",
  "metadata": {
    "agent_type": "claude-code",
    "session_id": "auto-detected-from-env",
    "agent_id": "review-bot-01"
  }
}

Explicit Mode

Override auto-detection with flags:

keito time start --project acme --task development \
  --source agent \
  --agent-id my-custom-bot \
  --session-id "$(uuidgen)"

Discarding Sessions

If an agent session fails and you want to discard the timer:

keito time stop --discard

This deletes the running time entry instead of saving it.

Paired Workflow

The recommended pattern for agent work is to always pair time and expense logging:

# Start
keito time start --project acme --task development

# ... agent does work ...

# Stop + log expense in one pipeline
keito time stop --notes "Reviewed 5 pull requests" && \
keito expense log --project acme --quantity 62 \
  --notes "claude-opus-4-6: 42k input + 20k output tokens"