# Using AI Coding Assistants

If you use an AI coding assistant — Claude Code, GitHub Copilot, Cursor, or similar — this page gives it static context about your CompactHive environment via a `CLAUDE.md`/`AGENTS.md`-style file in your repo.

**Prefer a live connection instead of a static file?** See **Connect Your AI Agent** for the MCP server — it lets a supported agent query your actual tenant (apps, services, build status, logs) instead of you keeping a file like this up to date by hand. Both approaches work; use whichever fits your workflow.

## Template
For the live MCP + Git workflow, use one CompactHive token from Settings → Agent
access, with Read + deploy + push code. Follow **Connect Your AI Agent** for local
credential setup; never paste the token into chat or an instructions file.


Create a `CLAUDE.md` (or `AGENTS.md`) in your project root:

```markdown
# Project Infrastructure (CompactHive)

## Environment
- Platform: CompactHive (self-hosted managed infra)
- Tier: Basic / Team / Pro / Business / Enterprise
- Slug: YOUR_SLUG

## URLs
- Portal: https://app.compacthive.io
- CI/CD: https://YOUR_SLUG-ci.compacthive.dev
- App URL pattern: https://YOUR_SLUG-APP_NAME.compacthive.dev
- Registry: registry.compacthive.dev

## Git provider
- Forgejo (built-in, default) or GitHub (beta — manual connect + Settings "Set Up" for CI).

## CI/CD
- Engine: Woodpecker CI (Kubernetes backend)
- Pipeline file: .woodpecker.yaml
- Build: Kaniko (daemonless, no Docker daemon)
- Registry auth: auto-injected Woodpecker secrets (registry_url, registry_user, registry_password)

## Database
- Engine: PostgreSQL 17 (CNPG operator)
- Host: pg-<tenant-id>-rw.NAMESPACE.svc.cluster.local, port 5432
- Connection string: see portal Connect or Developer Guide page

## Deploying apps
1. Push to Forgejo (or a connected GitHub repo, beta) — Woodpecker + Kaniko builds the image.
2. Image goes to registry.compacthive.dev/PROJECT/REPO:TAG.
3. Deploy via the portal Apps page or POST /api/portal/apps.
4. URL: https://YOUR_SLUG-APP_NAME.compacthive.dev

## Key constraints
- Kubernetes namespace isolation — no cluster-admin access.
- ResourceQuota limits CPU/memory/storage per tier; app count is capped per tier too.
- No Docker daemon in CI — use Kaniko, not `docker build`.
- TLS is terminated at the edge; apps receive plain HTTP on their configured port.

## Documentation
- https://docs.compacthive.io
```

## Giving an assistant task-specific context

| Task | What to tell the assistant |
|---|---|
| Write a Dockerfile | Target amd64/arm64, keep the image small, `EXPOSE` the right port |
| Write a CI pipeline | Engine Woodpecker, builder Kaniko (`--insecure`, registry secrets via `from_secret`) — see **CI/CD Pipelines** |
| Connect to the database | Host `pg-<tenant-id>-rw`, standard PostgreSQL driver, connection string from the Connect page |
| Debug a deployment | Check the portal Resources page for pod status, and the Logs viewer for app logs |
| Set up monitoring | Grafana at `YOUR_SLUG-grafana.compacthive.dev` (Monitoring service); Prometheus scrapes your pods automatically once Monitoring is enabled |