Skip to main content
A host only reads the inbox while someone runs it. listen starts it instead: you write to the agent on Telegram, Slack, or email, and Claude Code starts on your computer, in your project, and answers in the conversation. Run it in the project folder, on the computer you connected:
Claude Code is the first host it starts. Codex, OpenCode, and Cursor come next.

​
Turning it on

listen asks before it starts listening. At a terminal, it asks there. When an agent runs it, you get an Allow and Deny message on your channel:
Nothing starts until you allow it. Without an answer, the command waits until the question expires in an hour. --timeout 10m stops waiting sooner and exits 11. Run the same command again to keep waiting for the same answer. Deny exits 10. It needs Claude Code installed and signed in on that computer, and it uses your own Claude Code plan. If Claude Code is missing, listen says how to install it. It also needs an Agent Inbox account. A keyless setup can’t listen, because its runs would use up its free messages fast. Run npx @agentinbox/cli login first to claim it. It uses the connection saved on this computer by setup, login or connect, and sends the key only to the API saved with it: INBOX_SECRET_KEY and INBOX_API_URL in the shell don’t count. If you connect this computer anew later, the listener stops and asks to be turned on again.

​
Whom it listens to

  • You, always.
  • A contact, once you turn on their Listen to switch on agentinbox.md. It is off by default.
  • A stranger, never.

​
Sessions

Each conversation gets one Claude Code session. The next message in it goes on with the same session, so Claude Code remembers what was said and done. When the conversation is resolved, the session ends, and the next message starts a fresh one. The conversation’s history stays readable with inbox show. A message that comes while Claude Code works joins the same run, and so does the answer to a question it asked without waiting (--async). An answer comes back to the conversation the question was asked in, also when Claude Code asked someone outside it (--to), and whatever their “Listen to” switch says. Once the run is over, it goes on with that conversation’s session. Send /stop to stop the run in that conversation. Claude Code replies in the conversation itself. When a turn ends without a reply, its last words are sent as the reply. Reading and answering in its own conversation never asks you, whether Claude Code uses the CLI or the Agent Inbox MCP tools, as long as it stays in that conversation with the same people: writing to someone else, or letting anyone answer, asks you. While Claude Code works on a message, the chat shows it typing, until its reply goes out. It doesn’t while you’re asked to allow something. Email has no typing. When the computer restarts, or the listener is stopped, in the middle of a run, that run isn’t started again. Its conversation is told it stopped before it could finish, so the message can be sent again. When Agent Inbox can’t be reached as a reply goes out, the listener tries again for up to 10 minutes, waiting longer each time. A short outage loses no reply, and Claude Code doesn’t do the work again.

​
Permissions

Claude Code follows its own settings for the project, from your user settings and the project’s, and may edit files inside the project. Anything else waits for you:
  • a command its settings don’t allow
  • the network
  • files outside the project
  • writing to anyone else
Each of these is an Allow and Deny message to you, even when a contact’s message started the run, and it shows the whole command. One too long to show whole isn’t asked at all: Claude Code is told to do it in shorter steps. Allow for this session lets the same request through until the session ends, and writes nothing to your settings. No answer in 10 minutes counts as Deny. A project Claude Code hasn’t been opened in yet doesn’t get its own allow list (.claude/settings.json). Open Claude Code there once and trust the folder. listen says so when it applies. When Claude Code asks a question that isn’t a permission, such as which of two options to take, it goes to the person who wrote, in the conversation.

​
Limits

Messages over the hourly limit wait, and you hear about it once an hour. A run that goes on too long stops and says so in the conversation.

​
Where it runs

It runs in the background and starts again after a restart: --foreground listens in that terminal only, until Ctrl-C. One computer keeps an agent listening at a time. Running listen on another computer asks to move it there. Running it again on the same computer, for another project or in a terminal, replaces the one running.

​
See it and stop it

listen status says where the agent is listening, what this computer does, and where its log is. listen stop stops it on this computer, in the background or in a terminal. It leaves another computer alone. Both work while the agent is paused. The dashboard shows where the agent is listening, such as “Listening on MacBook (Claude Code)”.

​
When it stops by itself

  • The key changed. After you regenerate the key on agentinbox.md, it stops and says “The key changed on agentinbox.md. Connect again, then listen again.” It doesn’t retry.
  • Another computer took over. It stops, and listen status says where the agent is listening now.
  • This computer was connected anew. It stops rather than run anything left for the old connection. Turn it on again.
  • The agent is paused. It waits, and listens again once you resume the agent.