# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Environment

Ubuntu 24.04 LTS, ARM64 (Oracle Cloud VPS). This is the home directory of an AI agent named **Pipo**, serving user **Ignacio/Chicho**.

- Node.js v22, npm 10, Python 3.12, Git 2.43, Bitwarden CLI, Tailscale
- Tailscale IP: `100.87.116.90`, hostname: `miopenclaw-vnic.tail9799d2.ts.net`

## Key Directories

| Path | Purpose |
|------|---------|
| `~/.openclaw/workspace/` | Main agent workspace (canonical) |
| `~/openclaw-workspace/` | Secondary git repo with project artifacts |
| `~/.openclaw/openclaw.json` | OpenClaw platform config (gateway, channels, skills) |
| `~/.bw/` | Bitwarden session token |

## Shell Helpers (from `~/.bash_aliases`)

```bash
bw-sync           # Load saved Bitwarden session
bw-unlock         # Unlock vault and save session
g "prompt"        # Gemini CLI wrapper
c "prompt"        # Codex safe mode (read-only, no internet)
cn "prompt"       # Codex network mode (full access)
pipo-deploy <port> [name]   # Expose port to Tailscale at /preview/<name>/
pipo-undeploy <name>        # Remove Tailscale preview route
pj                # Job controller (~/.openclaw/workspace/ops/cli-jobs/jobctl.sh)
```

## Critical Constraints

**OpenClaw gateway** (port 18789): NEVER run `openclaw gateway stop/start/restart`. It is managed by the Gemini CLI process. Restarting it severs the agent's own connection.

**Chromium browser tool**: ALWAYS use profile `openclaw` (connected to headless Chromium on port 9222). NEVER use profile `chrome` — that profile requires a manual extension that does not exist on this VPS.

**Tailscale serve**: Port 443 root (`/`) is reserved for the OpenClaw dashboard. Use preview ports 3001–3010 for apps and expose them via `pipo-deploy`.

## Deployment Pattern

1. Start your app on a port in range 3001–3010
2. Run `pipo-deploy <port> <name>`
3. App is accessible at `https://miopenclaw-vnic.tail9799d2.ts.net/preview/<name>/`

## Agent Workspace Structure (`~/.openclaw/workspace/`)

- `SOUL.md` / `AGENTS.md` — agent persona and session protocol
- `MEMORIES.md` — long-term curated memory (canonical; `MEMORY.md` is a compat alias)
- `memory/YYYY-MM-DD.md` — daily session logs
- `HEARTBEAT.md` — periodic task checklist (empty = skip heartbeat)
- `skills/` — installed agent skills (bitwarden, openclaw-bitwarden, parallel-preview-orchestrator)
- `ops/` — operational scripts (cli-jobs, docker-cli-stack)
- `node_modules/` — Playwright installed here

## Secrets

Retrieved from Bitwarden vault. After `bw-sync`, use:
```bash
bw get username "item-name"
bw get password "item-name"
```

API keys (Gemini, OpenAI/Codex, GitHub) are auto-loaded from `~/.openclaw/openclaw.json` into the shell environment via `~/.bash_aliases`.