limiteinductive
75864eaf3d
- colony ssh — runs gcloud compute ssh under the hood - Removed scripts/ssh-vm.sh (bash scripts bad, Rust CLI good) - CLAUDE.md: "Avoid bash scripts — put commands in the Rust CLI instead" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Is
|
|
|
|
`apes` is a post-singularity research platform. No SaaS. Everything vibecoded. Self-hosted on GCP.
|
|
|
|
**Research goal:** Prove that RL training an LLM on formal games (Game of Life, Chess, Go) transfers to general capabilities/benchmarks.
|
|
|
|
**Team:** Benji and Neeraj (the apes). Claude Code agents are first-class collaborators.
|
|
|
|
## Infrastructure
|
|
|
|
| Service | URL | VM | Zone |
|
|
|---------|-----|----|----|
|
|
| Gitea | git.unslope.com | gitea-vm | europe-west1-b |
|
|
| Colony | apes.unslope.com | colony-vm | europe-west1-b |
|
|
|
|
**GCP project:** `apes-platform`
|
|
**Region:** `europe-west1`
|
|
**DNS:** Namecheap (Advanced DNS tab for A records)
|
|
|
|
## Non-Negotiable Rules
|
|
|
|
- **Apes don't do tasks.** Users of this repo are apes. Never ask them to do something you can do yourself. DNS config, API calls, server setup, debugging — handle it. If it requires a browser or a password the ape hasn't shared, explain what you need and why, but never punt work back to the ape when you have the tools to do it.
|
|
- **No SaaS.** If we can't self-host it, we don't use it.
|
|
- **Vibecoded.** Humans direct, agents build. Move fast, verify correctness.
|
|
- **GCP project is `apes-platform`.** Always pass `--project=apes-platform`.
|
|
- **Region is `europe-west1`.** Zone `europe-west1-b` unless there's a reason to change.
|
|
- **No split brains.** If two pieces of code represent the same thing, one must derive from the other. DB models and API types are separate Rust layers, but API types are the single source for the wire format. TypeScript types are generated from API types via `ts-rs`. SQL migrations are canonical for the DB. Never hand-write a type that can be derived.
|
|
- **Rust first.** Backend code is Rust. Type safety everywhere. If it compiles, it should work. Avoid bash scripts — put commands in the Rust CLI instead.
|
|
- **Always push.** After committing, push to origin immediately. Never ask the ape "should I push?" — just do it. Handle auth, firewall, DNS issues yourself.
|
|
- **Document decisions.** When discussing architecture, features, or design with apes, write the spec to `docs/` as a markdown file. Conversations are ephemeral, docs persist.
|
|
|
|
## Route By Task
|
|
|
|
| Need | Load |
|
|
|------|------|
|
|
| GCP commands | `/gcloud` skill |
|
|
| Stress-test a decision | `/critic` skill |
|
|
| Audit agent config quality | `/ax` skill |
|
|
| Frontend/UI work | `/frontend-design` skill (auto-loaded for `ui/**` files) |
|
|
|
|
## Git (Gitea)
|
|
|
|
**URL:** https://git.unslope.com
|
|
**Repo:** `benji/apes`
|
|
**API:** `https://git.unslope.com/api/v1/`
|
|
|
|
| User | Role |
|
|
|------|------|
|
|
| benji | admin |
|
|
| neeraj | collaborator |
|
|
|
|
```bash
|
|
# Clone (HTTP on port 3000 — no gcloud needed, works for everyone)
|
|
git clone http://git.unslope.com:3000/benji/apes.git
|
|
|
|
# Push uses same port. Auth via URL or token:
|
|
git remote set-url origin http://<user>:<token>@git.unslope.com:3000/benji/apes.git
|
|
|
|
# Create API token:
|
|
curl -u user:pass -X POST https://git.unslope.com/api/v1/users/<user>/tokens \
|
|
-H 'Content-Type: application/json' -d '{"name":"cc","scopes":["all"]}'
|
|
|
|
# If DNS fails, use IP directly: http://34.78.255.104:3000/benji/apes.git
|
|
```
|
|
|
|
**Web UI** at `https://git.unslope.com` (HTTPS via Caddy). **Git push/pull** on `http://git.unslope.com:3000` (direct to Gitea).
|
|
|
|
## Deployment Pattern
|
|
|
|
All services run as Docker Compose on GCP Compute Engine VMs behind Caddy (auto HTTPS via Let's Encrypt).
|
|
|
|
```bash
|
|
# SSH into a VM
|
|
gcloud compute ssh <vm> --zone=europe-west1-b --project=apes-platform
|
|
|
|
# Manage services
|
|
sudo bash -c 'cd /opt/<service> && docker compose up -d'
|
|
sudo docker logs <container> --tail 50
|
|
```
|
|
|
|
## Colony CLI
|
|
|
|
Two binaries for interacting with Ape Colony:
|
|
|
|
| Binary | Purpose |
|
|
|--------|---------|
|
|
| `colony` | Chat client — read, post, channels, inbox, ack |
|
|
| `colony-agent` | Agent runtime — worker, dream, birth |
|
|
|
|
```bash
|
|
# Chat
|
|
colony init --api-url https://apes.unslope.com --user benji
|
|
colony channels
|
|
colony read general --json
|
|
colony post general "hello" --type text
|
|
colony inbox --json
|
|
colony ack 1 2 --quiet
|
|
|
|
# Agent lifecycle
|
|
colony-agent birth scout --instruction "help with research"
|
|
colony-agent worker # start pulse+react loop
|
|
colony-agent dream # run memory consolidation
|
|
colony-agent pulse # one-shot pulse for testing
|
|
```
|
|
|
|
Crates: `crates/colony-cli/`, `crates/colony-agent/`
|
|
Spec: `docs/tech-spec-colony-cli-2026-03-29.md`
|
|
|
|
## Critic Reflex
|
|
|
|
When something is surprising, contradictory, or your confidence is low, use the `/critic` skill before proceeding. Good triggers: vibecoded code behaving unexpectedly, multiple valid architectures, research methodology questions.
|