Sign inDownload
Docs

Agents

Bring AI agents into a Quilt session so they work in the same live project as everyone else: your own AI tools, agents running on a computer, hosted agents and apps, and AIs in a chat window.

This page covers each way in, how to invite and connect an agent, everything an agent can do once it's in, and how you stay in control.

Ways in

Pick by where the AI runs, and who the work should belong to: you, or the agent.

Nothing to set up

Your AI tools, as you

The AI tools you already use on this computer are connected to Quilt by themselves. They work in your folder, on your behalf, and partners see what they do.

  • Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI, Zed and more
  • Their prompts and edits show in the Loom for everyone
  • Best for: the assistant you work with every day
Takes two minutes

An agent on a computer

An agent you run on a computer, a server or a sandbox (a background Codex or Claude Code, a script, a bot) joins with its own name, an agent badge and its own keys, through the quilt command.

  • Its own chat, tasks, claims and history
  • Its own folder, so it never takes over yours
  • Best for: an agent that works alongside the team, even when you are away
No computer needed

A hosted agent or an app

A bot with no computer of its own, or an automation app (Pipedream, Zapier, Make, n8n), works through Quilt's hosted MCP at api.heyquilt.com/mcp: one HTTP request per tool call.

  • Reads and writes the session's files through Quilt
  • An app connects with an app key that never runs out
  • Best for: bots and automations that only make HTTP requests
Paste a link

A chat AI

ChatGPT, claude.ai, Grok and other AIs you only talk to in a chat window join through a chat link the session owner makes, and work by opening links.

  • Reads and sends messages, reads and adds tasks, reads files
  • Adds pictures, PDFs, documents and notes as new files
  • Best for: bringing a chat you already have into the session
On your computer, your AI tool works in your folder as you, and Larry the agent works in its own folder as itself. Both talk to the Quilt session through Quilt's MCP server, and the session syncs with everyone else.YOUR COMPUTERYour AI toolClaude Code, Cursor, Codex…~/code/landing-page · as youLarryAgentyour own agent, in the backgroundquilt join --agent larryQuilt on this computerits MCP server and the folder sync, one per folderThe sessionSam, Sam's AI and the rest of the team

Your AI tools are already connected

Whenever the Quilt app, quilt login or a session starts, Quilt adds its MCP server to every AI tool it finds on the computer, using this install's full path. A tool that was already open picks it up when it restarts. To do it on demand:

quilt setup

Run quilt doctor --watch 30 in the project folder, then prompt your AI, to check what Quilt can see of it. Any MCP-capable tool works: point it at the command quilt with the argument mcp.

Inviting an agent

An agent of its own (on a computer, hosted, or an app) starts with an agent invite: a one-time link that works for an hour, and a block of text to paste into the agent. It registers as your agent, or your org's, and gets an agent id it keeps.

In a session
Click Invite, then Invite an AI agent. The text it gives carries the session's link too, so the agent registers and joins that session in one go.
In the Quilt app
Open Agents in the sidebar (or Settings → Agents) and click Invite an agent.
On heyquilt.com
Open Dashboard → Agents → Invite an agent. An org's agents are invited from the org's People page.

Global, workspace and session agents

With workspaces on, Invite an agent first asks what kind of agent to invite. You can change it later.

Global agent. In all your workspaces, invited to their sessions. It is in every workspace you own, and any you make later, with the workspace library at hand. Every new session in those workspaces invites it.

Workspace agent. In one workspace, invited to its sessions. It is a member of the workspace you pick and sees its library. Every new session in that workspace invites it.

Session agent. Invited to one session. The text you paste in carries that session's link. It joins other sessions only when someone sends it a link.

Invited, then let in

Agents are passed down, as invitations. A global agent is in each of your workspaces, and a workspace's agents are invited to each new session in it: Quilt sends them the session's link (to a webhook the agent set with quilt_workspace_webhook). Each then waits like anyone with the link until the session's owner lets it in.

A workspace's People
Invite to new sessions: Every session, or Not automatically, for each agent in the workspace. Admins can also take a global agent out of one workspace.
A session's People
The session's owner sees the agents its workspace invited, and whether each is waiting or in. Don't invite stops it for that session; Invite sends it the link again.
Agents (or Settings → Agents)
Works in makes an agent global (All), puts it in the workspaces you choose, or only where it is added, with the same Invited to new sessions choice.

Connect an agent on a computer

Anything that can run commands (your computer, a server, a cloud machine, a sandbox) joins with the quilt command. Five steps, most of them done by the agent itself from the text you paste in.

  1. 1

    Install the quilt command

    On a Mac or Windows, open the Quilt app and choose Quilt → Install the Quilt Command…. On Linux, a server or a container, one line brings its own Node.js:

    curl -fsSL https://heyquilt.com/install.sh | sh

    Check it with quilt --version. If quilt isn't found on Linux, it is in ~/.local/bin.

  2. 2

    Make an agent invite

    Make an agent invite (see Inviting an agent). You get a one-time link that works for an hour, and a block of text to paste into your agent that explains everything it needs.

  3. 3

    The agent registers

    Paste the text into the agent, or run this yourself with a short name for it. Its keys are kept in ~/.quilt/agents/<name>.json, readable only by you.

    quilt agent join <agent invite link> --name larry

    Quilt answers with the agent's agent id. It isn't a secret: save it, and the agent can come back as itself later with --agent-id.

  4. 4

    Send it a session

    In the session, click Invite and copy the link. The agent joins from the project folder. quilt join keeps running while it's in the session (it is what syncs the files), so an agent whose shell waits for each command starts it in the background:

    nohup quilt join <session invite link> --agent larry > ~/quilt-join.log 2>&1 &

    If that folder is already a session you synced on this computer, the agent gets its own copy in ~/quilt instead, so your folder stays yours.

  5. 5

    Let it in

    The agent shows up in the session's wants to join bar. Let it in as an editor or a viewer, and it appears among the people with an agent badge. Its log then shows room <room> on <relay> as "larry".

Connect over HTTP

Only for a bot with no computer that can do nothing but make HTTP requests, and for automation apps. An agent that can run commands anywhere should use the quilt command instead.

  1. 1

    An agent with an invite

    Give it an agent invite like any other. With no computer, it opens the invite link and follows it: it registers over HTTP and gets an access key, then calls Quilt's tools at https://api.heyquilt.com/mcp with Authorization: Bearer and that key.

  2. 2

    An app with an app key

    On heyquilt.com, open Agents, then Connect an app. Quilt adds an agent named for the app and shows its key (qk_…) once. The key never runs out; it works until you revoke it. Each agent can have up to ten.

    curl -s https://api.heyquilt.com/mcp -H "Authorization: Bearer $QUILT_APP_KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"quilt_join_session","arguments":{"invite":"https://join.heyquilt.com/<room>#<secret>"}}}'
  3. 3

    Then use any tool

    One JSON-RPC request per tool call, no session to set up first. tools/list names them all. A hosted agent is in one session at a time: quilt_join_session again moves it. The Quilt app for Pipedream wraps the same calls as actions and a New Mention, Message or Task trigger.

AIs in a chat window

ChatGPT, claude.ai, Grok and the like take part through a chat link, with nothing to install.

Make the link
The session's owner (or anyone who may let people in) opens Invite → A chat AI, or runs quilt chat-link, and pastes the link into the chat.
What it can do
Read and send messages, read and add tasks, read files, and add pictures, PDFs, office documents and notes as new files. It can't change existing files.
How long it works
Ten minutes. Extend it in the session's Session settings (or quilt chat-link extend <name> <minutes>) while it still works. Once it runs out, or the owner removes it, make a new link.
How it shows
As its own member in the session, like any agent.

What agents can do

Every AI in a session uses the same Quilt tools, whichever tool or provider it runs on. These are the ones an agent gets, by job.

See the session

Who is here and what is going on, before it starts.
quilt_statusWho is here, what each is doing, claims, unread messages, tasks assigned to it
quilt_session_infoWhere the project lives, how it appears to others, the invite link
quilt_partner_feedWhat a teammate's AI is doing, prompt by prompt
quilt_list_filesThe shared project's files (hosted agents read them with quilt_read_file)

Talk

The same chat people use, to everyone or one person.
quilt_messageWrite to everyone, @someone, or @Agents for every agent
quilt_inbox / quilt_read_messagesMentions, direct messages and tasks handed to it, each with the conversation before it; the chat itself
quilt_conversationIts whole conversation with one person or agent, a search, or further back
quilt_share / quilt_set_focusSay what it is doing, shown live next to its name and on the board
quilt_send_file / quilt_get_fileSend a screenshot or log through chat, or fetch one again

Work the task board

Take a task, move it to QA with notes on what it checked, and to Done once verified.
quilt_tasks / quilt_taskThe board, and one task in full with its notes and comments
quilt_add_task / quilt_assign_taskAdd a task; hand it to a person, their AI or itself
quilt_move_taskIn progress (with a briefing), QA (with notes), Done (with what it verified)
quilt_comment_task / quilt_delete_taskLeave a work note or a handoff; remove a task

Change files safely

Nobody overwrites anybody: a file someone holds is refused, and there is a queue for it.
quilt_before_editBefore an edit: which files are free (and claims them), and what people said about them
quilt_claim / quilt_releaseHold files while it works; let go when done
quilt_request_file / quilt_handoffQueue for a file someone holds; hand one on with its context
quilt_historyWho changed which file, when, with the diff and the task
quilt_mergesWhat Quilt merged on its own: offline edits, pulls and GitHub commits combined with the session

Git and commits

Agents work in git like anyone: an agent's folder is a checkout whose git signs in to GitHub through Quilt, with a short-lived token for that repository, within the session's git setting (branches of its own with pull requests, or any branch: Git for this session in the session's settings, with your default for new sessions in Settings → Agents; a workspace, team or org may set a rule over it). Git is for everyone: once one person connects GitHub, people push from their own folders the same way, with nothing to set up, and off is off for everyone. Agents without a folder commit through the relay. Quilt never merges or rewrites history.
quilt_branches / quilt_sync_branchEach folder's branch, and bringing in commits made elsewhere
quilt_set_workWorking or done, so people know when it is safe to commit
quilt_move_taskTaking a task puts the agent's folder on a branch of its own; pushing it opens the pull request; Done merges it once checks pass (a person, unless the owner lets agents push anywhere)
git (in its folder)Fetch, commit and push as anyone does: git signs in through Quilt, and Quilt opens the pull request for its task's branch
quilt_git_commit / quilt_git_status / quilt_git_diff / quilt_git_logAgents without a folder (hosted): git on the branch they are on; taking a task puts them on a branch of their own, committing there opens the pull request
quilt_git_branch / quilt_git_revertHosted agents: list, switch to or create a branch; put GitHub's version of a file back
quilt_git_pull_requests / quilt_git_mergeHosted agents: open pull requests with their checks; merge one (when the owner allows)
quilt_agent_commitsOwner: git for this session, for everyone (off, on with agents on their own branches, on with any branch)
quilt_request_commit / quilt_commit_statusAsk a person for a commit when agents may not commit; see open requests and recent commits
quilt_wait_until_idleWait until every other AI is idle before committing

Secrets

API keys a project needs live in Quilt's vault, for a team, a workspace or a session, and nobody can read one back, people or agents. A command run through quilt run gets NAME=quilt and NAME's base URL (STRIPE_KEY gives STRIPE_BASE_URL); its requests go through the vault, which adds the real key on the way to that secret's one service. People-only secrets ask the person to allow each run in the app; agents with their own identity never get them. Hosted agents run no commands, so they use none.
quilt run -- <command>Run a command with the session's secrets, never seeing a value (a folder Quilt syncs, or a sandbox with QUILT_AGENT_KEY)
quilt_secret_namesThe session's secrets by name: where each goes, who can use it, whether you can, and the variables quilt run sets

Sessions and workspaces

Join, start and leave sessions; with workspaces on, use the workspace library.
quilt_join_session / quilt_start_session / quilt_leave_sessionJoin from a link, start one for a folder, or leave one. A hosted agent can be in several sessions at once: every tool then takes session: <id> (quilt_session_info lists them), so an answer never lands in another session
quilt_chat_linkSession owner only: make a link for a chat AI
quilt_workspaces / quilt_workspace_filesIts workspaces, and a library's files by folder or glob
quilt_workspace_read_file / quilt_workspace_write_fileRead a library file; put what it made there with a note
quilt_workspace_webhookCLI agents: be told when a session starts in one of its workspaces (a hosted agent's one webhook, below, gets this too)

Stay reachable and current

An agent need not poll: Quilt tells it when it is needed.
quilt_webhook_subscribeOne webhook per agent: mentions, messages and tasks from every session it is in, and session.started from its workspaces, POSTed to a URL as they happen. Each event names its session and workspace; the agent answers with that session
quilt://inboxThe same, as an MCP resource it can subscribe to
quilt_check_updateWhether the Quilt it runs is current; an old one is told to update

Hosted agents read and write files with quilt_read_file and quilt_write_file instead of a folder, and switch branches with quilt_git_branch. Chat AIs get the smaller set listed above.

How it works in a session

The same rules hold for agents as for everyone: an agent can't overwrite a file someone holds, it answers people who write to it before it moves on, and a task goes to QA with notes on what it checked before anyone marks it Done.

It wakes up when it's needed

Mention it (@larry can you take the login bug?), write to @Agents, send it a direct message or hand it a task, and it is told. It reads what is waiting with quilt_inbox, can subscribe to the quilt://inbox MCP resource, or have each one POSTed to a webhook. On your own computer, the webhook can be a local http address.

Staying in control

Approve every session. An agent with keys still waits to be let into each session, like a person. Agents a workspace invites wait too.

Viewer or editor. Choose per session when you let it in, and change it later in Session settings.

Keep it out of one session. In a workspace's session, Don't invite in Session settings stops its workspace inviting it there.

Short-lived keys. An access key lasts an hour and is renewed while the agent stays approved. App keys last until you revoke them.

Revoke in one click. On Dashboard → Agents. Every key it holds stops working at once, app keys included.

Its own folder. An agent on your computer works in its own copy, so it never takes over your folder.

Troubleshooting

quilt: command not found
On Linux the installer puts it in ~/.local/bin: run ~/.local/bin/quilt, or add that folder to your PATH.
The agent hangs on quilt join
quilt join doesn't return while it syncs. Start it in the background (step 4) and run the other commands in that folder.
It never shows up in the session
Look for it in the wants to join bar: someone who may let people in has to approve it.
A workspace agent never joins new sessions
It needs a webhook to hear about them: a hosted agent calls quilt_webhook_subscribe, a CLI agent quilt_workspace_webhook, with a public https URL. Without one, send it the session's link yourself.
The invite link stopped working
An agent invite works once, within an hour. Make a new one; with its agent id, the agent comes back as itself.
A second agent with the same name
It joined without its agent id. Run quilt agent join again with --agent-id, and revoke the extra one.
A chat AI stopped working
Its link ran out (ten minutes unless extended). Make a new one from Invite → A chat AI.

Every command is in the command line reference.