|
1 | | -This file provides guidance to coding agents working in this repository. |
2 | | - |
3 | | -## What This Repo Is |
4 | | - |
5 | | -`deva.sh` is a Docker-based multi-agent launcher for: |
6 | | - |
7 | | -- OpenAI Codex |
8 | | -- Claude Code |
9 | | -- Google Gemini CLI |
10 | | - |
11 | | -The container is the sandbox. Agent-level permission theater is not. |
12 | | - |
13 | | -That is the core design. Do not "improve" it by moving trust back into |
14 | | -interactive prompt confirmations. |
15 | | - |
16 | | -## Workflow Rules |
17 | | - |
18 | | -We use issue-based development. |
19 | | - |
20 | | -1. Before any Git or GitHub CLI command, read the matching file in |
21 | | - `workflows/`: |
22 | | - - `GITHUB-ISSUE.md` |
23 | | - - `GIT-COMMIT.md` |
24 | | - - `GITHUB-PR.md` |
25 | | - - `RELEASE.md` |
26 | | -2. Keep one branch per issue when practical. |
27 | | -3. PRs should reference and close the relevant issue. |
28 | | - |
29 | | -## Release Rules |
30 | | - |
31 | | -Release workflow lives in `workflows/RELEASE.md`. |
32 | | - |
33 | | -Current release source of truth: |
34 | | - |
35 | | -- version comes from `deva.sh` |
36 | | -- changelog comes from `CHANGELOG.md` |
37 | | -- images are published by GitHub Actions |
38 | | - |
39 | | -Do not use `claude.sh` as the version source. That is old baggage. |
40 | | - |
41 | | -## Project Structure |
42 | | - |
43 | | -```text |
44 | | -deva/ |
45 | | -├── deva.sh |
46 | | -├── claude.sh |
47 | | -├── claude-yolo |
48 | | -├── agents/ |
49 | | -├── Dockerfile |
50 | | -├── Dockerfile.rust |
51 | | -├── docker-entrypoint.sh |
52 | | -├── install.sh |
53 | | -├── .deva.example |
54 | | -├── examples/ |
55 | | -├── docs/ |
56 | | -├── .github/workflows/ |
57 | | -├── workflows/ |
58 | | -├── CHANGELOG.md |
59 | | -├── DEV-LOGS.md |
60 | | -└── AGENTS.md |
61 | | -``` |
62 | | - |
63 | | -Important current roles: |
64 | | - |
65 | | -- `deva.sh`: primary entrypoint and container lifecycle manager |
66 | | -- `agents/*.sh`: agent-specific auth and command wiring |
67 | | -- `install.sh`: one-line installer |
68 | | -- `.github/workflows/ci.yml`: lint, docs, and smoke coverage |
69 | | -- `.github/workflows/release.yml`: tagged image + release flow |
70 | | -- `.github/workflows/nightly-images.yml`: scheduled nightly image refresh |
71 | | - |
72 | | -Legacy compatibility wrappers still exist: |
73 | | - |
74 | | -- `claude.sh` |
75 | | -- `claude-yolo` |
76 | | - |
77 | | -They are compatibility shims, not primary branding. |
78 | | - |
79 | | -## Security Model |
80 | | - |
81 | | -Deva runs agent CLIs inside Docker and disables their built-in permission |
82 | | -prompts: |
83 | | - |
84 | | -- Claude: `--dangerously-skip-permissions` |
85 | | -- Gemini: `--yolo` |
86 | | -- Codex: unrestricted mode equivalent |
87 | | - |
88 | | -That is deliberate. |
89 | | - |
90 | | -The security boundary is: |
91 | | - |
92 | | -- the container |
93 | | -- the exact mounts and env vars we pass into it |
94 | | - |
95 | | -So the real risks are the host bridges we expose: |
96 | | - |
97 | | -- mounted workspace paths |
98 | | -- mounted auth files |
99 | | -- `/var/run/docker.sock` |
100 | | -- `--host-net` |
101 | | -- tmux bridge tooling |
102 | | - |
103 | | -Do not document or implement this as if the agent sandbox is protecting the |
104 | | -host. It is not. |
105 | | - |
106 | | -## Auth And Config Model |
107 | | - |
108 | | -Deva supports multiple auth modes per agent. |
109 | | - |
110 | | -Current design: |
111 | | - |
112 | | -- default config root is `~/.config/deva` |
113 | | -- per-agent homes live under that root |
114 | | -- `--config-home` isolates auth state |
115 | | -- `-Q` means bare mode: no config loading, no autolink, no host auth mounts |
116 | | -- non-default auth overlays default credential paths instead of moving live |
117 | | - host files around |
118 | | - |
119 | | -If you touch auth code, verify real `--dry-run` output and one live path. |
120 | | -Auth bugs are usually mount bugs wearing a fake auth moustache. |
121 | | - |
122 | | -## Container Model |
123 | | - |
124 | | -Persistent containers are keyed by workspace plus container shape. |
125 | | - |
126 | | -Shape includes things like: |
127 | | - |
128 | | -- selected agent |
129 | | -- extra volumes |
130 | | -- explicit config home |
131 | | -- auth mode |
132 | | - |
133 | | -So it is not "one container per repo" in the naive sense. Different shapes |
134 | | -must not collide. |
135 | | - |
136 | | -For clean repros and CI smoke tests, use: |
137 | | - |
138 | | -```bash |
139 | | -deva.sh claude -Q -- --version |
140 | | -deva.sh codex -Q -- --version |
141 | | -deva.sh gemini -Q -- --version |
142 | | -``` |
143 | | - |
144 | | -Non-interactive launch paths must work without a TTY. |
145 | | - |
146 | | -## Common Checks |
147 | | - |
148 | | -Run these before claiming things work: |
149 | | - |
150 | | -```bash |
151 | | -./deva.sh --help |
152 | | -./deva.sh --version |
153 | | -./claude-yolo --help |
154 | | -./scripts/version-check.sh |
155 | | -``` |
156 | | - |
157 | | -If you changed container launch, mounts, auth, or the installer, also run: |
158 | | - |
159 | | -```bash |
160 | | -./deva.sh claude --debug --dry-run |
161 | | -./deva.sh claude -Q -- --version |
162 | | -./deva.sh codex -Q -- --version |
163 | | -./deva.sh gemini -Q -- --version |
164 | | -``` |
165 | | - |
166 | | -If you changed docs site plumbing, also run: |
167 | | - |
168 | | -```bash |
169 | | -mkdocs build --strict |
170 | | -``` |
171 | | - |
172 | | -## Bridges |
173 | | - |
174 | | -Bridges are deliberate holes from container back to host. |
175 | | - |
176 | | -Current ones: |
177 | | - |
178 | | -- Docker socket mount |
179 | | -- tmux bridge |
180 | | - |
181 | | -Treat bridge changes as security-sensitive. They change the real trust |
182 | | -boundary, not some fake marketing boundary. |
183 | | - |
184 | | -## Documentation Rules |
185 | | - |
186 | | -Public copy should say `deva.sh` first. |
187 | | - |
188 | | -Allowed: |
189 | | - |
190 | | -- mention `claude.sh` / `claude-yolo` as compatibility wrappers |
191 | | -- historical notes in changelog/dev logs |
192 | | - |
193 | | -Not allowed: |
194 | | - |
195 | | -- presenting the project as Claude-only |
196 | | -- using `claude.sh` as the primary interface in current docs |
197 | | -- leaving stale release or workflow prompts centered on old naming |
198 | | - |
199 | | -## Issue Hygiene |
200 | | - |
201 | | -Do not use the issue queue as a mirror of every upstream vendor changelog. |
202 | | - |
203 | | -If upstream version tracking is automated, close the old noise and keep the |
204 | | -real issue queue for: |
205 | | - |
206 | | -- bugs in deva |
207 | | -- missing features in deva |
208 | | -- docs gaps in deva |
209 | | -- concrete release/process work in deva |
| 1 | +@./.claude/CLAUDE.md |
| 2 | +@./CLAUDE.md |
| 3 | + |
| 4 | +<!-- deva:container-context --> |
| 5 | +# Container Environment (deva) |
| 6 | + |
| 7 | +You are inside a Docker container running Ubuntu Linux 24.04 LTS |
| 8 | +(Noble Numbat), not on the host machine. The workspace is a |
| 9 | +bind-mount from the host at the same absolute path, but the |
| 10 | +runtime is Linux. |
| 11 | + |
| 12 | +- This is Linux. Host-only tools (open, pbcopy, pbpaste, sw_vers, |
| 13 | + diskutil, defaults, launchctl) are not available. |
| 14 | +- No display server. Browsers and GUI tools will not work. |
| 15 | +- Hard links (`ln` without -s) fail across mount boundaries. |
| 16 | + Use `cp` or relative symbolic links (`ln -sr`). |
| 17 | +- Prefer relative paths for project-internal references. |
| 18 | + Absolute paths work here but are container-specific. |
| 19 | +- $HOME is /home/deva (not /root). sudo works without password. |
| 20 | +- Pre-installed: Node.js, Python (use `uv`, not pip), Go, git, |
| 21 | + gh, make, curl. pip is NOT in PATH. |
| 22 | +- Docker is available (socket mounted from host). |
| 23 | +- System packages and build caches persist across sessions. |
| 24 | +- Container details are in DEVA_* environment variables. |
| 25 | +<!-- /deva:container-context --> |
0 commit comments