agh 0.2.1

Self-hosted guidance distribution for coding agents

Agent Guidance Hub (AGH)

Self-hosted guidance distribution for coding agents.

Español

AGH gives teams one place to publish, version, assign, and pull reusable agent instructions and skills into their repos.

Use it when agent guidance needs the same discipline as infrastructure: reproducible changes, clear ownership, and self-hosted runtime.

Why AGH

• Centralize guidance — publish shared AGENTS.md, CLAUDE.md, and skill files once.
• Version every change — packs are immutable SemVer releases assigned to projects.
• Keep repos deterministic — each workspace pulls a manifest, records .agh/lock.toml, and applies only the chosen agent.
• Run it yourself — host the server with Docker, SQLite, and persistent /data storage.

How it works

Pack author ── publish ──▶ AGH server ── assign ──▶ Project
                              │                         │
                              │                         ▼
                         SQLite + /data          Repo workspace
                                                       │
                                                       ├─ AGENTS.md + .opencode/skills/
                                                       └─ CLAUDE.md + .claude/skills/

Each developer chooses one agent for a workspace:

agh agent select opencode # or: agh agent select claude

AGH stores that choice in .agh-cache/preferences.toml; you do not commit it.

Demo source: docs/assets/agh-workspace-demo.tape.

Quick start

Run the server with the published Docker image:

docker compose up -d
curl http://127.0.0.1:8912/api/v1/health

Install the CLI:

curl -fsSL https://raw.githubusercontent.com/giulianotesta7/AgentGuidanceHub/main/scripts/install.sh | sh

Or use uv directly:

uv tool install --force agh

Log in with the first owner token:

agh login \
  --url http://127.0.0.1:8912 \
  --email [e-mail] \
  --token "$(docker run --rm -v agh-data:/data busybox cat /data/secrets/initial_owner_token)"

Then work from a linked repo:

agh sync
agh agent select opencode # or: agh agent select claude
agh pull --dry-run
agh pull
agh agent

The default Compose image is:

ghcr.io/giulianotesta7/agent-guidance-hub:${AGH_IMAGE_TAG:-latest}

Pin production deployments with a release tag:

AGH_IMAGE_TAG=0.2.0 docker compose up -d

What gets committed

Commit the shared workspace state:

• .agh/project.toml
• .agh/lock.toml
• the generated target your team wants reviewed, such as AGENTS.md or CLAUDE.md

Do not commit local cache state:

.agh-cache/

AGH downloads packs to .agh-cache/packs/ and stores each developer's agent choice in .agh-cache/preferences.toml.

AGH generates skill targets under .claude/skills/ or .opencode/skills/ for the selected agent. Commit them only if your team wants agent skills reviewed in Git.

Docs

Guide	Use it for
Quickstart	First Docker run, login, project link, and workspace apply flow.
Installation	CLI installer, checkout install, PATH troubleshooting, and uninstall.
Packs	Create, publish, and list instruction/skill packs.
Projects	Create projects and assign packs to repos.
Admin	Bootstrap owner, users, roles, tokens, and local config.
Workspace guide	Repo setup, workspace apply behavior, markers, skills, lockfile, and Git rules.
Operations	Docker runtime layout, /data, logs, healthcheck, backup, and upgrades.
Contributing	Issue-first workflow, PR rules, and validation commands.
Security	Vulnerability reporting and supported security scope.

Status

AGH is an early self-hosted release for teams that want to own their agent guidance. It ships as a PyPI package and a GHCR server image.

Development

uv sync
uv run pytest

For local server builds and development, see Operations.