Track AI CLI tools on a remote server

If you run Claude Code, Cursor CLI or another AI command-line tool on a remote Linux server, the desktop app on your own computer can’t see those sessions. Install the headless agent on the server. It tracks the same command-line tools as the desktop app (Claude Code, Cursor CLI, Codex CLI, Gemini CLI, OpenCode, Aider and Ollama), each running session separately, with its project and whether it’s working or waiting for you.

Install

curl -fsSL https://app.timeuno.io/install-agent.sh | bash

The script:

• downloads the binary for your CPU (x86_64 or arm64) into ~/.local/share/timeuno/bin/ and checks its checksum. If minisign is installed, it also checks the release signature;
• links it as timeuno-agent in /usr/local/bin (or ~/.local/bin if it can’t write there);
• adds a shell hook for bash, zsh and fish that notes the name of each command you run (more on that below);
• sets up a systemd user service and turns on lingering, so the agent keeps running after you log out.

Set TIMEUNO_NO_SERVICE=1 to skip the systemd service, and TIMEUNO_NO_SHELL_HOOK=1 to skip the shell hook. Set TIMEUNO_REF to a release tag (like agent-v0.2.0) to install a specific version.

Connect it

timeuno-agent pair

This prints a link. Open it in the browser on your own computer, not on the server, and approve the connection. See Connect a device. Then:

systemctl --user start timeuno-agent

What leaves your device

The agent sends the same data as the desktop app: when each AI session starts and ends, whether it’s working or waiting, the model, token counts and cost, and the project folder. Your prompts never leave your device, which here means the server. Neither do the AI’s answers, the output of commands or your code.

So your timesheet lines can say what you worked on, it also sends these task details:

• the title the AI tool itself gave the session;
• the subjects of the commits the AI made;
• the paths of the files the AI edited, relative to the project folder;
• the kind of task (fix, build, test, docs…) and the area it touched (billing, login…), picked on your device from a fixed list, never in your words;
• from the shell hook, the name of each command you run, plus its first word for a few tools like git, npm, make or docker (git push, docker compose), never the rest of the line, and the folder you ran it in, with your home folder shown as ~.

Anything in a title or commit subject that looks like a key or token is replaced with [redacted] first. See AI tools for more.

To stop sending task details, turn off Settings → Your data → Share task details. The details already stored are deleted. At its next check-in the agent stops sending them and empties the shell hook’s file of commands it hasn’t sent yet. Time tracking carries on.

Shell hook

For each of bash, zsh and fish that’s on the server, the installer adds the hook: one line at the end of ~/.bashrc or ~/.zshrc that ends in # timeuno-shell-hook, and a file in ~/.config/fish/conf.d/ for fish. Before each command, the hook writes the command’s name and folder to a file the agent sends. Only the command’s name is kept, plus its first word for a few tools like git, npm, make or docker, never the rest of the line: git commit -m "fix login" is recorded as git commit, and vim notes.txt as vim. It only records names that resolve to a real command, so a mistyped line or a pasted secret isn’t kept. Until the agent is connected and your account shares task details, the hook writes nothing.

• To skip it when you install, set TIMEUNO_NO_SHELL_HOOK=1.
• To add it later, run timeuno-agent shell-hook install.
• To remove it, run timeuno-agent shell-hook remove. This also deletes the commands it hasn’t sent yet.
• timeuno-agent status shows, for bash, zsh and fish, whether the hook is installed, when it last recorded a command and how big its file is.

Commands

Command	What it does
timeuno-agent pair	Connects the agent to your account.
timeuno-agent status	Shows the version, whether updates are automatic, which AI tools it found and the shell hook’s state per shell.
timeuno-agent shell-hook install	Adds the shell hook (the installer does this for you).
timeuno-agent shell-hook remove	Removes the shell hook.
timeuno-agent update	Installs the latest version now.
timeuno-agent run	Runs the agent in the foreground (the service does this for you).
timeuno-agent version	Prints the version.

Updates

When it runs as the systemd service, the agent checks for a new version a couple of minutes after it starts and then every 6 hours. It verifies the signature, swaps itself in and restarts.

• After timeuno-agent update, run systemctl --user restart timeuno-agent.
• To turn automatic updates off, set "auto_update": false in ~/.config/timeuno/config.json, or set TIMEUNO_NO_AUTO_UPDATE=1 in the service’s environment.

Agents installed from version 0.1.0 can’t update themselves. Run the install command again once.

If systemctl fails

If systemctl --user says Failed to connect to bus: Permission denied, set XDG_RUNTIME_DIR=/run/user/$(id -u) in that shell and try again.