Skip to content

About

Personal Agent Protocol, "poppy" for short

Resources

Contributing

Security policy

Stars

160 stars

Watchers

12 watching

Forks

Latest commit

 

History

159 Commits

Folders and files

Repository files navigation

Personal Agent Protocol

Source for personalagentprotocol.org, the site that publishes the Personal Agent Protocol draft specification and its docs. The protocol lets personal agents discover participating companies, sign users in, and get things done through APIs, web pages, and company agents.

The site is a Next.js static export. It documents the protocol but does not implement the APIs the specification describes.

Development

Use Node.js 20.9 or newer and pnpm 10.34.0. Dependencies install from the public npm registry.

pnpm install --frozen-lockfile
pnpm dev

The site opens at http://localhost:3000. Before sending a change, run:

pnpm typecheck
pnpm format:check
pnpm build

If you changed the docs or kit/, run pnpm kit first. It regenerates the kit, and the build fails when the committed kit is out of date. pnpm kit and the validator's tests, pnpm test:kit, need Node.js 22.18 or newer.

The production build writes the static site to out/. Serve that directory with any static host.

pnpm-workspace.yaml sets minimumReleaseAge, so pnpm won't install a package version until it has been published for four days.

Pages

  • /: the overview, with interactive walkthroughs
  • /docs/introduction, /docs/changelog: the pages with one copy
  • /docs/<version>/spec, /docs/<version>/extensions, /docs/<version>/guides, and in 0.1 and 0.2, /docs/<version>/extensions/operations: each version of the protocol's pages, such as /docs/0.2/spec for draft 0.2 and /docs/0.1/spec for version 0.1, which is frozen. Without a version, such as /docs/spec, they redirect to the latest.
  • /license and /license/contributions: the license and the contribution terms
  • /kit/company: the Company implementation kit, not linked from the navigation

Each docs page is also served as Markdown at the same path with .md, for example /docs/0.2/spec.md, and /llms.txt lists them for AI agents. The kit's skill is served file by file under /kit/company/, and as /kit/implement-personal-agent-protocol.zip. Section links use a fragment, for example /docs/0.2/spec#sessions. The site also serves /robots.txt and /sitemap.xml, and unknown paths show a 404 page.

Structure

  • app/: Next.js routes, metadata, and the stylesheet.
  • components/: navigation, walkthroughs, code blocks, and review comments.
  • content/: the docs pages as MDX, in versions/<version>/ and shared/, docs.ts (the index of docs tabs and pages), versions/versions.json (the versions), the home page, and the walkthrough data. See content/AGENTS.md.
  • lib/: the MDX pipeline (mdx.ts, mdx-markdown.ts, docs-content.ts), the docs outline, the kit generator (lib/kit/), syntax highlighting, and analytics.
  • kit/company/: the source of the Company implementation kit: the skill's instructions, patterns, and milestones, the JSON Schemas, and the validator, with its tests.
  • skills/ and .claude-plugin/: the kit as agents install it, generated by pnpm kit from kit/ and the docs. Don't edit them by hand.
  • public/: the logo, link preview image, pronunciation clip, and the license text.

Editing the docs

See content/AGENTS.md for how the docs are written, where each page comes from, and how a version is published.

Hosting

On Vercel, vercel.json permanently redirects personalagentprotocol.ai, personalagentprotocol.net, and personalagentprotocol.com to https://personalagentprotocol.org, keeping paths and query strings. It also redirects older page URLs to their current paths, sends docs URLs without a version to the latest version (pnpm docs:sync writes those redirects), and sets security headers on every response: HSTS, nosniff, a strict referrer policy, a ban on framing the site, and a Content Security Policy that loads everything from the site itself.

Other static hosts need equivalent configuration. pnpm dev does not apply Vercel rules. On other hosts, a small script on the home page sends old /?page=spec links to the latest spec.

Feedback and contributions

To send feedback on the specification, see Providing feedback in the introduction. To change this repository, see CONTRIBUTING.md. Contributions are accepted under the contribution terms.

License

The specification and documentation are licensed under the Apache License 2.0. The license doesn't cover the names Personal Agent Protocol and Poppy, the logo, or the design of the site.

About

Personal Agent Protocol, "poppy" for short

Resources

Contributing

Security policy

Stars

160 stars

Watchers

12 watching

Forks

Contributors

Languages