diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md index eb2311f..81f64b3 100644 --- a/.devcontainer/CHANGELOG.md +++ b/.devcontainer/CHANGELOG.md @@ -11,6 +11,13 @@ - Updated prerequisites and installation docs to support all DevContainer clients (VS Code, CLI, JetBrains Gateway, DevPod, Codespaces) - Added tabbed client-specific instructions on the installation page - Added dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling +- **Ported `.devcontainer/docs/` to docs site** — migrated content from 5 legacy reference docs into the Starlight documentation site: + - New **Keybindings** page (Customization) — VS Code/Claude Code shortcut conflicts and resolution options + - New **Troubleshooting** page (Reference) — 12+ problem/solution entries for build, auth, plugins, and performance issues + - New **Optional Features** page (Customization) — mcp-qdrant vector memory setup guide + - Merged setup variables (`.env` flags) into the Environment Variables reference + - Merged `.secrets` file authentication docs into the Configuration page +- Removed `.devcontainer/docs/` directory — all content now lives in the docs site ### Fixed diff --git a/.devcontainer/docs/configuration-reference.md b/.devcontainer/docs/configuration-reference.md deleted file mode 100644 index e8e8b94..0000000 --- a/.devcontainer/docs/configuration-reference.md +++ /dev/null @@ -1,96 +0,0 @@ -# Configuration Reference - -Quick reference for all CodeForge configuration options. - -## Which File to Edit - -| Task | File to Edit | -|------|-------------| -| Change default model | `config/defaults/settings.json` | -| Change system prompt | `config/defaults/main-system-prompt.md` | -| Customize keybindings | `config/defaults/keybindings.json` | -| Control setup steps | `.env` | -| Add custom config file | `config/file-manifest.json` | -| Disable a feature | `devcontainer.json` (set `"version": "none"`) | -| Disable a plugin | `config/defaults/settings.json` (remove from `enabledPlugins`) | -| Skip a plugin install | `.env` (`PLUGIN_BLACKLIST`) | -| Change container memory | `devcontainer.json` (`runArgs`) | -| Add VS Code extension | `devcontainer.json` (`customizations.vscode.extensions`) | - -## `.env` Variables (Setup Behavior) - -These control what `setup.sh` does on each container start. Copy `.env.example` to `.env` and customize. - -| Variable | Default | Description | -|----------|---------|-------------| -| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Where Claude Code config files are stored | -| `CONFIG_SOURCE_DIR` | `(auto-detected)` | Source directory for config defaults | -| `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` | -| `SETUP_ALIASES` | `true` | Add cc/claude/ccraw/cc-tools aliases to shell | -| `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file | -| `SETUP_PLUGINS` | `true` | Install Anthropic plugins + register local marketplace | -| `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary | -| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal | -| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager | -| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` | -| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation | - -## `devcontainer.json` `remoteEnv` (Container Runtime) - -These environment variables are set in every terminal session inside the container. - -| Variable | Value | Description | -|----------|-------|-------------| -| `WORKSPACE_ROOT` | `/workspaces` | Workspace root directory | -| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Claude Code config directory | -| `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory | -| `TMPDIR` | `/workspaces/.tmp` | Temporary files directory | -| `CLAUDECODE` | `null` (unset) | Unsets the variable to allow nested Claude Code sessions (claude-in-claude) | - -## `config/file-manifest.json` (File Copy Rules) - -Each entry in the manifest array controls how a config file is deployed: - -```json -{ - "src": "defaults/settings.json", - "dest": "${CLAUDE_CONFIG_DIR}", - "destFilename": "settings.json", - "overwrite": "if-changed", - "enabled": true -} -``` - -| Field | Required | Default | Description | -|-------|----------|---------|-------------| -| `src` | Yes | — | Source file path relative to `config/` | -| `dest` | Yes | — | Destination directory (supports `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`) | -| `destFilename` | No | basename of `src` | Override the destination filename | -| `overwrite` | No | `"if-changed"` | `"always"`, `"never"`, or `"if-changed"` (sha256 comparison) | -| `enabled` | No | `true` | Set `false` to skip this entry | - -## Feature Options - -Each feature in `devcontainer.json` supports options defined in its `devcontainer-feature.json`. Common options: - -| Option | Description | Used By | -|--------|-------------|---------| -| `version` | Tool version to install. `"none"` skips installation. | All local features | -| `username` | Container user to install for. `"automatic"` auto-detects. | dprint, ruff, ccusage, ccburn, etc. | -| `shells` | Which shell rc files to modify (`"both"`, `"bash"`, `"zsh"`). | ccusage, ccburn | - -## `.secrets` File (Authentication) - -Create `.devcontainer/.secrets` with tokens for automatic authentication: - -```bash -GH_TOKEN=ghp_your_token_here -GH_USERNAME=your-github-username -GH_EMAIL=your-email@example.com -NPM_TOKEN=npm_your_token_here -CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here -``` - -The `CLAUDE_AUTH_TOKEN` is a long-lived token from `claude setup-token`. When set, `setup-auth.sh` creates `~/.claude/.credentials.json` on container start (skips if already exists). - -Environment variables with the same names take precedence over `.secrets` file values (useful for Codespaces). diff --git a/.devcontainer/docs/keybindings.md b/.devcontainer/docs/keybindings.md deleted file mode 100644 index 33a3c68..0000000 --- a/.devcontainer/docs/keybindings.md +++ /dev/null @@ -1,100 +0,0 @@ -# Keybinding Customization - -Claude Code runs inside VS Code's integrated terminal. Some VS Code shortcuts are intercepted before reaching the terminal, conflicting with Claude Code's keybindings. - -## Conflicts - -| Shortcut | VS Code Action | Claude Code Action | -|----------|---------------|-------------------| -| `Ctrl+G` | Go to Line | `chat:externalEditor` | -| `Ctrl+S` | Save File | `chat:stash` | -| `Ctrl+T` | Open Symbol | `app:toggleTodos` | -| `Ctrl+O` | Open File | `app:toggleTranscript` | -| `Ctrl+B` | Toggle Sidebar | `task:background` | -| `Ctrl+P` | Quick Open | `chat:modelPicker` | -| `Ctrl+R` | Open Recent | `history:search` | -| `Ctrl+F` | Find in Terminal | (navigation) | - -## Already Resolved - -`Ctrl+P` and `Ctrl+F` are configured to pass through to Claude Code via `terminal.integrated.commandsToSkipShell` in `devcontainer.json`: - -```json -"terminal.integrated.commandsToSkipShell": [ - "-workbench.action.quickOpen", - "-workbench.action.terminal.focusFind" -] -``` - -The `-` prefix removes the shortcut from VS Code's interception list when the terminal is focused. - -## Resolving Other Conflicts - -### Option 1: Use Meta (Alt) Variants - -Claude Code binds Meta (Alt) variants for all shortcuts. Use `Alt+G` instead of `Ctrl+G`, etc. No configuration needed. - -### Option 2: Add to VS Code's Skip List - -Add more shortcuts to `terminal.integrated.commandsToSkipShell` in `devcontainer.json`: - -```json -"terminal.integrated.commandsToSkipShell": [ - "-workbench.action.quickOpen", - "-workbench.action.terminal.focusFind", - "-workbench.action.gotoLine", - "-workbench.action.files.save" -] -``` - -Common command IDs: -| Shortcut | Command ID | -|----------|-----------| -| `Ctrl+G` | `workbench.action.gotoLine` | -| `Ctrl+S` | `workbench.action.files.save` | -| `Ctrl+T` | `workbench.action.showAllSymbols` | -| `Ctrl+O` | `workbench.action.files.openFile` | -| `Ctrl+B` | `workbench.action.toggleSidebarVisibility` | -| `Ctrl+R` | `workbench.action.openRecent` | - -### Option 3: Custom Claude Code Keybindings - -Edit `config/defaults/keybindings.json` to remap Claude Code actions to non-conflicting shortcuts: - -```json -{ - "bindings": [ - { - "key": "ctrl+shift+g", - "command": "chat:externalEditor", - "description": "Open external editor (remapped from Ctrl+G)" - }, - { - "key": "ctrl+shift+s", - "command": "chat:stash", - "description": "Stash conversation (remapped from Ctrl+S)" - } - ] -} -``` - -The keybindings file is copied to `~/.claude/keybindings.json` on container start (controlled by `file-manifest.json`). - -## Claude Code Keybinding Reference - -Full list of default Claude Code shortcuts (these work when Claude Code has terminal focus): - -| Key | Action | -|-----|--------| -| `Ctrl+C` / `Esc` | Cancel / Interrupt | -| `Ctrl+L` | Clear screen | -| `Ctrl+P` | Model picker | -| `Ctrl+R` | Search history | -| `Ctrl+G` | External editor | -| `Ctrl+S` | Stash conversation | -| `Ctrl+T` | Toggle todos | -| `Ctrl+O` | Toggle transcript | -| `Ctrl+B` | Background current task | -| `Ctrl+F` | Find in output | - -All of these also have `Meta` (Alt) variants that work even when VS Code intercepts the `Ctrl` version. diff --git a/.devcontainer/docs/plugins.md b/.devcontainer/docs/plugins.md deleted file mode 100644 index 74fe627..0000000 --- a/.devcontainer/docs/plugins.md +++ /dev/null @@ -1,176 +0,0 @@ -# Plugin System - -CodeForge includes a local plugin marketplace that provides specialized tools and hooks for Claude Code. - -## Architecture - -``` -plugins/devs-marketplace/ -├── .claude-plugin/ -│ └── marketplace.json # Marketplace manifest (lists all plugins) -└── plugins/ - ├── codeforge-lsp/ # LSP language servers - ├── ticket-workflow/ # EARS ticket workflow - ├── notify-hook/ # Desktop notifications - ├── dangerous-command-blocker/ # Safety: block destructive commands - ├── protected-files-guard/ # Safety: protect sensitive files - ├── auto-code-quality/ # Batch formatter + linter + advisory test runner - ├── agent-system/ # 17 custom agents + redirection hooks - ├── skill-engine/ # 22 coding skills + auto-suggestion - ├── spec-workflow/ # 8 spec lifecycle skills + spec-reminder - ├── session-context/ # Git state, TODO harvesting, commit reminders - └── workspace-scope-guard/ # Workspace scope enforcement -``` - -Each plugin has a `.claude-plugin/plugin.json` manifest defining its name, description, and capabilities. - -## Enabling/Disabling Plugins - -Plugins are enabled in `config/defaults/settings.json` under `enabledPlugins`: - -```json -"enabledPlugins": [ - "auto-code-quality@devs-marketplace", - "agent-system@devs-marketplace", - "skill-engine@devs-marketplace", - "spec-workflow@devs-marketplace", - "session-context@devs-marketplace" -] -``` - -To disable a plugin, remove its entry from the `enabledPlugins` array. - -## PLUGIN_BLACKLIST - -To skip a plugin during the installation/registration step (without editing `settings.json`), add it to `PLUGIN_BLACKLIST` in `.env`: - -```bash -PLUGIN_BLACKLIST="ticket-workflow,auto-linter" -``` - -This prevents the plugin from being registered on container start but doesn't remove it from `enabledPlugins`. - ---- - -## Plugin Reference - -### codeforge-lsp - -**Purpose**: Provides Language Server Protocol servers for code intelligence. - -**Servers**: -- **Pyright** — Python type checking and completion (`.py`, `.pyi`) -- **TypeScript Language Server** — TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`) -- **gopls** — Go language server (`.go`, `.mod`, `.sum`) - -Claude Code automatically uses these for hover info, go-to-definition, and find-references. - -### ticket-workflow - -**Purpose**: EARS-based ticket workflow with GitHub integration. - -Provides structured ticket management using EARS (Easy Approach to Requirements Syntax) format. Integrates with GitHub Issues for tracking. - -**Commands**: `/ticket:new`, `/ticket:work`, `/ticket:review-commit`, `/ticket:create-pr` - -### notify-hook - -**Purpose**: Desktop notifications when Claude Code finishes responding. - -Sends an OSC escape sequence and terminal bell when Claude completes a response, triggering desktop notifications in supported terminals (WezTerm, iTerm2, VS Code with the OSC notifier extension). - -**Configuration**: Enabled via `devcontainer.json` feature options: -```json -"./features/notify-hook": { - "enableBell": true, - "enableOsc": true -} -``` - -### dangerous-command-blocker - -**Purpose**: Prevents Claude Code from executing destructive bash commands. - -**Blocked patterns**: -- `rm -rf /` and variants -- `sudo rm` on system directories -- `chmod 777` on sensitive paths -- `git push --force` to protected branches -- `dd` with output to block devices -- Other destructive system commands - -The blocker runs as a PreToolUse hook on Bash commands. It checks the command against a pattern list and rejects matches. - -### protected-files-guard - -**Purpose**: Prevents Claude Code from modifying sensitive files. - -**Protected patterns**: -- `.env` and `.secrets` files -- Lock files (`package-lock.json`, `uv.lock`, `Cargo.lock`, etc.) -- `.git/` directory contents -- Credential files and SSH keys - -Runs as a PreToolUse hook on Write and Edit operations. - -### auto-code-quality - -**Purpose**: Batch-formats, lints, and runs advisory tests on files edited during a Claude Code session. - -**Supported formatters**: -| Language | Formatter | -|----------|-----------| -| Python | Ruff | -| Go | gofmt | -| JavaScript/TypeScript/CSS/JSON/GraphQL/HTML | Biome | -| Shell scripts | shfmt | -| Markdown/YAML/TOML/Dockerfile | dprint | -| Rust | rustfmt | - -**Supported linters**: -| Language | Linter | -|----------|--------| -| Python | Pyright + Ruff | -| JavaScript/TypeScript/CSS/GraphQL | Biome | -| Shell scripts | ShellCheck | -| Go | go vet | -| Dockerfile | hadolint | -| Rust | clippy | - -**How it works**: Runs as a Stop hook. When Claude Code stops, it checks which files were edited, detects their language, and runs the appropriate formatter and linter. Also includes an advisory test runner that runs affected tests. Results are informational — they don't block. - -### agent-system - -**Purpose**: 17 specialized agent definitions with built-in agent redirection. - -**Components**: -- **17 custom agents** — Specialized agent definitions for different task types (architect, explorer, test-writer, refactorer, security-auditor, researcher, doc-writer, etc.) -- **Agent redirection hook** — Transparently swaps built-in agent types to custom agents (e.g., `Explore` → `explorer`, `Plan` → `architect`) -- **CWD injection hook** — Injects current working directory into agent prompts -- **Read-only bash enforcement** — Prevents read-only agents from executing write operations - -For detailed agent documentation, see `plugins/devs-marketplace/plugins/agent-system/agents/`. - -### skill-engine - -**Purpose**: 22 domain-specific coding reference skills with auto-suggestion. - -**Skills**: fastapi, svelte5, docker, docker-py, pydantic-ai, sqlite, testing, debugging, security-checklist, refactoring-patterns, git-forensics, performance-profiling, documentation-patterns, migration-patterns, dependency-management, claude-code-headless, claude-agent-sdk, ast-grep-patterns, api-design, skill-building, team, worktree - -**How it works**: Skills are loaded on demand via the Skill tool. A PreToolUse hook auto-suggests relevant skills based on conversation context. - -For skill details, see `plugins/devs-marketplace/plugins/skill-engine/skills/`. - -### spec-workflow - -**Purpose**: 8 spec lifecycle skills with spec-reminder hook. - -**Skills**: spec-new, spec-refine, spec-build, spec-review, spec-update, spec-check, spec-init, specification-writing - -**How it works**: Provides a structured specification workflow. A Stop hook reminds users to update specs when code was modified but specs weren't. - -### workspace-scope-guard - -**Purpose**: Enforces workspace scope by blocking writes outside the working directory and warning on out-of-scope reads. - -Runs as a PreToolUse hook on Write, Edit, and Read operations. Compares file paths against the current working directory and rejects modifications to files outside the project scope. Read operations outside scope produce a warning but are not blocked. Resolves symlinks and worktree paths correctly via `os.path.realpath()`. diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 79aa12d..718806f 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -142,6 +142,8 @@ export default defineConfig({ { label: 'System Prompts', slug: 'customization/system-prompts' }, { label: 'Rules', slug: 'customization/rules' }, { label: 'Hooks', slug: 'customization/hooks' }, + { label: 'Keybindings', slug: 'customization/keybindings' }, + { label: 'Optional Features', slug: 'customization/optional-features' }, ], }, { @@ -155,6 +157,7 @@ export default defineConfig({ { label: 'Environment Variables', slug: 'reference/environment' }, { label: 'Architecture', slug: 'reference/architecture' }, { label: 'Port Forwarding', slug: 'reference/port-forwarding' }, + { label: 'Troubleshooting', slug: 'reference/troubleshooting' }, ], }, ], diff --git a/docs/src/content/docs/customization/configuration.md b/docs/src/content/docs/customization/configuration.md index aca08c7..0098b28 100644 --- a/docs/src/content/docs/customization/configuration.md +++ b/docs/src/content/docs/customization/configuration.md @@ -220,6 +220,32 @@ Optional secrets can be declared for VS Code Codespaces or other DevContainer ho } ``` +## Secrets File + +Create `.devcontainer/.secrets` to configure automatic authentication on container start. The file uses `KEY=VALUE` format: + +```bash +GH_TOKEN=ghp_your_token_here +GH_USERNAME=your-github-username +GH_EMAIL=your-email@example.com +NPM_TOKEN=npm_your_token_here +CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here +``` + +| Variable | Purpose | +|----------|---------| +| `GH_TOKEN` | GitHub Personal Access Token for `gh` CLI and git authentication | +| `GH_USERNAME` | GitHub username for `git config user.name` | +| `GH_EMAIL` | Email for `git config user.email` | +| `NPM_TOKEN` | NPM authentication token for publishing and private packages | +| `CLAUDE_AUTH_TOKEN` | Long-lived Claude Code token from `claude setup-token` | + +When `CLAUDE_AUTH_TOKEN` is set, `setup-auth.sh` creates `~/.claude/.credentials.json` on container start with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match the `sk-ant-*` format. + +:::caution[Don't Commit Secrets] +The `.secrets` file is listed in `.gitignore`. Never commit it to version control. For Codespaces, use [GitHub Secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces) instead — environment variables with the same names take precedence over `.secrets` file values. +::: + ## Configuration Precedence When the same setting is defined at multiple levels, the most specific value wins: diff --git a/docs/src/content/docs/customization/keybindings.md b/docs/src/content/docs/customization/keybindings.md new file mode 100644 index 0000000..2b92c4a --- /dev/null +++ b/docs/src/content/docs/customization/keybindings.md @@ -0,0 +1,114 @@ +--- +title: Keybindings +description: Resolve keyboard shortcut conflicts between VS Code and Claude Code, and customize Claude Code keybindings. +sidebar: + order: 6 +--- + +Claude Code runs inside VS Code's integrated terminal. Some VS Code shortcuts are intercepted before reaching the terminal, which conflicts with Claude Code's own keybindings. This page explains the conflicts and three ways to resolve them. + +## Shortcut Conflicts + +When the terminal is focused, VS Code intercepts these shortcuts before Claude Code can process them: + +| Shortcut | VS Code Action | Claude Code Action | +|----------|---------------|-------------------| +| Ctrl+G | Go to Line | External editor | +| Ctrl+S | Save File | Stash conversation | +| Ctrl+T | Open Symbol | Toggle todos | +| Ctrl+O | Open File | Toggle transcript | +| Ctrl+B | Toggle Sidebar | Background task | +| Ctrl+P | Quick Open | Model picker | +| Ctrl+R | Open Recent | Search history | +| Ctrl+F | Find in Terminal | Navigation | + +## Already Resolved + +CodeForge pre-configures Ctrl+P and Ctrl+F to pass through to Claude Code via `terminal.integrated.commandsToSkipShell` in `devcontainer.json`: + +```json +"terminal.integrated.commandsToSkipShell": [ + "-workbench.action.quickOpen", + "-workbench.action.terminal.focusFind" +] +``` + +The `-` prefix removes the shortcut from VS Code's interception list when the terminal is focused. + +## Resolving Other Conflicts + +### Option 1: Use Alt Variants + +Claude Code binds Alt (Meta) variants for all shortcuts. Use Alt+G instead of Ctrl+G, and so on. No configuration needed. + +### Option 2: Add to VS Code's Skip List + +Add more shortcuts to `terminal.integrated.commandsToSkipShell` in `devcontainer.json`: + +```json +"terminal.integrated.commandsToSkipShell": [ + "-workbench.action.quickOpen", + "-workbench.action.terminal.focusFind", + "-workbench.action.gotoLine", + "-workbench.action.files.save" +] +``` + +Common command IDs: + +| Shortcut | VS Code Command ID | +|----------|-----------| +| Ctrl+G | `workbench.action.gotoLine` | +| Ctrl+S | `workbench.action.files.save` | +| Ctrl+T | `workbench.action.showAllSymbols` | +| Ctrl+O | `workbench.action.files.openFile` | +| Ctrl+B | `workbench.action.toggleSidebarVisibility` | +| Ctrl+R | `workbench.action.openRecent` | + +### Option 3: Custom Claude Code Keybindings + +Edit `.devcontainer/config/defaults/keybindings.json` to remap Claude Code actions to non-conflicting shortcuts: + +```json +{ + "bindings": [ + { + "key": "ctrl+shift+g", + "command": "chat:externalEditor", + "description": "Open external editor (remapped from Ctrl+G)" + }, + { + "key": "ctrl+shift+s", + "command": "chat:stash", + "description": "Stash conversation (remapped from Ctrl+S)" + } + ] +} +``` + +The keybindings file is deployed to `~/.claude/keybindings.json` on container start via `file-manifest.json`. + +## Claude Code Shortcut Reference + +Full list of default Claude Code shortcuts (these work when Claude Code has terminal focus): + +| Key | Action | +|-----|--------| +| Ctrl+C / Esc | Cancel / Interrupt | +| Ctrl+L | Clear screen | +| Ctrl+P | Model picker | +| Ctrl+R | Search history | +| Ctrl+G | External editor | +| Ctrl+S | Stash conversation | +| Ctrl+T | Toggle todos | +| Ctrl+O | Toggle transcript | +| Ctrl+B | Background current task | +| Ctrl+F | Find in output | + +All of these also have Alt (Meta) variants that work even when VS Code intercepts the Ctrl version. + +## Related + +- [Configuration](./configuration/) — settings.json and file-manifest reference +- [Hooks](./hooks/) — lifecycle hooks that can be customized +- [Commands](../reference/commands/) — full CLI and slash command reference diff --git a/.devcontainer/docs/optional-features.md b/docs/src/content/docs/customization/optional-features.md similarity index 64% rename from .devcontainer/docs/optional-features.md rename to docs/src/content/docs/customization/optional-features.md index 3ad790c..4dc755b 100644 --- a/.devcontainer/docs/optional-features.md +++ b/docs/src/content/docs/customization/optional-features.md @@ -1,10 +1,15 @@ -# Optional Features +--- +title: Optional Features +description: Non-default features available in CodeForge — how to enable and configure them. +sidebar: + order: 7 +--- -CodeForge includes several features that are available but not enabled by default. This guide covers how to enable and configure them. +CodeForge includes several features that are available but not enabled by default. This page covers how to enable and configure them. ## mcp-qdrant (Vector Memory for Claude) -Adds persistent vector memory to Claude Code via a Qdrant MCP server. Claude can store and retrieve information across sessions. +Adds persistent vector memory to Claude Code via a Qdrant MCP server. Claude can store and retrieve information across sessions using `qdrant-store` and `qdrant-find` tools. ### Enabling @@ -29,15 +34,11 @@ Add to `devcontainer.json` under `"features"`: ### Supported Embedding Models -- `all-MiniLM-L6-v2` (default, smallest, fastest) +- `all-MiniLM-L6-v2` — default, smallest, fastest - `BAAI/bge-small-en-v1.5` - `BAAI/bge-base-en-v1.5` - `sentence-transformers/all-mpnet-base-v2` -### Prerequisites - -Already met by default container: Python 3.14 and uv are pre-installed. - ### How It Works 1. During container build, the embedding model is pre-downloaded from GCS (not HuggingFace, to avoid network issues in containers). @@ -50,7 +51,9 @@ Already met by default container: Python 3.14 and uv are pre-installed. uvx mcp-server-qdrant --help ``` ---- +:::note[Prerequisites] +Python 3.14 and uv are pre-installed in the default container — no additional setup required. +::: ## Disabling Default Features @@ -62,3 +65,13 @@ Any feature can be disabled without removing it from `devcontainer.json` by sett ``` The feature entry stays in the config for easy re-enabling — just remove `"version": "none"` or set it to `"latest"`. + +:::tip[When to Disable Features] +Disabling unused features speeds up container builds and reduces memory usage. If you don't use Go, for example, disabling the Go language server saves resources. +::: + +## Related + +- [Configuration](./configuration/) — settings.json and devcontainer.json reference +- [Plugins](../plugins/) — plugin system overview and per-plugin configuration +- [Troubleshooting](../reference/troubleshooting/) — solutions for build and feature issues diff --git a/docs/src/content/docs/reference/environment.md b/docs/src/content/docs/reference/environment.md index 77525da..5d8a559 100644 --- a/docs/src/content/docs/reference/environment.md +++ b/docs/src/content/docs/reference/environment.md @@ -87,6 +87,28 @@ Variables that configure individual tools within the container. | `RUFF_CONFIG` | ruff | Path to ruff configuration file | | `BIOME_CONFIG_PATH` | biome | Path to biome configuration file | +## Setup Variables (.env) + +These variables live in `.devcontainer/.env` and control what `setup.sh` does on each container start. Copy `.env.example` to `.env` and customize. + +| Variable | Default | Description | +|----------|---------|-------------| +| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Where Claude Code config files are stored | +| `CONFIG_SOURCE_DIR` | (auto-detected) | Source directory for config defaults | +| `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` | +| `SETUP_ALIASES` | `true` | Add `cc`/`claude`/`ccraw`/`cc-tools` aliases to shell | +| `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file | +| `SETUP_PLUGINS` | `true` | Install Anthropic plugins and register local marketplace | +| `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary | +| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal | +| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager | +| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` | +| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation | + +:::tip[Disabling Setup Steps] +Set any flag to `false` to skip that step. For example, `SETUP_PROJECTS=false` disables project auto-detection if you manage the Project Manager list manually. +::: + ## Language Runtime Variables Variables for language runtimes installed in the container. diff --git a/.devcontainer/docs/troubleshooting.md b/docs/src/content/docs/reference/troubleshooting.md similarity index 53% rename from .devcontainer/docs/troubleshooting.md rename to docs/src/content/docs/reference/troubleshooting.md index 815b6c4..0dbee68 100644 --- a/.devcontainer/docs/troubleshooting.md +++ b/docs/src/content/docs/reference/troubleshooting.md @@ -1,133 +1,148 @@ -# Troubleshooting +--- +title: Troubleshooting +description: Common issues and solutions for the CodeForge devcontainer. +sidebar: + order: 7 +--- -Common issues and solutions for the CodeForge devcontainer. +Solutions for common issues with the CodeForge devcontainer. If your problem isn't listed here, check [GitHub Issues](https://github.com/AnExiledDev/CodeForge/issues) or open a new one. ## Container Build Failures -**Problem**: Container fails to build during feature installation. +**Problem: Container fails to build during feature installation.** -- Check Docker has sufficient memory (6GB+ recommended). CodeForge sets `--memory=6g` by default. +- Check Docker has sufficient memory (6 GB+ recommended). CodeForge sets `--memory=6g` by default. - If a specific feature fails, disable it temporarily by setting `"version": "none"` in `devcontainer.json`. - Check internet connectivity — most features download binaries from GitHub releases. - If hitting GitHub API rate limits during build, set `GH_TOKEN` or `GITHUB_TOKEN` as an environment variable. -**Problem**: Build is slow or hangs. +**Problem: Build is slow or hangs.** -- The mcp-qdrant feature downloads an embedding model (~90MB). This is normal on first build. -- The mcp-reasoner feature clones and builds a Node.js project. This takes 1-2 minutes. +- The mcp-qdrant feature downloads an embedding model (~90 MB). This is normal on first build. - Use `"version": "none"` to skip optional features you don't need. +:::tip[Disabling Features] +Any local feature can be disabled without removing it from `devcontainer.json` by setting `"version": "none"`. The feature entry stays in the config for easy re-enabling — just remove the version override or set it to `"latest"`. +::: + ## Authentication Issues -**Problem**: `claude` command fails with authentication error. +**Problem: `claude` command fails with authentication error.** - Run `claude` once interactively to complete authentication. - If using API key auth, verify `ANTHROPIC_API_KEY` is set correctly. - Background update may be in progress — wait 10 seconds and retry. -**Problem**: `gh` CLI not authenticated. +**Problem: `gh` CLI not authenticated.** - Run `gh auth status` to check current state. - Run `gh auth login` for interactive setup. -- Or configure `.devcontainer/.secrets` with `GH_TOKEN` for automatic auth on container start. +- Or configure `.devcontainer/.secrets` with `GH_TOKEN` for automatic auth on container start. See [Configuration — Secrets](../customization/configuration/#secrets-file). - Credentials persist in `/workspaces/.gh/` across rebuilds. -**Problem**: Claude auth token not taking effect in Codespaces. +**Problem: Claude auth token not taking effect in Codespaces.** - When `CLAUDE_AUTH_TOKEN` is set via Codespaces secrets, it persists as an environment variable for the entire container lifetime. The `unset` in `setup-auth.sh` only clears it in the child process. This is a Codespaces platform limitation. - If `.credentials.json` already exists, the token injection is skipped (idempotent). Delete `~/.claude/.credentials.json` to force re-creation from the token. -**Problem**: Git push fails with permission error. +**Problem: Git push fails with permission error.** - Run `gh auth status` to verify authentication. - Check git remote URL: `git remote -v`. HTTPS remotes require `gh` auth; SSH remotes require SSH keys. - Verify `git config --global user.name` and `user.email` are set. -**Problem**: NPM publish/install fails with 401. +**Problem: NPM publish/install fails with 401.** - Set `NPM_TOKEN` in `.devcontainer/.secrets` or as environment variable. - Verify token: `npm whoami`. ## Feature Installation Failures -**Problem**: Feature checksum verification fails. +**Problem: Feature checksum verification fails.** - This usually means a corrupted download. Rebuild the container to retry. - If persistent, the release may have been re-tagged. Try pinning a specific version in `devcontainer.json`. -**Problem**: Feature download fails after retries. +**Problem: Feature download fails after retries.** - Check internet connectivity. - GitHub may be experiencing issues — check [githubstatus.com](https://www.githubstatus.com/). - Set `GH_TOKEN` environment variable to avoid rate limiting. -**Problem**: Permission denied during feature install. +**Problem: Permission denied during feature install.** - Features run as root during build. This shouldn't happen in normal use. -- If modifying features, ensure `install.sh` has `chmod +x` and starts with `#!/bin/bash`. +- If modifying features, ensure `install.sh` has execute permissions and starts with `#!/bin/bash`. ## Plugin Issues -**Problem**: Plugin not loading or not appearing in Claude Code. +**Problem: Plugin not loading or not appearing in Claude Code.** -- Check `enabledPlugins` in `config/defaults/settings.json` — the plugin must be listed there. +- Check `enabledPlugins` in `.devcontainer/config/defaults/settings.json` — the plugin must be listed there. - Verify the plugin directory exists under `plugins/devs-marketplace/plugins/`. - Run `check-setup` to verify core configuration is correct. - Check plugin blacklist: ensure it's not in `PLUGIN_BLACKLIST` in `.env`. -**Problem**: Auto-formatter or auto-linter not running. +**Problem: Auto-formatter or auto-linter not running.** - These run on the Stop hook — they only trigger when Claude Code stops (end of conversation turn). - Verify the underlying tools are installed: `cc-tools` lists all available tools. - Check the 30-second timeout hasn't been exceeded (large file sets may hit this). -## Agent Teams / tmux Issues +## Agent Teams and tmux Issues -**Problem**: Split panes not working. +**Problem: Split panes not working.** - Agent Teams requires tmux. Use the **"Claude Teams (tmux)"** terminal profile in VS Code. - Verify tmux is installed: `tmux -V`. - If using an external terminal, connect via `connect-external-terminal.sh`. -**Problem**: tmux Unicode/emoji rendering broken. +**Problem: tmux Unicode/emoji rendering broken.** - Ensure locale is set: `echo $LANG` should show `en_US.UTF-8`. - If not, run `source ~/.bashrc` or open a new terminal. ## "Command Not Found" Errors -**Problem**: `cc: command not found` or similar. +**Problem: `cc: command not found` or similar.** - Run `source ~/.bashrc` (or `~/.zshrc`) to reload aliases. - Or open a new terminal. - Verify setup ran: check for `# Claude Code environment and aliases` in your rc file. -**Problem**: Tool not found (e.g., `ruff`, `dprint`). +**Problem: Tool not found (e.g., `ruff`, `dprint`).** - Run `cc-tools` to see which tools are installed. - Check if the feature was disabled with `"version": "none"` in `devcontainer.json`. -- Some tools (like `ruff`) install to `~/.local/bin` — ensure it's in your PATH. +- Some tools (like `ruff`) install to `~/.local/bin` — ensure it's in your `PATH`. ## Performance Issues -**Problem**: Container is slow or running out of memory. +**Problem: Container is slow or running out of memory.** -- CodeForge defaults to 6GB RAM / 12GB swap. Increase in `devcontainer.json` `runArgs`. +- CodeForge defaults to 6 GB RAM / 12 GB swap. Increase in `devcontainer.json` `runArgs`. - Disable features you don't need with `"version": "none"`. - The background Claude Code update runs once on startup — it's not persistent. -**Problem**: Slow startup. +**Problem: Slow startup.** - First start is slower due to `postStartCommand` running all setup scripts. -- Subsequent starts skip unchanged config files (sha256 comparison). -- Disable steps you don't need via `.env` (e.g., `SETUP_PROJECTS=false`). +- Subsequent starts skip unchanged config files (SHA-256 comparison). +- Disable steps you don't need via `.env` (e.g., `SETUP_PROJECTS=false`). See [Environment Variables — Setup Variables](./environment/#setup-variables-env). ## How to Reset to Defaults -1. **Reset config files**: Delete `~/.claude/` and restart the container. `setup-config.sh` will recopy all files from `config/defaults/`. +1. **Reset config files** — delete `~/.claude/` and restart the container. `setup-config.sh` will recopy all files from `config/defaults/`. + +2. **Reset aliases** — delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash /workspaces/.devcontainer/scripts/setup-aliases.sh`. + +3. **Full reset** — rebuild the container from scratch (VS Code: **Dev Containers: Rebuild Container**). -2. **Reset aliases**: Delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash /workspaces/.devcontainer/scripts/setup-aliases.sh`. +4. **Reset a single feature** — set it to `"version": "none"`, rebuild, then set it back to the desired version and rebuild again. -3. **Full reset**: Rebuild the container from scratch (VS Code: "Dev Containers: Rebuild Container"). +## Related -4. **Reset a single feature**: Set it to `"version": "none"`, rebuild, then set it back to the desired version and rebuild again. +- [Configuration](../customization/configuration/) — settings and file manifest reference +- [Environment Variables](./environment/) — all environment variables +- [Commands](./commands/) — CLI commands and slash commands +- [Architecture](./architecture/) — system design and component relationships