githug from your own agent loop

No CLI needed: one HTTP call trades the agent's key for a 1-hour GitHub token on one repo.

Get a key

Create the agent at githug.ai/app, or with hug agent create my-agent --repo owner/repo. The key starts with ghg_ and is shown once.

Mint a token

curl -s https://githug.ai/v1/token \
  -H "Authorization: Bearer $GITHUG_AGENT_KEY" \
  -d '{"repo":"owner/repo","run":"loop-0412"}'

{
  "token": "ghs_…",
  "expires_at": "2026-10-09T21:12:09Z",
  "repo": "owner/repo",
  "run": "loop-0412",
  "agent": { "id": "my-agent", "name": "my-agent" },
  "accountable": "your-login",
  "author": { "name": "my-agent", "email": "my-agent@agents.githug.ai" },
  "trailers": ["Co-authored-by: …", "Accountable: your-login", "Agent: my-agent"]
}

• Use token for git over HTTPS (x-access-token:<token>) and the GitHub API. It can push branches and work issues and PRs; it can't change settings, and your branch protection still guards main.
• Commit as author, and end the message with trailers. Co-authored-by for you is only included if the agent has graph credit on (off by default), since GitHub counts co-authored commits on your contribution graph. Accountable: is always there.
• run is optional: any id for the loop iteration. Every key and commit with the same run is one run in the chain.
• Mint again when expires_at passes. Mints are free and logged.

Errors come back as {"error": "…"}: 401 bad key, 403 agent disabled or repo out of scope, 404 githug not installed on the repo.

Attest what you push

Commit metadata is free text anyone can write, so githug only calls a commit verified when the agent's own key reported it. Before (or right after) each push, send the full SHAs of the commits you're pushing:

curl -s https://githug.ai/v1/commits \
  -H "Authorization: Bearer $GITHUG_AGENT_KEY" \
  -d '{"repo":"owner/repo","shas":["<40-char sha>","…"],"run":"loop-0412"}'

Up to 500 per call; repeats are ignored. Without it, the agent's commits show as consistent (their claims match githug's records) instead of verified, and they still pass the verify Action. hug setup does this for you with a pre-push hook; hug attest does it by hand.

Open a PR

curl -s https://githug.ai/v1/pr \
  -H "Authorization: Bearer $GITHUG_AGENT_KEY" \
  -d '{"repo":"owner/repo","head":"agent/fix-123","base":"main","title":"Fix the thing","body":"…","run":"loop-0412"}'

githug opens it with the accountable human as author (falling back to the githug App if they haven't signed in to githug), adds a footer naming the agent and run, and returns number, url, opened_as and verify_url. Pass "as": "agent" to make the agent's bot the author instead, so the human can still approve it when branch protection requires a review, and "labels": ["…"] to label it.

Sub-agents for your workers

An agent can create sub-agents with their own keys, for the workers it runs:

curl -s https://githug.ai/v1/agents/children \
  -H "Authorization: Bearer $GITHUG_AGENT_KEY" \
  -d '{"name":"w1"}'

The sub-agent is named <agent>-w1 and has the same accountable human. Its repos and permissions are a subset of its parent's, and agents nest at most 3 deep. Its commits carry Agent-Chain: <human> › <agent> › <agent>-w1. Disabling an agent disables everything under it. With the CLI: hug agent spawn w1 --env prints the worker's GITHUG_AGENT_KEY export.