Skip to content

Your first issue, end to end

One full cycle: write an issue, hand it to an agent, watch the agent work, and respond to the result. This assumes you already have an agent set up — if not, start with hiring an agent.

1. Open the issue list

In the sidebar, under Work, click Issues. You get a table of every issue in the company, with its priority, title, status, assignee, and last update.

The filter bar across the top lets you narrow by status, priority, or assignee, search by text, and toggle the ⚠ Needs attention chip (issues the agents couldn't place — more on that in keeping an eye on things).

Click + New Issue (top right).

2. Fill out the form

A modal opens with these fields:

Field Notes
Title One sentence describing the work. Keep it short — the agent reads it.
Description Optional. Markdown. Anything the agent should know that isn't in the title.
Attachments Optional files. PDFs and text/code files are read by the agent; other types upload but the agent only sees a stub. Up to 50 MB per file, 20 files.
Status Defaults to Backlog. Pick Todo (or In Progress) if you want an agent to grab it on its next heartbeat — agents skip Backlog.
Priority Defaults to Medium. Higher-priority issues get picked first when an agent has several assigned. Choices: Low, Medium, High, Critical.
Assignee The agent who should do this. Leave Unassigned to let a triage agent (if you have one) route it.
Project Shown only when projects exist. Attach the issue if the work belongs to a project — also where the agent's /write-file output lands. Without a project, agent-written files fall back to the company files directory instead (see the /write-file action).

Click Create Issue.

3. The issue page

You land on the issue's detail page. The layout:

  • Blocked banner — appears only when the issue is blocked, showing the reason and which agent blocked it.
  • Header — priority icon, title, status badge, the issue ID, and thumbs-up/down vote arrows.
  • Description — the body. Click it to edit inline.
  • Live Transcript — appears while an agent is actively running on this issue, streaming the model's reply as it's produced.
  • Timeline — every event on the issue: comments, status changes, agent runs, file writes, approvals, relations. This is the issue's history.
  • Comment composer — add a reply (see step 6).
  • Documents — long-form markdown the agent can write and revise.
  • Attachments — files you or the agent uploaded.
  • Work Products — the agent's named deliverables.
  • Files written by agents — files the agent saved to the project workspace via /write-file.
  • Properties panel (right side) — quick edits for status, assignee, priority, and project, plus action buttons.

4. Hand it to the agent

If the agent's heartbeat is on, it picks the issue up on its own within its interval. To run it right now, use the right-hand Properties panel:

  • Run Agent — fires a one-shot run of the assigned agent against this issue. (Shown only when the issue has an assignee.)

You can also open the agent's page and click Run Heartbeat there for the same effect.

5. Watch the run

Roughly in this order, you'll see:

  • The agent's status flip to active (visible on the Dashboard and the Agents list).
  • The Live Transcript panel appear under the description and start streaming text.
  • When the reply is complete, the transcript closes and a new comment lands in the Timeline.
  • Any status, priority, or assignment changes the agent made (by emitting /status done, /assign …, and so on) show up as their own Timeline entries.
  • If the agent wrote files, they appear under Files written by agents (and in the project's workspace).
  • If the agent asked for sign-off, an "Approval requested" entry appears in the Timeline and a row shows up under Approvals → Pending.

6. Respond

From here you have options:

  • Comment — add a free-text reply. @mention an agent by name and that agent gets a wake-up to look at this issue on its next heartbeat.
  • Comment & Resume — shown when the issue is in a stalled or finished state (Blocked, Done, In Review, Cancelled). It posts your comment and moves the issue back to In Progress in one click, so the assigned agent reopens it with your new context.
  • Reassign — change the assignee in the Properties panel. The new assignee gets a wake-up (if its heartbeat is on).
  • Set status — flip to Done to close it, or Blocked to park it. You can also Promote to Routine to turn a one-off issue into a recurring scheduled job.
  • Run Agent again — useful right after you comment: "I replied, please re-evaluate."
  • Vote — thumbs up or down. Feedback exports use this to track which issues went well.

7. Close it out

When the work is done, set the status to Done. The agent skips it on future heartbeats. Done issues stay in the database and on the Timeline for the record, but drop out of the default Issues filters.

What can go wrong

  • The agent ran but the answer is weak. Comment with feedback, reassign if needed, or Run Agent again — agents self-correct on the next run when given new context.
  • The agent never picked it up. Check the issue is in a ready status (not Backlog), that it's assigned, and that the agent's heartbeat is on. More in the heartbeat page.
  • The agent stopped. It either set the issue to Blocked (read the comment for why) or raised an approval (look under Approvals → Pending — see handling approvals).