User guide

You use offtrack in three places. In Claude Code, sessions report on their own and you manage projects with commands. The web interface shows what is open on a map and lets you edit items by hand. On your phone, the same interface runs, and you can add items by voice from the Claude app. Setup is in the install guide.

Concepts

• Project: one or more directories on your machine. It has an owner and members; only you see it by default. If you work from two machines, both report to the same project on their own: offtrack also recognises a repo by its git remote and the location inside the repo (only a salted fingerprint of the address reaches the server, see the install guide), so the paths can differ, and the subprojects of a monorepo stay separate. For a repo with no remote, ask once on the second machine: “attach this session to the project project”.
• Thread: a line of work within a project. Every project has a main thread.
• Milestone: a finished step, such as an approved plan, a commit or a deploy.
• Open branch: unfinished work or a question awaiting a decision.
• Manual task: something you or a teammate has to do, not the session.
• Idea: a thought set aside for later. Private until you publish it.
• Link: the session touched another project's code, server or configuration.
• Hand-off: the to-do belongs to another project, so it goes there (to its main thread) and the source item closes. On the target, “← project” shows the source (with “#id” when there is a source item), or “← nickname: #id” for a task handed to a coworker (/cowork); when the target is done or dropped, the source thread’s next session gets a note (on the main thread if the source thread is archived). Only open branches and manual tasks can be handed off, and only to a project you can see.
• Coworker: a user with a nickname who works on the same repo as you. You can hand tasks to each other and see each other's work; details on the coworkers page.
• Repo label: the repo name shown on an item, such as “api · web”: the repos the item concerns.

The “Legend” item in the header menu explains every symbol.

In Claude Code

On its own

• At start the session receives the project's threads, open branches and new notes (the [offtrack] block) and picks up from there.
• While working Claude reports finished steps, the to-dos it lists at the end of an answer, manual tasks and ideas for later. The rules live in the offtrack block of ~/.claude/CLAUDE.md.
• At the end of an answer, if Claude is about to finish without reporting after a longer stretch of work, offtrack stops it once and asks for a report. Claude Code labels this “Stop hook error”, but it is not an error.
• Offline, reports wait locally and go out when the connection returns.
• New client version: if there is one, a line in the terminal says so when a session starts, with the update command.

On request

For common actions, just ask: “show the open items”, “attach this session to the Koller project”, “share the project with Peter”, “add a manual task to…”, “hand this off to futureal”. The /offtrack skill lists the commands when called without arguments. Requests about coworkers (“who else works on this repo?”, “hand this to Neo”) are listed on the coworkers page.

The offtrack command

Run it in a terminal, or in Claude Code with the ! prefix. <project> is the project's name.

Projects
offtrack projects	your projects, your root directories and the members
offtrack list [<project>]	open items by thread
offtrack attach <project> [--new]	attach the current session to a project
offtrack root <project> <directory>	add a directory (with its subdirectories) to the project
offtrack rename <project> <name>	display name (for example GreenGo)
offtrack rename-thread <thread-id> <title>	rename a thread, the main thread too (as owner)
offtrack merge <from> <into>	merge one project into another; cannot be undone
Sharing
offtrack share <project> <email>	share with a teammate (as owner)
offtrack unshare <project> <email>	remove a member (as owner)
offtrack transfer <project> <email>	hand ownership to a member
offtrack publish <item-id>	make your idea visible to the members
offtrack move <item-id> <project>	move an item to the other project's main thread (hand-off)
Coworkers (details)
offtrack nick [<nickname>]	show or set your nickname ("" clears it)
offtrack coworkers [<directory>]	who else works on this repo
offtrack cowork list	your coworks and pending requests
offtrack cowork <nickname> project | task | end	request project level, back to task level, end the cowork
offtrack cowork accept | decline <nickname>	accept or decline a request
offtrack share-item <item-id> <nickname>	share an item of yours with a coworker without handing it off
Machine and account
offtrack login	set the client token on this machine
offtrack whoami	which user this machine reports as
offtrack version	the installed client version, and whether a newer one exists
offtrack flush	send queued reports
offtrack mobile url | revoke	the Claude app connector's secret URL, or revoke it
offtrack install / uninstall	install or remove the client
Backfill
offtrack backfill [--dry]	proposal files from past sessions (~/offtrack-backfill/)
offtrack import <file…>	upload a reviewed proposal file (step by step: install guide)

offtrack help lists the admin commands too (offtrack admin …: users, tokens, allowlist).

In the web interface

Views and toolbar

• List: grouped by project; one card per thread, with its open items and latest steps. Your coworkers' cards follow your own, in a separate section per coworker.
• Map: each thread is a vertical line, with the newest events at the top. Grab the background with the mouse to pan; the header and the dates stay in place. Your coworkers' threads show in the project's column after your own, in a pale blue band.
• Completed: shows milestones too. Group: folds a thread's items for one day into one marker. Projects: filter by project. Only mine / Everyone: hides or shows your coworkers' work. Inactive: when on, every coworker shows, those without an open session at the end of the project's bands; a coworker with no visible work in the time range gets an empty band with their nickname. When off, only coworkers with an open session in the shared project show (one that reported in the last 4 hours). Range: from 1 day to 6 months. At the right end: the refresh button and the time of the last update; the interface updates live anyway, the button helps when the connection dropped.
• Projects on the map: collapse one with its arrow (when the filter shows only some projects, all of them stay expanded); drag its name (or press Alt+←/→) to move it.
• Links on the map: click a “→ project” label to see the full note and when it was recorded in a read-only box; for a hand-off, the target item's text, when and where it went, where it is now, and what became of it.

Menus

Click an item, a thread title or a project name.

• Item: Copy prompt, Done, Note, Move to another thread, Publish (for your private idea), Repo labels… (for your own item), Drop. A dropped item stays faded for a day; undo it from its menu. The move may target a thread of another project (for your own or unsorted items): the item then lands in the target project, and a “→ project #id” link stays on the source thread. On the target, the list and the map show a “← project” line for where it came from, and the source thread gets the closing note here too.
• Thread: New item here, Note on this thread, Rename, Archive, Merge into another thread, New thread in this project.
• Project: New thread; as owner, Display name and Share.

New item

Use the + button at the bottom right. The type can be open branch (the default), deadline (an open branch with a required date), idea or manual task; these show up on the map and the list right away as items. Open branches and manual tasks can have a deadline, and a manual task an assignee too. You can dictate the text with the microphone button. Without a thread, the item lands in the “Unsorted” sidebar, where you can file it.

Notes and clarifications are not items: they do not show on the map, and the thread's next session receives them when it starts.

Account and install

• Profile (top right, your picture or initials): its menu has Your account, the language switch and sign-out. On Your account you can link more sign-in methods, and set the appearance: theme (system, light, dark) and map background (drawing paper, white). The settings are saved to your account, so they apply on every device. This is also where you set your nickname and manage your coworks and pending requests (coworkers). Under Email notifications you can get an email at one of your sign-in addresses when someone gives you a task; each email lets you unsubscribe from that project, and you turn it back on here. The Client updates switch turns the morning email on or off that tells you when one of your machines runs an older client, and the Cowork requests switch the one about a coworker's project-level request.
• Your stats (in the main menu): your own work in numbers: open and overdue items, closed items, milestones, sessions, your most active projects and the language of your items, over the last 30 days. Only you see it.
• Install: generate a client token for each machine and the Claude app connector URL.

On your phone

The web interface

• The map shows one thread at a time. Tap a label in the row at the top to switch, or swipe sideways to the next thread.
• Long-press a label to open the thread's menu; menus open as sheets from the bottom.
• The + button adds an item to the thread on screen, by voice too.
• Added to the home screen, it runs as an app.

In the Claude app

With the mobile connector you can add items by voice from the Claude app (phone, desktop, web): “track: flyer for the website”, “add to offtrack that…”. If the text names a project, the item goes there; otherwise it lands in “Unsorted”. A phone icon shows it came from mobile. Setting up the connector is in the install guide.

Picking up an open branch

1. On the map or the list, click the item and choose Copy prompt.
2. Paste it into a Claude Code session in the project's directory. The prompt describes the project, the thread, the item and the latest steps.
3. Claude sums up the task and starts once you confirm. The item moves to in progress, and to done when the work is finished.