# porcelain for agents

porcelain is a git proxy: clone any GitHub repo through it and fetch issues, PRs,
reviews, and comments as files on a shadow branch. push changes back and they
propagate to GitHub. git is the only API you need.

## read

```
git clone https://git.porcelain.sh/github.com/{owner}/{repo}
# force (+) the overlay fetch: it's a server-maintained snapshot ref that is
# periodically compacted (rewound to a new root to bound history), so updates are
# not always fast-forward.
git fetch origin +refs/overlays/github:refs/overlays/github
git ls-tree -r refs/overlays/github --name-only
git show refs/overlays/github:issues/42.md
```

overlay files are markdown with YAML frontmatter:

```
---
id: 990000001
number: 42
state: open
author: 12345
---

# issue title

issue body text.
```

layout: issues/{n}.md, pulls/{n}.md, comments under the same tree.

## write

writeback requires a porcelain token. send it as the password in the remote URL
or as Authorization: Bearer.

```
git remote set-url origin https://x:{PORCELAIN_TOKEN}@git.porcelain.sh/github.com/{owner}/{repo}
```

to close an issue: fetch the overlay, commit a change to the issue file
frontmatter (state: open → closed), push the overlay ref:

```
git push origin refs/overlays/github:refs/overlays/github
```

to create an issue: add a file at issues/new.md (or issues/new-anything.md)
with a `# title` heading and body, commit, push the overlay ref. GitHub
assigns the real number and the overlay rematerializes as issues/{n}.md.

to comment on issue 42: add comments/42/new.md with the comment text, push.
to change labels: edit the labels list in the issue file frontmatter, push.

porcelain diffs the overlay push and calls the GitHub API for you. the webhook
round-trip updates the overlay within ~1s of GitHub confirming.

tokens can be path-scoped: a token scoped to `issues/` can create and close
issues but cannot touch anything else. out-of-scope pushes are rejected whole.

## faster installs — npm cache

porcelain proxies the npm registry and caches tarballs in-region (zero egress).
cold `npm install` is ~60s; warmed through porcelain it's ~2s. point npm at it:

```
npm config set registry https://npm.porcelain.sh
# or per-project .npmrc:  registry=https://npm.porcelain.sh
```

public packages need no token. integrity (sha512) still validates — porcelain
serves the exact upstream bytes, it just caches them. turbo + pip/uv caches and
fast diff-only tests (`porcelain test`) are coming on the same host.

## notes

- public repo reads need no token, no signup
- code pushes (refs/heads/*) also require a porcelain token and forward to GitHub
- every fetch prints a `remote: porcelain: ...` summary line with timing
- responses carry Server-Timing headers if you need to debug latency
- full docs: https://porcelain.sh/docs