Docs / Settings

Agents

Mention @claude in a comment to send it to a webhook.

An agent is a name you can mention in a comment, like @claude. When you post a comment that mentions it, Suru Me sends the comment to the agent's webhook. Whatever listens there does the work and answers in comments on the same issue. It could be an AI coding agent, an n8n or Zapier flow, or a script of your own.

Using an agentLink to this section

Type @ and the first letter or two of its name in a comment. Agents you're allowed to use in this project come first in the list, marked Agent; one an admin has switched off in this project doesn't show up. Write your message and press Comment:

@claude the login page times out on slow networks, have a look

The mention can go anywhere in the comment, at the start or after a space, and case doesn't matter (@Claude works too). Text glued to it, like me@claude, isn't a mention.

Once YouTrack has saved the comment, your browser sends it on. A line under the comment box says how it went:

• Sent to @claude means the receiver got it.
• Sent to @claude (not confirmed) means it went out, but the receiver doesn't let browsers read its answer, so Suru Me can't tell. The agent's own reply is the real confirmation.
• @claude refused: … shows the receiver's own reason, like "ana may not start agents", with a Retry button.
• Couldn't reach @claude has a Retry button too.

To say more, write another comment that mentions the agent. One comment can mention several agents, and each one gets it. A comment that mentions an agent you may not use is still posted, but nothing is sent to that agent.

Assigning an issue to an agentLink to this section

An agent with its own YouTrack account can be assigned work like a person. Pick it as the issue's assignee; agents are marked with a bot in the list. In the issue panel, Suru Me then asks for an optional note, like start with the login form. Press Assign.

Suru Me adds a comment that hands the issue over, @claude please take this. start with the login form, and sends it to the agent like any mention, from Suru Me's server this time rather than your browser. The issue's history shows who handed it over and why. Assigning from a list's row menu, a board, a bulk edit or through MCP works the same way, without the note. Press Cancel instead of Assign and nothing changes.

The handover comment is the only sign in the app that it went out: there's no Sent line, so the agent's reply is your confirmation. Through MCP, update_issue and update_issues answer agentsCalled with any error.

A few things to know:

• Any field that holds one person works, not only Assignee: setting a Reviewer field to an agent's account starts it too.
• You need to be allowed to use the agent. If you're not, the issue is still assigned, but no comment is added and nothing is sent.
• An agent that assigns an issue to its own account isn't called again.
• A task created already assigned to an agent, from the new task dialog, quick add (@claude) or create_task, doesn't start it. Assign it after creating it.
• Taking the issue away from an agent doesn't stop it; stop a run in the agent's own app, like Suru Agents.

The Agents pageLink to this section

Agents shows in the sidebar once your workspace has at least one agent. It lists every agent with counts of what it has on its plate. Open one to see its issues, read from YouTrack:

• Waiting for you: open issues in a state past the working one, like In review or Blocked.
• Working on: open issues in the state right after the one new tasks start in, like In progress.
• Queued: open issues still in the state new tasks start in, or before it.
• Done this week: its issues closed this week, by YouTrack's idea of the week.

Which state new tasks start in comes from Default states, and each issue is placed by its own project's state order, so this works with any states. An issue in a project with no state field counts as Working on. Each group shows up to 100 issues.

Only issues assigned to the agent's own YouTrack account show up. An agent without one says "No YouTrack account of its own" on the list, and its page explains that nothing can be assigned to it.

Agents handing work to each otherLink to this section

An agent that comments through Suru Me's MCP server can mention another agent, and Suru Me sends that comment on too. Claude can finish its part and write @codex please review this, and Codex picks it up. A comment posted through MCP goes out from Suru Me's server, since there's no browser behind it, and add_comment answers with the agents it reached and any that refused.

Each @name is checked against both people and agents. A person gets YouTrack's usual mention, an agent gets the comment, and a name that's neither is left alone. The author still has to be allowed to use the agent. An agent that has its own YouTrack account may use every agent, so give each agent an account (see Setting agents up). An agent that comments through a person's account can use what that person can: agents open to everyone, ones that list the person, and all of them if the person is an admin. When the author may not use an agent, add_comment says so in agentsCalled instead of sending it:

"agentsCalled": [
  { "agent": "codex" },
  { "agent": "deploy", "error": "claude may not use @deploy in CT" }
]

An agent missing from the list wasn't mentioned. An error is either that refusal, the receiver's own message, or why it couldn't be reached; Suru Me's server waits 10 seconds for an answer.

An agent never calls itself: a comment written by an agent's own account, or one that starts with its 🤖 name: mark, isn't sent to that agent even when it mentions it.

Nothing stops two agents from mentioning each other back and forth, so write their prompts to hand off only when there's work for the other one.

Replies from agentsLink to this section

An agent with its own YouTrack account replies as itself, and Suru Me shows its comments with a bot badge. An agent without one replies through someone else's account and starts its reply with 🤖 name:, for example 🤖 claude: Started on CT-12. Suru Me shows any comment that starts with 🤖 under the agent's name, with a bot badge, and hides the mark. A comment that starts with 🤖 but no name shows as Bot. Point at the name to see whose account posted it. Anyone can type that mark, so the badge is a label, not proof.

Answering an agentLink to this section

When an agent asks something in a comment, press Reply (the arrow at the top right) on its comment, or right-click the comment and pick Reply. The box starts with @claude, and a line above it shows which comment you're answering. Write your answer and press Comment. The agent gets your answer together with its own question. Press the cross beside that line to stop replying.

Reply shows only on an agent's comments, and only when you're allowed to use that agent.

Setting agents upLink to this section

Agents are set up once for the whole workspace, in Settings under Agents. Only admins can change them. Everyone else sees which agents exist. Here an admin means someone YouTrack lets change articles in the "Suru Me settings" project, which YouTrack's own admins can; so can the account Suru Agents writes with, once it's connected.

A name starts with a letter and has only letters, digits, - and _, up to 31 characters. Two agents can't share a name, whatever the case. Suru Me says what's wrong and saves nothing until it's fixed.

Each agent can also have:

• Its own YouTrack account, the account it replies as. Press the field and search for it by name or login. Its comments then get the bot badge, it shows up with a bot in assignee lists and on the Agents page, and it may use every agent, so it can hand work on. Make a YouTrack user for each agent that should reply as itself, then pick it here.
• Extra values sent with every call, one key=value per line, like repo=acme/web.
• Changes in a project. Pick a project to switch the agent off there (Off in this project), or give it another address, other people, or extra values. Anything you leave empty keeps the agent's own setting, and Same as the agent keeps who can use it. Extra values for a project are added to the agent's own, and win when a key is in both. Remove drops the project's changes.

Remove agent takes an agent out. Nothing changes in YouTrack until you press Save agents, and saving changes only the agents you edited, so agents Suru Agents wrote meanwhile stay as they are.

The agents live in an article, "Suru Me agents", in the settings project. Change them in Suru Me rather than in that article: a hand edit can be overwritten, and if it breaks the JSON, Suru Me shows no agents until an admin saves them again.

Connecting Suru AgentsLink to this section

Suru Agents runs agents like Claude Code on your own server. Connect it once and it writes its agents into Suru Me by itself: names, webhook addresses and accounts. After that, both apps share the same agents. A change made in either one, including who can use an agent, shows up in the other.

If nobody has saved agents yet, pressing Connect sets up the settings project first, as the first save would. Once connected, the section lists Suru Agents with its address, the account it writes as and when it last synced, and the button reads Connect again.

Agents you added by hand with the same name are filled in, not doubled. If Suru Me can't reach Suru Agents, or Suru Agents refuses, the section says why. If Suru Agents hasn't written its agents within 30 seconds, the section says so; Suru Agents keeps trying, and its Integrations page shows how that's going. A pairing link that wasn't started in this browser is ignored, so press Connect again. Agents you set up by hand keep working either way.

Nothing secret passes between the two apps. They meet in the agents article in YouTrack, which only admins, and the account Suru Agents writes with, can change. Allow proves the person connecting runs both, so a wrong address can't start receiving your comments.

The agents article

Any app can sync agents the same way. The article "Suru Me agents" in the "Suru Me settings" project holds a short note and then one JSON block:

{
  "format": 1,
  "agents": [
    {
      "name": "claude",
      "url": "https://agents.example.com/hooks/claude?integration=int_1",
      "account": "claude",
      "invokers": { "everyone": true, "logins": [] },
      "fields": { "repo": "acme/web" },
      "projects": { "CT": { "off": true } },
      "suruAgents": { "id": "a1" }
    }
  ],
  "peers": [
    {
      "name": "Suru Agents",
      "url": "https://agents.example.com",
      "account": "claude-ops",
      "syncedAt": 1762600000000
    }
  ]
}

name and url are required, and an agent without them, or with a name that breaks the naming rule, is skipped. account is the agent's YouTrack login. invokers is who can use the agent; admins always can, and an agent saved without it is for admins only. A project in projects can switch the agent off there or replace its url, invokers or fields. peers lists the apps that sync into the article. Every app that writes it keeps the keys it doesn't know, like suruAgents, reads the article again just before writing, and changes only the agents it edited.

To be found, an app answers GET /.well-known/agent-directory with {"name": "...", "pairUrl": "https://..."}. Suru Me opens pairUrl with youtrack, article, return and state, and the app sends the browser back to return with the same state and either account (the login it writes as) or error.

What the webhook receivesLink to this section

A POST with this JSON body. The comment box sends it from the person's browser. A comment added through MCP, and the handover comment when an issue is assigned to an agent, go from Suru Me's server instead. The body is the same either way.

{
  "agent": "claude",
  "youtrack": "https://acme.youtrack.cloud",
  "issue": "CT-12",
  "issueId": "CT-12",
  "commentId": "4-123",
  "author": "ana",
  "text": "@claude the login page times out…",
  "url": "https://surume.letmecome.in/i/CT-12",
  "state": {
    "field": "State",
    "current": "In Progress",
    "values": [
      { "name": "To do" },
      { "name": "In Progress" },
      { "name": "Done", "resolved": true }
    ]
  },
  "agents": ["@claude", "@codex"],
  "fields": { "repo": "acme/web" }
}

youtrack is the YouTrack address, issue the readable id, author the login of whoever wrote the comment, text the whole comment as written, and url the issue in Suru Me. fields holds the agent's extra values, with the project's changes applied.

state is the issue's current state and every state the project offers, leaving out archived ones. Only resolved states, like Done, carry "resolved": true. current is null when the issue has no state, and state is missing when the project has no state field. It's a hint for receivers that don't read YouTrack themselves; like the rest of the body, nothing proves it's true.

agents lists every agent the comment's author may call in this project, the called one included, written as they're mentioned. An agent can pass it on in its prompt so it knows who it can hand work to.

A reply to an agent's comment also carries replyTo, the comment it answers, with the 🤖 mark removed:

"replyTo": { "commentId": "4-120", "author": "runner", "text": "Which branch?" }

A receiver that keeps an agent running, like Claude in a tmux or herdr session, can use issue to pass the answer to the session already working on that issue instead of starting a new one.

The browser (or, for comments made through MCP, Suru Me's server) sends it straight to the receiver, so it carries no secrets and anyone who can see the address could send one like it. A receiver must check every call against YouTrack, using its own token, before it acts:

1. Read comment commentId on issue issue, and make sure it exists and mentions the agent.
2. Check that the comment's author is allowed to use the agent: an admin, an invoker, or any agent's own account.
3. Skip a commentId it has already handled. Calls can arrive twice.

issueId is the same as issue; the Suru Agents receiver reads that name.

To refuse a call, answer a 4xx status with {"code": "...", "message": "..."}, like 403 with "ana may not start agents" or 400 when the comment is more than 10 minutes old. Suru Me shows the message under the comment box, with Retry.

To show Sent instead of not confirmed, the receiver should answer the browser's CORS check for Suru Me's address. When the CORS check fails, the browser sends the call again as a simple request with Content-Type: text/plain, whose answer it can't read. The body is the same JSON, so a receiver should parse the body whatever its content type. That's also why calls can arrive twice.