Work with agents
Tasks, repositories and subtasks
Each task gets its own folder and branch. Attach repositories, split work into subtasks, find tasks in the sidebar, and archive or restore them.
Every task works in its own folder, apart from your main checkout and from every other task. Each repository you attach gets its own working copy, a git worktree, on a new branch made for the task. Several agents can work at once without touching each other's files.
Start a task
Click New or press ⌘N. Windows uses Ctrl in place of ⌘. The task gets a folder at once, with one subfolder per repository you attach:
~/.zokie/tasks/<task>/<repo>/
Your own checkout is never changed. Branches are named <prefix>/<type>/<slug>: your Mac user name, feat, bug or chore, and the task's title. The branch is named after your first message and keeps that name if you rename the task. To use another prefix, see Config file.
Attach repositories
- In the chat header, click Add repository, or + once one is attached.
- Click a repository to attach it. Click it again to detach it.
Esccloses the list.
The list offers:
- Groups you made in Settings › Workspace › Repos. Use attaches the whole group.
- Recent sets of repositories from your latest tasks.
- Every repository you added, with a search box to narrow the list.
At its foot, Add a local folder… adds any git repository on your computer, and Clone from GitHub or a URL… clones one from owner/name or a git URL. Hover a repository to rename it with the pencil, or remove it from the list with the ×. Nothing on disk changes.
You can attach a repository after the task starts too. The agent sees it from your next message.
To detach, click the × on its chip and confirm. The worktree is removed and the branch is kept with its commits. Zokie refuses while the worktree has uncommitted changes.
Subtasks
A subtask is a second chat under a task, with its own agent, working in the same folder and on the same branches. Use subtasks to run parts of one job at once.
- Send the main task its first message.
- Click + after the tabs in the chat's top row.
- Type what this part of the job needs and send it.
- A task can have up to 12 subtasks.
- A subtask starts on the main task's agent, model and effort.
- A repository attached from a subtask is attached for the whole family.
- The main task's agent can start subtasks too. Each opens in its own tab, and you can step in like any other chat.
- Double-click a tab to rename it. The × on a tab deletes the subtask and its chat; its changes stay.
- Archiving or restoring the main task does the same for all its subtasks.
Agents can still collide in the same file, so give each subtask a separate part of the work.
The task list
The sidebar lists your tasks in Today that aren't ticked off, plus any you Pin. Each row shows a dot for what its agent is doing, the title, the number of subtasks and its age.
⌘Ksearches task and subtask titles.- The filter button picks a status: To Do, In Progress, In Review or Merged.
- The funnel filters by Team, Priority or Project.
- Right-click a task to Pin it, Mark as Done, Move it to a team board, or Delete it.
- Double-click a row to rename the task.
Archive and restore
Archiving puts a finished task away. Clear completed on the Plan does it, and so does auto-archive. The agent stops, clean worktrees are removed, and branches stay.
Open the Archive from the archived link in the Plan header. Group it by Day, Week, Month or One list, search it, and filter by Priority, Assignee or Project. Click a title to read its chat.
To restore, click the restore arrow on a row, or Restore in the archived chat, and pick Inbox, Today, This week, Backlog or Done. Zokie rebuilds each worktree from its branch, and subtasks come back with their main task.
The cross on a row deletes a task for good after one confirm. Its branches stay.
Storage settings
Open Settings (⌘,) › Workspace › Tasks:
- Remove unused repo copies after: 1 day, 7 days (the default), 30 days or Never. Worktrees with uncommitted work are left alone. Zokie brings the rest back when you open the task again.
- Delete archived chats after: 7 days (the default), 30 days or Never. Restore a chat before then to keep it.
- Delete from: My Computer, or My Computer + Cloud.