Skip to content

Colony Mayor

The Colony Mayor is the assistant built into Colony Cloud. Open it from the button at the bottom-right of any authenticated dashboard page, or press ⌘J (Ctrl+J on Windows and Linux). It opens as a docked panel beside the page, so you can keep working while you talk to it.

The Mayor:

  • summarizes the state of your pipeline: work items, queues, reviews, estimates, tracks, reports and your enabled repositories;
  • links you to the page that does the job;
  • answers questions about Colony from these docs, and names the page and section it used;
  • runs work-item actions (from pausing and retrying to moving state and accepting) and creates drafts, after you approve them.

The Mayor doesn’t open or search your repository. It works from pipeline state, and that state can quote code: findings, review notes and agent transcripts can include what an agent read from your repository. Colony scrubs secrets it recognizes from transcripts before the Mayor sees them. What the Mayor reads can also be kept in your saved conversation. It also doesn’t file issues, import plans, or decide strategy. It points you to the page that does: Work › New proposal, Work › Import a plan, and Autonomy › Strategy.

The Mayor is backed by Claude and runs over a subset of the Colony tools in MCP & Editor Integration, chosen by your grants. Everyone gets the read tools. Work write adds colony_act and colony_create_draft. Autonomy adds colony_strategy for reading snapshots (list and get). The Mayor is offered only the tools your grants allow somewhere in the organization, and a call on a tenant or repository you can’t act on is refused. See MCP & Editor Integration for the full tool reference; the hosted MCP tool list is unchanged.

Write actions (pausing, canceling, retrying, reimplementing, moving state, sending feedback and the other work-item actions, and creating drafts) need your approval before they run.

When the Mayor proposes one or more changes, the panel pauses and shows a dialog titled Approve this action, or Approve N actions when it proposes several at once. Each proposed change is a row with a checkbox, ticked by default. A row shows the item’s title and state, what the change will do, and a warning if it can’t be undone, such as reimplementing, decomposing, moving state or a workflow action. Moving state names the target state, and feedback and answers say they send your text. Untick any row you want left alone.

Click Allow to run the ticked changes. Click Cancel to run none of them. The Mayor then carries on with the conversation. While a confirmation is pending, the panel and in-app navigation are locked so you can’t move away by accident.

This applies to the following tools: colony_act (any of its actions) and colony_create_draft (a draft lands in Proposals, and a person still authorizes it). Some actions need more than Work write (see MCP & Editor Integration); approval doesn’t widen what a person’s grants allow.

The Mayor can also accept an epic. Its confirmation first shows the epic’s open blocking findings, its children and why the review escalated, and asks about the follow-up choice for polish findings. Allowing it has the same effect as Accept on the item: the epic merges with its children once checks pass, and no code-host review is needed. A subtask can’t be accepted on its own; the confirmation says it is accepted through its epic.

Sessions with the viewer role cannot execute any write tool, and the Mayor is not offered one. The server enforces this independently of the confirmation dialog. Read tools are available to all roles and never ask for confirmation: colony_work, colony_estimate, colony_review, colony_tracks, colony_intelligence, colony_workflows, colony_flaky_checks, colony_queue, colony_standards, colony_report, colony_docs (searches these docs; the Mayor names the page and section it used), colony_repos (lists your organization’s enabled repositories), and colony_strategy (list and get, with the Autonomy grant).

Your conversations are saved, per person and per organization. Open the conversation list in the panel to return to an earlier one, delete one conversation, or delete them all. Other people in your organization can’t see your conversations.

A conversation is deleted automatically 30 days after its last message, along with all of its messages. Deleting a conversation yourself removes it immediately.

The Mayor has monthly and per-person daily cost limits, and a turn stops cleanly when one is reached. The daily count resets at midnight UTC; the monthly limits reset at the start of each calendar month (UTC). Only messages you send count as requests.

These limits apply when the Mayor runs on Colony’s model access. Use through your own model access (Mayor routing) doesn’t count against them, and Operations → Settings shows it separately.

When a limit is reached, the Mayor says so in the conversation. If your subscription is inactive, the Mayor pauses until it is active again.

To see use, open Operations → Settings (/operations/settings). It shows month-to-date use against the monthly limit and your own use today.

This is the same Mayor that answers comments addressed to it on the code host, with a wider reach there. On the code host it also sees the comment thread, and a reply that needs a closer look can read files in the repository.