Metadata-Version: 2.4
Name: agh
Version: 1.0.0
Summary: Self-hosted guidance distribution for coding agents
License-Expression: MIT
Project-URL: Homepage, https://github.com/giulianotesta7/AgentGuidanceHub
Project-URL: Documentation, https://github.com/giulianotesta7/AgentGuidanceHub#readme
Project-URL: Source, https://github.com/giulianotesta7/AgentGuidanceHub
Project-URL: Issues, https://github.com/giulianotesta7/AgentGuidanceHub/issues
Project-URL: Releases, https://github.com/giulianotesta7/AgentGuidanceHub/releases
Project-URL: Container, https://github.com/giulianotesta7/AgentGuidanceHub/pkgs/container/agent-guidance-hub
Keywords: agent-tools,ai-agents,cli,coding-agents,developer-tools,fastapi,self-hosted
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.27
Dynamic: license-file

<div align="center">

# Agent Guidance Hub (AGH)

<p><strong>Self-hosted guidance distribution for coding agents.</strong></p>

<p>
  <a href="https://pypi.org/project/agh/"><img alt="PyPI" src="https://img.shields.io/pypi/v/agh?color=1f6feb"></a>
  <a href="https://github.com/giulianotesta7/AgentGuidanceHub/pkgs/container/agent-guidance-hub"><img alt="GHCR" src="https://img.shields.io/badge/ghcr-agent--guidance--hub-1f6feb"></a>
  <a href="https://github.com/giulianotesta7/AgentGuidanceHub/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/giulianotesta7/AgentGuidanceHub/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/giulianotesta7/AgentGuidanceHub/releases"><img alt="Release" src="https://img.shields.io/github/v/release/giulianotesta7/AgentGuidanceHub"></a>
</p>

<p>
  <a href="#install">install</a> · <a href="#quick-start">quick start</a> · <a href="#how-agh-works">how it works</a> · <a href="#server-operations">server ops</a> · <a href="#development">development</a> · <a href="README.es.md">español</a>
</p>

</div>

[Español](README.es.md)

---

![AGH workspace pull demo](assets/agh-workspace-demo.gif)

**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:

```bash
brew install giulianotesta7/tap/agh
```

Windows (Scoop):

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

or with the install script:

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

Check the CLI:

```bash
agh --help
```

Run the server with the published Docker image:

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

The default Compose image is:

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

Pin production deployments with a release tag:

```bash
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](#clean-break).

Read the first owner token on the host running AGH:

```bash
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:

```bash
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:

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

Work from a linked repo:

```bash
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

| Command | What it does |
|---------|--------------|
| `agh login --email EMAIL --token TOKEN` | Validate credentials for the configured instance. |
| `agh whoami` | Show the authenticated user. |
| `agh logout` | Clear stored credentials. |
| `agh config [set URL] [clear]` | Show, set, or clear the instance URL. |
| `agh user ...` | Manage users: `list`, `create`, `describe`, `update`, `activate`, `deactivate`, `token rotate`. |
| `agh project ...` | Manage projects: `list`, `create`, `describe`, `update`, `activate`, `deactivate`, `member add/list/remove`. |
| `agh project skill ...` | Manage exact project skill assignments: `list`, `add`, `remove`, `upgrade`. |
| `agh project instructions ...` | Manage the canonical project instructions: `describe`, `upload`, `clear`. |
| `agh skill publish [PATH]` | Publish a skill directory or `.zip` (default: `.`). |
| `agh skill search [QUERY]` | Search the registry skill catalog. |
| `agh skill describe NAME` | Describe one registry skill. |
| `agh skill update NAME` | Update skill access or tags. |
| `agh skill archive NAME` / `disable NAME` / `enable NAME` | Manage the skill lifecycle. |
| `agh skill list` | List locally installed global skills. |
| `agh skill install NAME` | Install a registry skill into the selected target. |
| `agh skill upgrade [NAME]` | Upgrade installed global skills to the newest release. |
| `agh skill uninstall NAME` | Uninstall an installed global skill. |
| `agh target [set agents\|claude] [clear]` | Manage the local or global target. |
| `agh link` | Link this git repository to its matching AGH project. |
| `agh pull [--dry-run] [--force]` | Pull assigned project guidance into the linked repository. |

## How AGH works

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

| Piece | What it does |
|-------|--------------|
| Skills | Registry units with immutable releases. A release is an expanded skill directory. |
| Projects | One git repository plus the exact skill releases it should use. |
| Workspaces | A local repo linked with `agh link`, one selected target, and a committed lockfile. |

<details>
<summary><strong>Skill directory structure</strong></summary>

A skill is a directory with a root `SKILL.md` and optional files under `references/`, `scripts/`, or `assets/`:

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

`SKILL.md` follows the Agent Skills format: a `name`, a `description`, and a
required `metadata.version`. Versions are opaque strings, never parsed or
compared. **Immutable releases**: every publication adds a new release;
existing releases never change. Publish a new version for changes.

</details>

## Server operations

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

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

| Setting | Default |
|---------|---------|
| `AGH_DATA_DIR` | `/data` in the image, `.agh-data` locally |
| HTTP port | `8912` |
| Bootstrap owner email | `AGH_BOOTSTRAP_OWNER_EMAIL` |
| Health endpoint | `GET /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`:

| Path | Purpose |
|------|---------|
| `/data/agh.sqlite3` | SQLite database. |
| `/data/skills/` | Expanded skill release trees (`/data/skills/releases/<release-id>/`). |
| `/data/staging/` | Transient publication staging (`/data/staging/publications/<nonce>/`). |
| `/data/secrets/initial_owner_token` | First owner token, created once. |

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:

```text
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](#server-operations).

## Development

```bash
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](CONTRIBUTING.md)
- [Security](SECURITY.md)
