no-more-configs 1.3.1 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +676 -22
- package/package.json +29 -5
package/README.md
CHANGED
|
@@ -1,44 +1,698 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# NO MORE CONFIGS
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**A clone-and-go VS Code devcontainer built for Claude Code. Codex CLI included as an optional second agent.**
|
|
6
|
+
|
|
7
|
+
**Install. Open. Code.**
|
|
8
|
+
|
|
9
|
+
**Free, transparent, and fully customizable. No subscription walls, no black-box abstractions — just a devcontainer you own and control. For developers who'd rather read the source than trust the vendor.**
|
|
10
|
+
|
|
11
|
+
[](https://github.com/agomusio/no-more-configs)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
[](https://github.com/agomusio/no-more-configs/releases/latest)
|
|
14
|
+
[](https://www.npmjs.com/package/no-more-configs)
|
|
15
|
+
|
|
16
|
+
<br>
|
|
17
|
+
|
|
18
|
+
<pre>npx no-more-configs@latest</pre>
|
|
19
|
+
|
|
20
|
+
**Works on Windows (WSL2 + Docker Desktop) and Linux (Docker Engine).**
|
|
21
|
+
**Linux is significantly faster** — Docker Engine runs containers natively without the WSL2 virtualization layer that Docker Desktop requires on Windows.
|
|
22
|
+
macOS is untested — if you try it, [open an issue](https://github.com/agomusio/no-more-configs/issues) and let me know how it goes!
|
|
23
|
+
|
|
24
|
+
<br>
|
|
25
|
+
|
|
26
|
+
_"I spent weekends configuring Claude, Docker, and everything else — now you don't have to."_
|
|
27
|
+
|
|
28
|
+
<br>
|
|
29
|
+
|
|
30
|
+
[What You Get](#what-you-get) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Plugin System](#plugin-system) · [Agent Config](#agent-config)
|
|
31
|
+
<br>
|
|
32
|
+
[Architecture](#architecture) · [Firewall](#firewall) · [MCP Servers](#mcp-servers) · [GSD Framework](#gsd-framework) · [Langfuse Tracing](#langfuse-tracing)
|
|
33
|
+
<br>
|
|
34
|
+
[Shell Shortcuts](#shell-shortcuts) · [Project Structure](#project-structure) · [Customization](#customization) · [Troubleshooting](#troubleshooting) · [Known Issues](#known-issues)
|
|
35
|
+
|
|
36
|
+
</div>
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
<pre>
|
|
40
|
+
| You Container |
|
|
41
|
+
| │ ├── Claude Code CLI + Codex CLI |
|
|
42
|
+
| ├── config.json ──────────► ├── Firewall domains |
|
|
43
|
+
| │ (settings) ├── VS Code settings |
|
|
44
|
+
| │ ├── MCP server config |
|
|
45
|
+
| ├── secrets.json ─────────► ├── Claude + Codex auth tokens |
|
|
46
|
+
| │ (credentials) ├── Git identity |
|
|
47
|
+
| │ ├── Plugin env vars (hydrated) |
|
|
48
|
+
| ├── agent-config/plugins/ ► └── Hooks, commands, agents, skills, MCP |
|
|
49
|
+
| │ (self-registering) |
|
|
50
|
+
| └── Open in Container ────► Done. |
|
|
51
|
+
</pre>
|
|
52
|
+
</div>
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## What You Get
|
|
57
|
+
|
|
58
|
+
| Feature | Description | Status |
|
|
59
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------- |
|
|
60
|
+
| **Claude Code** | Anthropic's agentic coding CLI — Opus 4.6, high effort, permissions bypassed. **Only requires a Claude Pro/Max subscription.** | Out of the box |
|
|
61
|
+
| **Codex CLI** | OpenAI's agentic coding CLI — GPT-5.3-Codex, full-auto mode. Optional, requires separate ChatGPT Plus/Pro subscription. | Out of the box |
|
|
62
|
+
| **Plugin system** | Drop a directory with a `plugin.json` to register hooks, env vars, commands, agents, MCP servers | Out of the box |
|
|
63
|
+
| **GSD framework** | 30+ slash commands and 11 specialized agents for structured development | Out of the box |
|
|
64
|
+
| **BMAD Method** | AI-driven agile development framework — 21+ specialized agents, 50+ guided workflows (PRD, architecture, epics, QA) | Out of the box |
|
|
65
|
+
| **PostgreSQL client** | `psql` CLI for connecting to Postgres databases | Out of the box |
|
|
66
|
+
| **Bun** | JavaScript/TypeScript runtime and package manager | Out of the box |
|
|
67
|
+
| **Redis CLI** | `redis-cli` for connecting to Redis instances | Out of the box |
|
|
68
|
+
| **Opt-in SDKs** | Rust, Go, Deno — install at container start via `config.json → sdks` | Opt-in |
|
|
69
|
+
| **iptables firewall** | Default-deny network with domain whitelist (47 core domains), disable via `config.json` | Out of the box |
|
|
70
|
+
| **Oh-My-Zsh** | Powerlevel10k, fzf, git-delta, GitHub CLI | Out of the box |
|
|
71
|
+
| **Langfuse observability** | Self-hosted tracing — every conversation traced to a local dashboard | Opt-in (beta) |
|
|
72
|
+
| **MCP gateway** | Model Context Protocol tool access via Docker MCP Gateway | Opt-in (beta) |
|
|
73
|
+
| **Codex MCP server** | Let Claude delegate to Codex mid-session | Opt-in (beta) |
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Quick Start
|
|
78
|
+
|
|
79
|
+
### Prerequisites
|
|
80
|
+
|
|
81
|
+
- [Node.js](https://nodejs.org/) >= 18 (for npx)
|
|
82
|
+
- [VS Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
|
|
83
|
+
|
|
84
|
+
**Windows:**
|
|
85
|
+
|
|
86
|
+
- [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) enabled
|
|
87
|
+
- [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/) running (WSL2 backend)
|
|
88
|
+
|
|
89
|
+
**Linux:**
|
|
90
|
+
|
|
91
|
+
- [Docker Engine](https://docs.docker.com/engine/install/) with [buildx plugin](https://docs.docker.com/build/install-buildx/)
|
|
92
|
+
|
|
93
|
+
### 1. Install and Open
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npx no-more-configs@latest
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Or clone manually:
|
|
6
100
|
|
|
7
101
|
```bash
|
|
8
|
-
|
|
102
|
+
git clone https://github.com/agomusio/no-more-configs.git
|
|
103
|
+
cd no-more-configs
|
|
104
|
+
code .
|
|
9
105
|
```
|
|
10
106
|
|
|
11
|
-
|
|
107
|
+
This clones the repo, prints next steps, and tries to open VS Code automatically. You can also specify a directory: `npx no-more-configs my-workspace`.
|
|
108
|
+
|
|
109
|
+
> **Alternative:** `git clone https://github.com/agomusio/no-more-configs.git && cd no-more-configs && code .`
|
|
12
110
|
|
|
13
|
-
|
|
111
|
+
VS Code will detect the devcontainer and prompt to reopen in container. Click **Reopen in Container** (or use `Ctrl+Shift+P` → `Dev Containers: Reopen in Container`).
|
|
14
112
|
|
|
15
|
-
|
|
113
|
+
First build takes a few minutes. Subsequent opens are fast.
|
|
114
|
+
|
|
115
|
+
### 2. Authenticate
|
|
116
|
+
|
|
117
|
+
Once the container is running, authenticate Claude Code:
|
|
16
118
|
|
|
17
119
|
```bash
|
|
18
|
-
|
|
120
|
+
claude # Follow OAuth prompts (requires Claude Pro/Max subscription)
|
|
19
121
|
```
|
|
20
122
|
|
|
21
|
-
|
|
123
|
+
Optionally, authenticate Codex CLI if you have a ChatGPT Plus/Pro subscription:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
codex # Follow OAuth prompts (optional — separate subscription)
|
|
127
|
+
```
|
|
22
128
|
|
|
23
|
-
|
|
129
|
+
Set your git identity:
|
|
24
130
|
|
|
131
|
+
```bash
|
|
132
|
+
git config --global user.name "Your Name"
|
|
133
|
+
git config --global user.email "you@example.com"
|
|
25
134
|
```
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
135
|
+
|
|
136
|
+
Then capture everything so it survives container rebuilds:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
save-secrets
|
|
29
140
|
```
|
|
30
141
|
|
|
31
|
-
|
|
142
|
+
### 3. Clone Your Projects
|
|
32
143
|
|
|
33
|
-
|
|
34
|
-
- [Git](https://git-scm.com/)
|
|
35
|
-
- [VS Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
|
|
36
|
-
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows) or [Docker Engine](https://docs.docker.com/engine/install/) (Linux)
|
|
144
|
+
Your repos live in `projects/` — clone them there and register them in `config.json` so VS Code's git scanner picks them up:
|
|
37
145
|
|
|
38
|
-
|
|
146
|
+
```bash
|
|
147
|
+
cd /workspace/projects
|
|
148
|
+
git clone https://github.com/you/your-repo.git
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Then add the path to `config.json → vscode.git_scan_paths`:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{ "vscode": { "git_scan_paths": ["projects/your-repo"] } }
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Each project can have its own `CLAUDE.md` for project-specific agent instructions, and `.claude/plugins/` for project-scoped plugins that are auto-installed alongside the global ones.
|
|
158
|
+
|
|
159
|
+
### 4. Start the Langfuse Stack (Optional)
|
|
160
|
+
|
|
161
|
+
If you want conversation tracing:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
langfuse-setup
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
This generates credentials (into `secrets.json`), starts the stack, and verifies health. View traces at `http://localhost:3052`.
|
|
168
|
+
|
|
169
|
+
### 5. Done
|
|
170
|
+
|
|
171
|
+
Start coding:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
claude # Claude Code (Opus 4.6, high effort, permissions bypassed)
|
|
175
|
+
clauder # Resume a recent Claude session
|
|
176
|
+
codex # Codex CLI (GPT-5.3-Codex, full-auto mode)
|
|
177
|
+
codexr # Resume a recent Codex session
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Your projects go in `projects/`. Clone repos there and they'll be auto-detected by VS Code's git scanner.
|
|
181
|
+
|
|
182
|
+
### 5. Updating
|
|
183
|
+
|
|
184
|
+
**From the host** (outside the container):
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
npx no-more-configs@latest
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
**From inside the container:**
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
nmc-update
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Both pull the latest changes and tell you if a container rebuild is needed. The container shell also shows a notification banner when a new version is available.
|
|
197
|
+
|
|
198
|
+
## How It Works
|
|
199
|
+
|
|
200
|
+
### Two-File Configuration
|
|
201
|
+
|
|
202
|
+
Everything is driven by two files at the repo root:
|
|
203
|
+
|
|
204
|
+
**`config.json`** — non-secret settings (created by `save-config`):
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
{
|
|
208
|
+
"firewall": { "extra_domains": ["your-api.example.com"] },
|
|
209
|
+
"codex": { "model": "gpt-5.3-codex", "skip_dirs": [] },
|
|
210
|
+
"langfuse": { "host": "http://host.docker.internal:3052" },
|
|
211
|
+
"vscode": { "git_scan_paths": ["projects/my-project"] },
|
|
212
|
+
"mcp_servers": {
|
|
213
|
+
"mcp-gateway": { "enabled": false },
|
|
214
|
+
"codex": { "enabled": false, "targets": ["claude"] }
|
|
215
|
+
},
|
|
216
|
+
"plugins": { "nmc-langfuse-tracing": { "enabled": false } }
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
**`secrets.json`** (gitignored) — credentials and plugin secrets:
|
|
221
|
+
|
|
222
|
+
```json
|
|
223
|
+
{
|
|
224
|
+
"git": { "name": "Your Name", "email": "you@example.com" },
|
|
225
|
+
"claude": { "credentials": { "...auth tokens..." } },
|
|
226
|
+
"codex": { "auth": { "...oauth tokens..." } },
|
|
227
|
+
"gh": { "oauth_token": "...", "user": "...", "git_protocol": "https" },
|
|
228
|
+
"npm": { "auth_token": "npm_..." },
|
|
229
|
+
"infra": {
|
|
230
|
+
"postgres_password": "...", "encryption_key": "...", "nextauth_secret": "...",
|
|
231
|
+
"salt": "...", "clickhouse_password": "...", "minio_root_password": "...",
|
|
232
|
+
"redis_auth": "...", "langfuse_project_public_key": "...",
|
|
233
|
+
"langfuse_project_secret_key": "...", "langfuse_user_email": "...",
|
|
234
|
+
"langfuse_user_name": "...", "langfuse_user_password": "...",
|
|
235
|
+
"langfuse_org_name": "..."
|
|
236
|
+
},
|
|
237
|
+
"nmc-langfuse-tracing": { "LANGFUSE_HOST": "...", "LANGFUSE_PUBLIC_KEY": "...", "LANGFUSE_SECRET_KEY": "..." }
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
| Key | Source | Captured by |
|
|
242
|
+
| ---------------------- | ------------------------------------ | --------------------------------- |
|
|
243
|
+
| `git` | `git config --global` | `save-secrets` |
|
|
244
|
+
| `claude` | `~/.claude/.credentials.json` | `save-secrets` |
|
|
245
|
+
| `codex` | `~/.codex/auth.json` | `save-secrets` |
|
|
246
|
+
| `gh` | `~/.config/gh/hosts.yml` | `save-secrets` |
|
|
247
|
+
| `npm` | `~/.npmrc` | `save-secrets` |
|
|
248
|
+
| `infra` | `infra/.env` (Langfuse stack) | `langfuse-setup` → `save-secrets` |
|
|
249
|
+
| `nmc-langfuse-tracing` | Derived from `infra` + `config.json` | `save-secrets` |
|
|
250
|
+
|
|
251
|
+
Plugin secrets use namespaced keys (`secrets.json["plugin-name"]["TOKEN"]`). The `infra` section holds Langfuse stack infrastructure secrets. Run `langfuse-setup` to generate these automatically — `save-secrets` derives the plugin namespace from the infra keys.
|
|
252
|
+
|
|
253
|
+
On container creation, `install-agent-config.sh` reads both files, discovers plugins, hydrates `{{TOKEN}}` placeholders, and generates all runtime configuration. On container start, the firewall and MCP servers are initialized from the generated files.
|
|
254
|
+
|
|
255
|
+
> **Important:** All hooks, env vars, and functional settings must be in `settings.json`. Never use `settings.local.json` for hooks or env vars — Claude Code does not execute hooks defined there. The install script merges everything (template + plugins + GSD) into `~/.claude/settings.json`.
|
|
256
|
+
|
|
257
|
+
### Credential Persistence
|
|
258
|
+
|
|
259
|
+
```
|
|
260
|
+
authenticate Claude/Codex → set git identity → save-secrets → secrets.json → rebuild → auto-restored
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
`save-secrets` captures live Claude credentials, Codex credentials, git identity, infrastructure secrets, and derives plugin secret namespaces. The install script restores them on the next rebuild. Delete `secrets.json` to start fresh.
|
|
264
|
+
|
|
265
|
+
### Pre-configured Defaults
|
|
266
|
+
|
|
267
|
+
Both CLI agents are pre-configured for container use — no interactive prompts on subsequent starts:
|
|
268
|
+
|
|
269
|
+
| Setting | Claude Code | Codex CLI |
|
|
270
|
+
| --------------- | ------------------------------------------ | ---------------------------------------------- |
|
|
271
|
+
| **Permissions** | Bypassed (`bypassPermissions` in settings) | Bypassed (`approval_policy = "never"`) |
|
|
272
|
+
| **Model** | Opus 4.6 (high effort) | GPT-5.3-Codex (configurable via `config.json`) |
|
|
273
|
+
| **Credentials** | `~/.claude/.credentials.json` | `~/.codex/auth.json` (file-based, no keyring) |
|
|
274
|
+
| **MCP** | `~/.claude/.mcp.json` | `config.toml [mcp_servers.*]` |
|
|
275
|
+
| **Onboarding** | Skipped when credentials present | Workspace pre-trusted |
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Plugin System
|
|
280
|
+
|
|
281
|
+
Plugins are self-registering bundles discovered from `agent-config/plugins/*/plugin.json`. Each manifest can declare:
|
|
282
|
+
|
|
283
|
+
- **hooks** — registered in settings.json (multiple plugins accumulate on same events)
|
|
284
|
+
- **env** — injected with `{{TOKEN}}` placeholder hydration from `secrets.json[plugin-name][TOKEN]`
|
|
285
|
+
- **mcp_servers** — merged into `.mcp.json` with `_source` tagging for persistence
|
|
286
|
+
- **files** — skills, hooks, commands, agents copied to `~/.claude/` (skills and commands also mirrored to `~/.codex/`)
|
|
287
|
+
|
|
288
|
+
### Creating a Plugin
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
agent-config/plugins/my-plugin/
|
|
292
|
+
├── plugin.json # Manifest (required)
|
|
293
|
+
├── hooks/ # Hook scripts
|
|
294
|
+
├── commands/ # Slash commands (*.md)
|
|
295
|
+
├── agents/ # Agent definitions (*.md)
|
|
296
|
+
└── skills/ # Skills directories
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Minimal `plugin.json`:
|
|
300
|
+
|
|
301
|
+
```json
|
|
302
|
+
{
|
|
303
|
+
"name": "my-plugin",
|
|
304
|
+
"version": "1.0.0",
|
|
305
|
+
"description": "What this plugin does",
|
|
306
|
+
"hooks": {
|
|
307
|
+
"Stop": [
|
|
308
|
+
{
|
|
309
|
+
"type": "command",
|
|
310
|
+
"command": "python3 /home/node/.claude/hooks/my_hook.py"
|
|
311
|
+
}
|
|
312
|
+
]
|
|
313
|
+
},
|
|
314
|
+
"env": {
|
|
315
|
+
"MY_VAR": "value",
|
|
316
|
+
"MY_SECRET": "{{MY_SECRET}}"
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Only declare fields you use — no empty arrays needed.
|
|
322
|
+
|
|
323
|
+
### Plugin Control
|
|
324
|
+
|
|
325
|
+
Most plugins are enabled by default. Some opt-in plugins (like `nmc-langfuse-tracing`) are disabled by default. Enable or disable any plugin via `config.json`:
|
|
326
|
+
|
|
327
|
+
```json
|
|
328
|
+
{ "plugins": { "my-plugin": { "enabled": false } } }
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Override env vars via `config.json`:
|
|
332
|
+
|
|
333
|
+
```json
|
|
334
|
+
{ "plugins": { "my-plugin": { "env": { "MY_VAR": "override-value" } } } }
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
### Validation
|
|
338
|
+
|
|
339
|
+
The install script validates plugins and provides clear feedback:
|
|
340
|
+
|
|
341
|
+
- Missing hook scripts → plugin skipped with warning
|
|
342
|
+
- File conflicts between plugins → first-wins with warning
|
|
343
|
+
- Invalid `plugin.json` → friendly error + raw parse details
|
|
344
|
+
- Unresolved `{{TOKEN}}` placeholders → warning (non-fatal)
|
|
345
|
+
- All warnings recapped after install summary
|
|
346
|
+
|
|
347
|
+
### Included Plugins
|
|
348
|
+
|
|
349
|
+
| Plugin | Description |
|
|
350
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
351
|
+
| `nmc` | NMC system status command (`/nmc`) |
|
|
352
|
+
| `nmc-langfuse-tracing` | Claude Code conversation tracing to Langfuse (Stop hook + env vars) |
|
|
353
|
+
| `plugin-dev` | Plugin development guidance ([source](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev)) |
|
|
354
|
+
| `nmc-ralph-loop` | Ralph Wiggum technique for iterative, self-referential AI development loops (forked from [ralph-wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)) |
|
|
355
|
+
| `frontend-design` | Frontend design skills and patterns ([source](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design)) |
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
## Agent Config
|
|
360
|
+
|
|
361
|
+
The `agent-config/` directory is the version-controlled source of truth:
|
|
362
|
+
|
|
363
|
+
- **`settings.json.template`** — Permissions-only template (hooks and env come from plugins)
|
|
364
|
+
- **`plugins/`** — Self-registering plugin bundles with `plugin.json` manifests
|
|
365
|
+
- **`skills/`** — Standalone skills copied to `~/.claude/skills/` and `~/.codex/skills/`
|
|
366
|
+
- **`commands/`** — Standalone slash commands copied to `~/.claude/commands/` and `~/.codex/prompts/`
|
|
367
|
+
- **`mcp-templates/`** — MCP server templates (mcp-gateway, codex) with placeholder hydration
|
|
368
|
+
|
|
369
|
+
Add your own skills by creating a directory under `agent-config/skills/` with a `SKILL.md` file. They'll be installed to both Claude and Codex automatically on rebuild. Commands are also mirrored — `~/.claude/commands/` for Claude and `~/.codex/prompts/` for Codex (with Claude-specific frontmatter stripped).
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## Architecture
|
|
374
|
+
|
|
375
|
+
```
|
|
376
|
+
Host (Docker Desktop)
|
|
377
|
+
├── VS Code → Dev Container (Debian 12 Bookworm / Node 20)
|
|
378
|
+
│ ├── Claude Code + Codex CLI + plugins + GSD + BMAD
|
|
379
|
+
│ ├── Node.js, Bun, Python 3, psql, redis-cli
|
|
380
|
+
│ ├── iptables whitelist firewall
|
|
381
|
+
│ └── /var/run/docker.sock (from host)
|
|
382
|
+
│
|
|
383
|
+
└── Sidecar Stack (Docker-outside-of-Docker)
|
|
384
|
+
├── langfuse-web :3052
|
|
385
|
+
├── langfuse-worker :3030
|
|
386
|
+
├── docker-mcp-gateway :8811
|
|
387
|
+
├── postgres :5433
|
|
388
|
+
├── clickhouse :8124 (HTTP) / :9000 (native)
|
|
389
|
+
├── redis :6379
|
|
390
|
+
└── minio :9090 (API) / :9091 (console)
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
The dev container and sidecar services are sibling containers on the same Docker engine. They communicate via `host.docker.internal`.
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
## Firewall
|
|
398
|
+
|
|
399
|
+
Default policy is **DROP**. Only whitelisted domains are reachable.
|
|
400
|
+
|
|
401
|
+
To disable the firewall entirely, set `firewall.enabled` to `false` in `config.json`:
|
|
402
|
+
|
|
403
|
+
```json
|
|
404
|
+
{ "firewall": { "enabled": false } }
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Rebuild the container to apply. When disabled, all iptables rules are flushed and policies set to ACCEPT.
|
|
408
|
+
|
|
409
|
+
**Always included** (47 core domains): Anthropic API, GitHub, npm, PyPI, Debian repos, VS Code Marketplace, Azure Blob Storage (VS Code extensions), OpenAI (API + Auth + Platform + ChatGPT), Google AI API, Cloudflare, Amazon, Google Fonts, jsDelivr CDN, Vercel, and cloud Postgres providers (Supabase, Neon, Aiven dashboards — add your specific DB endpoint to `extra_domains`).
|
|
410
|
+
|
|
411
|
+
**Auto-generated**: Per-publisher VS Code extension CDN domains are derived from `devcontainer.json` so extensions install without firewall errors.
|
|
412
|
+
|
|
413
|
+
**User-configured**: Add domains to `config.json → firewall.extra_domains` — they're appended automatically on rebuild.
|
|
414
|
+
|
|
415
|
+
To temporarily allow a domain inside the container:
|
|
416
|
+
|
|
417
|
+
```bash
|
|
418
|
+
IP=$(dig +short example.com | tail -1)
|
|
419
|
+
sudo iptables -I OUTPUT -d "$IP" -j ACCEPT
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
To refresh DNS for all firewall domains without restarting:
|
|
423
|
+
|
|
424
|
+
```bash
|
|
425
|
+
sudo /usr/local/bin/refresh-firewall-dns.sh
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## MCP Servers
|
|
431
|
+
|
|
432
|
+
MCP servers come from two sources:
|
|
433
|
+
|
|
434
|
+
1. **Templates** in `agent-config/mcp-templates/`, enabled in `config.json → mcp_servers`
|
|
435
|
+
2. **Plugins** declaring `mcp_servers` in their `plugin.json` manifest
|
|
436
|
+
|
|
437
|
+
| Server | Source | Description |
|
|
438
|
+
| ------------- | -------- | ---------------------------------------------------------------------------------------- |
|
|
439
|
+
| `mcp-gateway` | Template | Docker MCP Gateway at `127.0.0.1:8811` |
|
|
440
|
+
| `codex` | Template | Codex CLI as MCP server — gives Claude access to `codex`, `review`, `listSessions` tools |
|
|
441
|
+
|
|
442
|
+
Enable a template server:
|
|
443
|
+
|
|
444
|
+
```json
|
|
445
|
+
{
|
|
446
|
+
"mcp_servers": {
|
|
447
|
+
"mcp-gateway": { "enabled": false },
|
|
448
|
+
"codex": { "enabled": true, "targets": ["claude"] }
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
### Server Targeting
|
|
454
|
+
|
|
455
|
+
By default, enabled MCP servers are configured for both Claude Code (`~/.claude/.mcp.json`) and Codex CLI (`config.toml [mcp_servers.*]`). To restrict a server to a specific agent, add `targets`:
|
|
456
|
+
|
|
457
|
+
```json
|
|
458
|
+
{ "mcp-gateway": { "enabled": true, "targets": ["codex"] } }
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
Valid targets: `"claude"`, `"codex"`. Default (when `targets` is omitted): both agents. The `codex` MCP server template should always target `["claude"]` since it would be circular for Codex to have itself as an MCP server.
|
|
462
|
+
|
|
463
|
+
Plugin MCP servers are registered automatically and persist across container restarts. The `mcp-setup` command regenerates base template servers on every container start for both agents while preserving plugin servers.
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## GSD Framework
|
|
468
|
+
|
|
469
|
+
[Get Shit Done](https://github.com/glittercowboy/get-shit-done) is a project management framework for Claude Code that breaks work into atomic tasks sized for fresh context windows, while logging everything in `.planning/` via Markdown.
|
|
470
|
+
|
|
471
|
+
**Key commands:** `/gsd:new-project`, `/gsd:plan-phase`, `/gsd:execute-phase`, `/gsd:verify-work`, `/gsd:progress`
|
|
472
|
+
|
|
473
|
+
Run `/gsd:help` inside a Claude session for the full command list.
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
## BMAD Method
|
|
478
|
+
|
|
479
|
+
[BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) (Breakthrough Method of Agile AI-driven Development) is a CLI-installable framework that provides 21+ specialized AI agents with role-based personas (PM, Architect, Developer, QA, UX Designer, etc.) and 50+ guided workflows for PRD creation, architecture design, epic/story generation, implementation, and testing.
|
|
480
|
+
|
|
481
|
+
BMAD is installed per-project into `_bmad/` and registers slash commands in `.claude/commands/`. The CLI is available globally in the container.
|
|
482
|
+
|
|
483
|
+
**Key commands:** `bmad install`, `bmad status`, `bmad list:agents`, `bmad list:expansions`
|
|
484
|
+
|
|
485
|
+
Run `/bmad-help` inside a Claude session for the full command list.
|
|
486
|
+
|
|
487
|
+
---
|
|
488
|
+
|
|
489
|
+
## Langfuse Tracing
|
|
490
|
+
|
|
491
|
+
The `nmc-langfuse-tracing` plugin traces every Claude conversation to your local Langfuse instance. It registers a Stop hook that reads transcript files, groups messages into turns, and sends structured traces with generation and tool spans.
|
|
492
|
+
|
|
493
|
+
Disabled by default. To enable, set in `config.json → plugins`:
|
|
494
|
+
|
|
495
|
+
```json
|
|
496
|
+
{ "plugins": { "nmc-langfuse-tracing": { "enabled": true } } }
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Then start the Langfuse stack and view traces at `http://localhost:3052`.
|
|
500
|
+
|
|
501
|
+
### Hook Logs
|
|
502
|
+
|
|
503
|
+
```bash
|
|
504
|
+
tail -50 ~/.claude/state/langfuse_hook.log
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
---
|
|
508
|
+
|
|
509
|
+
## Shell Shortcuts
|
|
510
|
+
|
|
511
|
+
| Command | Action |
|
|
512
|
+
| ---------------- | ----------------------------------------------------------------------- |
|
|
513
|
+
| `claude` | Claude Code — Opus 4.6, high effort, permissions bypassed |
|
|
514
|
+
| `clauder` | Alias for `claude --resume` |
|
|
515
|
+
| `codex` | Codex CLI — GPT-5.3-Codex, full-auto, no sandbox |
|
|
516
|
+
| `codexr` | Alias for `codex resume` |
|
|
517
|
+
| `save-config` | Capture settings and preferences to `config.json` |
|
|
518
|
+
| `save-secrets` | Capture live credentials, git identity, and keys to `secrets.json` |
|
|
519
|
+
| `nmc-update` | Pull latest NMC changes, detect if container rebuild is needed |
|
|
520
|
+
| `langfuse-setup` | Generate secrets, start Langfuse stack, verify health |
|
|
521
|
+
| `mcp-setup` | Regenerate MCP configs (Claude + Codex) and health-check gateway |
|
|
522
|
+
| `slc` | Show postCreate lifecycle log (`/tmp/devcontainer-logs/postCreate.log`) |
|
|
523
|
+
| `sls` | Show postStart lifecycle log (`/tmp/devcontainer-logs/postStart.log`) |
|
|
524
|
+
| `bmad` | BMAD Method CLI — install modules, check status, list agents |
|
|
525
|
+
| `psql` | PostgreSQL client CLI |
|
|
526
|
+
| `bun` | Bun runtime — JavaScript/TypeScript runtime and package manager |
|
|
527
|
+
| `redis-cli` | Redis CLI — connect to Redis instances |
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## Project Structure
|
|
532
|
+
|
|
533
|
+
```
|
|
534
|
+
/workspace/
|
|
535
|
+
├── .devcontainer/ # Container definition and lifecycle scripts
|
|
536
|
+
│ ├── Dockerfile
|
|
537
|
+
│ ├── devcontainer.json
|
|
538
|
+
│ ├── install-agent-config.sh # Master config generator (plugins, hooks, env, MCP)
|
|
539
|
+
│ ├── init-firewall.sh
|
|
540
|
+
│ └── ...
|
|
541
|
+
│
|
|
542
|
+
├── agent-config/ # Version-controlled agent config source
|
|
543
|
+
│ ├── settings.json.template # Permissions-only template
|
|
544
|
+
│ ├── plugins/ # Self-registering plugin bundles
|
|
545
|
+
│ │ ├── nmc-langfuse-tracing/ # Langfuse conversation tracing
|
|
546
|
+
│ │ ├── nmc/ # NMC system status
|
|
547
|
+
│ │ └── .../ # Your plugins here
|
|
548
|
+
│ ├── mcp-templates/ # MCP server templates (mcp-gateway, codex)
|
|
549
|
+
│ ├── skills/ # Standalone skills (Claude + Codex)
|
|
550
|
+
│ └── commands/ # Standalone slash commands
|
|
551
|
+
│
|
|
552
|
+
│
|
|
553
|
+
├── infra/ # Langfuse + MCP gateway stack
|
|
554
|
+
│ ├── docker-compose.yml
|
|
555
|
+
│ ├── data/ # Persistent bind mounts (gitignored)
|
|
556
|
+
│ └── mcp/mcp.json
|
|
557
|
+
│
|
|
558
|
+
└── projects/ # Your repos go here
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
## Customization
|
|
564
|
+
|
|
565
|
+
### Adding Firewall Domains
|
|
566
|
+
|
|
567
|
+
Edit `config.json`:
|
|
568
|
+
|
|
569
|
+
```json
|
|
570
|
+
{ "firewall": { "extra_domains": ["api.example.com", "cdn.example.com"] } }
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
Rebuild the container to apply.
|
|
574
|
+
|
|
575
|
+
### Enabling Opt-in SDKs
|
|
576
|
+
|
|
577
|
+
Edit `config.json`:
|
|
578
|
+
|
|
579
|
+
```json
|
|
580
|
+
{ "sdks": { "rust": true, "go": true, "deno": true } }
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
Rebuild the container. SDKs install during postCreate and persist for the container's lifetime.
|
|
584
|
+
|
|
585
|
+
### Changing the Codex Model
|
|
586
|
+
|
|
587
|
+
Edit `config.json`:
|
|
588
|
+
|
|
589
|
+
```json
|
|
590
|
+
{ "codex": { "model": "o4-mini" } }
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
Rebuild the container. Default is `gpt-5.3-codex`.
|
|
594
|
+
|
|
595
|
+
### Disabling Codex for Specific Projects
|
|
596
|
+
|
|
597
|
+
Project `.claude/` content (skills and commands) is automatically mirrored to Codex's global directories on rebuild. To exclude specific projects:
|
|
598
|
+
|
|
599
|
+
```json
|
|
600
|
+
{ "codex": { "skip_dirs": ["my-claude-only-project"] } }
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
Values are project directory names under `projects/`. Excluded projects still get `.codex/` gitignored as a placeholder.
|
|
604
|
+
|
|
605
|
+
### Adding Skills
|
|
606
|
+
|
|
607
|
+
Create `agent-config/skills/my-skill/SKILL.md` with a YAML front matter block and skill content. It'll be copied to both `~/.claude/skills/` and `~/.codex/skills/` on rebuild.
|
|
608
|
+
|
|
609
|
+
### Adding Plugins
|
|
610
|
+
|
|
611
|
+
Create `agent-config/plugins/my-plugin/plugin.json` with a manifest declaring hooks, env vars, commands, agents, or MCP servers. See the [Plugin System](#plugin-system) section for details.
|
|
612
|
+
|
|
613
|
+
### Adding Git Repos
|
|
614
|
+
|
|
615
|
+
```bash
|
|
616
|
+
cd /workspace/projects && git clone <url>
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
Add the path to `config.json → vscode.git_scan_paths` for VS Code git integration.
|
|
620
|
+
|
|
621
|
+
### Adding MCP Servers
|
|
622
|
+
|
|
623
|
+
Via templates:
|
|
624
|
+
|
|
625
|
+
1. Create a template in `agent-config/mcp-templates/`
|
|
626
|
+
2. Enable it in `config.json → mcp_servers`
|
|
627
|
+
3. Rebuild
|
|
628
|
+
|
|
629
|
+
Via plugins:
|
|
630
|
+
|
|
631
|
+
1. Add `mcp_servers` to your plugin's `plugin.json`
|
|
632
|
+
2. Add secrets to `secrets.json` under the plugin name
|
|
633
|
+
3. Rebuild
|
|
634
|
+
|
|
635
|
+
---
|
|
636
|
+
|
|
637
|
+
## Troubleshooting
|
|
638
|
+
|
|
639
|
+
### Langfuse unreachable / port 3052 blocked
|
|
640
|
+
|
|
641
|
+
WSL2's networking can enter a broken state (Windows only). Fix:
|
|
642
|
+
|
|
643
|
+
```powershell
|
|
644
|
+
# PowerShell as Administrator
|
|
645
|
+
wsl --shutdown
|
|
646
|
+
Restart-Service hns
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
Reopen VS Code and the container.
|
|
650
|
+
|
|
651
|
+
### Traces not appearing
|
|
652
|
+
|
|
653
|
+
1. Inside a Claude session, check `echo $TRACE_TO_LANGFUSE` (should be `true` — this env var is set in Claude's `settings.json`, not in the shell)
|
|
654
|
+
2. Check `curl http://host.docker.internal:3052/api/public/health`
|
|
655
|
+
3. Check `tail -20 ~/.claude/state/langfuse_hook.log`
|
|
656
|
+
|
|
657
|
+
### Plugin warnings during install
|
|
658
|
+
|
|
659
|
+
Check the install output for the `--- Warnings Recap ---` section. Common issues:
|
|
660
|
+
|
|
661
|
+
- Missing hook script file → plugin skipped (check the file path in your plugin.json)
|
|
662
|
+
- Unresolved `{{TOKEN}}` → add the secret to `secrets.json` under your plugin name
|
|
663
|
+
- File conflict → two plugins provide the same file (first alphabetically wins)
|
|
664
|
+
|
|
665
|
+
### Docker socket permission denied
|
|
666
|
+
|
|
667
|
+
```bash
|
|
668
|
+
sudo chmod 666 /var/run/docker.sock
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
### Git "dubious ownership" errors
|
|
672
|
+
|
|
673
|
+
Handled automatically. If it recurs: `git config --global --add safe.directory '*'`
|
|
674
|
+
|
|
675
|
+
---
|
|
676
|
+
|
|
677
|
+
## Known Issues
|
|
678
|
+
|
|
679
|
+
| Issue | Cause | Status |
|
|
680
|
+
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
681
|
+
| Claude Code Edit tool throws `ENOENT: no such file or directory` on files that exist (Windows only) | WSL2 bind mount (C:\ → 9P → container) causes stale file metadata; the Edit tool's freshness check sees a mismatched mtime and rejects the write | Intermittent, self-healing (re-read + retry succeeds). Likely resolved in a future Claude Code update. |
|
|
682
|
+
| Lifecycle terminal closes before you can read output | VS Code dismisses the postCreate/postStart terminal on completion | Use `slc` / `sls` aliases to view saved logs from `/tmp/devcontainer-logs/` |
|
|
683
|
+
|
|
684
|
+
---
|
|
685
|
+
|
|
686
|
+
<div align="center">
|
|
687
|
+
|
|
688
|
+
## Acknowledgments
|
|
689
|
+
|
|
690
|
+
Built on the shoulders of:
|
|
691
|
+
|
|
692
|
+
**[Claude Code](https://github.com/anthropics/claude-code)** (devcontainer, plugins, hooks framework) · **[claude-code-langfuse-template](https://github.com/doneyli/claude-code-langfuse-template)** · **[Get Shit Done](https://github.com/glittercowboy/get-shit-done)** · **[codex-mcp-server](https://github.com/tuannvm/codex-mcp-server)**
|
|
39
693
|
|
|
40
|
-
|
|
694
|
+
<br>
|
|
41
695
|
|
|
42
|
-
|
|
696
|
+
MIT License · Copyright (c) 2026 agomusio
|
|
43
697
|
|
|
44
|
-
|
|
698
|
+
</div>
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "no-more-configs",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.4.0",
|
|
4
|
+
"description": "Zero-config devcontainer for Claude Code & Codex CLI — firewall, plugins, Langfuse tracing, MCP servers, and 80+ slash commands out of the box. One command to install.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"no-more-configs": "index.js"
|
|
@@ -10,17 +10,41 @@
|
|
|
10
10
|
"index.js",
|
|
11
11
|
"README.md"
|
|
12
12
|
],
|
|
13
|
+
"scripts": {
|
|
14
|
+
"prepack": "cp ../README.md README.md"
|
|
15
|
+
},
|
|
13
16
|
"engines": {
|
|
14
17
|
"node": ">=18"
|
|
15
18
|
},
|
|
16
19
|
"keywords": [
|
|
17
20
|
"claude",
|
|
18
21
|
"claude-code",
|
|
22
|
+
"codex",
|
|
23
|
+
"codex-cli",
|
|
19
24
|
"devcontainer",
|
|
20
25
|
"vscode",
|
|
21
|
-
"
|
|
22
|
-
"ai",
|
|
23
|
-
"
|
|
26
|
+
"docker",
|
|
27
|
+
"ai-coding",
|
|
28
|
+
"ai-agent",
|
|
29
|
+
"agentic-ai",
|
|
30
|
+
"agentic-workflow",
|
|
31
|
+
"vibe-coding",
|
|
32
|
+
"mcp",
|
|
33
|
+
"model-context-protocol",
|
|
34
|
+
"langfuse",
|
|
35
|
+
"anthropic",
|
|
36
|
+
"openai",
|
|
37
|
+
"developer-tools",
|
|
38
|
+
"dev-environment",
|
|
39
|
+
"firewall",
|
|
40
|
+
"plugin-system",
|
|
41
|
+
"gsd",
|
|
42
|
+
"bmad",
|
|
43
|
+
"wsl2",
|
|
44
|
+
"linux",
|
|
45
|
+
"arch-linux",
|
|
46
|
+
"debian",
|
|
47
|
+
"containerized-development"
|
|
24
48
|
],
|
|
25
49
|
"repository": {
|
|
26
50
|
"type": "git",
|