Skip to content

Commit c98ff68

Browse files
claudeclaude
committed
Update documentation and refactor CLAUDE.md structure
- Move devcontainer guide from CLAUDE.md to AGENTS.md - CLAUDE.md now uses @AGENTS.md include directive - docs: update changelog, cli-tools reference, troubleshooting - docs: remove dashboard references, fix sidebar formatting - deps: update docs package-lock.json
1 parent e47953d commit c98ff68

15 files changed

Lines changed: 1386 additions & 870 deletions

File tree

‎container/.devcontainer/AGENTS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# DevContainer Development Guide
2+
3+
CodeForge devcontainer for AI-assisted development with Claude Code.
4+
5+
## Key Configuration
6+
7+
| File | Purpose |
8+
|------|---------|
9+
| `.codeforge/config/settings.json` | Model, tokens, permissions, plugins, env vars |
10+
| `.codeforge/config/main-system-prompt.md` | System prompt defining assistant behavior |
11+
| `.codeforge/config/orchestrator-system-prompt.md` | Orchestrator mode prompt (delegation-first) |
12+
| `.codeforge/config/ccstatusline-settings.json` | Status bar widget layout (deployed to ~/.config/ccstatusline/) |
13+
| `.codeforge/config/disabled-hooks.json` | Disable individual plugin hooks by script name |
14+
| `.codeforge/config/claude-code-router.json` | LLM provider routing config (deployed to ~/.claude-code-router/) |
15+
| `.codeforge/file-manifest.json` | Controls which config files deploy and when |
16+
| `devcontainer.json` | Container definition: image, features, mounts |
17+
| `.env` | Boolean flags controlling setup steps |
18+
19+
Config files deploy via `.codeforge/file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
20+
21+
## Commands
22+
23+
| Command | Purpose |
24+
|---------|---------|
25+
| `cc` / `claude` | Run Claude Code with auto-configuration |
26+
| `codeforge config apply` | Deploy config files to `~/.claude/` (same as container start) |
27+
| `ccraw` | Vanilla Claude Code (bypasses config) |
28+
| `ccw` | Claude Code with writing system prompt |
29+
| `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
30+
| `codex` | OpenAI Codex CLI terminal coding agent |
31+
| `ccms` | Session history search _(disabled — requires Rust toolchain; uncomment in devcontainer.json to enable)_ |
32+
| `codeforge proxy` | Launch Claude Code through mitmproxy — inspect API traffic in browser (port 8081) |
33+
| `ccr start` / `ccr stop` | Claude Code Router daemon control |
34+
| `ccr-apply` | Redeploy router config + restart daemon |
35+
| `ccusage` / `ccburn` | Token usage analysis / burn rate |
36+
| `agent-browser` | Headless Chromium (Playwright-based) |
37+
| `check-setup` | Verify CodeForge setup health |
38+
| `dbr` | Dynamic port forwarding ([devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge)) |
39+
| `cc-tools` | List all installed tools with versions |
40+
41+
## Plugins
42+
43+
Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
44+
45+
- **agent-system** — 19 custom agents + built-in agent redirection
46+
- **skill-engine** — 23 general coding skills + auto-suggestion
47+
- **spec-workflow** — 3 spec lifecycle skills (`/spec`, `/build`, `/specs`) + spec-reminder hook
48+
- **session-context** — Git state injection, TODO harvesting, commit reminders
49+
- **auto-code-quality** — Auto-format + auto-lint + advisory test runner
50+
- **workspace-scope-guard** — Blocks writes outside working directory
51+
- **dangerous-command-blocker** — Blocks destructive bash commands
52+
- **protected-files-guard** — Blocks edits to secrets/lock files
53+
- **codeforge-lsp** — LSP for Python + TypeScript/JavaScript
54+
- **ticket-workflow** — EARS ticket workflow + auto-linking
55+
- **git-workflow** — Standalone ship (commit/push/PR) + PR review
56+
- **notify-hook** — Desktop notifications on completion
57+
- **frontend-design** (Anthropic official) — UI/frontend design skill
58+
- **code-review** (Anthropic official) — Code review skill
59+
- **feature-dev** (Anthropic official) — Feature development skill
60+
- **pr-review-toolkit** (Anthropic official) — PR review commands + agents
61+
- **prompt-snippets** — Quick behavioral mode switches via /ps command
62+
63+
## Rules System
64+
65+
Rules in `.codeforge/config/rules/` deploy to `.claude/rules/` on every container start. They load into ALL sessions automatically.
66+
67+
**Current rules:** `auto-memory.md`, `explicit-start.md`, `plan-presentation.md`, `scope-discipline.md`, `session-search.md`, `spec-workflow.md`, `surface-decisions.md`, `workspace-scope.md`, `zero-tolerance-bugs.md`
68+
69+
**Adding rules:** Create `.md` in `.codeforge/config/rules/`, add a manifest entry in `.codeforge/file-manifest.json`.
70+
71+
## Authentication & Persistence
72+
73+
The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
74+
75+
**Token authentication:** Set `CLAUDE_AUTH_TOKEN` in `.devcontainer/.secrets` (or as a Codespaces secret) with a long-lived token from `claude setup-token`. On container start, `setup-auth.sh` auto-creates `~/.claude/.credentials.json` with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match `sk-ant-*` format.
76+
77+
Codex CLI credentials (`~/.codex/`) are backed by a separate Docker named volume (`codeforge-codex-config-${devcontainerId}`). Set `OPENAI_API_KEY` in `.devcontainer/.secrets` (or as a Codespaces secret) for automatic API key injection, or run `codex` interactively for browser-based ChatGPT OAuth.
78+
79+
**Claude Code Router:** Set provider API keys (`ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) in `.devcontainer/.secrets`. Keys are exported as env vars on container start and read at runtime by the router's `$ENV_VAR` interpolation in `~/.claude-code-router/config.json`. Edit routing rules in `.codeforge/config/claude-code-router.json` and run `ccr-apply` to redeploy.
80+
81+
## Modifying Behavior
82+
83+
1. **Change model**: Edit `.codeforge/config/settings.json` → `"model"` field
84+
2. **Change system prompt**: Edit `.codeforge/config/main-system-prompt.md`
85+
3. **Add config file**: Place in `.codeforge/config/`, add entry to `.codeforge/file-manifest.json`
86+
4. **Add features**: Add to `"features"` in `devcontainer.json`
87+
5. **Disable features**: Set `"version": "none"` in the feature's config
88+
6. **Disable setup steps**: Set flags to `false` in `.env`
89+
7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json`
90+
8. **Lock Claude Code version**: Set `CLAUDE_VERSION_LOCK=2.1.80` in `.env` — the update script installs that exact version on container start instead of updating to latest. Unset to resume auto-updates.
91+
9. **Disable individual hooks**: Add script name (without `.py`) to `disabled` array in `.codeforge/config/disabled-hooks.json` — takes effect immediately, no restart needed
92+
93+
## Plugin Development Notes
94+
95+
### `${CLAUDE_PLUGIN_DATA}` — Persistent Plugin Storage
96+
97+
Available since Claude Code v2.1.78. Resolves to a dedicated data directory per plugin that survives plugin updates (unlike `${CLAUDE_PLUGIN_ROOT}`, which points to the plugin's source directory).
98+
99+
**Current state:** Not used in CodeForge plugins. Plugins store transient state in `/tmp/{prefix}-{session_id}`.
100+
101+
**Future use:** When a plugin needs persistent state across sessions (cached configs, learned preferences, usage frequency), use `${CLAUDE_PLUGIN_DATA}` in hook commands instead of `/tmp/`.

‎container/.devcontainer/CLAUDE.md‎

Lines changed: 1 addition & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1 @@
1-
# DevContainer Development Guide
2-
3-
CodeForge devcontainer for AI-assisted development with Claude Code.
4-
5-
## Key Configuration
6-
7-
| File | Purpose |
8-
|------|---------|
9-
| `.codeforge/config/settings.json` | Model, tokens, permissions, plugins, env vars |
10-
| `.codeforge/config/main-system-prompt.md` | System prompt defining assistant behavior |
11-
| `.codeforge/config/orchestrator-system-prompt.md` | Orchestrator mode prompt (delegation-first) |
12-
| `.codeforge/config/ccstatusline-settings.json` | Status bar widget layout (deployed to ~/.config/ccstatusline/) |
13-
| `.codeforge/config/disabled-hooks.json` | Disable individual plugin hooks by script name |
14-
| `.codeforge/config/claude-code-router.json` | LLM provider routing config (deployed to ~/.claude-code-router/) |
15-
| `.codeforge/file-manifest.json` | Controls which config files deploy and when |
16-
| `devcontainer.json` | Container definition: image, features, mounts |
17-
| `.env` | Boolean flags controlling setup steps |
18-
19-
Config files deploy via `.codeforge/file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
20-
21-
## Commands
22-
23-
| Command | Purpose |
24-
|---------|---------|
25-
| `cc` / `claude` | Run Claude Code with auto-configuration |
26-
| `codeforge config apply` | Deploy config files to `~/.claude/` (same as container start) |
27-
| `ccraw` | Vanilla Claude Code (bypasses config) |
28-
| `ccw` | Claude Code with writing system prompt |
29-
| `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
30-
| `codex` | OpenAI Codex CLI terminal coding agent |
31-
| `ccms` | Session history search _(disabled — requires Rust toolchain; uncomment in devcontainer.json to enable)_ |
32-
| `codeforge proxy` | Launch Claude Code through mitmproxy — inspect API traffic in browser (port 8081) |
33-
| `ccr start` / `ccr stop` | Claude Code Router daemon control |
34-
| `ccr-apply` | Redeploy router config + restart daemon |
35-
| `ccusage` / `ccburn` | Token usage analysis / burn rate |
36-
| `agent-browser` | Headless Chromium (Playwright-based) |
37-
| `check-setup` | Verify CodeForge setup health |
38-
| `codeforge-dashboard` | Session analytics dashboard — auto-launches on start (port 7847) |
39-
| `dbr` | Dynamic port forwarding ([devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge)) |
40-
| `cc-tools` | List all installed tools with versions |
41-
42-
## Plugins
43-
44-
Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
45-
46-
- **agent-system** — 19 custom agents + built-in agent redirection
47-
- **skill-engine** — 23 general coding skills + auto-suggestion
48-
- **spec-workflow** — 3 spec lifecycle skills (`/spec`, `/build`, `/specs`) + spec-reminder hook
49-
- **session-context** — Git state injection, TODO harvesting, commit reminders
50-
- **auto-code-quality** — Auto-format + auto-lint + advisory test runner
51-
- **workspace-scope-guard** — Blocks writes outside working directory
52-
- **dangerous-command-blocker** — Blocks destructive bash commands
53-
- **protected-files-guard** — Blocks edits to secrets/lock files
54-
- **codeforge-lsp** — LSP for Python + TypeScript/JavaScript
55-
- **ticket-workflow** — EARS ticket workflow + auto-linking
56-
- **git-workflow** — Standalone ship (commit/push/PR) + PR review
57-
- **notify-hook** — Desktop notifications on completion
58-
- **frontend-design** (Anthropic official) — UI/frontend design skill
59-
- **code-review** (Anthropic official) — Code review skill
60-
- **feature-dev** (Anthropic official) — Feature development skill
61-
- **pr-review-toolkit** (Anthropic official) — PR review commands + agents
62-
- **prompt-snippets** — Quick behavioral mode switches via /ps command
63-
64-
## Rules System
65-
66-
Rules in `.codeforge/config/rules/` deploy to `.claude/rules/` on every container start. They load into ALL sessions automatically.
67-
68-
**Current rules:** `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
69-
70-
**Adding rules:** Create `.md` in `.codeforge/config/rules/`, add a manifest entry in `.codeforge/file-manifest.json`.
71-
72-
## Authentication & Persistence
73-
74-
The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
75-
76-
**Token authentication:** Set `CLAUDE_AUTH_TOKEN` in `.devcontainer/.secrets` (or as a Codespaces secret) with a long-lived token from `claude setup-token`. On container start, `setup-auth.sh` auto-creates `~/.claude/.credentials.json` with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match `sk-ant-*` format.
77-
78-
Codex CLI credentials (`~/.codex/`) are backed by a separate Docker named volume (`codeforge-codex-config-${devcontainerId}`). Set `OPENAI_API_KEY` in `.devcontainer/.secrets` (or as a Codespaces secret) for automatic API key injection, or run `codex` interactively for browser-based ChatGPT OAuth.
79-
80-
**Claude Code Router:** Set provider API keys (`ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) in `.devcontainer/.secrets`. Keys are exported as env vars on container start and read at runtime by the router's `$ENV_VAR` interpolation in `~/.claude-code-router/config.json`. Edit routing rules in `.codeforge/config/claude-code-router.json` and run `ccr-apply` to redeploy.
81-
82-
## Modifying Behavior
83-
84-
1. **Change model**: Edit `.codeforge/config/settings.json` → `"model"` field
85-
2. **Change system prompt**: Edit `.codeforge/config/main-system-prompt.md`
86-
3. **Add config file**: Place in `.codeforge/config/`, add entry to `.codeforge/file-manifest.json`
87-
4. **Add features**: Add to `"features"` in `devcontainer.json`
88-
5. **Disable features**: Set `"version": "none"` in the feature's config
89-
6. **Disable setup steps**: Set flags to `false` in `.env`
90-
7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json`
91-
8. **Lock Claude Code version**: Set `CLAUDE_VERSION_LOCK=2.1.80` in `.env` — the update script installs that exact version on container start instead of updating to latest. Unset to resume auto-updates.
92-
9. **Disable individual hooks**: Add script name (without `.py`) to `disabled` array in `.codeforge/config/disabled-hooks.json` — takes effect immediately, no restart needed
93-
94-
## Plugin Development Notes
95-
96-
### `${CLAUDE_PLUGIN_DATA}` — Persistent Plugin Storage
97-
98-
Available since Claude Code v2.1.78. Resolves to a dedicated data directory per plugin that survives plugin updates (unlike `${CLAUDE_PLUGIN_ROOT}`, which points to the plugin's source directory).
99-
100-
**Current state:** Not used in CodeForge plugins. Plugins store transient state in `/tmp/{prefix}-{session_id}`.
101-
102-
**Future use:** When a plugin needs persistent state across sessions (cached configs, learned preferences, usage frequency), use `${CLAUDE_PLUGIN_DATA}` in hook commands instead of `/tmp/`.
1+
@AGENTS.md

‎container/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ tree-sitter (JS/TS/Python), ast-grep, Pyright, TypeScript LSP
8181

8282
### Custom Features (21)
8383

84-
tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tree-sitter, lsp-servers, biome, ruff, shfmt, shellcheck, hadolint, dprint, ccms, notify-hook, mcp-qdrant, chromaterm, kitty-terminfo, claude-session-dashboard
84+
tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tree-sitter, lsp-servers, biome, ruff, shfmt, shellcheck, hadolint, dprint, ccms, notify-hook, mcp-qdrant, chromaterm, kitty-terminfo
8585

8686
### Agents (19) & Skills (34)
8787

‎docs/astro.config.mjs‎

Lines changed: 64 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,26 @@ export default defineConfig({
8989
icon: "rocket",
9090
items: [
9191
{ label: "Overview", slug: "start-here" },
92-
{ label: "Before You Install", slug: "start-here/before-you-install" },
93-
{ label: "Install in VS Code", slug: "start-here/install-in-vscode" },
94-
{ label: "Verify Your Install", slug: "start-here/verify-install" },
95-
{ label: "Start Your First Session", slug: "start-here/first-session" },
96-
{ label: "Your First Tasks", slug: "start-here/your-first-tasks" },
92+
{
93+
label: "Before You Install",
94+
slug: "start-here/before-you-install",
95+
},
96+
{
97+
label: "Install in VS Code",
98+
slug: "start-here/install-in-vscode",
99+
},
100+
{
101+
label: "Verify Your Install",
102+
slug: "start-here/verify-install",
103+
},
104+
{
105+
label: "Start Your First Session",
106+
slug: "start-here/first-session",
107+
},
108+
{
109+
label: "Your First Tasks",
110+
slug: "start-here/your-first-tasks",
111+
},
97112
{
98113
label: "DevContainer CLI",
99114
slug: "start-here/devcontainer-cli",
@@ -118,7 +133,6 @@ export default defineConfig({
118133
{ label: "Spec Workflow", slug: "use/spec-workflow" },
119134
{ label: "Ticket Workflow", slug: "use/ticket-workflow" },
120135
{ label: "Git and PRs", slug: "use/git-and-prs" },
121-
{ label: "Dashboard", slug: "use/dashboard" },
122136
{ label: "Memories", slug: "use/memories" },
123137
{ label: "Accessing Services", slug: "use/accessing-services" },
124138
],
@@ -145,7 +159,10 @@ export default defineConfig({
145159
label: "Keybindings and Terminal",
146160
slug: "customize/keybindings-and-terminal",
147161
},
148-
{ label: "Optional Components", slug: "customize/optional-components" },
162+
{
163+
label: "Optional Components",
164+
slug: "customize/optional-components",
165+
},
149166
],
150167
},
151168
{
@@ -159,10 +176,22 @@ export default defineConfig({
159176
{
160177
label: "Core Plugins",
161178
items: [
162-
{ label: "Agent System", slug: "extend/plugins/agent-system" },
163-
{ label: "Skill Engine", slug: "extend/plugins/skill-engine" },
164-
{ label: "Spec Workflow", slug: "extend/plugins/spec-workflow" },
165-
{ label: "Ticket Workflow", slug: "extend/plugins/ticket-workflow" },
179+
{
180+
label: "Agent System",
181+
slug: "extend/plugins/agent-system",
182+
},
183+
{
184+
label: "Skill Engine",
185+
slug: "extend/plugins/skill-engine",
186+
},
187+
{
188+
label: "Spec Workflow",
189+
slug: "extend/plugins/spec-workflow",
190+
},
191+
{
192+
label: "Ticket Workflow",
193+
slug: "extend/plugins/ticket-workflow",
194+
},
166195
],
167196
},
168197
{
@@ -189,12 +218,27 @@ export default defineConfig({
189218
{
190219
label: "Session & Integration",
191220
items: [
192-
{ label: "Session Context", slug: "extend/plugins/session-context" },
193-
{ label: "Git Workflow", slug: "extend/plugins/git-workflow" },
194-
{ label: "Prompt Snippets", slug: "extend/plugins/prompt-snippets" },
221+
{
222+
label: "Session Context",
223+
slug: "extend/plugins/session-context",
224+
},
225+
{
226+
label: "Git Workflow",
227+
slug: "extend/plugins/git-workflow",
228+
},
229+
{
230+
label: "Prompt Snippets",
231+
slug: "extend/plugins/prompt-snippets",
232+
},
195233
{ label: "Notify Hook", slug: "extend/plugins/notify-hook" },
196-
{ label: "CodeForge LSP", slug: "extend/plugins/codeforge-lsp" },
197-
{ label: "Frontend Design", slug: "extend/plugins/frontend-design" },
234+
{
235+
label: "CodeForge LSP",
236+
slug: "extend/plugins/codeforge-lsp",
237+
},
238+
{
239+
label: "Frontend Design",
240+
slug: "extend/plugins/frontend-design",
241+
},
198242
],
199243
},
200244
],
@@ -210,7 +254,10 @@ export default defineConfig({
210254
{ label: "CLI Tools", slug: "reference/cli-tools" },
211255
{ label: "Agents", slug: "reference/agents" },
212256
{ label: "Skills", slug: "reference/skills" },
213-
{ label: "Environment Variables", slug: "reference/environment-variables" },
257+
{
258+
label: "Environment Variables",
259+
slug: "reference/environment-variables",
260+
},
214261
{ label: "Architecture", slug: "reference/architecture" },
215262
{ label: "Troubleshooting", slug: "reference/troubleshooting" },
216263
{ label: "Changelog", slug: "reference/changelog" },

0 commit comments

Comments
 (0)