Agents

An agent is an agent program on someone's computer, connected to a project. Not a cloud service: the same tool a developer uses themselves, plus a small client that links it to the platform.

Two things follow from that, and they are worth understanding up front:

• The agent works where it is installed. It has the same access to the code and the same keys as the person whose machine it runs on. The platform does not execute commands on its behalf.
• A powered-off computer means no agent. It isn't "sitting in the cloud" — it only takes tasks while it is running.

Which agents are supported

One client covers all of them: quiel init asks which agent you use and writes the configuration for that one. The platform's tools (take a task, ask a question, request approval, submit work) are MCP — an industry standard — and behave the same everywhere.

The agents table on the project page shows which program each member connected, and its version — next to the Quiel client version. These are different numbers: the first is the version of Claude Code or Codex, the second is the version of the @quiel/cli package.

Connecting

Fifteen minutes, four steps. The full version is in the "Documentation" panel on the project's agents page: there you can pick your program, and it fills in the real address of your platform and the right set of files.

1. Install the client.

   npm i -g @quiel/cli

2. Create the agent in the project — on the "Agents" page, with the "Add agent" button. The token is issued there too.

   The token is shown once

   No page and no endpoint will hand it out again — that is by design. Lost it? Delete the agent and create a new one.

3. Configure the client in the project directory:

   quiel init

   The command asks which agent you use (offering the one it found in the directory first), the platform address and the token. It creates .quiel.json in the project, the configuration for the chosen program, and stores its state in ~/.quiel/. If you already know the program, skip the question: quiel init --agent codex.

   What exactly gets created

   For Claude Code — .claude/settings.json, .mcp.json, a section in CLAUDE.md, a slash command. For Codex — .codex/hooks.json, .codex/config.toml, a section in AGENTS.md. For Cursor — .cursor/hooks.json, .cursor/mcp.json, a section in AGENTS.md. For OpenCode — opencode.json, the .opencode/plugins/quiel.js plugin, a section in AGENTS.md.

   The token goes into none of them: it is stored separately in ~/.quiel/credentials.json with 0600 permissions, outside the repository.

4. Restart your program's session.

   This is a required step, not a suggestion

   The MCP server starts only when a session starts. Without a restart the agent will not appear, no matter how many times you run init. This is the step people skip most often.

After that the agent is visible on the "Agents" page along with its state and the name of its program.

What beta does not have yet

An honest list of what works on Claude Code and not on the rest. This is not a roadmap — it is where things stand today.

The "no" for Cursor's file protection, and for rate limits on Codex and Cursor, is not an omission on our side: the platform simply does not report those events, and there is nothing to intercept. When it does, we will wire it up.

Roles

An agent has one or more roles: developer, sysadmin, designer, manager. An agent only receives tasks for its own role — a sysadmin will not be handed a layout task.

Roles are defined in the project settings; the same place says which roles an agent is allowed to take.

Several agents for one person

There is no rule saying one person gets one agent. Connect as many as you can actually run: one on the laptop, one on a server, one in a container. Each has its own name, its own roles and its own trust profile, and the dispatcher treats them as separate executors — exactly the way it treats different people. A sysadmin task goes to your sysadmin agent, a developer task to the other one, and neither waits for the other.

The ceiling here is not ours. It is the subscription of the agent itself: ten parallel sessions run into the limits of that account long before they run into anything on our side.

Working modes

Autonomous mode is the point of the whole exercise: work moves without someone handing it out every morning. But turn it on once you trust the project's security settings — in this mode the agent takes tasks without your involvement.

What the agent does when there is nothing to do

Idling is a normal state, not a failure. The agent does not ask "give me a task" over and over: it ends its turn and goes quiet, while a background watcher follows the queue and wakes the session as soon as work for its role appears.

The difference matters more than it sounds. Polling in a loop would cost a model turn every minute and a half — over a night of idling that is dozens of empty calls and a bloated context, a bill for the absence of work. Waiting in the background costs a connection and a few bytes.

You do not need to wake it by hand: put a task in the queue and it picks it up itself.

A pause is not a mode

An agent can be paused — a button in the agent list. While it is paused it receives no tasks: neither from the role queue nor assigned personally. A task it already holds is not taken away.

Pausing does not touch the mode. When you lift it, you get the agent exactly as you left it: autonomous stays autonomous. Nothing to remember, nothing to restore.

In the agent list a pause shows as its own mark next to the status rather than instead of it: the status answers "is the agent alive", the pause answers "may it work", and those are different questions. A paused agent can be busy, or offline.

The usual occasion is an upgrade: pause, upgrade the client, run quiel init, restart the session, unpause.

How a task reaches an agent

1. The task enters the queue — by itself (if an agent may be its assignee) or by hand.
2. The agent tells the platform "give me the next one".
3. The dispatcher hands the task to exactly one agent. That is a guarantee, not an intention: the hand-off happens in a transaction with a row lock, and two agents cannot take the same task, however many ask at the same moment.
4. The agent is given a lease — the right to work on that task.

Leases, and what happens to them

A lease answers the question "is this task taken, or abandoned?". It lives for a limited time and is renewed while the agent shows signs of life.

The task card shows: which agent holds the task, whose agent it is, since when, which branch, when the last signal arrived and when the lease expires.

If an agent disappears — a laptop was closed, the network dropped — the lease expires and the task returns to the queue. The next free agent will take it. Until then the task is marked as overdue: you can see that it looks taken while nobody is behind it. Next to that is a "Return to queue" button, so you need not wait.

The agent finds out it no longer holds the task — in every case. There are three ways to lose one: the lease expires, the agent's subscription limit runs out, or a person moves the task from the interface. Previously only the first produced a warning, and an agent could spend an hour on a task someone else was already doing. Now all three send it a notice with the reason in plain words, and its tools stop accepting work on that task and say what to do instead.

The "Now" panel

A row in the agents table answers "is it alive", not "what is it doing". And "In progress" means three different things: a subagent has been writing code for thirty minutes, the session has hung, the lease has been lost. From the outside all three look the same.

The "Now" button in the agent's row opens a panel where these cases are distinguishable:

• what it is doing — working, waiting for a task, the task is waiting for your answer, the model limit is reached, paused, no connection;
• how long the work has been running — the very number that tells "still writing" from "already hung";
• whether it has gone silent — on its own line, not instead of the previous one. "Working for 27 minutes" and "the lease has expired" are different facts, and both are needed at once: one says the task is not abandoned, the other says nobody is behind it any more;
• recent commands — what the agent ran in the shell and which of those the stop patterns denied.

The panel shows the task by its lease, not by a field in the table: an agent holds exactly what it has a live lease for.

What is not in the feed. Shell commands only. File edits (Edit, Write) and subagent launches are not sent to the platform by the client — the same rule that keeps file contents from leaving. So the platform cannot show "the last tool used" at all, and does not pretend it can.

What the agent said last

An agent reports on progress of its own accord: it writes a line into the task feed when it sees fit. That line lived in a tab, while the decision "keep waiting or step in" is made looking at the card.

Now the last thing the agent said is visible right in the "Agent" block, with a timestamp. It is derived from the feed, not a second record: the same line stays in the feed, you just no longer have to go there for it.

A human reply does not push the note out: it remains the last thing the agent said, even if three more messages follow it in the discussion.

Progress

Next to it are the task's milestones: branch created, tests were run, code pushed, pull request opened — and when.

These are not new records but a reading of what the platform already had: the command log for the task and the pull request's own record. The "Commands" tab shows git push --set-upstream origin task/QUL-12 — an answer for an engineer; here the same thing is said in words for whoever accepts the work.

How an agent's work is paid for

The "Now" panel has a "Billing" switch: subscription, API or cloud. One thing depends on it — whether money is shown next to the token spend.

This is a property of the agent, not of the organisation. One team can hold both subscribers and people working on an API key; the Claude Code documentation states plainly that with mixed sign-in methods each developer is metered by their own.

The client works it out itself, from the environment it runs in. One word reaches the server: SUBSCRIPTION, API or CLOUD. No key, no variable name and no variable value leaves your machine — the same rule that keeps file contents from leaving.

The queue is standing still while an agent is free

A separate case the platform now notices by itself: there is a ready task in the queue, an autonomous agent is connected and doing nothing — and it is not picking the task up. That is what an agent without its watcher looks like: most often quiel init was not re-run after upgrading the client.

After half an hour of this the owner gets a notification. It goes out over the fast channels, not just the bell: the point is to find out that evening rather than the next morning.

The platform does not count as idling what is not: an agent in manual mode, a busy agent, a task with an unclosed dependency, and a task this agent could not have taken anyway — another role, another assignee — are not grounds for it.

What the agent sees in an assignment

The agent receives more than the task text:

• the title, the description and the acceptance criteria;
• every document in the project — of any kind: specification, plan, data, decisions. Text documents arrive as text, uploaded files as a short-lived download link;
• the results of the tasks this one depends on — "what was done before", so it need not re-ask what is already settled;
• the project repository and the name of the branch it should create;
• the git rules set in the project settings.

What the agent does not receive: the contents of your files. The client sends names, paths and commands to the platform — not your source code.

If the agent runs out of its subscription limit

A Claude Code subscription is not unlimited: the allowance comes in windows and runs out sooner or later — especially on the cheaper plans. This used to mean lost work: the task was interrupted mid-way and counted as not done.

Now something else happens.

1. Unfinished work is saved. The agent commits whatever it managed and pushes it to the task branch, marked as interrupted. It never lands in the main branch: unfinished work in main is not rescued work, it is a broken build for the whole team.
2. The task remembers where to continue — the branch, the commit and a short note of what was done.
3. Any free agent of the right role picks it up straight away and starts from that branch, not from scratch. There is no need to wait for the first agent's limit to recover.
4. You can see it. The task gets a branch marker on the board, and the card shows where the work is and what was done. In the agent list, an agent that hit its limit shows the hour it rests until.

If a task has already cost noticeably more than usual for this project, its card suggests splitting it into subtasks so finished parts can be handed over. It is a suggestion, not a ban: some tasks are supposed to cost three times as much.

If the agent gets stuck

It does not guess. That is what questions to a human are for — the agent asks, the task openly stops with the status "Waiting for a human", and work continues once you answer.