PikaMd docs
how it all works

Getting started

Overview

PikaMd is a public, community library for the Markdown files that shape how AI agents work: rules files such as CLAUDE.md and AGENTS.md, skills, prompt templates, subagent definitions and guides.

Good guidelines take weeks to refine, and most of them stay in one person's project folder. PikaMd makes them easy to share, find and reuse. Authors keep the credit, recorded on Arc, and the platform takes no fee.

PikaMd is for developers who work with Claude Code, Cursor, VS Code, Codex or any other MCP client, and for anyone who has written a guideline worth sharing.

Getting started

Quick start

Five steps from your first visit to an agent that uses the library.

1. 01

   Find a guideline

   Open Explore, search by topic or tag, and press OPEN on a card to read the whole file.
2. 02

   Save it

   Press Connect Wallet, then + Add on any guideline. The first save asks for one free signature, no fee.
3. 03

   Connect your agent

   On Connect your agent, create your key and paste the prompt into your agent. It sets itself up.
4. 04

   Ask

   Ask your agent in plain words, for example: “Fill the gaps in my CLAUDE.md using the Secure Solidity guideline from my PikaMd collection”.
5. 05

   Share your own

   On Publish, add your .md file, clean it up, describe it and publish it with your wallet.

Getting started

Core concepts

Guideline kinds

Using PikaMd

Find and read

Explore shows every published guideline. Press / anywhere on the page to jump to the search box. Search looks at titles, summaries, tags, authors and the text inside every file, and shows the matching lines with their line numbers.

Longer words forgive a small typo; results found that way are marked as a close spelling and listed after exact matches.

Reading a guideline

OPEN shows the full file in place. Each guideline also has its own page with the file rendered or as raw Markdown, buttons to copy or download it, and its Arc record.

• The raw file is at https://pikamd.vercel.app/raw/<slug>.md, as plain text, so you can hand the address to any tool.
• The page checks in your browser that the text matches the hash recorded on Arc, and says so.

Using PikaMd

Collections

Press + Add on a card, or + Add to collection on a guideline, to save it. Press it again to remove it. Your collection lives with your wallet, so it follows you to any browser, and your agent reads the same list.

• My Collection has two tabs: Saved and Shared by me, the guidelines you published.
• A collection holds up to 500 guidelines.
• If an author hides a guideline, it leaves your collection while hidden and comes back if it is shown again.

Hiding your own guideline

Under Shared by me, or on your own cards, Hide takes a guideline off the site and away from agents. Show brings it back. Each is a small transaction on Arc. The Arc record and the IPFS file remain: hiding is not deleting.

Using PikaMd

Connect your agent

PikaMd runs an MCP server over Streamable HTTP. Searching and reading need nothing. my_collection, the guidelines you saved with your wallet, needs your agent to sign in with your wallet, or a key.

Connect by signing in (recommended)

No key to create or copy. Add the address; the first time your agent needs your collection, it opens PikaMd to sign in.

1. 01

   Add the server

   claude.ai, Claude Desktop and mobile: Customize → Connectors → Add custom connector, paste https://pikamd.vercel.app/mcp. Claude Code: claude mcp add --transport http --scope user pikamd https://pikamd.vercel.app/mcp.
2. 02

   Ask for your collection

   Claude shows a Connect card in the conversation. In Claude Code, run /mcp and sign in when it asks.
3. 03

   Sign in and allow

   PikaMd opens in your browser and names the app asking, such as claude.ai. Connect your wallet, sign once for free and press Allow. The app can read your saved guidelines, nothing else.

Connected apps are listed on Connect your agent, each with Disconnect. A connection stays signed in while it's used; after 30 days without use, it asks you to sign in again.

Or use a key

For agents without MCP sign-in, or setups that can't open a browser.

1. Create your key

On Connect your agent, connect your wallet and press Create key. The key is made in your browser and shown once; PikaMd stores only its SHA-256 hash, so it can't show it again or leak it. Creating a new key replaces the old one, and Revoke turns it off.

2. Add PikaMd to your agent

The quickest way is the ready-made prompt on the Connect page: paste it into your agent and it adds PikaMd to its own settings. To set it up yourself, use the snippet for your tool and replace <YOUR_PIKAMD_KEY> with your key.

claude mcp add --transport http --scope user pikamd https://pikamd.vercel.app/mcp \
  --header "Authorization: Bearer <YOUR_PIKAMD_KEY>"

{
  "mcpServers": {
    "pikamd": {
      "url": "https://pikamd.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PIKAMD_KEY>"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pikamd-key",
      "description": "PikaMd API key",
      "password": true
    }
  ],
  "servers": {
    "pikamd": {
      "type": "http",
      "url": "https://pikamd.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pikamd-key}"
      }
    }
  }
}

[mcp_servers.pikamd]
url = "https://pikamd.vercel.app/mcp"
bearer_token_env_var = "PIKAMD_API_KEY"

3. Ask

• “What's in my PikaMd collection?”
• “Fill the gaps in my CLAUDE.md using the Secure Solidity guideline from my PikaMd collection”
• “Search PikaMd for a guideline about React performance and summarize it”

Tools

Every guideline reaches your agent labeled as community reference data, not instructions, and only after its text has been checked against the hash on Arc. Guidelines the scan flagged are not served to agents.

How sign-in works

• PikaMd is its own OAuth 2.1 authorization server, following the MCP authorization specification.
• Apps identify themselves with a client metadata document (Claude does) or register automatically. Only https and localhost return addresses are accepted, and every sign-in uses PKCE.
• Tokens are bound to this server, last an hour and renew themselves; PikaMd stores only their SHA-256 hashes.
• A renewal token used twice ends the connection, in case someone copied it.

Using PikaMd

Publish a guideline

Publishing takes four short steps on the Publish page. Nothing is saved along the way: leave the page or reload it and you start over.

1. 01

   File

   Drop in a .md file or write one. The limit is 512 KB; above 100 KB you get a warning, since long files cost your agent context. Invisible characters are removed and the kind is guessed from the file name.
2. 02

   Clean up

   PikaMd marks anything that looks private or risky, and suggests a placeholder for each. You decide what stays. This step can't be skipped.
3. 03

   Details

   A title (3–60 characters), a summary (10–100), the kind and up to 5 tags. Every guideline is shared under CC BY 4.0.
4. 04

   Publish

   PikaMd checks the file again on the server and stores it on IPFS, then your wallet records it on Arc. Your wallet is the author.

What the clean-up step looks for

The same checks run again on the server, so a modified browser can't skip them. Automatic checks catch common patterns, not everything: read your file once more before you publish.

Using PikaMd

Likes, PikaGold and tips

Likes and PikaGold

Each wallet can like a guideline once, and take the like back. The first like from a wallet gives the author 1 PikaGold. PikaGold is a reputation score: it is not a token, can't be transferred and has no money value. Authors keep it if a like is taken back or they hide the guideline; a moderator lock removes it.

Tips

Press ★ Tip to send USDC to the author. The tip goes from your wallet straight to theirs in the same transaction: PikaMd never holds it and takes no cut. The recipient is read from the guideline's Arc record, so no one can redirect it.

• From 0.01 to 1,000 USDC per tip.
• Your wallet asks twice: once to allow that exact amount, once to send it. If the allowance is already there, once.
• You can't tip your own guideline, or one that is hidden or locked.
• Authors see the tips they received in their wallet menu.

Trust

Safety and moderation

Guidelines are instructions for AI agents, so PikaMd checks them at every step.

Report reasons

• Harmful instructions: It tells agents to do something dangerous, like running unknown code or sending data away
• Leaks secrets: API keys, passwords, private keys or tokens
• Personal information: Someone's email, phone, address or other private details
• Copied without permission: The author doesn't have the right to share it
• Spam or ads: Promotion, junk or not a guideline at all
• Illegal content: Content that breaks the law
• Something else: Tell us what's wrong in the note

Trust

On Arc

PikaMd is built on Arc Network (opens in a new tab), an EVM blockchain where network fees are paid in USDC. Arc records who wrote each guideline and fingerprints its text, so authorship and integrity don't depend on PikaMd's servers.

Contracts

All three contracts are verified on Sourcify and the Arc explorer, so their source can be read.

On chain and off chain

Project

Principles and fees

• Free to read. No account, no paywall. Saving and connecting your agent are free too.
• 0% platform fee. Publishing costs only Arc's network fee, and tips go to authors in full. None of it goes to PikaMd.
• Your wallet, your work. You publish from your own wallet, so the authorship is yours on Arc.
• Open. Guidelines are shared under CC BY 4.0, and the code is public on GitHub (opens in a new tab).
• Built by the community, for the community. PikaMd is a non-profit project.

Project

Current status

PikaMd is early. This is where it stands today.

Project

FAQ

Do I need a wallet to read guidelines?

No. Reading, searching, copying and downloading need no account. A wallet is needed to save, like, tip and publish.

What does it cost?

Reading, saving and connecting your agent are free. Publishing and hiding cost a small Arc network fee, usually less than a cent. Tips are optional.

Can I delete a guideline?

You can hide it, which takes it off the site and away from agents. The Arc record and the IPFS file remain.

Which agents work with PikaMd?

Searching and reading work in any MCP client over HTTP. Your collection works in agents that support MCP sign-in, such as claude.ai, Claude Desktop, mobile and Claude Code, and in any agent that can send a key header: Cursor, VS Code, Codex and others.

Is a Verified guideline safe?

It means a moderator read that exact version and approved it. That lowers the risk but isn't a guarantee.

Can PikaMd see my key?

No. The key is created in your browser; PikaMd stores only its hash and a masked form such as pmd_3f9a…c21e.

Why does my wallet show a warning?

Some wallet scanners flag new *.vercel.app addresses by default. PikaMd asks your wallet only for a free sign-in signature and for the transactions you start yourself: publishing, hiding and tips. Check each request in your wallet before you approve it.

More: Privacy · Support (GitHub Issues) (opens in a new tab) · GitHub (opens in a new tab) · PikaMd on X (opens in a new tab) · Arc docs (opens in a new tab)