offtrack

Install

offtrack tracks work done with Claude Code: every session reports its milestones, open branches, manual tasks and ideas on its own, and the map shows at a glance what is still open. This page explains how to switch it on for your own machine and in the Claude app.

What you need

Installing the Mac client

The client installs from a public repository: offsite-solutions/offtrack-client (MIT licence).

git clone https://github.com/offsite-solutions/offtrack-client.git ~/Work/offtrack-client
cd ~/Work/offtrack-client && npm install
node install.mjs install
offtrack login        # paste the client token, then Enter
offtrack whoami

A client token for this machine. It is shown only once: copy it and paste it into offtrack login. Generate one per machine; earlier tokens stay valid.

offtrack login reads the token from standard input, so it stays out of your shell history. If ~/.local/bin is not on your PATH, add it. Restart running Claude Code sessions after the install; new ones report right away.

Keep the folder name offtrack-client: the installer recognises its own hooks by it. Updating: git pull in the folder; the client runs from there, so there is nothing to reinstall.

What the installer sets up

It leaves existing hooks and text alone and backs up every file it changes (.bak-offtrack-…). If the server is unreachable, the hooks let the session through silently, queue the reports locally and send them later (offtrack flush).

The CLAUDE.md block

The installer writes this English block into ~/.claude/CLAUDE.md by default, and everything else follows: sessions report in English, and the startup context, the Stop reminder, the offtrack command, the skill and the server's messages are in English too. For Hungarian, add --lang hu. The choice is remembered for later reinstalls. To set it up by hand, paste it between the two markers; the installer updates whatever sits between them.

<!-- offtrack:start -->
## Task tracking (offtrack)

Every session reports to offtrack on its own, with the `offtrack_*` tools. The `[offtrack]` block received at startup shows the project's threads, open branches and new notes; take them into account.

Report, but only in these situations (`offtrack_report`):
- **Milestone** (`kind: stop`): a closed, self-contained step – plan approved, migration run, deploy done, commit/PR done, root cause found.
- **Open branch** (`kind: branch`): when you list to-dos at the end of your answer. Independent to-dos are separate branches; one coherent list of suggestions (for example the points of a review) is a single branch, with the points listed briefly in the text. Getting stuck or waiting for a decision is a branch too, with the question. If you later do it or drop it: `offtrack_update`.
- **Manual task** (`kind: manual`): what the user has to do by hand (physical, needs access, depends on a third party, printing, approval).
- **Idea** (`kind: idea`): when the user refers to the future ("in the future", "later", "might be interesting later", "let's leave this for now") – without asking.
- **Link** (`offtrack_link`): when you touch another project's code, server or configuration.
- **New thread** (`offtrack_new_thread`): a new, multi-step workflow that does not fit the existing threads. When in doubt, the default thread.

Don't report single commands, file reads or small fixes. The text is 1–3 sentences, in English, focused on the outcome.

For requests about projects, attaching, merging, sharing, publishing, assigning, picking up a branch or user management, load the `offtrack` skill.
<!-- offtrack:end -->

The offtrack skill

The skill handles the less frequent operations and loads on its own when you ask for one (or when you call /offtrack). Examples:

Claude app: mobile connector

In the Claude app (mobile, desktop, web) you can add an item like this: “track futureal flyer”. It goes to the project the text names, otherwise to unsorted. Typing, dictation and voice mode all work.

  1. Generate a connector URL (below, or in a terminal: offtrack mobile url).
  2. claude.ai → Settings → Connectors → Add custom connector; name: offtrack, URL: the generated one. No sign-in is needed.
  3. Try it on your phone: “track <project> <task>”.

The URL works like a password: don't share it or write it into files. Generating a new URL invalidates the previous one.

Removal and troubleshooting