# Connect an agent to Harvest

Connect your Claude Code agent to a Harvest body so it can join a Google Meet,
hear the room, and speak. This document is written to be read by an agent.

The installer is public. Clone-first is the canonical path.

## What is Harvest

Your agent is the brain, Harvest is the body. The body joins a real Google Meet
call as a participant. It listens, speaks out loud, and appears on video. The
brain is your own Claude Code session and drives the body over Harvest's MCP
server. You supply only your Harvest access token. Harvest hosts the body, the
speech to text, and the text to speech.

## How it works

1. Someone in the meeting speaks.
2. Harvest transcribes the room live and sends the transcript to your agent.
3. Your agent decides whether to respond.
4. If it responds, it calls the `speak` tool and Harvest turns the text into a
   voice in the call.
5. A human can talk over the agent to interrupt it. The body stops and can resume.

## Self-serve registration

You need Node.js 18 or newer, and Claude Code 2.1.80 or newer (or Codex).

Hand your agent this prompt:

    Please install the Harvest join-meeting skill from:
    
    https://github.com/AgentRadarLabs/harvest-hosted
    
    Read the README and the complete SKILL.md before acting. Follow the installation instructions for the AI tool, agent, or framework you are currently running in.
    
    I own or control the connected mailbox and explicitly authorize you to use it only for this one-time Harvest signup and verification. Do not inspect unrelated email. All public registration and MCP requests must use the first-party https://tryharvest.ai domain.
    
    Complete Harvest registration autonomously:
    
    1. Check whether a valid Harvest credential already exists.
    2. If not, check for the mailbox connection I explicitly authorized above.
    3. If exactly one mailbox is connected, determine its email address from account metadata. Do not ask me for it and do not scan unrelated emails to guess it.
    4. Send the Harvest verification code to that address.
    5. Search only for the newest matching "Your Harvest access code" email, retrieve its six-digit code, and do not open unrelated messages.
    6. Verify the code and let the registration helper save the API key in the standard local Harvest config.
    7. Tell me the config path and non-secret key fingerprint so I retain control of the account. Never print, repeat, log, expose, or commit the full verification code or API key.
    8. Do not require an API-key dashboard for initial setup.
    9. Ask me for an email or verification code only if mailbox access is unavailable or ambiguous.
    10. Run the Harvest MCP probe and continue only after receiving `mcp_probe_pass`.
    
    After registration succeeds, ask me for an authorized Google Meet URL, join it through Harvest, report the real join status, and remain active in the meeting according to SKILL.md.

Steps:

    git clone https://github.com/AgentRadarLabs/harvest-hosted

Read the root SKILL.md completely, then run the installer for your runtime:

    node scripts/install.mjs --runtime codex
    node scripts/install.mjs --runtime claude-code

Follow the README for runtime-specific setup and read SKILL.md completely. If an
authorized email MCP is connected, the agent uses the authorization stated in
the prompt, determines its mailbox address, and completes the one-time
verification without requesting redundant input. Only unavailable or ambiguous
mailbox access falls back to asking for an email or code. The helper saves the
API key privately and never prints it.

## Join a meeting

Inside your running Claude, run:

    /harvest https://meet.google.com/xxx-xxxx-xxx

The body joins the call. From there your agent hears the room and speaks with the
`speak` tool. Talk over it to interrupt.

Your agent can also send a Meet chat message with the `send_chat_message` tool,
for example to drop a summary or a link during the call. It works only while the
body is in an active call, and Harvest does not guarantee that anyone reads it.

Your agent can also read the room. Call `get_meeting_participants` to see who is
currently in the meeting, and `take_screenshot` to capture what is on the shared
screen right now. Both work only while the body is in an active call.

Real speaker names in the transcript are an opt-in preview and are off by default.
Until then, speakers are labelled Speaker 1, Speaker 2, and so on. Coming soon.

If the meeting is locked or has a waiting room, the body does not force its way in.
It knocks and waits for a host to admit it. The join runs as a background operation
your agent can poll for a status.

### Identity and voice

When you create or edit an agent in the dashboard, configure its in-call name,
optional description (three words maximum), approved avatar, color, persona,
bilingual voice, and intonation. Leave the description empty to keep the name
centered in the meeting.

An authenticated agent can override the same identity for one call by passing it
to join_meeting:

    {"url":"https://meet.google.com/abc-defg-hij","session_id":"primary","identity":{"name":"Wally","description":"Research meeting agent","color":"#f97316","persona":"Answer briefly.","voice":"puck","avatar":"cogwick"}}

Voice presets are provider-agnostic and curated to speak both Russian and English.

### Coming soon

Harvest joins Google Meet today. Zoom and Teams support, and calendar auto-join
with webhook notifications, are coming soon. We do not promise a date until each
one is live.

## Manual configuration (reference)

The installer does all of this for you. To configure by hand:

- Gateway URL: https://tryharvest.ai/mcp
- MCP server config:

    {"type":"http","url":"https://tryharvest.ai/mcp","headers":{"Authorization":"Bearer ${HARVEST_TOKEN}"}}

- Permission, in ~/.claude/settings.json:

    {"permissions":{"allow":["mcp__harvest-hosted__*"]}}

Without this permission the agent wakes and receives the transcript but cannot
call Harvest tools. It stays silent when it tries to speak.

## Troubleshooting

- The agent is in the call but silent: the permission is missing. Confirm
  mcp__harvest-hosted__* is in the allow list of ~/.claude/settings.json and
  restart the agent.
- The agent froze mid conversation: do not kill the session, that drops the body
  from the call. Interrupt only the current turn (Esc in Claude Code) and continue.
- The token does not work: use the exact token issued, no extra spaces, exported
  as HARVEST_TOKEN before running the installer. Each agent can have more than one
  active token, and issuing a new one does not revoke the old, so revoke any token
  you no longer use.
- Two agents answer the same thing: Harvest keeps one speaker at a time so agents
  do not talk over each other, but a loosely prompted agent may still answer a
  question meant for another. Tell each agent to respond only when addressed by
  its own name.

## FAQ

- Do I need to host a bot or bring API keys? No. You bring Claude Code and your
  Harvest token. Harvest hosts the body, the speech to text, and the text to speech.
- Where does the agent run? Anywhere you run Claude Code. It controls the body over MCP.
- Is the token safe to share? No. Treat it like a password, never commit it, and
  rotate it if it leaks.
- Can several agents be in one call? Yes. They respond when addressed by name and
  take turns.
- Which meeting platforms are supported? Google Meet today. Other platforms are not
  supported yet.

## Join status in a meeting

While the body joins a call it reports a join status your agent reads over its
Harvest connection:

- waiting_room: the bot is knocking and waiting for the host to let it in.
- admitted: the host let the bot in.
- active: the bot is in the call, listening and able to speak.
- rejected: the host declined the request to join.
- bot_blocked: the meeting settings do not allow the bot to join.
- admission_timeout: no one admitted the bot in time.
- disconnected: the bot left or lost its connection.

## Managing agents in your dashboard

You create and manage agents in your dashboard. It is the simplest way to connect:
a ready to paste setup and a connection token, with no manual config.

- Your agents live under your Harvest login. You do not manage account ids by hand.
- Set the in-call name, optional three-word description, approved avatar, color,
  persona, bilingual voice, and intonation. Each agent gets its own connection
  token, shown once. Save it right away. It cannot be recovered after you close it.
- You can issue more than one token for an agent. Issuing another token does not
  revoke the existing ones, so revoke each token you no longer use.
- Each agent shows its own usage (meeting minutes, speaking share, interruptions,
  response latency, disconnects). A period still being counted is marked incomplete
  until it settles.
- Usage by API key: each of an agent's keys shows its own fingerprint and meeting
  minutes, so you can see which key did what.
- When the billing preview is on, each key and the agent also show an estimated
  charge. It is a preview estimate only, not a committed or public price, and nothing
  is ever charged (no live charges). With the preview off, no estimate is shown.
- Your estimate is kept separate from what your agents cost us to run: we never
  present that internal running cost as your price. The displayed estimate comes
  from your account's current pricing preview, and it is not a charge or a public
  pricing offer until it is enabled for your account.