The story behind Buddy

Everything Pyypl knows,
one question away.

Buddy is the colleague Pyypl built for itself: it knows our people, reads our tickets, messages, code and data, builds live reports, and drafts the work for a person to approve, instead of making five people open five tools to answer one question.

Built by Pyypl.

Tickets

Messages

Code

Data

Reports

People

Time off

Claims

15Buddy tools, each run as the person asking

4Connected systems, scoped per person

129Automated tests, security cases included

NoneChanges without a person's click

Why it exists

Every team at Pyypl already lived in its own tab: tech in its ticket and code tools, finance and operations in the data warehouse, everyone in chat, and HR in spreadsheets and email. No one could hold the whole picture without ten tabs open.

Buddy closes that gap: a colleague that already knows where everything lives and goes to get it, safely. It runs on Pyypl's own AWS account, everyone signs in with their Pyypl Microsoft account, and each person gets exactly the access they already have.

It began as Pyypl's HR home, so the people tools are built in: time off, claims, documents, onboarding. The brain sits on top of them.

The premise

An assistant for the whole company has to earn its access.

Giving Buddy more reach must never give anyone more access than they already had. Every answer and every action stays inside what the person asking could already do.

Ask

Answers from Pyypl's own data

People, the org structure, time off, claims, documents, company figures, and the systems an admin connected for you. Every answer shows the lookups behind it.

Act

Prepares the work, you approve it

Buddy drafts the ticket, the code review comment or the team message as a card. Nothing happens until you press Approve.

Run the team

People tools, built in

Time off and approvals, expense claims, documents with e-signature, onboarding and offboarding, announcements and analytics.

What it does

Ask, act, schedule, report.

Asking is the front door, not the whole house. Every row is somewhere you can open in Buddy.

Ask Buddy

Ask across everything at once

One question goes to whichever lookups can answer it, and the reply shows the steps it took. Start it from the chat, from Home, or from a saved quick action.

Approval cards

Drafts the work, you send it

A ticket, a code review comment, a team message or an email appears as a card with the exact text. Nothing leaves Buddy until you approve it.

Reports

Live dashboards, not walls of text

KPI tiles, charts and tables that re-run their lookups with your current access on refresh, and export as PDF like Analytics.

Scheduled questions

Standing questions that run themselves

Daily, weekdays, weekly or monthly at a Gulf-time hour. Answers land in their own chat and, if you like, in your inbox.

Memory

Only what you ask it to keep

"Remember that I manage the finance team" is added to every question you ask. Only you can see it, and you can delete it any time.

People tools

The HR home it grew from

Time off and approvals, expense claims, documents with e-signature, onboarding and offboarding, announcements and analytics.

In practice

Things people ask, and what happens.

Waiting for you

What's waiting for me today?

Leave to approve, claims to approve or pay, documents to sign and onboarding tasks, in one list.

Report

Build me a dashboard of monthly volume by channel.

Checks the tables, tests the queries, then saves a live report you can refresh and export.

Tickets

Summarise the open service desk issues updated this week.

Searches only the allowed projects and links every issue it mentions.

Approval card

Comment on the migration pull request that it needs a rollback plan.

Drafts the comment as a card. Posted only when you approve.

Time off

Who on my team is off next week?

Reads your direct reports' leave, nobody else's.

Memory

Remember that I prefer short answers with a table.

Saved to your memory only, used on every question after.

Read on

How Buddy works, page by page.

How it works

The architecture, and what happens from the moment you ask to the moment you approve.

The AI

Claude models, the agent loop, tools, memory, reports and schedules.

Security

Seven checks every question passes through, where keys live, and what gets logged.

Connections

The systems Buddy can reach: what it can do there, and what it structurally can't.

Who sees what

Roles, groups and the exact view each person gets.

Built by Pyypl

Designed and built with Claude Code, on Pyypl's own AWS and Claude accounts.

How it works

One sign-in, two engines.

A fast API for everything you click, and a separate engine for everything you ask. Both run on Pyypl's own AWS account and read from the same data.

Architecture

From your browser to Pyypl's data.

Every request goes through Pyypl's private GraphQL gateway, which checks your sign-in before Buddy sees anything.

Front door

Your browser

Sign in with your Pyypl Microsoft account.

Company sign-in

The same Microsoft sign-in as Pyypl's other internal tools. Groups decide roles.

Buddy web

Remix app behind CloudFront, with a strict content policy.

API

Private API gateway

Verifies your sign-in and forwards who you are. Not reachable from the internet.

Resolver Lambda

Accepts calls only from the gateway, rebuilds your identity on every call, applies role rules.

Scheduler

EventBridge every 15 minutes, for scheduled questions.

The brain

Agent Lambda

Runs each answer in the background, up to 15 minutes, with your identity snapshot.

Claude

Pyypl's own Anthropic account. Opus 5.5 by default.

Connections

Jira, Bitbucket, Slack, Databricks, each behind an allowlist.

DynamoDB

One table per record type.

S3

Documents and receipts, via short-lived links.

SSM

Keys and AI settings, set by tech.

SES

Emails from Buddy's verified domain.

CloudWatch

Logs, audit lines and alarms.

Start to finish

What happens when you ask a question.

A representative round trip, spelled out in the order it happens.

YouType a question in Ask Buddy or on Home. Only plain text leaves your browser.

GatewayPyypl's private API gateway checks your Microsoft sign-in and tells Buddy who you are.

ResolverRebuilds who you are: your work email, your employee record (former employees are refused), your direct reports and your sign-in groups.

ResolverSaves your question and a run, starts the agent in the background, and returns at once. The chat shows progress while it works.

ClaudeReads your question with the tools you are allowed to use, and picks lookups, several at once when they don't depend on each other.

ToolEach lookup runs the same Buddy function the app uses, as you. If you couldn't see it in the app, the tool says it's restricted.

ConnectionFor Jira, Bitbucket, Slack or Databricks, Buddy reads the key from SSM for that call and stays inside the admin's allowlist.

ClaudeWrites the answer in Markdown, with the steps it took shown above it.

YouRead the answer. If Buddy proposed a change, an approval card waits under it.

Changes

What happens when Buddy proposes a change.

ClaudeCalls a proposal tool, for example the one that posts in Slack. It cannot post anything itself.

BuddyChecks the channel, project or repository is allowed, then saves a pending card. Nothing has left Buddy.

YouSee the card with the exact text. Approve or decline. Only the person who asked can decide.

BuddyClaims the card with a conditional write, so a double click can't send twice, and checks your access again.

ConnectionSends it. Slack messages are signed "sent by Buddy for" your name.

YouSee the result and a link in the chat. Buddy remembers it for the rest of the conversation.

Background work

Schedules and report refreshes.

Scheduled questions

Every 15 minutes, the due ones start

EventBridge wakes the agent. For each due schedule, Buddy claims its time slot (so it never runs twice), looks the person up again, and starts the run as them. If they've lost access, the schedule pauses instead. Scheduled runs can't propose changes or create reports.

Reports

Refresh re-runs the lookups

A report stores how each widget gets its data, not the data. Refresh runs in the background as the owner, looked up again with their current access. It refreshes by itself when it's more than an hour old. Widget sources, such as SQL, never reach the browser.

The AI

Claude, working as you.

Buddy uses Anthropic's Claude on Pyypl's company account. It never gets a general-purpose tool like "run a command" or "call any URL". It gets a short list of named lookups that run with your permissions.

Models

Chosen by Buddy admins, in Settings.

The model and how hard it thinks (effort: low to max) are stored in SSM. Keys are not part of that screen.

Model	Used for	Notes
Claude Opus 5.5 Default	Answers in Ask Buddy, reports, schedules	Best balance of quality and cost. Effort defaults to high.
Claude Fable 5.1	Hardest questions	Most capable, slower and costlier.
Claude Sonnet 5.5	Faster answers	Cheaper, for everyday questions.
Claude Haiku 5.5	Chat titles; simple questions	Fastest. Writes each conversation's short title.

If a model declines a request, Anthropic's server-side fallback retries it on another model (not available for Haiku).

The agent loop

Look things up, then answer, within limits.

Each question runs as its own background job, so a long answer never hits the API's 30-second limit.

Context

A fixed system prompt (cached, so repeat questions are cheaper), then today's date, who is asking and their role, their connected systems and what they asked Buddy to remember.

History

The last 30 messages of the conversation, as text. Earlier answers are kept without their raw lookups.

Tool calls

Several lookups can run at once. Each result is capped at 60,000 characters and the model is told when something was cut.

Limits

At most 20 turns, 40 tool calls and 12 minutes per question. Then Buddy answers with what it has.

Progress

Every step ("Checking who's away", "Querying Databricks") is saved on the run and shown live in the chat.

Errors

Readable messages for a rejected key, rate limits or a failed lookup. A refusal ends the answer politely.

Tools

What Claude can call.

Buddy's own tools are available to everyone, but each one runs as you. Connection tools appear only for people an admin allowed on that connection.

ReadsSaves for youProposes a change (needs approval)

Buddy

Find peopleOpen a profileOrg structureLeave balancesLeave historyWho's awayWhat's waiting for youExpense claimsYour documentsAnnouncementsPublic holidaysCompany figuresRememberForgetBuild a report

Connections

Search issuesRead an issueCreate an issuePull requests and reviewsCommits and branchesComment on a pull requestRead channels and threadsPost a messageDescribe tablesRun a read-only query

Content is data

Buddy reads instructions from you, never from what it reads.

An issue, a Slack message or a table row might contain text that looks like an instruction. Buddy's prompt treats everything that comes back from a lookup as data. And even if a model were fooled, the worst it could do is draft a card you then decline.

Beyond a single answer

Memory, quick actions, reports and schedules.

Memory

Only what you ask it to keep

Say "remember that I manage the finance team" and it's added to every question you ask. Up to 50 notes, visible only to you, deletable from Ask → Memory.

Quick actions

Saved questions

Save any question as a chip on Home and in Ask. Up to 12 per person.

Reports

Live dashboards

KPI tiles, area, line, bar, ranked and donut charts, and tables. Claude checks each lookup works before saving it. Up to 12 widgets, exported as PDF like Analytics.

Schedules

Questions on a timer

Daily, weekdays, weekly or monthly at a Gulf-time hour. The answer is written as a self-contained update and can be emailed to you.

Security

Safe by construction, not by request.

Asking a model to behave is not a control. Buddy's limits are in code: what it can call, where it can reach, and what needs a person's click.

The checks

Seven checks between a question and Pyypl's systems.

In the order they happen, every time, for every user.

1

Sign-in

Only Pyypl's company Microsoft sign-in. Buddy's API accepts calls only from Pyypl's private GraphQL gateway, never directly from the internet.

calls from any other caller are rejected

2

Identity

On every call, Buddy matches your work email to an active employee record. Former employees are refused even with a valid token. Roles come from your sign-in groups.

dashboard Admin grants nothing in Buddy

3

Permission

Every tool calls the same function the app uses, as you. Salaries and ID documents stay with Buddy admins; your manager sees your leave, not your pay.

the AI never sees more than you could

4

Connection access

A connection's tools exist only for the people an admin listed on it, and only when it is switched on.

per person, not per department

5

Scope

Every connection call is checked against the admin's allowlist of projects, repositories, channels or tables, inside the tool itself.

https only, the service's own host, no redirects

6

Approval

Anything that changes something outside Buddy is saved as a card. Only the person who asked can approve it, and access is checked again at that moment.

the model can draft, it can never send

7

Log

Every question, lookup, approved action and change to a record becomes a structured CloudWatch line, written after the change is saved.

salary and ID changes log field names only

Underneath every connection

Where the keys live.

No key is ever typed into Buddy, stored in its database, or sent to the browser or the model.

Storage

AWS SSM Parameter Store, as encrypted values.

Who sets them

Tech, directly in AWS. Buddy has no screen and no API that accepts a key.

Who can read them

Only Buddy's two Lambdas, by IAM policy, and only under the AI and connections paths. Neither can change a key.

What admins see

Whether each key is set. Never the value.

When it's read

At the moment a call needs it, cached for a few minutes, and used only in that request's header.

On errors

A failed call returns a short message such as "refused the request (401)". The service's response body is never passed on.

The hardest connection

Letting an assistant query the data warehouse.

Databricks holds Pyypl's transaction data. Buddy can only read it, through a guard that every query must pass before it is sent, and through a service principal whose own grants are the final limit.

Allowed

SELECT month, sum(amount)
FROM catalog.schema.transactions
GROUP BY monthOne statement, full catalog.schema.table name, on an allowed table.

WITH t AS (SELECT … FROM catalog.schema.balances)
SELECT … FROM tNamed sub-queries are fine.

Refused before it's sent

DELETE FROM … · INSERT · MERGE · DROP · ALTERAnything that writes: read-only.

SELECT … ; SELECT …Only one statement at a time.

SELECT * FROM catalog.schema.other_tableNot on the allowlist.

Functions that read files, call the internet or read secretsRefused, even inside an otherwise valid query.

Everywhere else

Smaller rules that close real gaps.

Private by owner

Conversations, memory, quick actions, reports and schedules belong to one person. Admins can't open them either.

Schedules re-check access

Each run looks the person up again. If they left Pyypl or lost their groups, the schedule pauses.

No double actions

Approvals, claims, signatures and schedule slots use conditional writes, so two clicks or two timers can't both win.

Files by short-lived link

Uploads and downloads go straight to S3 through presigned links, checked by kind and size.

Emails from one sender

SES may send only from Buddy's own address, one copy per person so addresses are never shared.

Alarms

Unexpected errors, slow calls, failed answers and web 5xx responses alert through SNS.

Connections

Reaches where the work happens.

Each connection has a short, fixed list of operations. Buddy admins choose what it may reach, who may use it, and whether Buddy may propose changes. Anything not listed below does not exist in the code.

Read, runs on its ownChange, proposed as an approval card

J

Jira

Account email and API token, kept in SSM

Changes need approval

Scope

The allowed project keys. A search covers only those projects; asking for another one is refused.

Only the company's own Jira site is accepted.

Tools

List projectsSearch issuesRead an issueCreate an issue

Searches are built from typed filters (text, status, assignee, type, dates), never free-form JQL from the model.

Never possible

Editing, moving, commenting on or deleting an issue. Those operations were never written.

B

Bitbucket

Account email and API token, kept in SSM

Changes need approval

Scope

The allowed repositories, written as workspace/repository.

Tools

Pull requestsPull request detailsCommitsBranchesComment on a pull request

Pull requests come back with reviewers, approvals, changed files with line counts, and recent comments.

Never possible

Merging, declining, approving a pull request, pushing code or editing files.

#

Slack

Bot token, kept in SSM

Changes need approval

Scope

The allowed channels. The bot also has to be invited to each one, which is Slack's own rule.

Tools

List channelsRead a channelRead a threadPost a message

Mentions and links come back as readable names. Posts are signed "sent by Buddy for" the person who approved.

Never possible

Direct messages, posting outside the allowed channels, editing or deleting messages.

DB

Databricks

OAuth client credentials, kept in SSM

Read-only

Scope

The allowed tables, as catalog.schema.table, through one SQL warehouse. A dedicated service account signs in with a SQL-only permission.

Tools

Describe tablesRun a read-only query

Claude checks the columns first, then runs one SELECT. Up to 500 rows come back; long queries are cancelled after about two minutes.

Never possible

Any write, any second statement, any table not allowed, and file, network or secret functions. See Security for the guard.

Admin controls

Settings → Connections.

Buddy admins manage each connection on one screen.

On or off

When off, nobody can use it, whatever else is chosen.

What it reaches

Pick projects, repositories, channels or tables, loaded live from the service.

Who can use it

Choose people one by one. Access is per person.

Propose changes

Allow approval cards, or keep it read-only. Databricks is always read-only.

Who sees what

The right view for every role.

Roles come from sign-in groups, plus what the directory says about you: who reports to you, and which department you're in.

Role	How you get it	Ask & reports	People	Admin
Employee	An active employee record with your work email	Your own data and the company directory; connections an admin granted you	Your time off, claims, documents and tasks	None
Manager	Someone reports to you in the directory	Also your direct reports	Approve your team's time off	None
Management	You're in the Management department	Also every expense claim	Approve claims and mark them paid	None
HR	The Buddy HR group	Also employee records and company figures	Records, leave, documents, onboarding	People and leave settings
Buddy admin	The Buddy admin group	Everything, including salaries and ID documents	Everything	Model, connections and access

Dashboard Admin isn't Buddy admin

Being an admin in the Pyypl dashboard gives nothing extra in Buddy. Buddy admin is its own group.

Connections are per person

Being HR or an admin doesn't give you Jira or Databricks in Ask Buddy. An admin adds you to each connection.

Leaving ends access

A former employee can't sign in, and their schedules pause at the next run.

Getting access

Ask a Buddy admin.

To sign in: an active employee record with your Pyypl work email.
For HR or admin rights: the matching Buddy group, granted by an admin.
For a connection in Ask Buddy: an admin adds you to it in Settings → Connections.