Metadata-Version: 2.4
Name: agh
Version: 0.1.0
Summary: Agent Guidance Hub
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.27

<div align="center">

# Agent Guidance Hub (AGH)

<p><strong>Self-hosted agent instructions and skills, synced per repo.</strong></p>

</div>

---

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

## What AGH is for

AGH gives teams one place to publish the instructions and reusable skills their coding agents use in repos: `AGENTS.md`, `CLAUDE.md`, and skill files placed under agent harness directories.

Without AGH, those files tend to drift from repo to repo. With AGH, you publish a versioned pack, assign it to a project, and apply the assigned files in each repo.

```text
AGH Docker service
  ├─ /data/agh.sqlite3
  ├─ /data/packs/
  ├─ /data/logs/agh.log
  └─ /data/secrets/initial_owner_token
        ↓ manifest + pack downloads
repository
  ├─ AGENTS.md / CLAUDE.md
  ├─ .claude/skills/.../SKILL.md
  ├─ .opencode/skills/.../SKILL.md
  └─ .agh/lock.toml
```

## Quick Start

Run the server with Docker:

```bash
docker build -t agh .
docker run --rm -p 8912:8912 -v agh-data:/data \
  -e AGH_BOOTSTRAP_OWNER_EMAIL=owner@example.com \
  agh
```

Install the local CLI, then log in with the first owner token:

```bash
uv tool install --force .

agh login \
  --url http://127.0.0.1:8912 \
  --email owner@example.com \
  --token "$(docker run --rm -v agh-data:/data busybox cat /data/secrets/initial_owner_token)"
```

Then work from a repo:

```bash
agh sync
agh pull --dry-run
agh pull
agh agent
```

## Docs

| Guide | Use it for |
|-------|------------|
| [Installation](docs/installation.md) | Install the local `agh` CLI and run the Docker server. |
| [Quickstart](docs/quickstart.md) | First Docker run, login, project link, and workspace apply flow. |
| [Packs](docs/packs.md) | Create, publish, and list instruction/skill packs. |
| [Projects](docs/projects.md) | Create projects and assign packs to repos. |
| [Admin](docs/admin.md) | Bootstrap owner, users, roles, tokens, and local config. |
| [Workspace guide](docs/workspace.md) | Repo setup, workspace apply behavior, markers, skills, lockfile, and Git rules. |
| [Operations](docs/operations.md) | Docker runtime layout, `/data`, logs, healthcheck, backup, and upgrades. |

## Core Concepts

| Concept | Meaning |
|---------|---------|
| Pack | Versioned set of instruction files and agent skills. |
| Project | AGH record linked to a git repository. |
| Pull manifest | Server plan for the files a repo should download and apply. |
| Lockfile | `.agh/lock.toml`; resolved versions, checksums, sources, and placement mode. |
| Cache | `.agh-cache/packs/`; downloaded pack files that AGH can rebuild. |

## Git Rule

Commit the stable project state:

- `.agh/project.toml`
- `.agh/lock.toml`
- `AGENTS.md` / `CLAUDE.md`

Ignore the cache:

```gitignore
.agh-cache/
```

Skill targets under `.claude/skills/` and `.opencode/skills/` are generated by the workspace pull flow. Commit them only if your team wants agent skills reviewed in Git. If they are symlinks, refresh the workspace after clone to rebuild `.agh-cache/packs/`.

## Development

```bash
uv sync
uv run pytest
```

For local server work without Docker, see [Operations](docs/operations.md#local-development).
