hrs / docs

Agent Integration

The problem

hrs started as a markdown file archive with a TUI wrapper. Three things broke that approach:

  1. Blind writes — Claude would attempt to write directly to the markdown file, fail, and waste an entire tool-use cycle retrying.
  2. File locking — multiple agents running concurrently would clobber each other's writes to the same file.
  3. Sandboxing — once we added guardrails (like toolgate) that prevent writes outside the active project directory, agents couldn't reach a shared worklog at all.

The fix: a CLI and HTTP API backed by SQLite, so agents can log work from anywhere without touching files directly.

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 with `hrs log`.
Run `hrs log -h` to discover the flags.

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}'

Goals & strategies for agents

Agents can also set daily goals, link them to entries, and work toward strategies. This is optional — if you just want work logging, the instructions above are enough.

The workflow

  1. Check for active strategies: hrs strategy
  2. Set a daily goal before starting work: hrs goals add "..."
  3. Log entries as you work: hrs log -c dev -t "..." -b "..." -e 2
  4. Mark the goal done and link entries: hrs goals done <id> -e <entry_ids>
  5. Check strategy progress: hrs strategy <id>

CLI quick reference

# goals
hrs goals                        # list today's goals
hrs goals add "goal text"        # add a goal
hrs goals add "text" -s 1        # add a goal linked to strategy #1
hrs goals done <id>              # mark complete
hrs goals done <id> -e 41,42    # complete and link entries
hrs goals link <id> -e 41,42    # link entries without completing
hrs goals undo <id>              # reopen
hrs goals rm <id>                # delete

# strategies
hrs strategy                     # list all strategies
hrs strategy <id>                # view report (goals done, total hours)
hrs strategy add -t "title"      # create
hrs strategy done <id>           # mark completed
hrs strategy archive <id>        # pause
hrs strategy reopen <id>         # reactivate

Via HTTP

# create a goal
curl -s -X POST http://localhost:9746/goals -d '{"text": "implement oauth2 pkce"}'

# complete with linked entries
curl -s -X PUT http://localhost:9746/goals/1/done -d '{"entry_ids": [41, 42]}'

# create a strategy
curl -s -X POST http://localhost:9746/strategies -d '{"title": "ship v2 auth"}'

# check strategy progress
curl -s http://localhost:9746/strategies/1

Example CLAUDE.md snippet

Add this alongside your work logging instructions:

## Goals & strategies (optional)

Before starting a task, check for active strategies and today's goals:

    hrs strategy
    hrs goals

If the current task aligns with a strategy, set a goal for it:

    hrs goals add "description of what you're about to do"

After completing the work and logging entries, mark the goal done and
link the entry IDs:

    hrs goals done <goal_id> -e <entry_id1>,<entry_id2>

Don't create strategies. Just work within existing ones.

See Goals & Strategies for the full guide.

Tips

← API Reference TUI Explorer →