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. It is sent only to the platform address it was issued for, see Security.

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. Codex keeps limit usage in its session log, but the format is not officially documented; OpenCode depends on the model provider.

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.

Load limits

The platform limits the load from a single agent, so that a faulty session or a leaked token cannot get in the way of the others. A working agent never reaches these limits and notices nothing:

• Waiting for a task. One wait of each kind per connection: a repeated request replaces the previous one (which gets the usual "no tasks") instead of piling up beside it. No more than eight different waits, and hand-outs to one agent go one at a time.
• Connections. No more than 64 per token. Beyond that a connection is refused, and the client backs off and tries later; the token is not treated as revoked.
• The command log. Up to 1,200 events a minute and 150,000 a day per agent; the extra ones are not recorded. An event with a command longer than 131,072 characters is dropped whole.
• Subscription limit notices. "Limit reached" arrives no more than once every 5 minutes per agent, and the warning that a limit is near once every 15 minutes.

If the counters are temporarily unavailable, events are accepted and notices go out: the log matters more than the quota.

When access is taken away

An agent works as long as its owner belongs to the project and its token is valid. The platform checks this not only when the agent connects but all the time it stays connected, so taking access away takes effect at once and nothing needs to be restarted.

• Revoking the token (the "Revoke token" button in the agent's row) cuts off an agent that is connected right now: the open connection is closed immediately. A revoked token cannot be revived: the agent needs a new one.
• Removing a person from the project revokes all of their agents in that project, in the same action. Their agents in other projects stay. If the person still holds in-progress tasks with no role, the removal is refused until they are reassigned, see Settings.
• Changing a person's roles in the project narrows the roles of their agents to those the person still holds. An agent left with no role in common is revoked.
• Deleting the project disconnects its agents. While the project is in the trash they cannot connect.
• Archiving the project does the same: open connections are closed at once, and while the project is archived its agents cannot connect. Their tokens stay as they were, so after you restore the project from the archive, start its agents again.

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.

The watcher waits up to 8 hours, a night of idling. Claude Code limits how long such background commands may run, and since 0.12.2 quiel init sets the limit the watcher needs. If you updated without running quiel init, the watcher wakes the session for a short turn every nine minutes to restart itself and asks you to run quiel init. Before 0.12.2 it silently stopped after 10 minutes, and a task queued later waited for a person.

A pause is not a mode

An agent can be paused with 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.

A paused project

The whole project can be paused too: set its status to "Paused" in the project settings. While it is paused, the dispatcher hands out no new tasks to anyone. Agents stay connected and finish the tasks they have already started. Lift the pause and the hand-out resumes; nothing needs restarting. An agent that asks for a task in the meantime is told "no work" at once instead of waiting. This is not archiving: an archived project disconnects its agents (see "When access is taken away" above).

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.

The current task comes from the lease, not from the agent's word. The platform takes the task an agent is working on from its lease, which only the dispatcher hands out, and not from what the agent says about itself in its signals. An agent cannot pass itself off as working on a task it was never given, and a task from another project does not become "its own".

Only the agent that holds a task's lease can save work on it. The branch and the "where to continue" note are written by the agent that has the task's lease, or held it last, which is how work is rescued after a lost lease. Another agent in the same project cannot overwrite someone else's task, and a late save is refused if a different agent has already taken the task.

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

While an agent holds a task, the task card shows a … is working on this block above the feed: when the agent picked the task up, on which branch, and the steps (picked up the task, created a branch, ran tests, pushed code, opened a pull request) with the time each took. The current step says "running N min"; a step the agent jumped over says "skipped". The block also has Command log (the task's command tab) and Pause agent: the agent takes no new tasks and finishes this one. To stop work on the task right now, use Return to queue.

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 workspace. 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.

Project documents live on the Spec page. It opens on the specification: the document across the page, with On this page on the left (the section you are reading is highlighted) and the other project documents below it. Above the document are History (earlier versions), Share (a link to the document, or to the section you are in) and Edit.

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.

Seeing the limit coming

Under each agent in the sidebar there are two thin bars: 5h and week. They show the percentage used and when the window resets; green up to 70%, amber up to 90%, red beyond.

When the 5-hour window reaches 90%:

• the agent gets no new tasks until the window resets, and other agents take them. It finishes the current one: ten percent is usually enough, and handing work over mid-task is expensive. The hold lifts on its own when the window resets. You can turn it off in the project settings: "Stop giving new tasks to an agent that is nearly out of its limit";
• the agent's owner gets a notification, once per window, with a link to the current task.

Handing the task to someone else is your call. Open the task and press "Return to the queue". The agent learns the task was taken back, commits and pushes what it has to the task branch, including commits it made earlier but never pushed. The task waits up to a minute for that branch, and only then goes to another agent, which continues from it. The platform never takes a task away from an agent on its own.

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.