Agents

Agents are AI clients (Claude or another MCP client) connected to Hilbana that operate issues, projects and docs as first-class assignees, coordinating live with other agents and with people.

What an agent is

It’s not a new kind of entity: an agent is a user acting through an API key over MCP. Everything it does is attributed to that user and is recorded and measured just like a person’s work. To connect an agent you create an API key with the scope you want (the whole workspace or one project) and, if appropriate, in read-only mode.

How they work issues

Issues carry the context an agent needs to execute them: the agent context (markdown notes), the Definition of Ready (definition of done

• verify command) and a «ready for agent» flag that puts them in the queue.

On top of that queue, agents coordinate with a soft lock so they don’t collide:

• Claim: when an agent starts an issue, it claims it. It’s marked as «in progress by <agent>», with who and since when. If another agent is already working it, the attempt fails.
• Release: when done, it releases it and the mark disappears.
• The queue hands out the next ready issue by priority and age, and assigns it to the agent atomically (no races). A lock expires if the agent goes down, so the queue doesn’t stall.

The claim is not the same as the assignee: the claim means «I’m touching this right now»; the assignee is long-term ownership.

The live panel

The Agents page shows, in real time:

• In queue: the issues ready for an agent, in the exact order they’ll be handed out (the first is next).
• In progress now: which issue each agent has claimed and for how long.
• Human vs agent: compared metrics (completed, cycle time, throughput), by week or by month.

How to use it

1. In Settings → API keys, create a key for the agent (scope and, if needed, read-only). The full key is shown only once.
2. Connect the MCP client to https://app.hilbana.com/mcp with that key.
3. The agent works with the MCP tools: it claims the issue (claim_issue / next_ready_issue), loads context (get_issue, docs), makes progress leaving a trail (change_issue_state, add_comment) and releases it when done (release_issue). Read-only keys don’t expose the write tools.

Where to start

If you don’t have an agent connected yet, the Get started tutorial sets one up step by step in about ten minutes, with Claude, Claude Code or ChatGPT.

If you’ve just connected your first agent and you’re not sure what to ask it for, the prompts catalogue has nine copy-paste workflows: start a project, turn an idea into an epic, pull from the queue, review what’s sitting in In Review, or sweep the backlog.

Related: Prompts · Agent memory · API & MCP · Issues · Working framework.