Work Tracebook

Work Tracebook keeps a local record of what your coding agents finished. Agents send short reports through factorylog; the app turns those reports into task lists and timelines.

Install and connect an agent

After buying, connect your GitHub account in Polar and accept the invitation. Download the app from the customer releases, unzip it, and move it to Applications. You need macOS 15 or later.

The welcome screen walks through setup:

1. Install the command-line tool. This puts factorylog in ~/.local/bin and checks that your login shell can find it. Use Add to PATH if offered for zsh.
2. Connect your agent. The Codex option adds standing instructions and log-folder access. The Cursor option installs a rule.
3. Send a test report, or ask the connected agent to make a real change.

You can return to these controls under Settings → Integrations. For another agent, choose Copy the instructions and put them in that agent’s standing instructions. A sandboxed agent also needs permission to write the log folder.

Start a new agent session after installing its instructions. An existing conversation may not have read them yet.

Record one task

Work Tracebook records durable outcomes, such as a code fix or documentation change. Questions and explanations do not need tasks.

From the project folder, start a task with a title and a short factual summary:

factorylog start --title "Add recipe search" --summary "Starting recipe search by ingredient." --source codex

The JSON response contains event.taskID. Keep that value. Use it in later commands instead of starting another task for the same work.

Add a report when there is a meaningful result:

factorylog report --task-id "$task_id" --summary "Recipe search now matches ingredient names."

Here, task_id must hold the ID returned by start. Close the task after finishing:

factorylog archive --task-id "$task_id" --summary "Finished and checked recipe search."

Reports should describe outcomes. Keep source code, terminal output and secrets out of them. factorylog --help and factorylog capabilities explain the command’s other options.

Read your work history

The app updates when reports arrive; there is no refresh step.

Shortcut	View
⌘1	Today
⌘2	Yesterday
⌘3	Week
⌘4	Insights

Today and Yesterday show time estimates, projects and tasks. Hover over a session bar to see the tasks behind it. An open task says Doing. You can close it in the app with its final outcome.

Week shows each day’s work sessions and the split between projects. Use the arrows to visit earlier weeks. Insights shows longer periods and project totals. Select a project to inspect its history. Right-click a project to hide it; bring it back in Settings.

Understand the time estimates

Agents report outcomes rather than hours. Reports in one project at most 45 minutes apart form a session. Each session adds five minutes before its first report.

Projects are measured separately. Two agents working on different projects at the same time contribute time to both. Treat the totals as an estimate of project activity rather than a timesheet.

Optional Ollama summaries turn a finished day’s reports into a sentence per project. Without Ollama, the app still works and shows task titles.

If reports are missing

Run command -v factorylog in a new Terminal window. If the command is missing, revisit Integrations and check your PATH. If Send a test report works but agent reports do not, start a fresh agent session and check its instructions and sandbox access.

The log is ~/Library/Application Support/Factory Log/events.jsonl. Back up its containing folder. The app reads the reports you supply; it does not inspect your source or terminal. Download app updates manually from customer Releases.