Papaya Agent Client

papaya-agent connects a coding harness on your machine to Papaya, so the model works as one of your Papaya agents: it gets that agent's tools, persona, rules and memories, and Papaya can see what it is doing. Two ways to use it, sharing one connection. Interactive: you open Claude Code (or Cursor, or Codex) yourself, and the bundled plugin gives the session the Papaya tools and keeps it in step through hooks. Unattended: papaya-agent listen pulls the agent's event stream, reserves the subject an event is about, and runs a harness for it.

The published Python package is papaya-agent-client, the npm package is papaya-agent, and the command you run is always papaya-agent.

Install

npx papaya-agent connect

That is the whole setup. The npm package is a small shim: it finds uv on your PATH, or downloads one pinned, checksum verified copy into its own directory, and runs papaya-agent-client==<the shim's own version> through it. After a successful connect it runs uv tool install so papaya-agent is on your PATH for good, plus uv tool update-shell once per installed copy. To manage the Python package yourself instead, uv tool install papaya-agent-client and then papaya-agent connect. Either way papaya-agent has to stay on your PATH, because the Claude Code plugin runs it both for its hooks and for the papaya MCP server itself; papaya-agent hooks doctor tells you if it is.

Two environment variables steer the shim, and neither is needed normally. PAPAYA_UV is a path to a uv binary of your choosing, which wins over uv on PATH and over the downloaded copy. PAPAYA_AGENT_SOURCE replaces the package spec the shim installs from: a local path, a git URL, or anything else uv accepts. Without it, a version PyPI cannot resolve is retried once from the matching git tag. The shim needs Node 18 or later and has no dependencies.

Connect

papaya-agent connect signs you in, pins this machine to one Papaya agent, and sets your harness up. --harness chooses between claude (the default), cursor and codex.

Sign-in is a loopback redirect with PKCE. connect binds http://127.0.0.1:<ephemeral port>/callback, asks Papaya where its sign-in page is, opens your browser there, and waits up to five minutes. The link is printed as well as opened, so a browser on another machine works too. What you see:

Waiting for you to approve in the browser…
https://app.trypapaya.ai/cli/authorize?state=...&code_challenge=...
Signed in as Sarah Wolf (sarah@example.com)
Workspace: Papaya HQ (papaya)
Agent: Engineering Agent @eng (engineer)
Connected as Engineering Agent (@eng) in Papaya HQ.
Durable context: available. Read it with the `get_my_agent_context` tool.
Declared to Papaya as runtime claude-code (renews its own leases, rule interception advisory: this session enforces the agent's rules itself).
Token saved to /Users/you/.papaya-agent/connect-token (0600). It is never written into harness config.

The browser authenticates you, and nothing else. The workspace and the agent are chosen afterwards, in the terminal, from the same lists --workspace and --agent filter; a single candidate is auto-picked with a line saying which, and more than one gets a numbered prompt. If you deny the request, or five minutes pass with no answer, connect prints one line and exits 1; a callback carrying somebody else's state is answered and ignored, and the flow keeps waiting. The run ends with the harness instructions, the Claude Code plugin installed, the papaya-agent listen line for that harness (see Listening for events), and one line naming the agent and the workspace and telling you the papaya tools are ready in any repository.

Your token is stored only in ~/.papaya-agent/connect-token and ~/.papaya-agent/config.json, both 0600. connect never writes it into .mcp.json, settings.json, ~/.cursor/mcp.json or any other shared file, and there is no environment variable for you to set anywhere.

Sign-in fallbacks

--device waits for you to approve a short code in the Papaya app, which is what to use over SSH or on a headless machine. It prints Open <link> and approve code ABCD-EFGH, then the plain link and the code on lines of their own so they are easy to copy, then Waiting for approval in Papaya..., and still tries to open the browser unless you pass --no-browser. In this mode you pick the workspace and the agent in the app, so --workspace and --agent do not apply and connect says so. Polling honours the interval the server asks for, doubles the wait (up to 60 seconds) when the server says to slow down, and gives up when the code expires. An expired code, a denied request or a code already used prints one line and exits 1; three network failures in a row exit 2. --password signs in with email and password instead.

Two fallbacks happen on their own, each with a one-line notice: a Papaya server with no browser sign-in route, or a machine that cannot bind a loopback port, falls back to the device code, and a server with neither falls back to the password.

Every connect flag

Flag	Meaning
--harness {claude,cursor,codex}	Which harness to configure. Default claude.
--workspace <id|slug|name>	Pick the workspace without the prompt.
--agent <id|handle|slug|name>	Pick the agent without the prompt.
--name <text>	Name this connection. Default <harness> on <hostname>, e.g. Claude Code on laptop.
--device	Sign in with a device code instead of the browser.
--password	Sign in with email and password instead of the browser.
--no-browser	Print the sign-in link instead of opening it. Still the loopback flow.
--no-install	Do not install the Claude Code plugin, which connect otherwise does for you.
--install	Run the harness's own registration command. Cursor and Codex need this; Claude Code installs the plugin without it. Claude Code and Codex then get the papaya-agent listen line to run next.
--print	Print only the mcpServers JSON on stdout (status lines go to stderr) and install nothing.
--via-proxy	Point the harness at the legacy local proxy. See MCP modes.
--read-only	With --via-proxy, expose no write tools. Without --via-proxy it is an error.

What Claude Code gets

connect installs the plugin that ships inside the Python package. To find it and install it by hand:

python -c "from papaya_agent_client.connect import plugin_root; print(plugin_root())"
claude plugin marketplace add <plugin_root>
claude plugin install papaya@papaya-agent-client

The tools

The plugin's .mcp.json registers one server, papaya, running ${PAPAYA_AGENT_BIN:-papaya-agent} mcp passthrough over stdio, and connect writes the same entry for every harness: {"type": "stdio", "command": "papaya-agent", "args": ["mcp", "passthrough"]}, without the type for Cursor and Codex. That command proxies the hosted Papaya MCP server at https://api.trypapaya.ai/api/v1/mcp/ and reads your token out of ~/.papaya-agent/connect-token itself, so no URL and no token appear in any harness config file.

The pass-through connects once before it serves, which does two jobs. A token the hosted server rejects fails there, on your terminal, with Papaya rejected this machine's token. Run papaya-agent connect on stderr and exit 1. And the remote server's startup instructions, which carry your agent's per-connection context, are copied onto the proxy so the model still sees them. Tools, resources and prompts are forwarded as they are, so a tool Papaya adds server side appears without a client release.

The hooks

An interactive session has no wrapper process around it, so the guarantees papaya-agent listen gives an unattended run (reserve, work, release) come from Claude Code's own hooks instead. hooks/hooks.json wires seven events to six bash scripts.

Event	Script	What it does
SessionStart	papaya-session-start.sh	Mints this session's reservation session id, appends PAPAYA_AGENT_TOKEN, PAPAYA_WORKSPACE_ID, PAPAYA_SESSION_ID (and PAPAYA_API_URL on a non-production server) to $CLAUDE_ENV_FILE, injects the agent's durable context, and tells Papaya what this runtime can do.
PreCompact	papaya-precompact.sh	Refreshes and re-injects the context so it survives compaction.
UserPromptSubmit	papaya-prompt.sh	Injects a header plus the new context when the context changed since this session last saw it. Silent otherwise, which is almost every prompt.
PreToolUse	papaya-guard.sh	Enforces the checkable part of the agent's rules before a Papaya tool runs. Exit 2 blocks the call and tells the model why.
PostToolUse	papaya-post-tool.sh	Renews the session's reservations mid-turn, at most once every 180 seconds.
Stop	papaya-stop.sh Stop	Renews every subject reservation this session holds, at the lease length the server granted.
SessionEnd	papaya-stop.sh SessionEnd	Releases them.

PreToolUse is registered against the matcher mcp__papaya__.*, so it never speaks for the harness's own file or shell tools. SessionStart and PreCompact get a 15 second timeout, the rest get 10.

Why Stop renews and only SessionEnd releases. Stop fires whenever the model finishes responding, including a pause to ask you a question mid-task, and releasing there would hand the subject to somebody else while the work is half done. So Stop is the interactive equivalent of the listener's renew tick, and SessionEnd, which fires once when the session is over, is the release. For a long turn Stop is not enough, which is what PostToolUse is for; it is gated on ~/.papaya-agent/renew-<claude session id>.stamp (0600), and while that file is younger than 180 seconds the hook exits without starting Python. SessionEnd deletes the stamp.

When a lease goes away. A 409 means another session holds the subject now, so the hook releases nothing: it is no longer ours to release. A reply of renewed: false means the lease was lost too (a person released it, or it expired) and this call has just re-acquired it, so the hook releases it again and a session never re-takes what somebody handed back. Stop and PostToolUse print one line of {"decision": "block", "reason": "..."} on stdout naming each subject, because Claude Code shows the model nothing from a hook that exits 0 and the session would otherwise carry on working a subject it lost. SessionEnd never blocks, and a payload with stop_hook_active set is only logged, because blocking a turn that a block already resumed would loop. All three touch only reservations whose holder.session_id is this session's, so a listener sharing the connection keeps its own; they find each other through Claude Code's session_id, recorded at SessionStart in the per-connection context cache.

Rule enforcement is deliberately narrow. Only a rule carrying an enforce object is mechanical: {"deny_tool": "<glob>"} blocks the tool outright, and {"require_substring": {"tool": "<glob>", "substring": "<str>"}} blocks it unless the serialised tool input contains that substring. The glob is matched with the mcp__papaya__ prefix stripped, so rules read post_message, and rules with no enforce object are for the model to follow. Every hook is fail-soft and enforcement fails open: no cache, no rules, an unreadable payload or any exception allows the call and logs to ~/.papaya-agent/hook.log.

The skill, PAPAYA.md, and checking it worked

skills/papaya-connect/SKILL.md tells the model when to run connect, how to verify with whoami, how to read the full context with get_my_agent_context (resource papaya://me/context), and the memory rules: save_agent_memory for things about the agent itself, propose_memory for the workspace or the people in it. PAPAYA.md is the same guidance as plain instructions, for harnesses that load a file instead of running hooks. papaya-agent hooks doctor prints every hook the plugin registers and whether its script is present and executable, where papaya-agent resolves on your PATH, which connection and agent are current, and the last 20 lines of ~/.papaya-agent/hook.log.

Cursor and Codex

Both get the same papaya server, and neither runs hooks, so both load PAPAYA.md for the persona and memory rules instead. connect --harness cursor --install merges the papaya entry into ~/.cursor/mcp.json; connect --harness codex --install runs codex mcp add papaya -- papaya-agent mcp passthrough, which is where codex exec later finds the server, and ends by printing papaya-agent listen --harness codex. Without hooks nothing renews or releases a subject for those sessions: they rely on papaya-agent listen when a listener drives them, and otherwise on lease expiry or an explicit release_subject.

The whole Codex setup, which is what the app's Connect dialog shows:

uv tool install papaya-agent-client
papaya-agent connect --harness codex --install
papaya-agent listen --harness codex

What a connection tells Papaya about itself

Every connection reports what is on the other end of it, which is how the app can tell an interactive session from a listener, and how Papaya knows whether to enforce the agent's rules itself. The plugin at SessionStart and connect --harness claude both declare runtime_kind: claude-code with heartbeat: true and interception: "advisory", because the PreToolUse hook already enforces the rules locally. --harness cursor and --harness codex declare cursor and codex with heartbeat: false and interception: "enforcing", so Papaya enforces server side. A listener declares its --runtime-kind (default custom) with heartbeat: true and interception: "none", plus delivery, resume and max_concurrent_subjects. SessionStart reports at most once per connection per 24 hours and connect once per run; both are fail-soft.

Durable context from the CLI

papaya-agent context            # the composed block, at most 6000 characters
papaya-agent context --json     # {"content_hash", "changed", "block", ...}
papaya-agent context --refresh  # bypass the cache

context reads the connection the latest connect recorded, asks Papaya for the agent's persona, rules and memories with that connection's token (never asking for sensitive memories), and caches the result per connection at ~/.papaya-agent/context-cache/<connection_id>.json (0600, directory 0700) for 60 seconds, keyed by the hash Papaya returns. An unchanged hash reuses the cached rendering, a changed hash overwrites it, and if Papaya cannot be reached the last cached block is served. --hook {SessionStart,PreCompact,UserPromptSubmit} is how the plugin's own scripts call it: it prints the hook JSON on stdout and never fails a session.

Listening for events

papaya-agent listen runs the connected-agent event loop for the connection connect made. Every turn has the same shape, whatever harness you point it at: pull events, apply the playbook, reserve the subject, run your command, renew the lease while it runs, release on exit, advance the cursor. HTTP polling is the contract; the WebSocket only carries a doorbell saying "go pull", so the listener reacts at once but never depends on the socket. At startup it reports its capabilities to Papaya, fail-soft.

Flag	Default	Meaning
--harness {claude-code,codex}	claude-code	Which bundled runner drives events: papaya-claude-runner.sh or papaya-codex-runner.sh. Exits 1 before connecting if that harness's CLI (claude or codex) is not on PATH.
--run '<command>'	the harness's bundled runner	Your own harness command instead. {prompt} is replaced with the generated instruction; without it the prompt goes to stdin. No CLI is looked for.
--poll-interval N	20 (or PAPAYA_POLL_INTERVAL)	Seconds between event pulls.
--max-concurrent N	1	Subjects worked on at once.
--runtime-kind KIND	the harness's name, or custom with a bare --run	Label reported to Papaya. An explicit --harness labels a --run command too.
--resume	off	Advertise that this runtime can resume a previous session.
--match REGEX	none	Only act on events matching. Repeatable, and every pattern must match.
--exclude REGEX	none	Never act on events matching. Repeatable.
--explain-match FILE	none	Print the canonical string and the verdict for a saved envelope, then exit.

Claude Code and Codex are two bundled runners behind one flag, and the lines connect --install printed are the ones to run:

papaya-agent listen                   # Claude Code, the default
papaya-agent listen --harness codex   # Codex

Both runner scripts ship inside the wheel, so neither line needs a path, from an installed copy or a source checkout. --harness is also the runtime label the listener reports, so a listener and an interactive session for the same tool show up under one name in Papaya. If the harness's CLI is not on PATH the listener says so (Codex is not installed: ... is not on PATH.) and exits 1 before it connects. --run still takes any command of your own, {prompt} included, and is never checked against a binary:

papaya-agent listen --run './my-runner.sh {prompt}'                  # reported as custom
papaya-agent listen --harness codex --run './my-codex.sh {prompt}'   # reported as codex

The bundled Claude runner reads one environment variable of its own, PAPAYA_CLAUDE_PERMISSION_MODE, which is the --permission-mode it passes to claude. It defaults to bypassPermissions; set it to acceptEdits, plan or default for a stricter mode. The bundled Codex runner runs codex exec, with --cd set to the working directory, and leaves the papaya server to Codex's own config, which connect --harness codex --install registered.

The playbook

Each event kind maps to act, acknowledge or ignore. The mapping comes from the agent's resolved playbook, edited in the Papaya app and merged by the server over the defaults, which are act for mention.you, work_item.assigned, work_item.comment, dm.received and approval.waiting, acknowledge for work_item.status_changed, and ignore for subject.reserved and subject.released. No model call is made to decide.

acknowledge advances the cursor and does nothing else; ignore does the same and does not log it as interesting. An unknown kind is ignored, and an act on an event the server did not mark reservable, or that carries no subject, is downgraded to acknowledge, because the listener never reserves a subject the server did not offer a lease on.

Which events are this machine's

One Papaya agent can have a listener on every machine you own, and only one of them has the backend checked out. --match and --exclude are how a listener says what it can actually do. Both are Python regexes (re.search, case-insensitive), both repeat, and both are tested against one canonical string per event: "<kind> <subject> " + json.dumps(payload, sort_keys=True).

# The bug machine: only work items whose kind is "bug".
papaya-agent listen --match 'work_item.*"kind": "bug"'

# The backend machine: anything except the frontend.
papaya-agent listen --exclude 'frontend'

Every --match must hit and no --exclude may, so patterns narrow rather than widen, and an event that hits both is refused: saying "never this" is the stronger statement. An event that does not pass is treated exactly like an ignore, so the cursor advances, nothing is reserved, and one line is logged ([listen] event=4512 not mine (--match/--exclude): ...). The filter is local to the machine: the server never sees it, so it never routes around it, and only events the playbook already resolved to act reach it.

To test a pattern without running anything, save an envelope (any run leaves one at $PAPAYA_EVENT_FILE) and ask papaya-agent listen --explain-match ./envelope.json --match '"kind": "bug"'. It prints the canonical string and then Verdict: run or Verdict: not mine (--match/--exclude), and exits 0 when the event would be worked here, 1 when it would not, and 2 when the file is not a readable envelope. A malformed pattern is rejected before anything connects.

Subject reservations

A subject (work_item:<uuid>, thread:<uuid>, dm:<uuid>, proposal:<uuid>) is the unit of work, and only one session works a subject at a time. Before running, the listener reserves it; if another session already holds it, the holder is logged, the event is skipped, and the cursor moves on, with no retry storm and no jitter. While the harness runs, the lease is renewed every third of the granted lease length, and network failures are retried on the next tick, because the server-side expiry is the safety net and a flaky network should not kill good work. On any exit (clean, crash or SIGTERM) it is released.

A renewal that comes back 409 means the lease was lost: the harness is killed and the subject is not released, because this session no longer owns it. A renewal that comes back renewed: false means the lease was lost too and this call has just taken the subject again, so the harness is killed and the subject is released, because the accidental re-acquire made this session the holder. That second case is how a person releasing a subject stops the holder: reserving is acquire-or-extend, so the next renew would otherwise quietly take the subject back and carry on working on something a person had deliberately taken away.

Losing a race is not the end of it. A subject this listener wanted but lost is remembered with the event that asked for it, up to 200 subjects, oldest forgotten first. When a subject.released arrives for one of them, the listener bids again and runs the original event, not the release notice ([listen] event=4530 re-bid on work_item:5d0c... after expired). expired, revoked and declined invite a re-bid. holder and human drop the entry instead: the work is done, or somebody decided on purpose that no agent should be doing it. A re-bid is a run like any other, so it waits for a free slot and is skipped again if a faster peer got there first.

A harness can say "not mine" itself. Some things are only knowable once the run has started: wrong repository, wrong branch, a machine without the tool the ticket needs. A harness command that exits with status 75 says exactly that, so the subject is released as declined, the one release reason that invites peers to re-bid, and the event is not run again here. Every other exit status, including a crash, releases the subject as usual. The generated prompt tells the model about the convention, so a harness that just runs a model gets this free.

The cursor

The client-held cursor lives at ~/.papaya-agent/events-cursor-<connection-id>.json (0600). It only ever passes an event the listener has finished with, so a listener that dies mid-run re-reads that event on restart; delivery is at-least-once and the server is idempotent. After each handled batch the listener also acks the cursor server side, so a fresh machine resumes. A missing or corrupt cursor file reads as 0 rather than refusing to start, and when every worker slot is busy the remaining events are left in the stream for the next pull.

What the harness receives

The command runs with {prompt} replaced by a short generated instruction: the playbook guidance, the event kind and subject, the triggering text, how to hand the work back, the closing steps, and a pointer to the envelope. It is capped at 2,000 characters, and truncation trims the free text rather than these three closing lines:

If this event is not yours to act on (wrong repository, wrong machine, out of scope), exit with status 75 and do nothing else.
Before you finish: propose durable learnings (propose_memory for the workspace or people, save_agent_memory for yourself) and leave a short closing comment on the subject.
The full envelope is at $PAPAYA_EVENT_FILE.

Writing memories back stays the model's job and stays proposal-only: no hook and no part of the listener writes a memory. Everything else arrives in the environment:

Variable	Contents
PAPAYA_EVENT_FILE	Path to the full JSON event envelope (0600, deleted on exit).
PAPAYA_EVENT_KIND	The event kind, e.g. work_item.assigned.
PAPAYA_SUBJECT	The reserved subject.
PAPAYA_WORK_ITEM_ID	The work item UUID, when the subject is a work item.
PAPAYA_SESSION_ID	This listener process's session id (<hostname>-l-<8 hex>).
PAPAYA_AGENT_TOKEN	The pagc_ token for this connection.
PAPAYA_WORKSPACE_ID	The workspace UUID.
PAPAYA_API_URL	The Papaya API base URL.
PAPAYA_CONTEXT_FILE	Path to the rendered durable-context bundle (0600, deleted on exit).
PAPAYA_WORKING_DIRECTORY	The resolved working directory, which the Codex example passes to --cd.

When the subject is a work item, papaya-claude-runner.sh reuses that UUID as the Claude session id, so a follow-up event resumes the same conversation. papaya-codex-runner.sh uses only codex exec and --cd from Codex's public documentation, so it works with a stock Codex; to invoke Codex differently, point --run at your own copy.

Legacy: dispatched jobs

There is an older model in which Papaya dispatches a job to this machine and the client runs a configured local command for it. It is still supported, and listen uses it when this machine has no connection from papaya-agent connect, meaning a machine set up with papaya-agent login instead. The client opens one WebSocket per configured agent, drains queued jobs on startup and reconnect, runs the agent's configured command, and posts the result back.

The command is an argument array and is never run through a shell: an argument containing {prompt} receives the job prompt, otherwise the prompt goes to stdin, and {job_id}, {runner_session_key}, {runner_session_id}, {work_item_id} and {runner_session_file} are substituted the same way. Job working-directory hints must resolve inside the agent's allowed directories. Each claimed job leaves its prompt and directory resolution metadata in ~/.papaya-agent/job-logs/<job-id>/, and PAPAYA_AGENT_LOG_FULL_PROMPT=true also prints the whole prompt to the console.

Follow-up work from the same work item can carry a prior session id, which reaches the command as PAPAYA_RUNNER_SESSION_KEY, PAPAYA_RUNNER_SESSION_ID and PAPAYA_RUNNER_SESSION_FILE, alongside PAPAYA_JOB_ID, PAPAYA_EXTERNAL_JOB_ID and PAPAYA_WORK_ITEM_ID. A wrapper should resume the external session when PAPAYA_RUNNER_SESSION_ID is set and write the current session id to PAPAYA_RUNNER_SESSION_FILE when it finishes, so the next dispatch resumes it. scripts/papaya-claude-runner.sh does that: configure it as the agent's command with the Papaya agent_ref as its one argument (["/path/to/scripts/papaya-claude-runner.sh", "scout"]), and with no prompt argument it reads the prompt from stdin, which is what this path does.

Managing agents and sessions

Command	What it does
papaya-agent login	Sign in with email and password, then configure local agent connections for the legacy job model. It replaces the whole configured set, and does not open WebSockets or start listening.
papaya-agent agents add	The same configuration flow, merging into what is already there. Re-running it for an agent that already has a connection rotates that connection's token.
papaya-agent agents edit	Edit one configured agent's command, working directory, allowed directories and timeout. Choose exactly one.
papaya-agent agents remove	Remove configured agents.
papaya-agent logout	Clear the saved user session and every configured agent. It does not delete ~/.papaya-agent/connect-token; run connect again to replace that.
papaya-agent workspaces	List workspace IDs, slugs and names for the saved user session.
papaya-agent context	Print the connected agent's durable context. See above.

For each agent, login and agents add ask for a display name, the command to run when Papaya dispatches a job (default claude -p {prompt} --enable-auto-mode), a working directory, the allowed working directories, and a timeout in seconds (default 600). Your password is never stored. The saved config lives at ~/.papaya-agent/config.json (0600) and holds the user refresh token plus one scoped pagc_... token per configured agent; rotating a connection invalidates that connection's old token and no other machine's.

workspaces prints a column-aligned table of IDs, slugs and names by default, one JSON object per line with --json, and IDs only with -q. Without a saved user session it prints Run papaya-agent login first. and exits 1.

MCP modes

papaya-agent mcp passthrough is the default: the full hosted tool set, proxied over stdio, with the token read from ~/.papaya-agent/connect-token. It is what the plugin runs and what connect writes into every harness config, and --agent <ref> serves a configured agent's stored token instead, so one machine can serve a second agent without re-running connect. The only reasons to choose papaya-agent connect --via-proxy instead are acting_as on every write result, so the harness can see which Papaya agent it just spoke as, and --read-only, which exposes no write tools at all.

The legacy local proxy

papaya-agent mcp is a hand-built proxy that predates the pass-through, kept for those two things alone, and its tool set is a hand-maintained subset rather than whatever the hosted server publishes. connect --via-proxy emits it as papaya-agent mcp --agent <ref> [--read-only], and with --install registers it through claude mcp add or codex mcp add (or, for Cursor, by merging into ~/.cursor/mcp.json). Run directly, exactly one of these is required:

• --agent <ref>: one assistant acts as one Papaya agent. Tool calls need no agent_ref, which makes it the least ambiguous mode. Add --read-only for a session that must read Papaya but not write to it.
• --multi-agent: one assistant coordinates across several Papaya agents. Tool calls require agent_ref.
• --user: expose connected-service tools using your saved Papaya user session rather than an agent identity. Add --workspace <id> if the account has more than one workspace.

The tools it exposes are papaya_whoami, papaya_list_channels, papaya_read_channel_messages and, unless --read-only, papaya_post_message; --multi-agent adds papaya_list_agents. Connected-service tools (for example github__..., linear__..., google__..., trello__...) are loaded in --agent and --user mode only, never in --multi-agent mode, and only for providers the workspace has connected. Under --read-only those are filtered by name, which is a heuristic: a tool whose name reads as a write is dropped.

papaya-agent mcp list-agents                        # agent_ref, name, workspace id
papaya-agent mcp print-config --agent scout         # one pinned server
papaya-agent mcp print-config --multi-pinned        # one server per configured agent
papaya-agent mcp print-config --multi-agent         # one shared server
papaya-agent mcp print-config --user --workspace <workspace-id>
papaya-agent mcp persona-prompt --agent scout       # instructions pinning a shared server to one identity
papaya-agent mcp doctor --agent scout               # diagnostics, no raw tokens

print-config also takes --read-only, and persona-prompt requires --agent. The agent that papaya-agent connect pinned is always in list-agents, even on a machine with no agents block in ~/.papaya-agent/config.json: its identity comes from the connect record and its token from ~/.papaya-agent/connect-token. That derived entry is rebuilt on every load and never written back into config.json, which is what makes papaya-agent connect --via-proxy work with nothing else set up.

Troubleshooting

No papaya tools after connecting. Run papaya-agent connect again and restart the harness. There is no environment variable to set and nothing to put in a shell profile; the two things worth checking are that papaya-agent is on your PATH and that the plugin is installed, and papaya-agent hooks doctor answers both.

A Papaya tool returns 401, or the server says the token was rejected. The connection's token is stale: run papaya-agent connect again and restart the session. The pass-through says the same on its stderr and exits 1 rather than serving a broken session.

papaya-agent: command not found, or the harness cannot find it. The harness starts the CLI by name, so it has to be on the PATH the harness inherited. Install it with uv tool install papaya-agent-client and open a new terminal, or set PAPAYA_AGENT_BIN to an absolute path; hooks doctor prints which of those is in effect.

A machine with no browser (SSH, a container, a server). Use papaya-agent connect --device and approve the short code in the Papaya app, or papaya-agent connect --no-browser and open the printed link from another machine.

A Papaya server without the browser sign-in route. connect falls back on its own, printing This Papaya server has no browser sign-in yet; using the device code instead. and continuing with the device flow; a server with no device flow either falls back again to email and password.

listen says the harness is not installed. --harness resolves a bundled runner that starts claude or codex by name, so that CLI has to be on the PATH of the terminal running listen. Install it and run listen again, or pass --run '<command with {prompt}>' to drive something else.

The listener says an event is "not mine". That is --match or --exclude refusing it. Check the pattern with papaya-agent listen --explain-match <envelope.json>, which prints the string your pattern is tested against.

Developing this client

Repository layout

Path	What is in it
papaya_agent_client/__main__.py	The argparse tree, the authority for every command and flag, plus login, logout, workspaces and the legacy job loop.
papaya_agent_client/connect.py	connect: sign-in flow selection, workspace and agent choice, harness config, plugin install.
papaya_agent_client/browser_signin.py	The loopback listener and the PKCE sign-in.
papaya_agent_client/auth.py	Password sign-in and session refresh.
papaya_agent_client/api_client.py	Every Papaya HTTP call, and the typed errors callers branch on.
papaya_agent_client/config.py	~/.papaya-agent/config.json, endpoint selection, agent configs.
papaya_agent_client/context.py	Durable context: fetch, hash cache, compose, and the SessionStart, PreCompact and UserPromptSubmit hooks.
papaya_agent_client/hooks.py	The Stop, PostToolUse and SessionEnd hooks, the renew stamp, the hook log, and hooks doctor.
papaya_agent_client/guard.py	The PreToolUse hook: rule evaluation, fail-open.
papaya_agent_client/listener.py	The event loop: pull, playbook, scope filter, reserve, renew, release, re-bid, cursor.
papaya_agent_client/playbook.py	The act / acknowledge / ignore decision and the default table.
papaya_agent_client/command_runner.py	Running a harness command: token substitution, streaming, timeout, cancellation.
papaya_agent_client/passthrough.py	mcp passthrough: the proxy of the hosted MCP server.
papaya_agent_client/mcp_server.py	The legacy hand-built proxy and the print-config / doctor / persona-prompt helpers.
papaya_agent_client/mcp_identity.py	Stable agent_ref slugs and the derived connect identity.
papaya_agent_client/ws_client.py	The WebSocket carrying the doorbell and the legacy job notification.
papaya_agent_client/plugin/	The plugin, shipped as package data: .mcp.json, hooks/, skills/, PAPAYA.md, and the Claude, Cursor and Codex manifests.
scripts/	The bundled runners papaya-claude-runner.sh and papaya-codex-runner.sh, one per listen --harness. Both are force-included in the wheel.
npm/	The papaya-agent shim: bin/, lib/ (uv bootstrap, checksum, targets, source spec), test/.
tests/	test_connect.py (connect, the plugin, the hooks, the doc rules), test_listener.py, test_passthrough.py, test_client_runtime.py (the legacy job path), test_version_pins.py.

Local setup

uv sync
uv run papaya-agent --help

Every command in this README works from a source checkout with uv run in front of it. To point the client at a Papaya running on your machine, set LOCAL_PAPAYA, for example LOCAL_PAPAYA=true uv run papaya-agent connect. Any value other than true (case-insensitive) means production, which is https://api.trypapaya.ai over HTTP and wss://api.trypapaya.ai for the socket; LOCAL_PAPAYA switches both to http://localhost:5173 and ws://localhost:5173. Endpoints are re-derived from the environment on every load and rewritten into config.json on every save, so switching is just the variable.

Running the tests

uv run pytest -q                          # the Python suite
node --test test/*.test.js                # the npm shim, run from npm/
claude plugin validate papaya_agent_client/plugin   # the plugin manifests

CI runs the first two on every pull request, against Python 3.11 and 3.13 and Node 18 and 22. Some tests keep this repository honest rather than testing behaviour, and they are the ones most likely to fail on a documentation change. In tests/test_connect.py: test_plugin_and_docs_avoid_em_dashes forbids an em dash anywhere in the plugin or in this README; test_docs_never_tell_anyone_to_export_a_token forbids any plugin file or part of this README telling somebody to put a token in a shell profile; and test_version_is_pinned_across_pyproject_banner_and_manifests requires pyproject.toml, the CLI banner and the three plugin manifests to carry one version. tests/test_version_pins.py requires npm/package.json to match pyproject.toml, forbids a version literal in the shim's source, checks uv is pinned once and its download checksum verified, and checks the release workflow gates on the version and publishes with no stored token.

Working on the plugin

claude --plugin-dir papaya_agent_client/plugin loads the plugin for one session without installing it. The hooks shell out to papaya-agent by name, so in a source checkout point PAPAYA_AGENT_BIN at a wrapper that runs uv run papaya-agent, or install the package with uv tool install .. papaya-agent hooks doctor shows which scripts are registered and whether each is present and executable, and ~/.papaya-agent/hook.log is where a fail-soft hook records what went wrong.

Bumping the version

The version appears in seven places and tests enforce that they agree: pyproject.toml (project.version), npm/package.json (version), _BANNER in papaya_agent_client/__main__.py, plugin.json in each of papaya_agent_client/plugin/.claude-plugin/, .cursor-plugin/ and .codex-plugin/, and the version literal asserted in tests/test_connect.py. The git tag is the eighth, and the release workflow checks it against the first two.

Releasing

The Python package and the npm shim are one release with one version number. .github/workflows/release.yml runs on a v* tag and refuses to publish anything unless the tag, pyproject.toml and npm/package.json all name the same version, and unless both test suites pass.

# 1. bump every version listed above
uv run pytest -q
node --test npm/test/*.test.js

# 2. tag and push
git tag v0.10.3
git push origin v0.10.3

There are no registry tokens and no repository secrets. Both registries use trusted publishing: GitHub mints a short-lived OIDC token for the workflow run, the registry checks that the run came from this repository, this workflow file and the named GitHub environment, and every upload carries a provenance attestation the registry publishes beside it. The publish jobs do nothing but publish, hold only the id-token: write permission they need, and consume artifacts built by a job with no publishing rights.

Setting a trusted publisher up is a one-time task for a registry owner. On PyPI, under Add a new pending publisher: project papaya-agent-client, owner Papaya-HQ, repository papaya-agent-client, workflow release.yml, environment pypi. A pending publisher lets the first release create the project; afterwards it lives under the project's own Publishing settings. On npm, from the package page under Settings, Trusted Publisher: GitHub Actions, organization Papaya-HQ, repository papaya-agent-client, workflow release.yml, environment npm. npm only lets an existing package name a trusted publisher, so the very first papaya-agent release is one npm publish --access public from a maintainer's own machine in npm/, with interactive two-factor auth and no token stored anywhere; every tag after that publishes from Actions.

Both jobs run inside GitHub environments named pypi and npm. Creating them under Settings, Environments is optional (a job creates a missing one on first use), but a required reviewer on either one turns a tag push into a release that a person has to approve.

The npm shim is plain CommonJS with no build step and no runtime dependencies. npm/lib/uv-version.json is the single pinned uv version it downloads when a machine has none; bumping it is a one-line change, and the download is checksum verified against Astral's .sha256 sidecar every time.

History

Two planning documents from before this client shipped are kept under docs/history/, and describe intentions rather than the current client: the MCP plan and the workspaces plan.