# 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

```json
{
  "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

```json
{
  "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
}
```