hrs / docs

Agent Integration

The problem

AI coding agents are sandboxed to their working directory. They can't write to a shared worklog at ~/worklogs/2026-04-13.md if they're running in ~/projects/my-app/.

Two ways to log

Agents can use either the CLI or the HTTP daemon — both write to the same SQLite database and produce the same markdown output.

Option A: CLI (hrs log)

The simplest option. No daemon needed — the CLI writes directly to the database.

hrs log -c dev -t "built auth flow" -b "oauth2 pkce,token refresh,tests" -e 3

This works if your agent is allowed to run arbitrary commands.

Option B: HTTP daemon (hrs serve)

If your agent is sandboxed and can't write outside its project directory, run the daemon and have agents POST via HTTP instead.

This is useful when you use tools like toolgate to restrict file writes to the project root — the agent can still log work via HTTP without needing write access to the hrs database.

# start the daemon (once)
hrs serve &

# agents post entries from any directory
curl -s -X POST http://localhost:9746/entries -d '{
  "category": "dev",
  "title": "built auth flow",
  "bullets": ["oauth2 pkce", "token refresh", "tests"],
  "hours_est": 3
}'

Agents can self-discover fields via GET /schema.

Which to use?

CLIHTTP
Setupnonerun hrs serve
Works sandboxedno (needs DB write)yes
Works without daemonyesno
Outputsamesame

The CLI itself is smart — it tries the HTTP server first, then falls back to a direct database write. So if the daemon is running, hrs log uses it automatically.

Example: Claude Code

Add to your CLAUDE.md:

## Work Logging

After completing significant work, log it:

```bash
hrs log -c dev -t "Short description" -b "outcome one,outcome two" -e 2
```

Log proactively. Don't wait to be asked.

If using toolgate or another sandbox that blocks writes outside the project directory, use curl instead:

## Work Logging

After completing significant work, log it:

```bash
curl -s -X POST http://localhost:9746/entries -d '{
  "category": "dev",
  "title": "Short description of work",
  "bullets": ["What was accomplished", "Key outcomes"],
  "hours_est": 2
}'
```

Discover fields: `curl -s http://localhost:9746/schema`

Log proactively. Don't wait to be asked.

Example: Cursor / other agents

Same pattern — any agent that can shell out can log:

# CLI
hrs log -c dev -t "..." -b "..." -e 1

# or HTTP
curl -s -X POST http://localhost:9746/entries \
  -H "Content-Type: application/json" \
  -d '{"category":"dev","title":"...","bullets":["..."],"hours_est":1}'

Tips

← API Reference TUI Explorer →