Agent Tracker

Record agent work sessions in Happy Amali via its MCP endpoint.

Setup

On first use, configure the MCP connection automatically:

Ask the user for their Happy Amali agent token:

I need a Happy Amali agent token to track time. Visit https://happyamali.xyz/mcp-setup, generate a token, and paste it here.
Write the MCP server config to .mcp.json at the project root (create or merge):

{
  "mcpServers": {
    "happy-amali-agent": {
      "type": "url",
      "url": "https://happyamali.xyz/api/mcp/agent",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN>"
      }
    }
  }
}

Replace <PASTE_TOKEN> with the value the user provided. After writing the file, the MCP tools become available automatically.

If the agent runtime does not support .mcp.json, write the equivalent config to the platform's MCP config file (e.g. .cursor/mcp.json for Cursor). If the runtime has no MCP config support, see references/http-api.md for direct HTTP access.

Workflow

1. Start a run

Call start_agent_run at the beginning of a work session.

Field	Required	Notes
idempotencyKey	yes	Fresh UUID
runId	yes	Fresh UUID — identifies this run
startedAt	yes	ISO-8601 timestamp (now)
agentName	yes	e.g. "claude-code", "codex"
runtime	yes	e.g. "claude-code", "cursor"
repo	no	Repository name or URL
branch	no	Current git branch
taskRef	no	Issue/ticket reference

2. Log activity segments

Call log_agent_activity for each unit of work. Multiple segments per run are expected.

Field	Required	Notes
idempotencyKey	yes	Fresh UUID
segmentId	yes	Fresh UUID
runId	yes	From step 1
startedAt	yes	ISO-8601 segment start
endedAt	yes	ISO-8601 segment end
activityType	yes	`task_execution` / `planning` / `review` / `coordination` / `idle`
summary	no	Short description of work done (max 500 chars)
taskRef	no	Issue/ticket reference
attribution	yes	See below

attribution object (required):

{
  "confidence": 0.8,
  "strategy": "heuristic",
  "project": { "name": "Project Name" },
  "category": { "name": "Engineering" }
}

confidence: float 0–1
strategy: "explicit" | "heuristic" | "fallback"
project: identify by name, shortCode, or id (at least one)
category: identify by name or id (at least one)
If project/category is unknown, omit them and set "unattributedReason" to one of: "missing_project", "missing_category", "unknown_mapping", "insufficient_context"

3. End the run

Call end_agent_run when the session is done.

Field	Required	Notes
idempotencyKey	yes	Fresh UUID
runId	yes	From step 1
endedAt	no	ISO-8601 (defaults to now)

4. Query summary (optional)

Call get_agent_time_summary to see totals for a time window.

Field	Required	Notes
from	yes	ISO-8601 window start
to	yes	ISO-8601 window end
groupBy	no	Array of `"source"`, `"project"`, `"category"`
includeIdle	no	Boolean, default false

Tips

All writes are idempotent — safe to retry with the same idempotencyKey.
Generate fresh UUIDs for every idempotencyKey, runId, and segmentId.
Use task_execution as the default activityType for coding work.
For attribution when inferring from context, use "strategy": "heuristic" and "confidence": 0.8.
Log segments as you go rather than one big segment at the end — overlapping segments are normalized automatically.

agent-tracker