Working with a coding agent

Orbi has its own MCP server (Collaboration). When a coding agent connects to it, your board becomes its work queue. It reads the card, does the work, opens the branch, sends the pull request and moves the card to review.

This page explains how to set that up. None of it is theoretical either, because the Orbi team uses its own board exactly this way.

#What it looks like

1. You open a card, for example "The / shortcut in global search does not work".
2. The agent pulls the card, reads the code and fixes it.
3. It opens a branch, pushes and opens a pull request, and it writes the PR description itself.
4. It leaves a "what I did, what I thought" comment under the card, moves the card to review and assigns it to you.
5. You look at the board in the morning.

The difference comes down to this. The work of an agent running in a chat window stays in the chat history, while the work of an agent connected to the board stays where the rest of the team will see it.

#Setup

#1. Create the agent

The most solid setup makes the coding agent a team member on the board.

Create an agent with Settings → Team → Add a team member → Add agent (for example "Developer"), set where it runs to "Connects from outside" and press Create. The setup guide and tokens are on the Tool access tab of your profile; the Connection section on the agent page only shows the connection status and takes you there with Open Tool access (Agents). You do not need to generate a key; identity is granted in the browser in the next step.

That way every comment the agent writes appears on the board under that agent's name, and the "did I do this or did the AI" question disappears. Your own notifications work as well. Since the agent is not acting in your name, you hear about it when it comments on your card or moves it to review.

You can also connect in your own name. If you pick "Me" on the consent screen the agent works in your name, so everything it does looks like yours on the board, and because you get no notifications for your own actions, you miss the changes. That is good enough for a quick trial, not for a permanent setup.

#2. Connect the agent

The setup guide is a set of client cards (Claude Code, Claude, Cursor, VS Code, Other client); pick a card to see its numbered steps, and they all rest on a single piece of information: Orbi's address. The guide is on the Tool access tab of your profile. For Claude Code the command looks like this, with no key in it.

claude mcp add --transport http orbi https://mcp.orbiwork.space/mcp

Then type /mcp in Claude Code and choose Authenticate next to the server. Orbi opens in your browser; if you are not signed in, you sign in first. The consent screen asks two things: which workspace and on whose behalf. Pick the agent you created and press Allow. When you return to the terminal the connection is up.

For Cursor the guide has an Add to Cursor button; clicking it adds the server and Cursor shows "Needs login" next to it, which opens the same consent screen. The VS Code card has an Add to VS Code button too; if the button does not work, a ready block to paste into .vscode/mcp.json in your project is there. For other clients that use a settings file, the address is on the Other client card. In Claude desktop and claude.ai, paste the address into Settings → Connectors → Add custom connector.

If you have more than one workspace, each one is a separate connection. You add the same address once more under a different name and pick the other workspace on the consent screen. The number of connections does not change; what goes away is copying keys.

Clients without a browser still have the secret-key path: press Create token on the Tool access tab of your profile. An Admin creates tokens that act as an agent, picking the agent under Acts as in the dialog. The token is shown once, next to steps for Claude Code, Cursor, VS Code, the stdio bridge and your own client. The mcp-remote bridge and scripts you write yourself use this path. If you are connecting a client you wrote yourself, there is only one thing to know. There is a single address, every request goes to it, and every request carries the authentication header.

However you connect, the connection shows up as a row in the Access tokens list on the Tool access tab of your profile, and the moment you revoke it the client is cut off on its next call. Click the row and the token's panel opens: when it was created, when it expires, when it was last used, which device connected with it and, for a grant made from the browser, which client it was given to. The revoke button is in that panel too. The token sees a closed space only when you choose it there with Choose closed spaces.

To verify the connection, tell the agent to call the whoami tool. It reports which user, which workspace, which permissions and which Orbi installation it is connected to. That last part matters, because if you work with more than one Orbi installation (a trial one and a real one, say), card numbers are the same on both but the cards are different. Work reported as "fixed" that was done in the wrong installation is work nobody can find, and whoami settles it in one call.

The moment the connection is made, Orbi sends the agent an introduction to the workspace (projects, collections, defined agents, workspace context and working rules), and the details are in Collaboration. The practical consequence is this. You do not have to start every session by explaining the project from scratch. Keep the knowledge you want the agent to have in Orbi. The text you write under Settings → General → Workspace context goes to both Orbi's own agents and the coding agent that connects. Project-specific rules belong in the project description, and what the team has learned belongs in collections.

#3. Prepare the cards

An agent works well with a good brief, just like a person (Tasks). Put these on the card.

• What you want. Write a concrete result rather than "improve this".
• Where. Give the file or screen name, or link to earlier work with @task.N.
• What to follow. Match the existing pattern, add no new dependency, keep the tests passing.

Assign the card to the agent and queue it. A card assigned to an agent that connects from outside is not run inside Orbi. It waits in the queue marked "waiting for its client", and your agent finds it in its own queue (list_tasks called without filters returns its own work). Next to the mark you can see whether the agent's client is online, offline or has never connected, and the answer to "why is it not starting" is usually right there. If the client is not connected at that moment, Orbi already tells you so while you queue the card and asks you to confirm.

If the agent works in more than one repository. Add as many repositories as you need to the "Repositories" list on the agent page; every addition uses the same picker (choose from the connected devices' folders or type the address), the first row is the default, and each row says which devices hold that repository; if none does, it warns you as you add it. A card assigned to such an agent shows a repository selector under its message box, and you pick which repository the card works in; the agent does not guess. On a single-repository agent the selector never appears. For work that touches two dependent repositories, such as a server and a client, open a parent card: write the shared contract (endpoints, message format) in its description, open one subtask per repository and link them with the "Link to a parent card" or "Add subtask" picker in the drawer (it searches by title or number); an agent can also set up the subtasks itself by naming the parent when it creates a card. When a subtask goes to a device the parent's description goes with it, so both subtasks read the same contract; the subtasks' pull requests are listed together on the parent card. To keep such work on a single card instead, give the card to a squad: its coordinator opens one member run per repository, each on its own branch, and the pull requests land on the same card.

If nobody picks it up, the card goes to error after 6 hours, so no card sits waiting silently because of a closed laptop. The same ceiling applies after your agent has taken the card, so if the card makes no progress at all for 6 hours, it goes to error. A long job is not cut off by this, because coding work can take hours. A stalled session, on the other hand, does not leave a card in "in progress" forever.

#Driving the loop

An agent run does not last forever, it ends when the model stops calling tools. That is not a defect, because an agent stuck in an endless loop fills its context window and has nowhere left to stop.

The right pattern is to drive the loop from the outside.

every N minutes:
  1. list_tasks            → unfinished cards assigned to me
  2. no cards              → exit
  3. get_task              → read the whole card
  4. do the work           → branch, commit, PR
  5. add_task_comment      → write down what you did
  6. set_task_state review → the card goes back to the person who opened it

If the agent skips the last step, the card stays "in progress", hits the ceiling above and drops to error. Finished work then looks on the board as though it never started. So add one thing to your script: when the command finishes with exit code zero and the card is still "in progress", move the card to Review yourself. If the agent has already done so, that call changes nothing, because the first author is always the agent.

Whatever the scheduler is (cron, a systemd timer, a CI scheduler), what matters is that the state lives on the board, not in the agent. Even if a run is cut off half-way, the next round carries on from where it stopped, because the truth is written on the card.

You do not have to write your own loop. Orbi Node connects your device or server to the board; you pick from the interface which coding tool runs in which folder, and the application takes over claiming and closing the card. The loop above still holds, and works under the same contract if you would rather write your own script: it finishes without asking questions, returns the right exit code and reaches MCP.

#The team's shared memory

A coding agent reads and writes more than cards, because it also uses the team's shared memory. It reaches collections (list_collections, read_collection, search_records, write_record) and files (list_files, read_file, write_file). The full list is in Collaboration.

In practice this means that when your agent writes an architectural decision, a measurement or a "we tried this approach and here is why it did not work" note into a collection, that knowledge is there in your teammate's session too. The same holds for Orbi's own agents, because the tools are identical, so the Orbi orchestrator reads the record your coding agent wrote.

Two practical habits make this easier.

• Search before you write. search_records works semantically, and writing the same knowledge a second time does not grow the memory, it pollutes it. If the collection has a dedup field, write_record may find the similar record and refuse to write (check the written field in the result). With no dedup field defined there is no such protection, and the searching is up to you.
• Write to memory, not to the card. A comment is a conversation and falls out of the flow once the card is closed, while a collection record is permanent and searchable. "What I did in this run" belongs in a comment, and "we need to know this from now on" belongs in a collection.

#Two traps

Setting queued with set_task_state starts Orbi's own agents. If your coding agent wants to mark a card as "I have queued this", it should use todo, because queued is an order to execute (Tasks).

An @agent.<name> in a comment starts that agent. If your coding agent wants to refer to an Orbi agent, it should name it in plain text rather than mention it.

#Permissions and security

• The token defines no separate permission system, it inherits its owner's role. If your role drops, the token's permissions drop with it immediately.
• A read-only token is the right choice for clients that only watch the board, because opening cards, changing states and writing comments are disabled.
• Revocation takes effect on the next call, and there is no session cache.
• Do not commit the token to a repository. Keep it in an environment variable.

#Limits

• The coding agent's own usage limits are not under Orbi's control. For long unattended runs, check your provider's billing model.
• There is currently no per-token rate limit on the Orbi MCP server. That is not a problem for your own team's own token, but do not share the token with a third party.
• Shared memory cannot be deleted remotely. Deleting a collection record or someone else's file stays in the interface. Your coding agent can write and update them, not delete them. There are two narrow exceptions. A card can be deleted (delete_task), and that requires a person to have asked for it explicitly. A file the agent wrote itself, that is not an upload and is not attached to any card, can be moved to the trash (delete_file) and restored from the interface for 30 days. Who deleted it stays in the activity log.