Metadata Conventions

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

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
}