Docs

Issues

The issue tracker is the primary mechanism for queueing work for the orchestrator. Open issues are the backlog — the orchestrator reads them at the start of every turn and decides which to delegate next. Issues are persisted locally in .agenties/issues.json and synced through Agenties cloud sync for multi-machine access.

Issue structure

TypeScript
interface Issue {
  id: string;                  // "issue_<nanoid>"
  seq: number;                 // Sequential number for display (#1, #2, ...)
  title: string;               // Short description
  description?: string;        // Full markdown body with context and acceptance criteria
  status: IssueStatus;
  priority: IssuePriority;
  assignee?: string;           // team member id or "orchestrator"
  linkedAgentId?: string;      // Running agent currently working on this issue
  agentRole?: AgentRole;       // Role of the assigned agent

  // Metadata
  labels?: string[];
  createdAt: string;
  updatedAt: string;
  closedAt?: string;
  createdBy: "user" | "orchestrator" | "routine" | "heartbeat";
}

Statuses

openIn the backlog. The orchestrator will pick this up on its next turn.
in_progressAn agent is currently working on this. linkedAgentId is set.
blockedCannot proceed — waiting for a dependency, external input, or human decision.
doneCompleted successfully. closedAt is set.
closedManually closed without completion (e.g. won't fix, duplicate).

Priorities

PriorityOrchestrator behaviour
urgentAlways delegated before any other issues. Bypasses normal queue order.
highDelegated before medium and low. Shown with a colour indicator in the UI.
mediumDefault. Normal queue order.
lowPicked up only when no higher-priority issues are open.
noneNo priority set. Treated as low.
Note:The orchestrator reads issue priority as a sorting signal, not a strict rule. It may still choose a lower-priority issue if it is a better dependency unblock for the current in-progress work.

Creating issues

From the UI

Navigate to /issues or the Issues tab. Click New issue. Fill in the title, description (markdown supported), priority, and any labels. The issue immediately becomes visible to the orchestrator on its next turn.

From chat

Describe a task in the chat and the orchestrator will create an issue automatically. You can also ask explicitly: "Create a high-priority issue to refactor the auth module."

Via MCP tool

TypeScript
create_issue({
  title: "Refactor auth module to use JWT RS256",
  description: "## Background\n\nCurrently using HS256 with a shared secret...",
  priority: "high",
  labels: ["backend", "security"]
})

Via routines

Routines (API, schedule, GitHub) automatically create issues when they fire. The issue carries the routine's injected context and is immediately visible to the orchestrator.

How the orchestrator uses issues

At the start of every turn, the orchestrator calls list_issues withstatus: "open" sorted by priority descending. It then:

1.Reads the first 5–10 open issues (configurable).
2.Checks if any in_progress issues are blocked — if so, unblocking them takes priority.
3.Selects the highest-priority open issue that it can act on immediately.
4.Calls spawn_agent with issueId set — the agent reads the issue and uses it as its task spec.
5.Updates the issue status to in_progress and sets linkedAgentId.

Sync

Issues are synced with a 1-second debounce after any local change. Incoming sync events are applied as diffs — individual issue fields are merged rather than the whole file being replaced, which prevents data loss when multiple machines modify different issues concurrently.

All 5 issue statuses are synced. The linkedAgentId is local-only and not synced, since running agents are machine-specific.

Tip:Use labels to create sprint-like groupings. The Issues tab supports filter by label, status, and priority. You can save filter presets for quick access.