# Set up the Time Momentum agent collector

Guide for AI agents (Claude Code, Cursor, Codex). The agent collector records time, model and tokens of the human's AI coding sessions through the hooks of Claude Code, Cursor and Codex and reports them to Time Momentum. It never sends source code, file names or conversations.

## Rule: the API key stays out of the conversation

- Never ask the human for the API key. Never read it from anywhere (clipboard, config files, environment variables) and never print it.
- Do not run `tm collect init` yourself. It asks for the key with hidden input, which only works in a real terminal. The human runs it in a terminal of their own.

## 1. Check Node.js

`node -v` must show at least 22.14. If Node.js is missing or older, ask the human before installing or upgrading it (macOS: `brew install node`, otherwise https://nodejs.org).

## 2. Install tm

- macOS and Linux: `curl -fsSL https://app.time-momentum.com/install-cli.sh | sh`
- Windows (PowerShell): `irm https://app.time-momentum.com/install-cli.ps1 | iex`

If tm is already installed (`tm version`), `tm update` is enough. The installer adds tm's directory to the PATH; your running shell does not see that yet. In your session, call tm by its full path: `~/.time-momentum/bin/tm` (Windows: `%USERPROFILE%\.time-momentum\bin\tm.cmd`).

## 3. Let the human connect

Ask the human to open a new terminal window (outside your session) and run:

```
tm collect init
```

The command asks for the API key with hidden input, lets the human choose the tools and asks whether to report subscription limits. The human creates the key in Time Momentum under Datenquellen › Agent-Kollektor. Other hooks stay untouched; a `.bak` file is written before every change. If the server rejects the key, the command exits with code 3 and changes nothing. If the new terminal cannot find tm, give the human the full path. Wait until they are done.

## 4. Verify

- `tm collect status --json`: `api_key` must be `true`; `tools` lists the connected tools.
- Trigger the first upload including existing sessions: `tm collect sync`.
- Sessions appear in Time Momentum under KI-Sessions; the setup page then shows "Verbunden".

## 5. Report back

Tell the human briefly which tools are connected and whether anything failed.

## Troubleshooting

- `command not found: tm`: use the full path or a new terminal.
- Exit code 3 from `tm collect init`: the key is invalid or revoked. The human creates a new one.
- More commands: `tm collect --help`, guide for agents: `tm skill`.