CLI Tracker

The DevClocked CLI tracks your terminal sessions, automatically detecting git repositories and syncing activity to your dashboard. Perfect for developers who spend significant time in the terminal.

Built for AI-Assisted Development

The CLI tracker was designed specifically to capture time spent with terminal-based AI coding tools. If you use any of these, the CLI tracker is essential:

• Claude Code - Anthropic's agentic coding assistant runs in the terminal. The CLI tracker captures every session automatically.
• Codex CLI - Track terminal-native Codex sessions alongside your editor and GitHub work.
• Aider - AI pair programming in your terminal. Track your Aider sessions alongside your VS Code work.
• Cursor Composer (Terminal) - When you use Cursor's terminal features, the CLI tracker picks up the activity.
• GitHub Copilot CLI - Track time spent with Copilot's command-line tools.
• Any terminal workflow - SSH sessions, Docker builds, debugging, deployment scripts, and shell-heavy work all count.

Requirements

• Node.js 18 or higher
• npm or yarn

Installation

Install the CLI globally via npm:

npm install -g @devclocked/cli

Verify the installation:

devclocked --version

Authentication

Before tracking, you need to authenticate with your API key:

1. Go to your DevClocked Dashboard → Settings → API Keys
2. Generate a new API Key (name it something like "Terminal CLI")
3. Run the login command:

devclocked login

Paste your API key when prompted. Your credentials are stored locally at ~/.config/devclocked/cli.json.

Starting a Tracked Session

Launch a tracked terminal session:

devclocked session

This spawns a wrapped shell that tracks your activity. Use it like your normal terminal — all commands work as expected. When you're done, just type exit or press Ctrl+D.

Available Commands

Command	Description
devclocked login	Authenticate with your API key
devclocked session	Start a tracked terminal session
devclocked status	Check authentication and session state
devclocked flush	Force sync queued activity to server
devclocked summary	Show today's coding activity from the terminal
devclocked setup	Authenticate and register the MCP server for supported AI tools
devclocked mcp-server	Start the local MCP server used by AI assistants
devclocked mcp-list-tools	List the MCP tools exposed by DevClocked
devclocked mcp-health	Run MCP auth, connectivity, and tool checks
devclocked logout	Clear stored credentials

How It Works

The CLI uses a "wrapped shell" approach:

• Your default shell (zsh, bash, fish, etc.) runs inside a pseudo-terminal
• Activity timing is detected based on input/output events
• The current working directory is monitored to detect git repositories
• Ticks are batched and synced to DevClocked every 30 seconds

Privacy

The CLI tracker is designed with privacy in mind:

• No command logging — We never record what commands you type
• No argument logging — Command arguments and flags are not stored
• No output capture — Terminal output is not stored or transmitted
• Timing only — We only track when activity occurs, not what it is
• Local storage — Credentials are stored locally, never in the cloud

Troubleshooting

CLI not found after install?

Ensure your npm global bin directory is in your PATH. Run npm bin -g to find the location.

Session not syncing?

Run devclocked status to check if you're authenticated and devclocked flush to force a sync.