Automate ngit safely

ngit has an explicit machine interface. Agents should consume that interface instead of scraping terminal prose or inventing Nostr identifiers.

Owned by ngit + ngit-docsVerified ngit 3.0.0-rc.7 @ 8eb500aded76automation contract

Install repository guidance

Maintainers can install ngit's bundled skill into a repository:

ngit skill install
ngit skill status
ngit skill upgrade

The skill teaches supported collaboration commands and adds a compact pointer to existing agent instruction files. Installation and upgrades make dedicated commits; contributors should propose them from a pr/ branch.

Stable output

Always add --json when an agent reads an ngit command:

ngit pr list --json
ngit issue view nevent1… --comments --json --offline

stdout contains exactly one JSON document after the command finishes. Relay progress and human diagnostics stay on stderr. Native git commands do not support this flag.

Add global --quiet when non-essential stderr progress and notices are not useful. It does not hide primary results, warnings, or failures, and it cannot be combined with --verbose.

Cache-aware reads

Use the network for the first ngit read in a session, then prefer --offline while the local event cache is fresh:

ngit repo --json
ngit pr list --json --offline
ngit issue list --json --offline

git fetch origin also refreshes repository state and cache data.

Select the repository explicitly

When multiple nostr:// remotes identify different repositories, pass a remote name, naddr, or Nostr URL:

ngit --repo upstream issue list --json
ngit pr --repo upstream list --json --offline

Before a signing command, check the target repository diagnostic on stderr. ngit fails rather than guessing when selection is ambiguous.

Use returned identifiers

JSON id and reply_to fields use nevent1…. Pass the complete value back to <ID|nevent> parameters. Within a Markdown body, prefix it with nostr::

ngit issue comment nevent1… \
  --body "Related to nostr:nevent1…" \
  --json

Never fabricate NIP-05 names. Use an npub1… unless a NIP-05 address was explicitly provided.

Select signers without exposing secrets

ngit --signer alice issue create \
  --subject "Bug" \
  --body "Details" \
  --json

git -c nostr.signer=alice push origin pr/fix

For CI, prefer --nsec-file with a protected ephemeral file. Do not export an nsec merely to switch between configured identities.

Machine-readable documentation

The built site publishes:

Endpoint	Purpose
/llms.txt	Curated page index with short descriptions.
/llms-full.txt	All public Markdown in one bounded, grep-friendly document.
/api/docs-manifest.json	Page URLs, raw Markdown URLs, owners, source repos, and verified versions.
/markdown/<route>.md	Raw source for an individual public page.
/api/ngit/3.0.0-rc.7/cli.json	Complete tagged 3.0.0-rc.7 command schema.
/api/ngit-grasp/upcoming/reference.json	ngit-grasp command and configuration schema.
/api/ngit-ci/upcoming/manifest.json	Coordinator and microVM adapter artifact index.

Use the manifest to discover content and the raw Markdown endpoint to retrieve only the required page. The HTML site remains the canonical human experience; these outputs are deterministic views of the same source.

The guide index connects human tasks to these source-generated facts.