Developing with Claude

Run AI coding agents safely on your own machine — where the Git repository is the memory, not the chat history.

---

How it works

flowchart TB
    subgraph host["Your Machine"]
        secrets["Secrets and Keys"]
        folders["Workspace Folders"]
    end

    subgraph container["Bounded Container — Agents Work Here"]
        claude["Claude Code"]
        codex["Codex CLI"]
        gemini["Gemini CLI"]
    end

    subgraph repo["Git Repository — The Persistent Memory"]
        rules["Rules"]
        state["State Docs"]
        tools["Scripts"]
    end

    folders -->|mounts into| container
    container <-->|reads before acting / writes when done| repo
    secrets -.->|stays on host — never enters container| host

The container is bounded and disposable. The repository is permanent. Agents read the repo before every session — not the chat history — so context survives restarts, rebuilds, and parallel sessions.

---

Why this exists

Most AI-assisted development setups share the same failure mode: context lives in chat history. The session ends, the context is gone. The next session starts blind.

This guide describes a different model:

• The Git repo is the operating memory — rules, state, decisions, and handoff notes all live in version-controlled Markdown
• The Docker container is a bounded workspace — agents can see what is mounted, not the whole machine
• Secrets stay on the host — never in the repo, never in the container
• Production actions stay with the operator — the container is powerful within its boundary; it does not have unlimited reach

Works on a laptop with no GPU, no VPN, no server. Grows as far as you want to take it.

---

What's in this guide

Document	What it covers
GETTING-STARTED.md	Step-by-step: discover your machine, design your setup, build the baseline, orient Claude to current tooling

---

The five-minute version

1. Discover your machine — paste the discovery prompt from GETTING-STARTED.md into Claude. Get a machine-discovery.md report.

2. Design your setup — paste the design prompt with your discovery report into Claude Opus. Get a setup plan tailored to your hardware.

3. Build the baseline — workspace root, subfolders, Git repo, Docker container, Claude Code authenticated. Nothing more until it works.

4. Orient Claude — fetch current Anthropic docs and store them in the repo. Force Claude to read before it writes. Training data is frozen; the docs are not.

5. Grow deliberately — add layers only when you have a real reason.

---

Where it grows

flowchart LR
    A["Laptop<br/>Docker + Claude Code"]
    B["VPS<br/>Git hosting + VPN"]
    C["Home Server<br/>Local AI + Ollama"]
    D["Mobile<br/>Remote operator access"]

    A -->|stable baseline| B
    B -->|stable infrastructure| C
    C -->|stable local AI| D

Each stage is independent. None requires the next. Most of the value is in stage one.

---

Core principles

The repo is the memory. Everything important lives in Git. Agents read it before acting. Nothing is lost when a session ends.

Secrets stay on the host. API keys, SSH keys, tokens — never in the repo, never in the container. Passed in at runtime.

Production actions stay with the operator. Ansible runs, SSH, DNS changes — your terminal, not the container. You are always the gate.

Persistence is designed, not assumed. Named Docker volumes for agent auth. A bootstrap script to verify state after rebuilds. Nothing relies on the container surviving.

Start simple. Grow deliberately. Laptop first. Server when you need one. Local AI when the hardware justifies it.

---

Getting started

→ Read GETTING-STARTED.md

---

Licensed under CC BY 4.0