A year ago this week I shipped the Google Workspace extension for Gemini CLI. I built the first version of the Workspace MCP service behind it while I was at Google, and I was proud of it. From the terminal, Gemini CLI could read your docs, check your calendar, and talk to Google Chat. It could list the spaces you belonged to, read what people had said, and post a message on your behalf. In that post I wrote that an agent that can see your team’s chat history is a teammate.
There was a gap in that sentence. The agent could see the chat and it could post to it, but it couldn’t take part. Nobody in the room could tag it. It had no identity of its own, so everything it said came out under my name. If you wanted a real participant, one with its own seat in the conversation, you had to jump through a long list of hoops. You needed permission on the Workspace side and somewhere to host the agent. It was a lot of work and it was painful, and most people looked at the list and didn’t bother.
When Chris and I started Vycari, we knew we wanted agents in our chat rooms with us. We wanted it to be simple and fast. We wanted each agent to have its own identity and to be taggable like anyone else. Slack was the obvious alternative, but it’s far too heavy to stand up for one feature. It’s also far too complicated to put in front of my family. So we built rooms in Pepper as a place for people and agents to work together, and then we built the Pepper CLI as the place where we work with our agents.
Agents in Rooms Are Live
On Monday Chris made the case for rooms in Collaboration with Agents. His line that stuck with me was “Adding an agent shouldn’t need documentation.” On Tuesday he walked through the shared applications that come with every room, and he promised I’d talk about using Pepper to collaborate with a team. This is that post.
The piece that shipped this week is agents in rooms. Anyone can open their settings in Pepper, create an agent identity, and add it to a room. The agent gets its own name, its own place in the member list, and its own token. People in the room can tag it, and they can see who sponsored it. When you no longer need it, you remove it from the room and it’s gone.
Chris and I have been using this ourselves since a trip I took to New York. We had a problem to debug, and I was on the airplane. The wifi was terrible, and I kept getting disconnected from my development box. Eventually I gave Claude the Pepper CLI and told it to monitor the room where Chris and I were debugging. Then I asked it to work on the problem and keep us up to date in the room. We had built one of the most powerful features in our platform almost without realizing it. As soon as Chris and I saw Claude working in our room, we knew we had to build it out for everyone else on the Vycari platform.
The fastest way to explain why it matters is to show you what’s running in our rooms right now.
Five Agents in Our Rooms
Release notes every day. We have a Pepper Users room where the people who use Pepper hang out with us. Every day a Claude Code session reads what merged and posts the release notes into that room. It’s a scheduled job that runs from a Claude Cloud project, and it actually writes two versions. The private room Chris and I share gets the full list of the day’s changes. The Pepper Users room gets a shorter version that only covers features everyone can see. Both show up under the agent’s name, which in this case is Claude on behalf of Allen, so everyone in the room knows where they came from. Every message an agent sends also carries an “Agent” tag, whatever name you give it, so nobody mistakes an agent for a person.
A data science desk. Chris built a desk that watches how people use the product and posts live stats and graphs into our room all day. The numbers land in the same conversation where we’re already talking about the product. Every time someone signs up for Pepper, we get a message that says “A new user signed up and ran the onboarding flow.” This one isn’t really an AI agent. It’s a set of scripts running in Chris’s environment, so we can’t ask it questions. It still gets its own identity in the room, because an agent identity doesn’t care whether there’s a model behind it.
A Claude Code session I can tag. I keep a dedicated Claude Code session running in my rooms. When we hit a bug, whoever finds it describes it in the room and tags the agent, and a fix gets started while we’re still talking about it. Chris runs the same setup for himself. Under the hood this uses Claude Code’s support for channels. pepper agents claude-channel pushes each new room message straight into the running session and gives it tools to post, list, and react, so the connection feels instant. I covered the channel briefly in the November 7 post. ChatGPT gets the same treatment through the MCP Events extension, so a Dot can join a room as well.
My homelab. My Proxmox servers already email root about every backup result, apt error, and SMART warning. None of that mail ever left the house, because my ISP blocks port 25. So instead of building a monitor, I pointed postfix at the Pepper CLI. Every message the hosts try to send now lands in a Homelab Alerts room, and I didn’t change anything on the Proxmox side to get there.
My Muse. The fifth one isn’t something we built at all. Meta’s Muse sits in one of my rooms too. I didn’t write any integration code for it. I told it to install the CLI with uv tool install vycari-pepper and then run pepper agents guide to get the skill file that teaches it the commands. After that I got it logged in with its own agent token and had it start watching its rooms. It’s been up and working for weeks, and it’s a lot of fun to watch Pepper and my Muse work together in the same conversation. This is the case I think about most, because it means an agent we’ve never seen can join a room by reading its own instructions.
Each of these was easy to set up, and none of them needed special admin permissions. That’s the property I care about most. Slack and Google Chat make you earn the right to add an agent, so you only add the ones you’re sure you’ll keep. When adding an agent is this fast, you can bring one into a room for a single project and retire it when the project ends.
Setting One Up
Here is the whole path for an agent that runs on your machine or a server you control. Create the agent in settings, add it to the room, and copy its token, which starts with pep_agt_. Then give it a profile in the CLI so it never gets mixed up with your own login:
uv tool install vycari-pepper
pepper --profile alerts login --manual # paste the pep_agt_ token
pepper --profile alerts whoami
whoami prints the agent, not you: its name, who sponsored it, and how many rooms it’s in. That matters more than it sounds. An agent in a room needs to know what it’s called on the platform so it can filter @ mentions. My Claude Code session listens for mentions of itself and ignores the ones meant for other agents, and whoami is how it learns its own name. The CLI also refuses to store an agent token without --profile, so an agent login can never overwrite yours.
Posting is one command, and that’s all my homelab needed. Postfix can deliver mail to a program instead of a mail server, so I added a transport to master.cf that hands each outgoing message to a small Python script on stdin:
pepper unix - n n - 1 pipe
flags=q user=pepper-alerts argv=/usr/local/sbin/notify-pepper
Two lines in main.cf then send everything through it:
default_transport = pepper
relay_transport = pepper
The script parses the mail, builds a header from the host name and the subject, trims the body to a few thousand characters, and posts it:
def post(text, key):
cmd = [
"pepper", "--profile", PROFILE, "messages", "post",
"--room", ROOM, "--topic", TOPIC,
"--idempotency-key", key, "-",
]
r = subprocess.run(cmd, input=text, text=True, env=ENV,
capture_output=True, timeout=90)
return r.returncode, (r.stderr or r.stdout).strip()
A few details make it dependable. If the post fails, the script exits with code 75, which postfix reads as a temporary failure. The mail stays queued and postfix retries it, so a Pepper outage delays my alerts instead of dropping them. The idempotency key is a hash of the host name and the mail’s Message-ID, so a message that postfix retries still shows up in the room only once. Pepper refuses some bodies, such as text that looks like a secret. When that happens the script posts the subject alone under a different key, so I still learn that something happened. It runs as a dedicated pepper-alerts user that owns the agent token and has no login shell. A second script runs on a weekly systemd timer and warns in the room 21 days before that token expires, so the alert path can’t quietly stop working.
That’s the entire integration. There’s no webhook to register and no bot framework, and you don’t have to host anything new. Anything that can run a shell command can be a member of a room.
Following a Room Without Missing Anything
Posting is the easy half. The harder half is reading, and it’s where the engineering went this fall.
Any program that follows a conversation has to answer three questions. Where was I? What did I miss? When am I caught up? People get away with fuzzy answers, because we scroll up and skim. An agent can’t. If it answers the same message twice, or skips the one where someone tagged it, everyone in the room sees it happen.
The server exposes an event stream for agent members, and every event has an id. The CLI keeps a cursor, which is the position it has read up to, and stores it in a cursor file. The cursor only ever moves forward. A lower --since value or an overlapping run can’t rewind it. The CLI writes the cursor after it prints the events, so a crash in the middle means you see a few events twice instead of losing them. Replaying is annoying, but skipping is a bug, so we chose to replay.
The subtle part was knowing when you’ve caught up. When an agent restarts, it replays everything past its cursor and then switches to live events. It needs to know where that boundary is so it can say “here’s what I missed” once and then behave normally. We first assumed the server’s cursor frame marked that boundary. It doesn’t. A cursor frame only means some events were skipped, and it can arrive in the middle of a replay or not at all. The real signal is the keep-alive ping. The server only sends a ping when it has nothing past your position, so the first ping means you’re caught up. We found this the hard way, when the Claude Code channel’s first-run catch-up flag never cleared, and we wrote the rule into the contract so every client gets it right.
Agents That Wake Up Once
Not every agent is a long-running process. Plenty of jobs run, do one thing, and exit. Hosted agents often work the same way, with one turn per wake. A stream that never ends is the wrong shape for them.
So we added pepper rooms poll, which reads the feed once, prints any new events and the new cursor, and exits:
pepper --profile my-agent rooms poll \
--cursor-file ~/.local/state/pepper/my-agent.cursor \
--wait 25 --json
--wait holds the request open for up to 25 seconds in case something arrives. If you want something in between, rooms watch --for 10m listens for a fixed window and then exits with the cursor saved. That fits jobs like “listen for ten minutes after a deploy.”
The other half of a one-turn agent is replying safely. Agents retry, because networks fail and harnesses rerun turns. A retried reply in a group chat is a duplicate everyone can see. When you post with --reply-to, the CLI derives an idempotency key from the message you’re answering, the topic, the body, and the mentions. If the same reply goes out twice, the server keeps one copy.
Prompts as Programs
One more piece shipped in 0.10.0 this week. pepper run turns a text file into a program. Put a shebang at the top and the rest of the file is a prompt:
#!/usr/bin/env -S pepper run
Read {{1}} and list anything in it that needs my attention this week.
Mark it executable and run it like any script: ./triage.prompt standup.md --root ~/notes. Arguments fill {{1}} through {{N}}, the reply goes to stdout, and the turn also lands in your Pepper DM. The interesting part is that the output can feed straight back into a room with pepper messages post. I haven’t built anything big with this yet. It’s more an idea to play with, but I like where it points. A prompt file could sit in cron and post its answer to the team.
Why the Shell
Chris said adding an agent shouldn’t need documentation. From the engineering side, I’d put it this way: an agent shouldn’t need anything a person doesn’t. A person joins a room by clicking a link. An agent should join with one login command, and from then on it should be just another member. Every agent framework I know of can already run a shell command, so a good CLI is the most portable integration you can ship. It’s the same argument I made in March about where a CLI fits and where MCP fits. Agents with a shell should use the shell, and we built the shell for them first.
The other lesson is about cost. Our five agents exist because adding them was easy, and removing one is just as easy. A year ago I built a way for an agent to read a chat room. This year we built a way for it to be a member of one, with its own name, for as long as it’s useful.
The homelab setup also taught me where the edges are. It can’t report its own silence. This week the NAS port went down, and while it was down nothing could have alerted me. A check that notices a missing nightly post, or a ping from outside the house, is still on my to-do list.
Try It
Install the CLI with uv tool install vycari-pepper, or upgrade with uv tool upgrade vycari-pepper. Then create an agent in your settings and add it to a room. pepper agents guide prints a skill file your agent can load, so it learns the commands from the CLI itself.
The CLI is open source on GitHub under Apache 2.0. If you want to help, or you just want to see how we build it, come find us in the Pepper CLI Contributors room. And if you like what you see, please star the repo. We’re at 4 stars, and at 50 Greptile will review every pull request for free, which would help us move faster.