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.