Work: tasks and Today
Work is the dashboard's list of what your workspace has to do, one screen for what needs you now, and a way to have a coding session do a task ("Do it") and look at what it did. Plans made with AI and repeating work come later.
The page
Work is in the sidebar right under Home, and in the phone's bar.
- Today: Needs you (tasks overdue or due this week, tasks waiting for you, and the sessions on any of your computers that need an OK or reached a usage limit), To review (what a session has done: its answer, with Accept and Send back), This week (today and the six days after, day by day) and Done lately (the last seven days). "This week" is one rule everywhere: today and the six days after, for Needs you, This week, the Tasks part's "Next seven days" and the command.
- Tasks: every task, in groups: waiting for you, ready for your review, a session works on it, overdue, today, the next seven days, later, no date; done and dropped folded away. Filter by project and by who does it (you or the AI). Add task opens a sheet: the task, the day it is due (or none), a project of your workspace, the priority, who does it and a note. The round button marks a task done (and open again); ⋯ has Change, Waiting for you, Drop and Remove. Every action names the task by its place in the list and its id together, so of two tasks with one id the one you pressed is changed.
- Activity: the runs of every task (see "Do it" below), newest first and grouped by day; filter them by project and by day.
- Save: when the list has changes that are not committed, a bar says so ("2 changes not saved in git yet"). Save shows first what it will do (the file, and per task: added, done, dropped, changed, removed, new id), then does it. A save reaches the server or leaves your change in the file: there are no saves "not sent yet".
- Lines that ask for one thing, shown over both parts when they apply:
- This file has things a change would alter (a hand edit, see "The file as it is written" below), with Tidy the file once;
- 2 tasks share their ids with another (two computers added the same title), with Give the doubles new ids: a change like any other, shown in the Save plan;
- This list is a planning tool's file, with your id in this file (see below);
- A save of the Work list was interrupted …: one sentence when it was finished, or, when the repository is not where that save left it, where its list is kept, with Drop the record once you have looked (see Save).
Do it: a session does a task
Do it (the ▷ button on a task, or ⋯ → Do it with a session) opens a sheet that shows what will start, and lets you change it first:
- the brief: the first time the task's title and note; a brief you change is kept on the task (
work.brief); - the project and the folder in it: the project's own folder or one of its code repositories (
code/<name>). The task's project is the default; a task without a project asks for one; - the provider (the folder's own, as New session picks it), the model and the effort (Settings → New-session defaults), and the coding tool when more than one is on;
- one line: "A session starts in <folder> with this brief. It changes files there as you allow in that session; nothing is pushed or merged by this."
Start opens an App session (the same kind a schedule starts) whose first message is the brief and one sentence asking for a short report at the end: what was done, what was checked, what is left. The task is doing while it works; its row offers Open the session, not a second start (two presses of Start make one run). Start goes with the brief the sheet showed: when the task changed since (a merge, a save), nothing starts and the sheet shows it anew. A brief, also one made from a task that came from another computer, is at most 4,000 characters and holds no character that cannot be seen (a zero-width one, an invisible tag, a direction mark, words hidden in variation selectors, a blank filler); when it does, the sheet offers Take them out, and the brief without them is kept on the task when it starts. A session that works on the task on another computer is said in the sheet and does not stop a start here; its run is shown, with no session to open on this computer.
When the session's turn ends well, the task goes to review, with the session's last answer, the commits made in
the folder's repositories since the start and the files it left changed and not committed (a file that was changed
before it started and holds the same is not counted). Accept makes the task done; Send back opens it again,
and what you write is added to its brief for the next run (the task's own text and the newest of what you sent
back, the oldest left out when they no longer fit together). A task in review is not started again before Accept or
Send back. A turn that ends in an error, at a usage limit with no other provider going on with it, or because you
stopped it puts the task back to open (or waiting, when it was waiting for you), with the reason. A
dashboard restart while a session works leaves the run working; when the dashboard is back it is settled from the
session's own record of how its turn ended, or marked stopped when the session is gone for good. In a planning
tool's file doing and review are written as status: "open" with Work's state, as for the other statuses.
A run is the record of one such session for one task: a file of its own beside the list, runs/<run id>.json (the
id holds the date and time and random characters, so two computers never write one file), written only by the
dashboard that ran it. It holds the task's id and title, when it started and ended, who started it, the project and
folder (never a full path), the coding tool, the provider's name, the model, the effort, the session's id, its state
(running, done, failed, limit, stopped) and reason, the answer (at most 4,000 characters, anything that
looks like a secret masked and the computer's own paths taken out), the commits (repository, short id, subject) and
the files left changed (repository, path, kind; at most 200, the rest and any name a run does not hold counted).
Commit subjects are cleaned like the answer, and the computer's name is taken out too. A run file is at most 64 KiB.
What the session started from (each repository's commit, the files changed before it) stays in this dashboard's
state folder, never in the run. Save commits a file in runs/ only when it is a run of its own name (a plain file,
not a link); anything else there is named and left alone. Runs are not kept on the task, so a task changed on two computers
is still one change. The run file and the task's status are written under Work's one lock; when the status cannot be
written (the file needs a tidy, two tasks share the id), the run is written all the same and says why.
Where the data lives
One file in a git repository of your workspace, chosen in Settings → Work ("Work data lives in"):
- The AI brain (the default):
ai_brain/work/tasks.json. The brain is on every computer of yours, so every computer sees the same list after a sync. - A project: a folder inside one project of the workspace, for example
docs/plans.
The folder must be inside the brain or the project: a plain relative path, no .., no dot-folder, no private
folder, and no link that leads out (checked on the server each time, not only when you choose it). When the folder
already has a planning list named deadlines.json and no tasks.json, that file is used as it is.
The file is JSON: { "items": [ … ] }. Each item:
| Key | What |
|---|---|
id | made from the title (renew-the-domain), unique (two computers that add the same title can make doubles: see above) |
title | one line, 3 to 200 characters |
date | YYYY-MM-DD or null (no date); approx: true for "about then" |
kind | task, deadline, gate or opportunity |
status | open, doing (a session works on it), review (the AI is done, you look), waiting (it needs you: an account, a purchase, a yes), done, dropped |
state | only in a planning tool's file: the status that tool does not know, beside status: "open" |
priority | high or low (none: normal) |
note | up to 2000 characters |
by | who does it: me, ai or a role name |
project | a project of the workspace |
source | where it came from: your id for a task you added, else the plan note it was made from |
created, doneAt | days; doneAt only while it is done |
plan, after, repeat, work, runs | kept and shown; filled by later parts of Work (plans, "Do it", repeating work) |
A task you added can be removed. A task that came from a plan note is dropped instead, so the plan still shows what was decided.
A planning tool's list in the same shape (items with owner and brands, the owner's own id for "you") is
opened as it is: owner is read as who does it. When the file does not use your id yet, the page says once that it
is a planning tool's file and asks for your id in this file, filled with the id the file uses most (also
Settings → Work and hoprig tasks owner <id>); until you say it, Work writes nothing that would put its own word
for "you" into that file (adding a task, "who does it: me"). That tool knows the statuses open, done and dropped and
counts only "open" as open work: in its file a task set to waiting, review or doing is written as status: "open"
with the real one in Work's own key state, which Work reads back as the status, so both tools show it as open.
The file as it is written
A change writes only what changed, in the file's own style: its indent (or all on one line), its line ends, its final newline and a byte-order mark. It never moves or drops a key Work does not know, and a file opened and saved unchanged stays byte for byte the same.
Before any write Work checks that writing the file back unchanged in that style would give the same bytes. Some
hand-edited files would not: a number JSON cannot hold exactly (12345678901234567890) or writes another way
(1.0, 1e3), a string written with escapes (\u00e9, \/), a key written twice (only its last value is read),
mixed line ends, a list written on one line in a file that is otherwise spread over lines, bytes that are not UTF-8
(a Latin-1 "é": the file is read strictly, and a write would put "�" in its place). Work then changes nothing
by itself: the page and the command list what a write would alter (which keys, which numbers, the line ends, the
layout, the bytes and their line), and offer one action, Tidy the file once (hoprig tasks tidy [--dry-run]),
which shows that exact difference line by line and writes it only on your yes. The sheet shows up to 400 lines of
it, each cut at 300 characters, and says so; hoprig tasks tidy --dry-run shows all of it. After that, changes work
again. A file nested more than 100 levels deep, or with a number longer than 400 characters, is not read at all:
Work says which and where, and writes nothing.
Every value is checked when it is written: a title is one line of 3 to 200 characters, and neither a title nor a note may hold control characters or the marks that turn the direction of text around (a line break in a note is fine). A file that is not valid JSON is reported by line and column and never overwritten. One change is written at a time (a lock in Hoprig's state folder, never next to your file), through a temporary file and a rename. The lock names its process (its pid and when it started), so a writer that still runs keeps it however long it takes; a lock whose process has ended is taken at once, and one whose process cannot be told is taken after 60 seconds without the refresh its holder makes every 5 seconds. "Today" is counted on this computer's clock, or in the time zone named in Settings → Work.
Save
Save commits the Work file and the new or changed run files (runs/), by name, in the repository that holds them,
and sends it to the branch's server branch.
It is one unit that either reaches the server or leaves your change in the file as a change not committed yet:
- Look. It asks the server for news (a fetch). Everything it decides is read after that: what this computer has that the server lacks, whether the server only moved forward, the last version both had. A server branch that was rewritten (another computer forced it, and commits it had are gone) changes nothing: the message says so.
- Merge by task, when the server changed the Work file too. The two lists are brought together task by task, not line by line: a change on one side wins over no change, tasks added on either side are kept (two different new tasks with one id: yours gets a new id), a task removed on one side and untouched on the other is removed, and the file's other keys follow the same rule. A task changed differently on both computers is yours to decide: before anything changes, your list is also kept in the repository (see below), then the Save sheet's result is written. The Save sheet shows "3 changes of yours, 2 from another computer, 1 to decide" and both versions, and Merge and send waits until you chose one for each. Tasks that share an id (in any of the three versions) are never paired by their place: all of them count as one group, taken as one side left it when the other did not change it, else one choice for the whole group. When only this computer changed the list, the result is your list as it stands, its order included.
- Fast-forward. The server's new commits come in by fast-forward, never by a merge commit or a rebase. When they change a file that is changed or staged here, or that is here as a file git does not keep (also an ignored one), nothing is touched and the message names the files.
- Write and commit. The merged list is written and committed; the commit names only the Work file, so other changed or staged files stay as they are. Your hooks run; when one changes the file while committing, the message says so.
- Send. The save's own commit, named by its id, goes to the one server branch
(
git push --quiet --no-follow-tags --recurse-submodules=no <remote> <id>:<server branch>), never with your tags or another branch. Right before it, what lies between the server's commit and that id is checked once more: only the save's commit and earlier commits of the Work file alone. When the send fails (no connection, the server moved again, it refused), the commit just made is taken back: the branch goes back to where it was before it, the file keeps its content, nothing else is touched, and the answer says "Not saved to git: <why>. Your changes are kept in the file; Save again." A repository with no server branch: the save is the commit alone. A branch that git sends to another place than the branch it follows (branch.<name>.pushRemote,remote.pushDefault, a push refspec of the remote, or apush.defaultthat names no place:@{push}is not@{upstream}): Work does not guess, the save is the commit alone, and the answer says "this branch is sent to another place than it follows, so Work did not send it".
When you work in the same repository while a save runs (a commit in a terminal, a switch of branch, an edit),
nothing of yours is lost, moved or sent. The plan records the commit it judged; when the branch is no longer on it
as the save begins, nothing is done and the answer says why ("your commit 1a2b3c4 "…" came in while the save ran",
or that another command brought the server's commits in). The save knows its own commit for certain (made on the
commit it stood on, of the Work file alone, with the save's subject); when a commit of yours lands on top of it,
nothing more is touched: "your commit … came in while the save ran; the save's commit … is under it, not sent",
and what sends it (Save again, or your own git push when your commit changes other files). A failed send takes
its commit back only while the repository is still on that branch, the branch exactly on the save's commit and the
file as committed; otherwise nothing is taken back and the answer names the save's commit, the branch it is on,
and that it is not on the server.
What is never sent by Save: a commit of yours that changes anything but Work's files (the list and the run files in
runs/; in the AI brain also the workspace map Hoprig keeps there); the commit subject plays no part. While one of those is not on the server,
Save commits nothing and names it by short id and subject: send it first. When your own commits are not on the
server and the server moved, nothing is touched, and the message gives the commands to run (git stash push -- <file>, git pull --no-rebase, git stash pop). An earlier commit of the Work file alone that an older version
or your own hand left unsent is sent along by the next Save; when the server moved meanwhile, nothing is touched
and the message gives one command (git reset --soft <commit>) that makes it a change in the file again, so the
next Save merges it task by task.
A save that was interrupted is finished the next time. Before its first change to the repository a save writes
a journal to Hoprig's state folder (work-journal/) and flushes it to disk: the repository, the branch and its
commit, the server's commit, the list it writes and your choices. Every look at the Work list (the page, a Save,
the command) checks for one first. When the repository is where one of the save's steps left it and nothing else
changed, the save is brought to a state you know, and one sentence says which: the list it was writing is in the
Work file as a change not committed yet (a commit that was made and not sent is taken back), or it had reached the
server and is done. In any other state nothing is touched: the page says where the list is kept and how the
repository stands, and Save waits until you Drop the record (hoprig tasks save --drop-interrupted). A save
killed before it changed anything changes nothing on recovery, also when you changed or discarded the file since.
During a merge your list is kept in git too. Between putting the file back to its last commit and writing the
merged list, your list is in no file. So before the file is put back, it is stored in the repository as a git
object under a ref of Hoprig's own, refs/hoprig/work-save/<12 hex digits> (git never prunes what a ref points at),
and deleted when the save is done or dropped. git show refs/hoprig/work-save/<…> prints it; every message of a
failure that leaves it names that command. When the journal is gone (the state folder was removed, or a dashboard
and a terminal use two state folders), the next look at the Work list finds the kept list, says so and shows how to
put it back (git show <ref> > <file>); it is never applied by itself, and Save waits until you drop it. A journal
that cannot be read, or one from another repository, also says where your list is kept.
One save runs at a time per repository: a lock in Hoprig's state folder, shared with the AI brain's own upkeep (its map commit, its fetch and fast-forward, its push). While a save holds it, the upkeep skips its round and comes again at the next tick; while the upkeep holds it, a save waits a few seconds, then says "The workspace is being synced: Save again in a moment". The lock of the file is held only from the last look at it to the commit; when the file or the server changed after the plan you saw, nothing is committed and the new plan is shown. git's own messages (with the server's address or a full path) go to the dashboard's log, not to the page: an error on the page is one plain sentence with a short code. The commit subject is a setting (default "Update work items").
Commands
hoprig tasks [today] what needs you, this week, done lately
hoprig tasks list [--all] [--project P] [--by me|ai|<role>]
hoprig tasks add "<title>" [--date YYYY-MM-DD] [--project P] [--priority high|normal|low]
[--by me|ai|<role>] [--note "..."] [--kind task|deadline|gate|opportunity] [--approx]
hoprig tasks edit <id> [--title "..."] [--date D|none] [--project P|none] [--priority P|none]
[--by W] [--note "..."|none] [--kind K] [--status S]
hoprig tasks done | open | drop <id>
hoprig tasks remove <id> only one you added
hoprig tasks owner [<id>] your id in a planning tool's file: shown, or set
hoprig tasks fix-ids give tasks that share an id ids of their own
hoprig tasks tidy [--dry-run] [--yes] a file a change would alter: the difference, then written once
hoprig tasks do <id> [--project P] [--folder F] [--brief "..."] [--dry-run] [--yes]
a session does the task (through the dashboard): its brief first, then a yes
hoprig tasks runs [<id>] what the sessions did: answers, commits, changed files
hoprig tasks save [--seen <token> --decide "<task>=mine|theirs,..."] commit, merge by task when needed, send
hoprig tasks save --drop-interrupted drop the record of an interrupted save you have looked at
tasks do starts the run through the dashboard running on this computer (it reads a token the dashboard makes
in its state folder at each start, good for that one request); without a running dashboard it says so. --dry-run
checks everything and says what would start.
The command is tasks, not work, so that a provider named "work" keeps starting with hoprig work. A save that
stops at tasks to decide prints them and a token of what it showed (--seen): a choice is taken only with it, so
it never overrides a change the other computer made after you looked (then the new conflicts are shown).
Every command takes --json; the ones that change something take --dry-run (everything is checked, nothing is
written). A command refuses an option it does not understand (add --status done, --title beside a title), and
an id that two tasks share (it names both and points to fix-ids). With --json a refusal is one JSON object on
standard output, { "ok": false, "code": "...", "message": "..." }, with the same exit code (2: not understood,
1: refused or failed). tidy writes only with --yes or a yes typed on the terminal. The sessions that need an OK
are shown on the dashboard's Today only.
Not built yet
Plans and "Plan with AI", repeating tasks and the Automations page folded into Work, a session on a branch of its own, Tia's Work tools, a token and webhooks for other programs.