agh

Español

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

• Centralize guidance: publish shared skills and project instructions once.
• Version every change: skill releases are immutable and assigned to projects exactly.
• Keep repos deterministic: each workspace records .agh/lock.toml and applies only the selected target.

Install

Linux / macOS:

brew install giulianotesta7/tap/agh

Windows (Scoop):

scoop bucket add agh https://github.com/giulianotesta7/scoop-agh
scoop install agh

or with the install script:

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

Check the CLI:

agh --help

Run the server with the published Docker image:

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

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

Quick start

AGH uses a clean-break schema: provision a fresh empty data volume and the server initializes it on first start — it never migrates or reuses package-era databases. See Clean break.

Read the first owner token on the host running AGH:

docker run --rm -v agh-data:/data busybox \
  cat /data/secrets/initial_owner_token

Configure the instance URL once, then log in from your machine:

agh config set <instance-url>
agh login --email owner@example.com --token "<initial-owner-token>"

agh config shows the configured instance URL; agh config clear removes it, and agh logout clears stored credentials.

Create a project with the repo URL developers use in git remotes:

agh project create "Agent Guidance Hub" \
  --git-url https://github.com/giulianotesta7/AgentGuidanceHub.git

Work from a linked repo:

agh link
agh target set agents # or: agh target set claude
agh pull --dry-run
agh pull
agh target

agh target shows the selected target for this workspace; agh target clear removes the workspace selection, and --global manages the global default.

CLI reference

How AGH works

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

reviewer/
├── SKILL.md
├── references/
│   └── guide.md
├── scripts/
│   └── check.sh
└── assets/

Server operations

The server listens on port 8912; the health endpoint is:

curl http://127.0.0.1:8912/api/v1/health

The first owner token is written once to /data/secrets/initial_owner_token — store it, AGH will not show it again. The server stores token hashes, not plaintext tokens.

Runtime state lives under AGH_DATA_DIR:

The CLI stores login credentials locally; agh config shows only the instance URL, never the token.

A database created by the previous package-era schema fails closed, and the file is preserved untouched for diagnosis:

INCOMPATIBLE_SCHEMA: incompatible schema at <path>; use a fresh empty AGH_DATA_DIR

Clean break

AGH uses a clean-break schema with no migration path. The server initializes the database only when it is empty or absent; it does not migrate or reuse package-era data. To upgrade, provision a fresh empty AGH_DATA_DIR and re-create users, projects, and skill releases. Skill releases are immutable, so republishing an unchanged skill directory produces the same release checksum. An incompatible database fails closed with INCOMPATIBLE_SCHEMA — see Server operations.

Development

uv sync
uv run pytest
uv run uvicorn agh.server.app:app --host 0.0.0.0 --port 8912

Local data uses .agh-data/ by default.

Contributing and security:

• Contributing
• Security