# 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
```mermaid
flowchart LR
host["Your Machine
Secrets and workspace folders"]
container["Bounded Container
Claude Code, Codex, Gemini"]
repo["Git Repository
Rules, state docs, scripts"]
host -->|mounts into| container
container -->|reads and writes| repo
```
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](./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
```mermaid
flowchart LR
A["Laptop
Docker + Claude Code"]
B["VPS
Git hosting + VPN"]
C["Home Server
Local AI + Ollama"]
D["Mobile
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](./GETTING-STARTED.md)**
---
Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)