Projects
Issues
Track a project’s work in a list, a board and full issue pages, and let your agents file, pick up and close issues with you.
Every project, and every folder with chats, has its own issue tracker. You plan the work there, hand an issue to an agent, and follow what it does in the same window as the chat doing it. Agents in the project’s chats can read, file, move and comment on issues too, so the tracker stays current without you copying anything across.
Open a project’s issues
- Click Issues on the project’s row in the sidebar. The button shows how many issues are active and stays visible while there are any; otherwise it appears when you hover the row.
- Choose Issues from the project’s … menu or right-click menu.
- Choose Navigate ▸ Issues (⌘⇧I) to open the tracker you last had open, or the current chat’s project’s.
- Type the project’s name in the command palette (⌘K) and choose ‹Project› Issues, or New Issue in ‹Project› to go straight to a new issue.
- Click the issue ID on a tracker row in a chat, such as “Updated COD-5”.
Issues are numbered under a prefix Codz suggests from the project’s name, such as COD-12. To change it, click … in the tracker’s header and choose Change identifier, which shows the current prefix. The prefix is letters and digits, up to seven characters, starting with a letter; existing issues keep their numbers.
Issues are stored on this Mac.
Views
The tracker opens on the tab you used last:
- Active: issues in Todo, In Progress and In Review.
- Backlog: issues in Backlog.
- All issues: everything.
Each tab keeps its own view. Press ⌘B to switch between a list and a board, or set it in Display options (⇧V), which also chooses how issues are grouped (status, assignee, agent, priority or label, plus parent issue on a board), how they’re ordered, how long closed issues stay visible, whether sub-issues show, and which properties each row or card displays. A dot on the display options button means the view differs from the tab’s defaults, and Reset puts it back.
- Filter (F) narrows the view by status, assignee, agent, creator, priority, labels, due date, content, relations, dates or links. ⇧F removes the last filter and ⌥⇧F clears them all.
- The details panel (]) counts the issues in view by assignee, agent, label or priority. Click a row to filter by it, and again to lift the filter.
- Drag issues into another group, in a list or on a board, to change the field they’re grouped by (labels excepted). When the view is ordered Manual, where you drop them is their new place.
- On a board, a column’s menu has Hide column. Hidden columns wait in the Hidden columns list, where Show column brings them back.
Create an issue
Press C, click the compose button in the tracker’s header, click + on a group, or choose New Issue in ‹Project› in the command palette.
- Type a title, and a description if you want one. The description is Markdown.
- Set any of Status, Priority, Assignee and Labels with the buttons under it, or press S, P, A or L when you aren’t typing. The … button has Set due date… (⇧D) and Set parent issue… (⌘⇧P).
- Click Create issue or press ⌘↩.
A new issue starts in Backlog, or in Todo when you create it from the Active tab, or with the status, priority, assignee or label of the group you created it from. Turn on Create more to keep the sheet open for the next one. The paper clip, Attach images, files, or videos (⌘⇧U), adds links to files on your Mac to the description. If you close the sheet with a title or description typed, Codz keeps the draft for your next new issue in that tracker until you quit; Discard draft clears it.
The issue page
Click an issue, or press ↩ or O on it, to open its page. Esc goes back to the list.
The page has the title and description, the properties, sub-issues, links and the activity feed:
| Field | Values |
|---|---|
| Status | Backlog, Todo, In Progress, In Review, Done, Canceled, Duplicate |
| Priority | No priority, Urgent, High, Medium, Low |
| Assignee | No assignee or you. Choosing an agent here hands it the issue. |
| Agent | The agent the issue is delegated to |
| Labels | Bug, Feature and Improvement to start with, plus any you create |
| Due date | A day, shown as “Due today” or “Overdue” when it applies |
| Parent | Makes the issue a sub-issue |
| Relations | Blocked by, Blocking, Related, Duplicate of |
| Links | URLs such as the pull request |
Done, Canceled and Duplicate count as closed. Duplicate isn’t in the status menu: marking an issue as a duplicate of another closes it that way.
- Sub-issues: Add sub-issue (⌘⇧O) or Link existing issue as sub-issue….
- Relations: the … beside the breadcrumb has Relations, with Mark as blocked by…, Mark as blocking…, Reference related issue… and Mark as duplicate of….
- Links and files: Add link… attaches a URL; Attach files adds links to files on your Mac to the description.
- Comments: write in Leave a comment… and press ⌘↩. Your own comments have Edit and Delete in their … menu, and any comment can be copied as Markdown. Agents can reply in a comment’s thread.
- History: the feed records every change and who made it, you or an agent.
The same … menu, and a right-click on any issue in a list or board, has Copy: Copy ID (⌘.), Copy link (⌘⇧,), Copy branch name (⌘⇧.) and Copy as prompt. A copied link looks like codz://issue/COD-12 and opens that issue in Codz.
To delete an issue, choose Delete issue or press ⌘⌫. Edit ▸ Undo (⌘Z) brings it back.
New labels come from New label… in the tracker’s … menu, or from typing a name the labels menu doesn’t have and choosing Create new label.
Hand an issue to an agent
Choose an agent under Agents in the issue’s Assignee menu, or Work on issue with in its right-click menu, or press W then O. To hand several issues over at once, select them and click the agent button in the bar that appears.
For each issue, Codz:
- Starts a new chat with that agent in Agent mode, in the project’s primary folder, named after the issue’s ID and title.
- Sends the agent the issue as its brief and links the chat on the issue.
- Moves the issue to In Progress if it was in Backlog or Todo. You stay its assignee; an unassigned issue becomes yours.
Choosing the agent an issue already has starts another run.
When a turn ends, the issue says so: the agent “finished working”, “is waiting for input”, “stopped with an error” or “was stopped”. If the agent didn’t comment during the turn, Codz posts its final answer as the agent’s comment. If it left the issue in In Progress, Codz moves it to In Review for you to check.
A list row shows the latest run’s state: Working…, Needs input, Error or Finished. On the issue page, each run reads like “Claude is working on this”, with Open chat. An agent that isn’t ready to start is listed with the reason, such as Not installed or Sign in to Codex.
What agents can do
Agents reach the tracker through tools Codz gives them in the project’s chats. They work with the tracker of the project the chat runs in:
| Tool | What it does |
|---|---|
tracker_info | Describes the tracker: its prefix, statuses, labels, who you are, and the issues this chat is working on |
list_issues | Searches and lists issues, filtered by status, priority, label, assignee, agent, parent or blocked state |
get_issue | Reads one issue in full, with its sub-issues, relations, links, agent chats, comments and recent activity |
create_issue | Files an issue or sub-issue. A title that matches an open issue isn’t filed; the agent is pointed at that issue instead |
update_issue | Changes only the fields it names, such as the status, priority, labels, due date or parent |
work_on_issue | Takes the issue on in this chat: links the chat, makes the agent its delegate and moves it to In Progress |
comment_on_issue | Comments on an issue, or replies in a comment’s thread |
link_issues | Adds or removes a blocking, blocked-by, related or duplicate relation |
add_issue_link | Attaches a URL, such as the pull request it opened |
There is no delete tool: an agent that wants an issue gone cancels it, which leaves its history. An agent can take an issue on for itself with work_on_issue, but it can’t hand one to another agent or start another agent’s chat, since that spends your plan; delegating stays with you. The tools never stop a turn to ask for approval, and every change they make is recorded under the agent and the chat.
In the chat, each call is a row in the tracker’s words, such as “Filed COD-12 …”, “Updated COD-5”, “Working on COD-11” or “Commented on COD-9”. Click the ID to open the issue.
Which agents get the tools
- Claude Code, Codex, Cursor and OpenCode get them through an MCP server named
codz-issuesthat Codz adds when it starts the chat. Codz never edits their configuration files to do it. - OpenRouter chats have them built in. They can read the tracker in Ask and Plan modes, and change it only in Agent mode.
- DeepSeek chats don’t get the tools. You can still hand an issue to DeepSeek, and Codz posts its final answer on the issue.
The tools are on by default. Turn them off with Settings ▸ Browser & tools ▸ Issue tracker, or with Agents can use the tracker in the tracker’s … menu. Without Codz Pro, no agent gets them, whatever the setting says.
Keyboard shortcuts
The single-letter keys work on the tracker when you aren’t typing in a field. On an issue page they act on that issue; in a list or board, on the selected issues or the one under the keyboard focus.
| Key | Action |
|---|---|
| C | New issue |
| ↩ or O | Open the focused issue |
| Esc | Back to the list, or clear the selection |
| J K or ↓ ↑ | Move the focus |
| ⇧↓ ⇧↑ | Extend the selection |
| X | Select or deselect the focused issue |
| ⌘A | Select every issue in view |
| S | Change status |
| P | Set priority |
| A | Assign |
| I | Assign to yourself, or unassign if it is already yours |
| L | Labels |
| ⇧D | Due date |
| ⌘⇧P | Set parent issue |
| ⌘⇧O | New sub-issue |
| ⌥↑ ⌥↓ | Move up or down, when the list is ordered by hand |
| ⌘⌫ | Delete (⌘Z undoes it) |
| F | Filter |
| ⇧F | Remove the last filter |
| ⌥⇧F | Clear all filters |
| ⇧V | Display options |
| ] | Details panel |
| ⌘B | Switch between list and board |
| G then A, B or E | Active, Backlog or All issues |
| W then O | Work on the issue with an agent |
| ⌘. | Copy ID |
| ⌘⇧. | Copy branch name |
| ⌘⇧, | Copy link |
In the new-issue sheet, ⌘↩ creates the issue, S, P, A, L and ⇧D open the pickers when you aren’t typing, and Esc closes it. On an issue page, ⌘↩ posts a comment.
Questions
An agent won’t start on an issue. The agent menus show why: the agent isn’t installed, isn’t signed in, or needs connecting in Settings. If the project’s folder has gone, Codz says “This project’s folder is missing, so an agent has nowhere to work.”
My agent doesn’t seem to know about the tracker. Check that Settings ▸ Browser & tools ▸ Issue tracker is on and that this Mac is signed in to Codz Pro. DeepSeek chats never get the tools.
Can I get a deleted issue back? Right away, with Edit ▸ Undo (⌘Z).