Metadata Conventions

Best practices for the metadata field on agent time entries and expenses.

Recommended Fields

Field	Type	Required	Description
`agent_id`	string	Yes	Unique agent identifier
`agent_type`	string	Yes	Platform: `claude-code`, `codex`, `cursor`, `langchain`, `crewai`, `custom`
`session_id`	string	Yes	UUID linking time + expense
`model`	string	Yes	LLM model name
`input_tokens`	number	Expense	Input tokens consumed
`output_tokens`	number	Expense	Output tokens consumed
`pr_url`	string	Optional	Pull request URL (for code review agents)
`task_description`	string	Optional	Human-readable task description

Size Limits

The metadata field has a 4KB maximum. In practice, this is more than enough for agent context. If you’re hitting the limit, you’re likely storing data that belongs in notes or an external system.

Naming Conventions

Use snake_case for all metadata keys.
Use consistent agent_id values across sessions (it’s the agent’s identity, not the session’s).
Use consistent agent_type values (lowercase, hyphenated).

What NOT to Store

Sensitive data (API keys, credentials, PII)
Full LLM responses or prompts
Binary data or base64-encoded content
Ephemeral data that changes every second

Example: Well-Structured Metadata

Time Entry

{
  "agent_id": "review-bot-01",
  "agent_type": "claude-code",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "claude-opus-4-6",
  "pr_url": "https://github.com/acme/app/pull/42"
}

LLM Expense

{
  "agent_id": "review-bot-01",
  "agent_type": "claude-code",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "claude-opus-4-6",
  "input_tokens": 25000,
  "output_tokens": 15000
}