gist-share

Post any content — summaries, plans, reports, pitches, logs — to GitHub Gist and share the URL. A lightweight way for agents to publish rich context that humans and other agents can read from anywhere.

Why Gists?

Agents communicate through messages, but messages disappear into scroll. A gist is:

• Persistent — stays at a stable URL
• Readable by anyone — no auth required for public gists
• Markdown-rendered — GitHub renders it beautifully
• Shareable — paste the URL anywhere

When an agent needs to hand off context to a human, another agent, or a future session — a gist beats a wall of chat text.

Setup (One-Time)

You need a GitHub Personal Access Token (PAT) with the gist scope.

Step 1: Create a PAT

1. Go to github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it a name like openclaw-gist
4. Check the gist scope (that's all you need)
5. Click Generate token
6. Copy the token — you won't see it again

Step 2: Authenticate the gh CLI

OpenClaw uses the gh CLI to post gists. Set your token as an environment variable for the session:

export GITHUB_TOKEN=ghp_yourTokenHere

Or add it permanently to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export GITHUB_TOKEN=ghp_yourTokenHere' >> ~/.zshrc
source ~/.zshrc

Step 3: Verify it works

gh auth status

You should see your account and gist listed under token scopes.

How to Post a Gist

Basic usage

Use the exec tool to call gh gist create:

gh gist create --public --desc "Your description here" --filename "your-file.md" - << 'EOF'
Your content here.

Supports **markdown** formatting.
EOF

With a flag for secret gists

Replace --public with --secret if the content shouldn't be publicly indexed.

Full template

gh gist create \
  --public \
  --desc "DESCRIPTION" \
  --filename "FILENAME.md" - << 'GISTEOF'
# TITLE

CONTENT GOES HERE
GISTEOF

The command returns the gist URL on success:

✓ Created public gist FILENAME.md
https://gist.github.com/USERNAME/HASH

Workflow

1. Prepare content — write your markdown (report, summary, plan, pitch, log)
2. Choose visibility — --public for sharing freely, --secret for targeted sharing
3. Post it — run gh gist create via exec
4. Return the URL — share it in the conversation, send it to another agent, or log it

Example: Posting a Strategic Summary

gh gist create --public --desc "Q2 Roadmap Summary" --filename "q2-roadmap.md" - << 'EOF'
# Q2 Roadmap Summary

## Phase 1 — Foundation (April)
- Complete ClawDash MVP
- Ship ClawCanvas v1

## Phase 2 — Expansion (May)
- Launch ClawText beta
- Begin ClawTomation integration

## Phase 3 — Scale (June)
- Public launch of suite
- Partner integrations go live
EOF

Tips

• Filename matters — use .md extension for GitHub to render markdown
• Description is searchable — write something meaningful
• One gist per topic — don't cram everything into one file; use focused gists
• Update with gh gist edit GIST_ID — gists are editable if you need to revise
• List your gists — gh gist list shows recent gists with their IDs and URLs

Troubleshooting

Gists: the simplest way for a claw to leave a note the world can read.