diff --git a/README.md b/README.md index ece757a..697d668 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Monorepo for CodeForge — an AI-powered development environment for Claude Code | Package | Description | Version | |---------|-------------|---------| -| [`container/`](container/) | CodeForge DevContainer (`codeforge-dev` on npm) | 2.0.0 | +| [`container/`](container/) | CodeForge DevContainer (`codeforge-dev` on npm) | 2.1.0 | | [`cli/`](cli/) | CodeForge CLI (`codeforge-cli`) | 0.1.0 | | [`dashboard/`](dashboard/) | Session analytics dashboard (Svelte 5 SPA + Bun backend) | — | | [`docs/`](docs/) | Documentation site ([codeforge.core-directive.com](https://codeforge.core-directive.com)) | — | diff --git a/cli/README.md b/cli/README.md index fea5b29..68c0f5e 100755 --- a/cli/README.md +++ b/cli/README.md @@ -2,7 +2,7 @@ CLI for CodeForge development workflows. Manages sessions, plugins, configuration, codebase indexing, and devcontainers. -> **Experimental** — v0.1.0. Ships with CodeForge v2.1.1. +> **Experimental** — v0.1.0. Ships with CodeForge v2.1.0. ## Install diff --git a/container/.codeforge/config/settings.json b/container/.codeforge/config/settings.json index bca1189..f45906e 100644 --- a/container/.codeforge/config/settings.json +++ b/container/.codeforge/config/settings.json @@ -60,7 +60,7 @@ "code-review@anthropics/claude-code": true, "feature-dev@anthropics/claude-code": true, "pr-review-toolkit@anthropics/claude-code": true, - "codeforge-lsp@devs-marketplace": true, + "codeforge-lsp@devs-marketplace": false, "ticket-workflow@devs-marketplace": true, "notify-hook@devs-marketplace": true, "dangerous-command-blocker@devs-marketplace": true, diff --git a/container/.devcontainer/CHANGELOG.md b/container/.devcontainer/CHANGELOG.md index 264be55..962fb16 100644 --- a/container/.devcontainer/CHANGELOG.md +++ b/container/.devcontainer/CHANGELOG.md @@ -22,6 +22,9 @@ ### Scope Guard +- Fix `/dev/null` false positive — redirects to system paths (`/dev/`, `/proc/`, `/sys/`, etc.) are now allowed regardless of the primary command, not just for system commands like `git` or `pip` +- Fix CWD drift — scope root is now persisted on first invocation per session, preventing `cd` commands in Bash from silently changing the enforced scope boundary +- CWD context injector now uses the same persisted scope root, keeping advisory context aligned with enforcement - Fix false positives blocking writes to system paths (`/dev/null`, `/usr/`, `/etc/`, `$HOME/`) — scope guard now only enforces isolation between workspace projects - Remove complex system-command exemption logic (no longer needed) @@ -76,14 +79,6 @@ - Dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling - Document `${CLAUDE_PLUGIN_DATA}` variable in CLAUDE.md for future plugin persistent storage -## v2.1.1 — 2026-03-13 - -### Workspace Scope Guard - -- Fix `/dev/null` false positive — redirects to system paths (`/dev/`, `/proc/`, `/sys/`, etc.) are now allowed regardless of the primary command, not just for system commands like `git` or `pip` -- Fix CWD drift — scope root is now persisted on first invocation per session, preventing `cd` commands in Bash from silently changing the enforced scope boundary -- CWD context injector now uses the same persisted scope root, keeping advisory context aligned with enforcement - ## v2.1.0 — 2026-03-13 ### Spec Workflow v2 — "Spec Packages" diff --git a/container/.devcontainer/CLAUDE.md b/container/.devcontainer/CLAUDE.md index 9853346..e11db37 100644 --- a/container/.devcontainer/CLAUDE.md +++ b/container/.devcontainer/CLAUDE.md @@ -39,7 +39,7 @@ Config files deploy via `.codeforge/file-manifest.json` on every container start Declared in `settings.json` under `enabledPlugins`, auto-activated on start: -- **agent-system** — 21 custom agents (4 workhorse + 17 specialist) + built-in agent redirection +- **agent-system** — 19 custom agents + built-in agent redirection - **skill-engine** — 23 general coding skills + auto-suggestion - **spec-workflow** — 3 spec lifecycle skills (`/spec`, `/build`, `/specs`) + spec-reminder hook - **session-context** — Git state injection, TODO harvesting, commit reminders diff --git a/container/.devcontainer/devcontainer.json b/container/.devcontainer/devcontainer.json index 74f02f9..1f8fd2e 100755 --- a/container/.devcontainer/devcontainer.json +++ b/container/.devcontainer/devcontainer.json @@ -131,7 +131,7 @@ // }, "./features/ast-grep": {}, "./features/tree-sitter": {}, - "./features/lsp-servers": {}, + "./features/lsp-servers": { "version": "none" }, "./features/agent-browser": {}, "./features/kitty-terminfo": {}, "./features/chromaterm": { diff --git a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/.claude-plugin/plugin.json b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/.claude-plugin/plugin.json index a686443..dd27401 100644 --- a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/.claude-plugin/plugin.json +++ b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-system", - "description": "17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement", + "description": "19 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement", "author": { "name": "AnExiledDev" } diff --git a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/AGENT-REDIRECTION.md b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/AGENT-REDIRECTION.md index 8c36137..e54ab78 100644 --- a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/AGENT-REDIRECTION.md +++ b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/AGENT-REDIRECTION.md @@ -207,7 +207,6 @@ agent-system/ │ └── hooks.json # Hook registrations └── scripts/ ├── redirect-builtin-agents.py # The redirection hook - ├── inject-cwd.py # CWD injection for subagents └── guard-readonly-bash.py # Read-only bash enforcement ``` diff --git a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md index a75146d..ca0a215 100644 --- a/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md +++ b/container/.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md @@ -81,12 +81,6 @@ Claude calls the Task tool (spawning a subagent) | +-> Built-in agent name? -> Rewrite to custom agent | +-> Already custom? -> Pass through | - +-> SubagentStart fires (all subagents) - | | - | +-> inject-cwd.py - | | - | +-> Injects working directory as additionalContext - | +-> Subagent works... | +-> TaskCompleted fires @@ -119,7 +113,6 @@ Read-only agents (explorer, researcher, architect, etc.) have their Bash access | Script | Exit 0 | Exit 2 | |--------|--------|--------| | redirect-builtin-agents.py | Allow (or rewrite) | Block with error | -| inject-cwd.py | Inject context | N/A | | guard-readonly-bash.py | Allow command | Block write operation | | task-completed-check.py | Tests pass | Tests fail (block completion) | | teammate-idle-check.py | No incomplete tasks | Has incomplete tasks | diff --git a/container/README.md b/container/README.md index ddcc886..a9a510d 100644 --- a/container/README.md +++ b/container/README.md @@ -83,9 +83,9 @@ tree-sitter (JS/TS/Python), ast-grep, Pyright, TypeScript LSP 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 -### Agents (17) & Skills (35) +### Agents (19) & Skills (34) -The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 23 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills. +The `agent-system` plugin includes 19 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 23 general coding skills, `spec-workflow` adds 3 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills. 4 plugins are official Anthropic contributions. ## Architecture @@ -106,7 +106,7 @@ CodeForge operates in three layers, each building on the one below: **DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 23 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others). -**CodeForge Layer** — The intelligence. 17 plugins register hooks that validate commands, inject context, and enforce safety. 21 agents provide specialized personas. 38 skills offer on-demand reference material. System prompts and rules shape behavior. +**CodeForge Layer** — The intelligence. 17 plugins register hooks that validate commands, inject context, and enforce safety. 19 agents provide specialized personas. 34 skills offer on-demand reference material. System prompts and rules shape behavior. **Claude Code** — The AI assistant, executing tools and coordinating work. CodeForge enhances it through configuration — replacing built-in subagents, adding safety guardrails, and wiring up quality checks that run automatically. @@ -118,11 +118,11 @@ All configuration lives in `.devcontainer/` and deploys automatically on contain | File | What It Configures | User-Modifiable? | |------|--------------------|------------------| -| `config/defaults/settings.json` | Model, plugins, permissions, environment variables | Yes | -| `config/defaults/main-system-prompt.md` | Claude's behavioral guidelines and directives | Yes | -| `config/defaults/keybindings.json` | Keyboard shortcuts | Yes | -| `config/defaults/ccstatusline-settings.json` | Terminal status bar widgets and layout | Yes | -| `config/file-manifest.json` | Which config files deploy and how they update | Yes | +| `.codeforge/config/settings.json` | Model, plugins, permissions, environment variables | Yes | +| `.codeforge/config/main-system-prompt.md` | Claude's behavioral guidelines and directives | Yes | +| `.codeforge/config/keybindings.json` | Keyboard shortcuts | Yes | +| `.codeforge/config/ccstatusline-settings.json` | Terminal status bar widgets and layout | Yes | +| `.codeforge/file-manifest.json` | Which config files deploy and how they update | Yes | | `devcontainer.json` | Container image, features, runtimes, ports | Yes | | `.env` | Setup phase toggles (auth, plugins, aliases, etc.) | Yes | @@ -177,7 +177,7 @@ npm publish ## Changelog -See [CHANGELOG.md](.devcontainer/CHANGELOG.md) for release history. Current version: **2.0.0**. +See [CHANGELOG.md](.devcontainer/CHANGELOG.md) for release history. Current version: **2.1.0**. ## Further Reading diff --git a/container/package.json b/container/package.json index 3ee40ab..806cbcb 100644 --- a/container/package.json +++ b/container/package.json @@ -1,6 +1,6 @@ { "name": "codeforge-dev", - "version": "2.1.1", + "version": "2.1.0", "description": "Complete development container that sets up Claude Code with modular devcontainer features, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.", "main": "setup.js", "bin": { diff --git a/dashboard/README.md b/dashboard/README.md index 0ceab72..d000bff 100644 --- a/dashboard/README.md +++ b/dashboard/README.md @@ -2,12 +2,12 @@ Session analytics dashboard for Claude Code. Parses JSONL session files into a SQLite database and serves a Svelte 5 SPA for browsing sessions, conversations, plans, tasks, agents, and memory. -> **v0.1.0** — Ships with CodeForge v2.1.1. +> **v0.1.0** — Ships with CodeForge v2.1.0. ## Quick Start ```bash -# Development — starts the Bun backend (port 5173) +# Development — starts the Bun backend (port 7847) and Vite frontend (port 5173) bun run dev # Development — starts only the Vite frontend dev server diff --git a/docs/src/content/docs/customization/configuration.md b/docs/src/content/docs/customization/configuration.md index 6925378..963e13f 100644 --- a/docs/src/content/docs/customization/configuration.md +++ b/docs/src/content/docs/customization/configuration.md @@ -15,7 +15,7 @@ The primary configuration file lives at `.codeforge/config/settings.json`. It is ```json { - "model": "opus", + "model": "opus[1m]", "effortLevel": "high", "cleanupPeriodDays": 60, "autoCompact": true, @@ -27,7 +27,7 @@ The primary configuration file lives at `.codeforge/config/settings.json`. It is | Setting | Purpose | Default | |---------|---------|---------| -| `model` | Default Claude model (`opus`, `sonnet`, `haiku`) | `opus` | +| `model` | Default Claude model (`opus[1m]`, `sonnet`, `haiku`) | `opus[1m]` | | `effortLevel` | Response effort (`low`, `medium`, `high`) | `high` | | `cleanupPeriodDays` | Days before old session data is cleaned up | `60` | | `autoCompact` | Automatically compact context when it gets long | `true` | @@ -41,11 +41,10 @@ The `env` block sets environment variables that configure Claude Code internals: ```json { "env": { - "ANTHROPIC_MODEL": "claude-opus-4-6", - "BASH_DEFAULT_TIMEOUT_MS": "240000", + "ANTHROPIC_MODEL": "claude-opus-4-6[1m]", + "BASH_DEFAULT_TIMEOUT_MS": "120000", "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000", "MAX_THINKING_TOKENS": "63999", - "CLAUDE_CODE_SHELL": "zsh", "CLAUDE_CODE_EFFORT_LEVEL": "high", "CLAUDE_CODE_ENABLE_TASKS": "true", "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" @@ -53,7 +52,9 @@ The `env` block sets environment variables that configure Claude Code internals: } ``` -See [Environment Variables](../reference/environment/) for the complete list of available variables and their effects. +:::note[Not Exhaustive] +The `env` block shown above is a subset. Many more environment variables are available — see [Environment Variables](../reference/environment/) for the complete list. +::: ### Permissions @@ -190,7 +191,7 @@ DevContainer features install runtimes and tools. CodeForge pins external featur "features": { "ghcr.io/devcontainers/features/node:1.7.1": { "version": "lts" }, // "ghcr.io/devcontainers/features/rust:1.5.0": { "version": "latest" }, // Opt-in - "ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5": {}, + "./features/claude-code-native": {}, "./features/ruff": { "version": "latest" }, // "./features/ccms": {} // Currently disabled — replaced by `codeforge session search` } @@ -251,6 +252,23 @@ When `CLAUDE_AUTH_TOKEN` is set, `setup-auth.sh` creates `~/.claude/.credentials 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. ::: +## disabled-hooks.json + +The file `.codeforge/config/disabled-hooks.json` controls per-hook disabling. Add script names to the `"disabled"` array to prevent specific hooks from firing, without disabling the entire plugin: + +```json +{ + "disabled": [ + "git-state-injector", + "ticket-linker", + "spec-reminder", + "commit-reminder" + ] +} +``` + +Changes take effect immediately — no container rebuild required. To re-enable a hook, remove its name from the array. See [Hooks — Per-Hook Disable](./hooks/#per-hook-disable) for details. + ## Configuration Precedence When the same setting is defined at multiple levels, the most specific value wins: diff --git a/docs/src/content/docs/customization/hooks.md b/docs/src/content/docs/customization/hooks.md index 899095e..c4aaaef 100644 --- a/docs/src/content/docs/customization/hooks.md +++ b/docs/src/content/docs/customization/hooks.md @@ -259,7 +259,6 @@ Here is a quick reference of all hooks registered by CodeForge's default plugins | Plugin | Hook Point | Script | Purpose | |--------|-----------|--------|---------| | agent-system | PreToolUse (Task) | `redirect-builtin-agents.py` | Swap built-in agents for enhanced custom agents | -| agent-system | SubagentStart | `inject-cwd.py` | Inject working directory into subagent context | | agent-system | TeammateIdle | `teammate-idle-check.py` | Check incomplete tasks before teammate shutdown | | agent-system | TaskCompleted | `task-completed-check.py` | Run test suite after task completion | | auto-code-quality | PostToolUse (Edit\|Write) | `collect-edited-files.py` | Track edited files for batch processing | @@ -269,6 +268,7 @@ Here is a quick reference of all hooks registered by CodeForge's default plugins | auto-code-quality | Stop | `advisory-test-runner.py` | Run affected tests | | session-context | SessionStart | `git-state-injector.py` | Inject git branch, status, recent commits | | session-context | SessionStart | `todo-harvester.py` | Surface TODO/FIXME comments | +| session-context | PostToolUse (Edit\|Write) | `collect-session-edits.py` | Track session file edits for context | | session-context | Stop | `commit-reminder.py` | Remind about uncommitted changes | | dangerous-command-blocker | PreToolUse (Bash) | `block-dangerous.py` | Block destructive bash commands | | protected-files-guard | PreToolUse (Edit\|Write) | `guard-protected.py` | Block edits to sensitive files | @@ -281,7 +281,28 @@ Here is a quick reference of all hooks registered by CodeForge's default plugins | spec-workflow | Stop | `spec-reminder.py` | Remind about spec updates after code changes | | skill-engine | UserPromptSubmit | `skill-suggester.py` | Suggest relevant skills based on prompt content | | ticket-workflow | UserPromptSubmit | `ticket-linker.py` | Auto-fetch GitHub issues/PRs from `#123` references | -| notify-hook | Stop | (bell/OSC) | Desktop notification when Claude finishes | +| notify-hook | Stop | `claude-notify` | Desktop notification when Claude finishes | + +## Per-Hook Disable + +Individual hooks can be disabled without turning off their entire plugin. The file `.codeforge/config/disabled-hooks.json` contains a `"disabled"` array of script names: + +```json +{ + "disabled": [ + "git-state-injector", + "ticket-linker", + "spec-reminder", + "commit-reminder" + ] +} +``` + +To disable a hook, add its script name (without path or extension) to the array. To re-enable, remove it. + +Changes take effect immediately — no container rebuild or session restart required. This is useful for temporarily silencing noisy hooks or disabling hooks that conflict with your workflow without losing the rest of the plugin's functionality. + +See also [Optional Features — Per-Hook Disable](./optional-features/#per-hook-disable) for more examples. ## Related diff --git a/docs/src/content/docs/customization/index.md b/docs/src/content/docs/customization/index.md index 39537d9..f0a09c7 100644 --- a/docs/src/content/docs/customization/index.md +++ b/docs/src/content/docs/customization/index.md @@ -21,7 +21,7 @@ Customization works through four layers, each targeting a different aspect of th | Layer | What It Controls | Key Files | Documentation | |-------|-----------------|-----------|---------------| -| [Configuration](./configuration/) | Feature flags, plugin toggles, runtime settings, container setup | `settings.json`, `devcontainer.json`, `file-manifest.json` | Settings and deployment | +| [Configuration](./configuration/) | Feature flags, plugin toggles, runtime settings, container setup | `settings.json`, `devcontainer.json`, `file-manifest.json`, `disabled-hooks.json` | Settings and deployment | | [System Prompts](./system-prompts/) | Claude Code behavior, coding standards, response style | `main-system-prompt.md`, `writing-system-prompt.md` | Behavioral guidance | | [Rules](./rules/) | Hard constraints applied to all sessions | `.claude/rules/*.md` | Mandatory requirements | | [Hooks](./hooks/) | Scripts that run at lifecycle points | `hooks.json` + Python scripts | Automation and validation | @@ -38,9 +38,9 @@ Edit `settings.json` and change the `model` field: ```json { - "model": "sonnet", + "model": "opus[1m]", "env": { - "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929" + "ANTHROPIC_MODEL": "claude-opus-4-6[1m]" } } ``` diff --git a/docs/src/content/docs/customization/keybindings.md b/docs/src/content/docs/customization/keybindings.md index 67ae8ee..97ffc04 100644 --- a/docs/src/content/docs/customization/keybindings.md +++ b/docs/src/content/docs/customization/keybindings.md @@ -88,6 +88,10 @@ Edit `.codeforge/config/keybindings.json` to remap Claude Code actions to non-co The keybindings file is deployed to `~/.claude/keybindings.json` on container start via `file-manifest.json`. +:::note[Shipped Default] +CodeForge ships with an empty bindings array (`"bindings": []`) in `.codeforge/config/keybindings.json`. No custom keybindings are active by default — add your own entries to the array using the format above. +::: + ## Claude Code Shortcut Reference Full list of default Claude Code shortcuts (these work when Claude Code has terminal focus): diff --git a/docs/src/content/docs/customization/optional-features.md b/docs/src/content/docs/customization/optional-features.md index 4dc755b..ef4e456 100644 --- a/docs/src/content/docs/customization/optional-features.md +++ b/docs/src/content/docs/customization/optional-features.md @@ -7,6 +7,147 @@ sidebar: CodeForge includes several features that are available but not enabled by default. This page covers how to enable and configure them. +## Per-Hook Disable + +Individual hooks can be disabled without turning off their entire plugin. The file `.codeforge/config/disabled-hooks.json` contains a `"disabled"` array of script names: + +```json +{ + "disabled": [ + "git-state-injector", + "ticket-linker", + "spec-reminder", + "commit-reminder" + ] +} +``` + +Add a hook's script name (without path or extension) to disable it. Remove it to re-enable. Changes take effect immediately — no container rebuild required. + +This is useful when a hook is noisy or conflicts with your workflow but you want the rest of the plugin to keep running. See [Hooks — Per-Hook Disable](./hooks/#per-hook-disable) for the full reference. + +## LSP Servers + +Language Server Protocol servers provide inline diagnostics, go-to-definition, and completions for supported languages. LSP servers are disabled by default. + +### Enabling + +1. In `devcontainer.json`, set the `lsp-servers` feature version to `"latest"`: + +```json +"./features/lsp-servers": { "version": "latest" } +``` + +2. In `settings.json`, ensure the `codeforge-lsp` plugin is enabled: + +```json +{ + "enabledPlugins": { + "codeforge-lsp@devs-marketplace": true + } +} +``` + +3. Rebuild the container. + +## Dashboard + +The CodeForge Dashboard is a Svelte 5 SPA for visual session analytics, conversation replay, task/plan/agent views, and cost tracking. It is opt-in. + +### Enabling + +Uncomment or add the `claude-session-dashboard` feature in `devcontainer.json`, or use the `codeforge-dashboard` feature: + +```json +"./features/codeforge-dashboard": {} +``` + +Rebuild the container after enabling. The dashboard runs on a forwarded port — check the container's port list after startup. + +## ccms (Claude Code Memory Search) + +A Rust-based session search tool. Replaced in the default build by `codeforge session search`, but still available as an opt-in feature. + +### Enabling + +Uncomment the `ccms` entry in `devcontainer.json`: + +```json +"./features/ccms": {} +``` + +:::caution[Requires Rust] +ccms is a Rust binary. Enabling it also requires the Rust toolchain — uncomment the Rust feature as well if it is not already enabled. +::: + +## ccburn + +A terminal burn-down visualization tool. Currently commented out in the default build — it has been replaced by `ccstatusline`. + +If you want the older burn-down view, uncomment it in `devcontainer.json`: + +```json +"./features/ccburn": {} +``` + +:::note +`ccstatusline` is the active replacement and is enabled by default. Only enable ccburn if you specifically need its burn-down visualization. +::: + +## Rust Toolchain + +The Rust compiler and Cargo are available as an opt-in feature for projects that need Rust compilation (including ccms). + +### Enabling + +Uncomment the Rust feature in `devcontainer.json`: + +```json +"ghcr.io/devcontainers/features/rust:1.5.0": { "version": "latest" } +``` + +Rebuild the container after enabling. + +## Go Runtime + +The Go compiler and toolchain are available as an opt-in feature for projects that include Go code. + +### Enabling + +Uncomment the Go feature in `devcontainer.json`: + +```json +"ghcr.io/devcontainers/features/go:1": { "version": "latest" } +``` + +Rebuild the container after enabling. + +## Formatters and Linters + +Several formatters and linters are present in `devcontainer.json` but disabled by default (set to `"version": "none"`). To enable any of them, change the version to `"latest"` and rebuild: + +| Tool | Feature Path | Purpose | +|------|-------------|---------| +| shfmt | `./features/shfmt` | Shell script formatter | +| dprint | `./features/dprint` | Pluggable code formatter (Markdown, TOML, JSON, etc.) | +| shellcheck | `./features/shellcheck` | Shell script static analysis | +| hadolint | `./features/hadolint` | Dockerfile linter | + +### Example + +```json +{ + "features": { + "./features/shfmt": { "version": "latest" }, + "./features/dprint": { "version": "latest" }, + "./features/shellcheck": { "version": "latest" }, + "./features/hadolint": { "version": "latest" } + } +} +``` + +These tools integrate with the auto-code-quality plugin — once installed, they are automatically invoked at Stop for any files they support. + ## 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 using `qdrant-store` and `qdrant-find` tools. diff --git a/docs/src/content/docs/customization/rules.md b/docs/src/content/docs/customization/rules.md index 42c1d39..9f404a9 100644 --- a/docs/src/content/docs/customization/rules.md +++ b/docs/src/content/docs/customization/rules.md @@ -50,11 +50,11 @@ Key requirements: ### Session Search (`session-search.md`) -Configures the `ccms` session history search tool. Mandates project-scoped searches to prevent cross-project information leakage, and requires CLI mode (no interactive TUI) for automation compatibility. _(Note: `ccms` is currently disabled in the default container build. This rule remains deployed so it takes effect if ccms is re-enabled.)_ +Configures the `codeforge session search` tool. Mandates project-scoped searches to prevent cross-project information leakage, and requires non-interactive mode for automation compatibility. Key requirements: - Always pass `--project ` to scope results -- Always pass a query string (no bare `ccms` TUI mode) +- Always pass a query string (non-interactive mode) - Use `--no-color` for clean output parsing - Default to `-n 20` to limit result count @@ -99,7 +99,7 @@ Claude treats rule file content as mandatory. If you write "consider using X," C └── rules/ ├── spec-workflow.md # Built-in: specification workflow ├── workspace-scope.md # Built-in: project isolation - ├── session-search.md # Built-in: ccms configuration + ├── session-search.md # Built-in: session search configuration ├── coding-standards.md # Custom: your team's standards ├── git-workflow.md # Custom: branching and commit rules └── security.md # Custom: security requirements diff --git a/docs/src/content/docs/customization/system-prompts.md b/docs/src/content/docs/customization/system-prompts.md index a70cbba..0c5ea2c 100644 --- a/docs/src/content/docs/customization/system-prompts.md +++ b/docs/src/content/docs/customization/system-prompts.md @@ -5,7 +5,7 @@ sidebar: order: 3 --- -System prompts define how Claude Code behaves during your sessions -- its coding style, response format, tool usage patterns, and decision-making priorities. CodeForge ships two system prompts: one for development work and one for writing tasks. +System prompts define how Claude Code behaves during your sessions -- its coding style, response format, tool usage patterns, and decision-making priorities. CodeForge ships three system prompts: one for development work, one for writing tasks, and one for delegation-first orchestration. ## Main System Prompt @@ -66,6 +66,23 @@ The writing system prompt is activated when you launch Claude with the `ccw` com Use `cc` for coding sessions and `ccw` for writing sessions. Both are shell aliases that point Claude Code at different system prompt files. ::: +## Orchestrator System Prompt + +The orchestrator system prompt is activated when you launch Claude with the `cc-orc` command. It configures a delegation-first orchestrator mode where Claude prioritizes decomposing work into subagent tasks rather than doing everything inline. + +**Location:** `.codeforge/config/orchestrator-system-prompt.md` +**Deployed to:** `~/.claude/orchestrator-system-prompt.md` + +### Key Differences from Main Prompt + +- Prioritizes task decomposition and subagent delegation over inline execution +- Optimized for multi-agent workflows where the orchestrator coordinates rather than implements +- Designed for complex tasks that benefit from parallel subagent execution + +:::tip[When to Use] +Use `cc` for standard coding sessions, `ccw` for writing sessions, and `cc-orc` for complex tasks where delegation-first orchestration produces better results. +::: + ## Customizing Prompts ### Editing the Main Prompt diff --git a/docs/src/content/docs/features/agents.md b/docs/src/content/docs/features/agents.md index c98693d..d3be4b7 100644 --- a/docs/src/content/docs/features/agents.md +++ b/docs/src/content/docs/features/agents.md @@ -1,11 +1,11 @@ --- title: Agents -description: Complete reference for all 21 CodeForge agents — capabilities, tool access, and use cases. +description: Complete reference for all 19 CodeForge agents — capabilities, tool access, and use cases. sidebar: order: 2 --- -CodeForge provides 21 specialized agents, each configured with a focused system prompt, specific tool access, and domain expertise. Claude automatically delegates to the appropriate agent based on your request — ask about architecture and you get the architect; ask for a security review and you get the security auditor. +CodeForge provides 19 specialized agents, each configured with a focused system prompt, specific tool access, and domain expertise. Claude automatically delegates to the appropriate agent based on your request — ask about architecture and you get the architect; ask for a security review and you get the security auditor. ## How Agents Work @@ -30,7 +30,7 @@ CodeForge **entirely replaces** all six built-in agents with enhanced custom spe The redirect is fully transparent — you can use either the built-in name or the custom name interchangeably. Asking Claude to "explore the codebase" triggers the same enhanced explorer agent whether the system selects the `Explore` type or the `explorer` type. -Beyond the six replacements, CodeForge adds **15 entirely new specialists** that have no built-in equivalent: debug-logs, dependency-analyst, doc-writer, documenter, git-archaeologist, implementer, investigator, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, tester, and test-writer. These are available only in CodeForge. +Beyond the six replacements, CodeForge adds **13 entirely new specialists** that have no built-in equivalent: debug-logs, dependency-analyst, documenter, git-archaeologist, implementer, investigator, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, and test-writer. These are available only in CodeForge. :::tip[Why This Matters] The redirect happens at the hook level, not the prompt level. This means the upgrade is enforced — not suggested. Even if Claude's internal routing tries to use a stock Explore agent, the hook intercepts the call and swaps in the enhanced explorer before any code executes. The result is a strictly better agent every time, with zero user effort. @@ -110,28 +110,16 @@ Analyzes project dependencies for outdated packages, security vulnerabilities, v "Audit the project dependencies for security vulnerabilities and outdated packages." ::: -### doc-writer - -Full (worktree) Opus documentation-patterns - -A technical writing specialist that creates and maintains README files, API documentation, inline comments (docstrings, JSDoc), and architectural guides. Reads and understands your code first, then produces documentation that reflects actual verified behavior — never aspirational or assumed behavior. Works in a git worktree for safe isolation. - -**When activated:** "Write a README," "document this module," "add docstrings," API documentation requests. - -:::tip[Try this] -"Document the public API for the user service module. Include usage examples and parameter descriptions." -::: - ### documenter -Full Opus documentation-patterns spec build specs +Full (worktree) Opus documentation-patterns spec build specs -A documentation and specification lifecycle agent. Handles READMEs, API docs, inline documentation, and architectural guides alongside the full spec workflow — creating, refining, and building from spec packages. Carries 4 frontloaded skills covering documentation patterns and all 3 spec operations. Unlike doc-writer, the documenter works directly (no worktree isolation) and owns the spec lifecycle. Never modifies source code logic. +A documentation and specification lifecycle agent. Handles READMEs, API docs, inline documentation, and architectural guides alongside the full spec workflow — creating, refining, and building from spec packages. Carries 4 frontloaded skills covering documentation patterns and all 3 spec operations. Works in a git worktree for safe isolation and owns the spec lifecycle. Never modifies source code logic. **When activated:** "Document this module," "write a README," "create a spec and document the feature," specification lifecycle tasks that combine docs and specs. -:::tip[documenter vs doc-writer] -Use **doc-writer** for pure documentation tasks (READMEs, docstrings, API docs) where worktree isolation is preferred. Use **documenter** when documentation and specification work are interleaved — it has the full spec skill set (`/spec`, `/build`, `/specs`) built in. +:::tip[Try this] +"Create a spec for the notification feature and document the public API alongside it." ::: ### explorer @@ -148,7 +136,7 @@ A fast codebase navigator for file discovery, pattern matching, and structural a ### generalist -Full Sonnet +Full Inherited The general-purpose development agent for tasks that don't fit a specialized role. Has access to all tools and can handle mixed workloads — small features, bug fixes, multi-file investigations, and miscellaneous development tasks. Used when no specialist clearly matches. @@ -196,7 +184,7 @@ Use the **investigator** when an investigation spans multiple domains (e.g., "wh ### migrator -Full (worktree) Opus migration-patterns +Full (worktree) Opus Plans and executes framework upgrades, language version bumps, API changes, and dependency migrations. Works methodically — creating a migration plan, transforming code in controlled steps, and verifying functionality after each change. Uses web research to consult official migration guides. Works in a git worktree so your main branch stays clean. @@ -220,7 +208,7 @@ A performance engineer that measures application performance, identifies bottlen ### refactorer -Full (worktree) Opus refactoring-patterns +Full (worktree) Opus A disciplined refactoring specialist that performs behavior-preserving code transformations. Identifies code smells (god classes, deep nesting, duplication, long parameter lists), applies established refactoring patterns (extract function, replace conditional with polymorphism, introduce parameter object), and rigorously verifies that tests pass after every single edit via a PostToolUse hook. Works in a git worktree. @@ -232,7 +220,7 @@ A disciplined refactoring specialist that performs behavior-preserving code tran ### researcher -Read-only Sonnet documentation-patterns +Read-only Sonnet A technical research analyst that investigates codebases, searches documentation, and gathers web-based evidence to answer technical questions. Follows a disciplined codebase-first, web-second approach — local evidence is more reliable than generic documentation. Evaluates source recency, authority, and specificity. Produces structured reports with citations. @@ -278,21 +266,9 @@ A specialist for configuring the Claude Code terminal statusline. Converts shell "Convert my current PS1 prompt to a Claude Code statusline. Include git branch, Python version, and working directory." ::: -### tester - -Full (worktree) Opus testing build - -A test suite creation and verification agent. Analyzes existing code, writes comprehensive tests, and ensures all tests pass before completing via a Stop hook. Supports pytest, Vitest, Jest, Go testing, and Rust test frameworks. Works in a git worktree. Functionally equivalent to test-writer with the addition of the build skill for closing the spec loop after writing tests. - -**When activated:** "Write tests for," "add test coverage," "create integration tests," test creation tasks. - -:::tip[tester vs test-writer] -These agents are nearly identical. **tester** includes the `/build` skill for spec-driven workflows. **test-writer** is the built-in replacement agent. Both produce the same quality of tests — use whichever surfaces based on your request. -::: - ### test-writer -Full (worktree) Opus testing +Full (worktree) Opus A senior test engineer that analyzes existing code and writes comprehensive test suites. Detects test frameworks (pytest, Vitest, Jest, Go testing, Rust tests), follows project conventions exactly, and verifies all written tests pass before completing. A Stop hook automatically checks that no tests are failing when the agent finishes. Works in a git worktree. Never modifies source code — if a bug is found, it reports the bug rather than fixing it. @@ -311,29 +287,27 @@ A senior test engineer that analyzes existing code and writes comprehensive test | claude-guide | Read-only | Haiku | -- | -- | claude-code-headless, claude-agent-sdk | | debug-logs | Read-only | Sonnet | -- | -- | debugging | | dependency-analyst | Read-only | Haiku | -- | Yes | dependency-management | -| doc-writer | Full | Opus | Worktree | -- | documentation-patterns | -| documenter | Full | Opus | -- | -- | documentation-patterns, spec, build, specs | +| documenter | Full | Opus | Worktree | -- | documentation-patterns, spec, build, specs | | explorer | Read-only | Haiku | -- | -- | ast-grep-patterns | | generalist | Full | Inherited | -- | -- | spec workflow | | git-archaeologist | Read-only | Haiku | -- | -- | git-forensics | | implementer | Full | Opus | Worktree | -- | refactoring-patterns, migration-patterns, build | | investigator | Read-only | Sonnet | -- | -- | documentation-patterns, git-forensics, performance-profiling, debugging, dependency-management, ast-grep-patterns | -| migrator | Full | Opus | Worktree | -- | migration-patterns | +| migrator | Full | Opus | Worktree | -- | -- | | perf-profiler | Read-only | Sonnet | -- | Yes | performance-profiling | -| refactorer | Full | Opus | Worktree | -- | refactoring-patterns | -| researcher | Read-only | Sonnet | -- | -- | documentation-patterns | +| refactorer | Full | Opus | Worktree | -- | -- | +| researcher | Read-only | Sonnet | -- | -- | -- | | security-auditor | Read-only | Sonnet | -- | Yes | security-checklist | | spec-writer | Read-only | Opus | -- | -- | spec, specs | | statusline-config | Full | Sonnet | -- | -- | -- | -| tester | Full | Opus | Worktree | -- | testing, build | -| test-writer | Full | Opus | Worktree | -- | testing | +| test-writer | Full | Opus | Worktree | -- | -- | ## Access Levels at a Glance | Access Level | Agents | |-------------|--------| | **Read-only** | architect, claude-guide, debug-logs, dependency-analyst, explorer, git-archaeologist, investigator, perf-profiler, researcher, security-auditor, spec-writer | -| **Full** | bash-exec, doc-writer, documenter, generalist, implementer, migrator, refactorer, statusline-config, tester, test-writer | +| **Full** | bash-exec, documenter, generalist, implementer, migrator, refactorer, statusline-config, test-writer | :::note[About Model Selection] Agents use different Claude models based on task complexity. Opus handles the most demanding tasks (architecture, refactoring, test writing, migration). Sonnet covers analytical tasks that need strong reasoning (security audits, research, debugging). Haiku powers fast, focused tasks (exploration, dependency analysis, git history). The generalist inherits whichever model the main session is using. @@ -346,7 +320,7 @@ Several agents include built-in safety hooks: - **Read-only bash guard** — The architect, explorer, investigator, security auditor, dependency analyst, and git-archaeologist all have a PreToolUse hook that blocks any Bash command that could modify files or state. - **Git-readonly guard** — The git-archaeologist has a specialized guard that only permits read-only git subcommands (log, blame, show, diff, reflog, etc.). - **Post-edit test verification** — The refactorer runs tests automatically after every single Edit operation. If tests fail, the change is immediately reverted. -- **Stop verification** — The test-writer and tester have a Stop hook that verifies all written tests pass before the agent completes. The implementer has a similar Stop hook that runs regression checks. +- **Stop verification** — The test-writer has a Stop hook that verifies all written tests pass before the agent completes. The implementer has a similar Stop hook that runs regression checks. ## Related diff --git a/docs/src/content/docs/features/code-intelligence.md b/docs/src/content/docs/features/code-intelligence.md index 65bbd23..b1d57c0 100644 --- a/docs/src/content/docs/features/code-intelligence.md +++ b/docs/src/content/docs/features/code-intelligence.md @@ -147,6 +147,10 @@ In practice, Claude and the specialized agents use ast-grep for cross-file patte LSP servers provide semantic code intelligence — they understand types, scopes, definitions, and references at a level that syntax analysis alone cannot reach. CodeForge configures LSP servers for your installed language runtimes, giving Claude access to the same "go to definition" and "find references" operations your IDE provides. +:::note[Opt-In Feature] +LSP servers are disabled by default. To enable them, set the `codeforge-lsp` feature to `"latest"` in `devcontainer.json` and rebuild the container. +::: + ### Installed LSP Servers | Language | Server | Version | diff --git a/docs/src/content/docs/features/index.md b/docs/src/content/docs/features/index.md index c1f7a46..37bf1fe 100644 --- a/docs/src/content/docs/features/index.md +++ b/docs/src/content/docs/features/index.md @@ -13,8 +13,8 @@ This section is your reference guide to everything CodeForge provides. Whether y Out of the box, CodeForge gives you: -- **21 specialized AI agents** with focused expertise and safety-calibrated tool access -- **38 domain knowledge packs** (skills) for frameworks, patterns, and workflows +- **19 specialized AI agents** with focused expertise and safety-calibrated tool access +- **34 domain knowledge packs** (skills) for frameworks, patterns, and workflows - **23 CLI tools** for session management, code quality, and development - **3 layers of code intelligence** — AST-based search, syntax parsing, and LSP semantic analysis - **Visual analytics dashboard** with session replay, cost tracking, and activity heatmaps @@ -25,27 +25,27 @@ All of these features work together. An agent can load skills for domain experti ## AI Agents -CodeForge includes **21 specialized AI agents**, each with focused expertise, calibrated tool access, and a detailed system prompt that shapes its behavior. When you ask Claude a question, the agent system automatically delegates to the right specialist — an architect for design questions, a security auditor for vulnerability reviews, a test writer for coverage gaps. +CodeForge includes **19 specialized AI agents**, each with focused expertise, calibrated tool access, and a detailed system prompt that shapes its behavior. When you ask Claude a question, the agent system automatically delegates to the right specialist — an architect for design questions, a security auditor for vulnerability reviews, a test writer for coverage gaps. Agents fall into two categories: - **Read-only agents** (11 total) — can search, read, and analyze your codebase but never modify it. These include the architect, explorer, investigator, security auditor, researcher, dependency analyst, and spec-writer. -- **Full-access agents** (10 total) — can read, write, and execute commands. These include the implementer, tester, documenter, test writer, refactorer, migrator, doc writer, and generalist. +- **Full-access agents** (8 total) — can read, write, and execute commands. These include the implementer, documenter, test writer, refactorer, migrator, and generalist. -A key distinction: CodeForge doesn't just add new agents — it **replaces Claude Code's six built-in agent types entirely**. A `PreToolUse` hook intercepts every agent spawn and transparently redirects stock agents (Explore, Plan, general-purpose, Bash, claude-code-guide, statusline-setup) to enhanced custom specialists with frontloaded skills, calibrated models, and safety hooks. You never interact with a generic agent — every request is silently upgraded. The remaining 15 agents (test-writer, refactorer, security-auditor, and others) are entirely new specialists with no built-in equivalent. +A key distinction: CodeForge doesn't just add new agents — it **replaces Claude Code's six built-in agent types entirely**. A `PreToolUse` hook intercepts every agent spawn and transparently redirects stock agents (Explore, Plan, general-purpose, Bash, claude-code-guide, statusline-setup) to enhanced custom specialists with frontloaded skills, calibrated models, and safety hooks. You never interact with a generic agent — every request is silently upgraded. The remaining 13 agents (test-writer, refactorer, security-auditor, and others) are entirely new specialists with no built-in equivalent. Key safety features set CodeForge agents apart: -- **Worktree isolation** — agents like the refactorer, test-writer, migrator, and doc-writer work in git worktrees, so their changes never touch your working branch until you merge them. +- **Worktree isolation** — agents like the refactorer, test-writer, migrator, and implementer work in git worktrees, so their changes never touch your working branch until you merge them. - **Background execution** — agents like the security auditor, dependency analyst, and perf profiler run asynchronously, returning results while you continue working. - **Hook enforcement** — read-only agents have bash guards that block any command that could modify files. The refactorer runs tests after every single edit. The test writer verifies all tests pass before completing. - **Built-in replacement** — all six of Claude Code's stock agents are intercepted at the hook level and replaced with strictly better specialists. This is enforced, not suggested. -[View all 21 agents →](./agents/) +[View all 19 agents →](./agents/) ## Skills -**38 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. The skill engine provides 23 core skills covering frameworks, practices, and Claude/CodeForge topics. Additional skills come from the spec-workflow (8), ticket-workflow (4), git-workflow (2), agent-system (1), and prompt-snippets (1) plugins. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task. +**34 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. The skill engine provides 23 core skills covering frameworks, practices, and Claude/CodeForge topics. Additional skills come from the spec-workflow (3), ticket-workflow (4), git-workflow (2), agent-system (1), and prompt-snippets (1) plugins. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task. Each skill is built around a "mental model" — a concise explanation of how a technology works, followed by concrete patterns, code examples, and guidance. This is not generic documentation; skills encode the kind of working knowledge a senior specialist carries. @@ -57,7 +57,7 @@ Skills cover three categories: | **Practices** | Testing, Debugging, Security, Refactoring, API Design | Methodology, checklists, and established patterns | | **Claude & CodeForge** | Agent SDK, Headless Mode, Skill Building, Spec Writing | Guidance for building on and extending CodeForge itself | -[View all 38 skills →](./skills/) +[View all 34 skills →](./skills/) ## CLI Tools @@ -103,8 +103,8 @@ The **memory management system** lets you review and curate the observations Cla | Category | Count | Highlights | |----------|-------|------------| -| [Agents](./agents/) | 21 | Architect, Explorer, Security Auditor, Test Writer, Refactorer, and 16 more | -| [Skills](./skills/) | 38 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 32 more | +| [Agents](./agents/) | 19 | Architect, Explorer, Security Auditor, Test Writer, Refactorer, and 14 more | +| [Skills](./skills/) | 34 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 28 more | | [CLI Tools](./tools/) | 23 | Session search, token tracking, code quality, formatters, and runtimes | | [Code Intelligence](./code-intelligence/) | 3 | ast-grep, tree-sitter, LSP servers for Python/TS/Go | | [Dashboard](./dashboard/) | -- | Session replay, cost tracking, activity heatmaps, real-time SSE updates | diff --git a/docs/src/content/docs/features/skills.md b/docs/src/content/docs/features/skills.md index 2cfae32..894dc44 100644 --- a/docs/src/content/docs/features/skills.md +++ b/docs/src/content/docs/features/skills.md @@ -1,6 +1,6 @@ --- title: Skills -description: Complete reference for all 38 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. +description: Complete reference for all 34 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. sidebar: order: 3 --- @@ -219,13 +219,21 @@ Git worktree creation, management, and cleanup for parallel development workflow **Auto-suggested when:** You mention creating a worktree, `EnterWorktree`, git worktree commands, parallel branches, or isolating work. +### agent-browser + +Headless Chromium browser automation using Playwright for agents that need to inspect web content, take screenshots, or interact with web UIs. Covers browser launch, page navigation, element interaction, and screenshot capture patterns. + +**Key topics:** Playwright headless Chromium, page navigation, screenshot capture, element selectors, waiting strategies, cookie and session management. + +**Auto-suggested when:** You mention browser automation, taking screenshots, inspecting a web page, or headless browsing. + ## Skill Categories Summary | Category | Skills | Focus | |----------|--------|-------| | **Frameworks** | fastapi, svelte5, pydantic-ai, docker, docker-py, sqlite | Framework-specific patterns and APIs | | **Practices** | testing, debugging, refactoring-patterns, security-checklist, api-design, documentation-patterns, performance-profiling, dependency-management, migration-patterns | Methodologies and established patterns | -| **Claude & CodeForge** | claude-code-headless, claude-agent-sdk, skill-building, git-forensics, ast-grep-patterns, team, worktree | Building on and extending the Claude ecosystem | +| **Claude & CodeForge** | claude-code-headless, claude-agent-sdk, skill-building, git-forensics, ast-grep-patterns, team, worktree, agent-browser | Building on and extending the Claude ecosystem | :::note[Skills vs Agents] Skills and agents serve different purposes. An **agent** is a specialized Claude instance with specific tools and constraints — it *does work*. A **skill** is a knowledge pack that *informs work* — it provides the patterns, best practices, and domain knowledge that make an agent (or the main Claude session) more effective. Many agents have associated skills that load automatically when the agent is spawned. diff --git a/docs/src/content/docs/features/tools.md b/docs/src/content/docs/features/tools.md index 4f9ac6b..2320ec8 100644 --- a/docs/src/content/docs/features/tools.md +++ b/docs/src/content/docs/features/tools.md @@ -174,6 +174,35 @@ codeforge container ls When run outside the container, commands auto-proxy into the running devcontainer. Use `--local` to run against the host filesystem. +### codeforge proxy — API Traffic Inspection + +Launch Claude Code through mitmproxy to inspect API traffic between Claude and the Anthropic API. Useful for debugging prompt construction, token usage, and request/response payloads. + +```bash +# Launch Claude Code with traffic inspection on port 8081 +codeforge proxy +``` + +The proxy runs on port 8081. Open the mitmproxy web interface to view, filter, and inspect all API calls in real time. + +### dbr — Devcontainer Bridge + +Dynamic port forwarding bridge for the devcontainer. Forwards ports between the host and the running devcontainer, enabling access to services running inside the container from the host machine. + +```bash +# Start the devcontainer bridge +dbr +``` + +### ccstatusline — Terminal Status Bar + +A status bar widget for your terminal prompt that displays contextual information about your current Claude Code session — active agent, model, token usage, and session status. Integrates with your shell prompt to provide at-a-glance session awareness. + +```bash +# Configure the statusline +ccstatusline +``` + ## Code Quality Tools These tools are used both manually and automatically by the [Auto Code Quality Plugin](../plugins/auto-code-quality/) to maintain code standards. @@ -233,28 +262,31 @@ CodeForge uses `uv` as the default Python package manager. It is significantly f | # | Command | Category | Description | |---|---------|----------|-------------| | 1 | `cc` / `claude` | Session | Claude Code with CodeForge config | -| 2 | `ccraw` | Session | Vanilla Claude Code | -| 3 | `ccw` | Session | Claude Code in writing mode | -| 4 | `ccms` | Session | Session history search _(currently disabled)_ | -| 5 | `ccusage` | Session | API usage statistics | -| 6 | `ccburn` | Session | Token burn analysis | -| 7 | `ccstatusline` | Session | Terminal statusline | -| 8 | `codeforge-dashboard` | Session | Web-based session dashboard | -| 9 | `claude-monitor` | Session | Real-time session monitor | -| 10 | `agent-browser` | Session | Headless browser for agents | -| 11 | `check-setup` | Session | Installation health check | -| 12 | `cc-tools` | Session | List all available tools | -| 13 | `ruff` | Quality | Python linting and formatting | -| 14 | `biome` | Quality | JS/TS/JSON linting and formatting | -| 15 | `shellcheck` | Quality | Shell script linting | -| 16 | `shfmt` | Quality | Shell script formatting | -| 17 | `dprint` | Quality | Markdown/TOML/JSON formatting | -| 18 | `hadolint` | Quality | Dockerfile linting | -| 19 | `sg` / `ast-grep` | Intelligence | Structural code search | -| 20 | `tree-sitter` | Intelligence | Syntax tree parsing | -| 21 | `pyright` | Intelligence | Python LSP server | -| 22 | `typescript-language-server` | Intelligence | TypeScript/JS LSP server | -| 23 | `codeforge` | Session | CodeForge CLI — session search, plugins, indexing _(experimental)_ | +| 2 | `cc-orc` | Session | Claude Code in orchestrator mode (delegation-first) | +| 3 | `ccraw` | Session | Vanilla Claude Code | +| 4 | `ccw` | Session | Claude Code in writing mode | +| 5 | `ccms` | Session | Session history search _(currently disabled)_ | +| 6 | `ccusage` | Session | API usage statistics | +| 7 | `ccburn` | Session | Token burn analysis | +| 8 | `ccstatusline` | Session | Terminal status bar widget | +| 9 | `codeforge-dashboard` | Session | Web-based session dashboard | +| 10 | `claude-monitor` | Session | Real-time session monitor | +| 11 | `agent-browser` | Session | Headless browser for agents | +| 12 | `check-setup` | Session | Installation health check | +| 13 | `cc-tools` | Session | List all available tools | +| 14 | `codeforge` | Session | CodeForge CLI — session search, plugins, indexing _(experimental)_ | +| 15 | `codeforge proxy` | Session | Launch Claude Code through mitmproxy for API traffic inspection | +| 16 | `dbr` | Infrastructure | Devcontainer bridge for dynamic port forwarding | +| 17 | `ruff` | Quality | Python linting and formatting | +| 18 | `biome` | Quality | JS/TS/JSON linting and formatting | +| 19 | `shellcheck` | Quality | Shell script linting | +| 20 | `shfmt` | Quality | Shell script formatting | +| 21 | `dprint` | Quality | Markdown/TOML/JSON formatting | +| 22 | `hadolint` | Quality | Dockerfile linting | +| 23 | `sg` / `ast-grep` | Intelligence | Structural code search | +| 24 | `tree-sitter` | Intelligence | Syntax tree parsing | +| 25 | `pyright` | Intelligence | Python LSP server | +| 26 | `typescript-language-server` | Intelligence | TypeScript/JS LSP server | ## Related diff --git a/docs/src/content/docs/getting-started/devcontainer-cli.md b/docs/src/content/docs/getting-started/devcontainer-cli.md index f278f6b..b1340f4 100644 --- a/docs/src/content/docs/getting-started/devcontainer-cli.md +++ b/docs/src/content/docs/getting-started/devcontainer-cli.md @@ -66,7 +66,7 @@ devcontainer exec --workspace-folder . cc-tools VS Code auto-forwards container ports to your host automatically. **The CLI does not.** You need an explicit forwarding mechanism. :::caution[No automatic port forwarding] -Unlike VS Code, the devcontainer CLI does not auto-forward ports. Services running inside the container (like the Claude Dashboard on port 7847) won't be accessible on your host unless you set up forwarding manually. +Unlike VS Code, the devcontainer CLI does not auto-forward ports. Services running inside the container (like the Claude Dashboard on port 7847) won't be accessible on your host unless you set up forwarding manually. Note that the dashboard requires enabling the feature in your DevContainer configuration. ::: **Recommended:** Install [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge) (`dbr`) for dynamic, automatic port forwarding that works with any terminal client. CodeForge pre-installs the container side — you only need the host daemon: diff --git a/docs/src/content/docs/getting-started/first-session.md b/docs/src/content/docs/getting-started/first-session.md index c193e18..d2e797f 100644 --- a/docs/src/content/docs/getting-started/first-session.md +++ b/docs/src/content/docs/getting-started/first-session.md @@ -91,13 +91,13 @@ cc-tools # Check API token usage ccusage -# Open the session analytics dashboard +# Open the session analytics dashboard (opt-in — requires enabling the feature) codeforge-dashboard ``` ## Agents and Skills -CodeForge includes **21 specialized agents** and **38 skills** that activate automatically based on what you're working on. You don't need to memorize names — just describe what you want, and Claude delegates to the right specialist. The examples in "What to Try First" above show this in action. +CodeForge includes **19 specialized agents** and **34 skills** that activate automatically based on what you're working on. You don't need to memorize names — just describe what you want, and Claude delegates to the right specialist. The examples in "What to Try First" above show this in action. - **[Agents](../features/agents/)** — specialized AI personas for architecture, debugging, testing, security, migrations, and more - **[Skills](../features/skills/)** — domain-specific knowledge packs (FastAPI, Docker, Svelte, debugging patterns, etc.) that the skill engine suggests automatically or you invoke with slash commands like `/spec` @@ -129,7 +129,7 @@ The session context plugin reminds you to commit when there are significant unco ## Next Steps - [Plugins Overview](../plugins/) — understand how each plugin enhances your workflow -- [Agents](../features/agents/) — explore all 21 specialized agents in detail +- [Agents](../features/agents/) — explore all 19 specialized agents in detail - [Skills](../features/skills/) — browse the complete skill catalog - [Configuration](../customization/configuration/) — customize CodeForge to match your preferences - [Commands Reference](../reference/commands/) — full reference for all CLI commands diff --git a/docs/src/content/docs/getting-started/index.md b/docs/src/content/docs/getting-started/index.md index 5a2ba5b..f1ac694 100644 --- a/docs/src/content/docs/getting-started/index.md +++ b/docs/src/content/docs/getting-started/index.md @@ -5,7 +5,7 @@ sidebar: order: 1 --- -CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 17 plugins, 22 tools, 21 specialized agents, and 38 skills into a single `npx codeforge-dev` install. +CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 17 plugins, 22 tools, 19 specialized agents, and 34 skills into a single `npx codeforge-dev` install. ## What is CodeForge? @@ -29,7 +29,7 @@ If you already have Docker and VS Code installed, you can go from zero to a runn **Start productive immediately.** New projects and new team members skip the setup ritual entirely. One command installs a complete, consistent environment with every tool pre-configured. -**AI that understands your workflow.** CodeForge doesn't just install Claude Code — it teaches it. System prompts, plugin hooks, and rules give Claude deep context about your project structure, coding standards, and preferred workflows. The agent system provides 21 specialized AI agents, each tuned for a specific task like architecture planning, debugging, or security auditing. +**AI that understands your workflow.** CodeForge doesn't just install Claude Code — it teaches it. System prompts, plugin hooks, and rules give Claude deep context about your project structure, coding standards, and preferred workflows. The agent system provides 19 specialized AI agents, each tuned for a specific task like architecture planning, debugging, or security auditing. **Safety built in.** Workspace scope guards prevent accidental writes outside your project directory. Dangerous command blockers catch destructive shell commands before they run. Protected file guards keep secrets and lock files safe. You get the power of AI-assisted development with guardrails that prevent costly mistakes. @@ -37,13 +37,13 @@ If you already have Docker and VS Code installed, you can go from zero to a runn ## What's Included -### 14 Plugins +### 17 Plugins -Plugins are the backbone of CodeForge. They hook into Claude Code's lifecycle to enhance, guard, and automate your workflow. Highlights include: +Plugins are the backbone of CodeForge. They hook into Claude Code's lifecycle to enhance, guard, and automate your workflow. 4 are official Anthropic contributions. Highlights include: -- **Agent System** — 21 specialized agents for architecture, debugging, testing, security, and more +- **Agent System** — 19 specialized agents for architecture, debugging, testing, security, and more - **Skill Engine** — 23 domain-specific knowledge packs covering frameworks, patterns, and workflows -- **Spec Workflow** — specification-driven development with 8 lifecycle skills +- **Spec Workflow** — specification-driven development with 3 lifecycle skills - **Session Context** — automatic git state injection, TODO harvesting, and commit reminders - **Auto Code Quality** — formatting, linting, and advisory test runs on every change - **Safety Guards** — workspace scope, dangerous command blocking, and protected file enforcement @@ -64,7 +64,7 @@ CodeForge installs a comprehensive toolchain so you never have to stop and insta See the [Features Overview](../features/) for the complete reference. -### 21 Custom Agents +### 19 Custom Agents Agents are specialized AI personas that Claude delegates to based on your request. Each agent carries domain-specific instructions and behavioral guidelines: @@ -73,11 +73,11 @@ Agents are specialized AI personas that Claude delegates to based on your reques - **Test Writer** — test generation with framework-aware patterns - **Security Auditor** — vulnerability detection and security review - **Refactorer** — safe, incremental code transformations -- And 16 more covering debugging, documentation, migration, performance, and beyond +- And 14 more covering debugging, documentation, migration, performance, and beyond See [Agents](../features/agents/) for the full roster. -### 38 Skills +### 34 Skills Skills are domain-specific knowledge packs that Claude can draw on. They provide curated best practices, patterns, and workflows for specific technologies and tasks: diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md index a8cdffc..8242c1f 100644 --- a/docs/src/content/docs/getting-started/installation.md +++ b/docs/src/content/docs/getting-started/installation.md @@ -38,7 +38,7 @@ npm install -g codeforge-dev codeforge-dev # Pin a specific version -npx codeforge-dev@2.0.0 +npx codeforge-dev@2.1.0 ``` ### What the Installer Creates @@ -152,7 +152,7 @@ A healthy installation shows all of these as available: | Category | Tools | |----------|-------| | Claude Code | `claude`, `cc`, `ccw`, `ccraw` | -| Session tools | `ccusage`, `ccburn`, `claude-monitor` (`ccms` currently disabled) | +| Session tools | `ccusage`, `ccburn` (disabled by default), `claude-monitor` (`ccms` currently disabled) | | Languages | `node`, `python`, `bun` (`rustc` opt-in) | | Code intelligence | `ast-grep`, `tree-sitter`, `pyright`, `typescript-language-server` | | Linters/Formatters | `ruff`, `biome` | @@ -181,7 +181,7 @@ A few features ship with `"version": "none"` by default (shfmt, dprint, shellche - **ccusage** / **ccburn** — token usage analysis and burn rate tracking - **ccstatusline** — session status in your terminal prompt - **claude-monitor** — real-time session monitoring -- **codeforge-dashboard** — web-based session analytics on port 7847 +- **codeforge-dashboard** — web-based session analytics on port 7847 _(opt-in — may not be available if the feature is disabled)_ - **agent-browser** — headless Chromium via Playwright for web interaction - **ast-grep** / **tree-sitter** — structural code search and parsing diff --git a/docs/src/content/docs/getting-started/migrating-to-v2.md b/docs/src/content/docs/getting-started/migrating-to-v2.md index de0e7c9..9dbbb6b 100644 --- a/docs/src/content/docs/getting-started/migrating-to-v2.md +++ b/docs/src/content/docs/getting-started/migrating-to-v2.md @@ -7,10 +7,6 @@ sidebar: CodeForge v2 externalizes user configuration from `.devcontainer/config/defaults/` to a new top-level `.codeforge/` directory. This separates your customizations from the DevContainer infrastructure, making updates cleaner and reducing merge conflicts. -:::note[Unreleased] -v2 is the next release. The current published version is 1.14.2. This guide is forward-looking — use it when v2 ships or if you're testing from the main branch. -::: - ## What Changed In v1.x, user-customizable files lived inside `.devcontainer/config/defaults/`. This meant every CodeForge update touched the same directory as your customizations, making it hard to tell what changed and what you'd modified. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index b54c8d4..4004a8a 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: CodeForge -description: The complete Claude Code development environment. 14 plugins, 22 tools, 21 AI agents — battle-tested and ready to go. +description: The complete Claude Code development environment. 17 plugins, 22 tools, 19 AI agents — battle-tested and ready to go. template: splash hero: tagline: Your AI dev environment, battle-tested. diff --git a/docs/src/content/docs/plugins/agent-system.md b/docs/src/content/docs/plugins/agent-system.md index 1fa7c17..3bcfea6 100644 --- a/docs/src/content/docs/plugins/agent-system.md +++ b/docs/src/content/docs/plugins/agent-system.md @@ -1,11 +1,11 @@ --- title: Agent System -description: The agent system plugin provides 21 specialized AI agents with automatic delegation, CWD injection, and read-only enforcement. +description: The agent system plugin provides 19 specialized AI agents with automatic delegation and read-only enforcement. sidebar: order: 2 --- -The agent system is CodeForge's flagship plugin. It gives you access to 21 specialized AI agents, each purpose-built for a specific kind of development task — from architecture planning and code exploration to test writing and security auditing. When you make a request, the system automatically delegates to the most appropriate agent, so you get expert-level results without having to think about which tool to use. +The agent system is CodeForge's flagship plugin. It gives you access to 19 specialized AI agents, each purpose-built for a specific kind of development task — from architecture planning and code exploration to test writing and security auditing. When you make a request, the system automatically delegates to the most appropriate agent, so you get expert-level results without having to think about which tool to use. ## How Delegation Works @@ -67,7 +67,7 @@ Each redirect is a strict improvement. The custom agents carry capabilities that - **Calibrated models** — the architect uses Opus for deep reasoning, the explorer uses Haiku for speed. Stock agents all inherit the session default. - **Safety hooks** — read-only agents have `guard-readonly-bash.py` blocking write operations. The refactorer runs regression checks after every edit. Stock agents have no per-agent safety enforcement. - **Focused system prompts** — each custom agent has a detailed system prompt shaping its behavior, expertise boundaries, and workflow. Stock agents use a generic prompt. -- **Worktree isolation** — the test-writer, refactorer, migrator, and doc-writer work in isolated git worktrees. Stock agents always work on the active branch. +- **Worktree isolation** — the test-writer, refactorer, migrator, and documenter work in isolated git worktrees. Stock agents always work on the active branch. The redirect is fully transparent to you and to Claude. Using either name works — `Explore` and `explorer` both resolve to the same enhanced agent. @@ -77,13 +77,11 @@ Claude Code has a seventh built-in agent type, `magic-docs`, which handles inter ## Safety Mechanisms -The agent system includes two key safety mechanisms that run automatically. +The agent system includes safety mechanisms that run automatically. ### CWD Injection -Every time a subagent starts, the `inject-cwd.py` hook fires. It reads the current working directory and injects it as context for the agent, ensuring every agent knows exactly which project directory to work in. This prevents agents from accidentally operating in the wrong directory — a subtle but important safeguard when working across multiple projects. - -The hook fires on the `SubagentStart` event and adds a message like: *"Working Directory: /workspaces/projects/MyApp — restrict all file operations to this directory."* +Working directory context is injected into every subagent by the [Workspace Scope Guard](./workspace-scope-guard/) plugin, not by the agent system itself. The scope guard's `inject-workspace-cwd.py` script fires on `SubagentStart` (among other events) and ensures every agent knows exactly which project directory to work in. See the [Workspace Scope Guard](./workspace-scope-guard/) documentation for details. ### Read-Only Enforcement @@ -105,7 +103,7 @@ Read-only agents don't just have instructions saying "don't write files." The gu ## Agent Reference -CodeForge includes 21 specialized agents. Each one is tailored for a specific class of development task. +CodeForge includes 19 specialized agents. Each one is tailored for a specific class of development task. ### Read-Only Agents @@ -133,28 +131,28 @@ These agents can read and write files, run commands, and make changes to your co | **generalist** | General-purpose development tasks | Inherited | No | spec skills | | **test-writer** | Test creation, coverage analysis, framework detection | Opus | Worktree | testing | | **refactorer** | Behavior-preserving code transformations | Opus | Worktree | refactoring-patterns | -| **doc-writer** | Documentation writing and maintenance | Opus | Worktree | documentation-patterns | +| **documenter** | Documentation writing and maintenance | Opus | Worktree | documentation-patterns | | **migrator** | Code migration, framework upgrades | Opus | Worktree | migration-patterns | +| **implementer** | Task implementation from specs and plans | Opus | No | spec skills | +| **investigator** | Deep codebase investigation and root-cause analysis | Sonnet | No | debugging | | **bash-exec** | Shell command execution and scripting | Sonnet | No | — | | **statusline-config** | Statusline customization | Sonnet | No | — | :::note[Model Selection] -Agents use different Claude models based on task complexity. The architect, test-writer, refactorer, doc-writer, migrator, and spec-writer use Opus for maximum reasoning capability. The explorer, dependency-analyst, and git-archaeologist use Haiku for speed. The researcher, security-auditor, debug-logs, perf-profiler, bash-exec, and statusline-config use Sonnet for balanced performance. The generalist inherits the session's model setting. +Agents use different Claude models based on task complexity. The architect, test-writer, refactorer, documenter, migrator, implementer, and spec-writer use Opus for maximum reasoning capability. The explorer, dependency-analyst, and git-archaeologist use Haiku for speed. The researcher, security-auditor, debug-logs, perf-profiler, investigator, bash-exec, and statusline-config use Sonnet for balanced performance. The generalist inherits the session's model setting. ::: ## Hook Scripts -The agent system registers hooks across several lifecycle events: +The agent system registers three hooks in its `hooks.json`: | Script | Event | What It Does | |--------|-------|-------------| | `redirect-builtin-agents.py` | PreToolUse (Task) | Redirects built-in agent types to CodeForge's custom specialists | -| `inject-cwd.py` | SubagentStart | Injects the working directory so agents operate in the correct project | -| `guard-readonly-bash.py` | PreToolUse (Bash) | Blocks write operations for read-only agents | -| `verify-no-regression.py` | PostToolUse (Edit) | Checks for test regressions after code edits (refactorer) | -| `verify-tests-pass.py` | Stop | Validates all tests pass at the end of a turn (test-writer) | -| `task-completed-check.py` | TaskCompleted | Verifies task results meet requirements in team workflows | | `teammate-idle-check.py` | TeammateIdle | Monitors teammate activity and reassigns work if needed | +| `task-completed-check.py` | TaskCompleted | Verifies task results meet requirements in team workflows | + +Additional hooks like `guard-readonly-bash.py`, `verify-no-regression.py`, and `verify-tests-pass.py` are registered per-agent in each agent's frontmatter `hooks` section, not in the plugin-level `hooks.json`. CWD injection is handled by the [Workspace Scope Guard](./workspace-scope-guard/) plugin. ## How Agent Definitions Work @@ -215,7 +213,7 @@ The agent system supports multi-agent team workflows for complex tasks. When a t For example, implementing a feature from a specification might involve: - A **researcher** exploring the codebase for patterns and conventions - A **test-writer** creating tests in a worktree -- A **doc-writer** updating documentation +- A **documenter** updating documentation The team is coordinated through the task system, with hooks like `task-completed-check.py` and `teammate-idle-check.py` ensuring smooth collaboration. @@ -223,7 +221,7 @@ The recommended team compositions vary by task type: | Task Type | Recommended Teammates | |-----------|----------------------| -| Full-stack feature | researcher + test-writer + doc-writer | +| Full-stack feature | researcher + test-writer + documenter | | Backend-heavy work | researcher + test-writer | | Security-sensitive feature | security-auditor + test-writer | | Refactoring | refactorer + test-writer | diff --git a/docs/src/content/docs/plugins/codeforge-lsp.md b/docs/src/content/docs/plugins/codeforge-lsp.md index 7bd825e..cf80277 100644 --- a/docs/src/content/docs/plugins/codeforge-lsp.md +++ b/docs/src/content/docs/plugins/codeforge-lsp.md @@ -7,6 +7,12 @@ sidebar: The CodeForge LSP plugin gives Claude access to the same code intelligence that powers your IDE -- type checking, go-to-definition, find-references, and more. By connecting Claude to Language Server Protocol servers, it can navigate and understand your codebase with precision rather than relying on text search alone. +:::caution[Disabled by Default] +LSP servers are **disabled by default** in CodeForge. The `lsp-servers` devcontainer feature ships with `version: "none"` and the plugin is set to `false` in settings. To enable LSP support: +1. Set the `lsp-servers` feature version to `"latest"` in your `devcontainer.json` +2. Set the `codeforge-lsp` plugin to `true` in your `settings.json` +::: + ## How It Works This is a purely declarative plugin -- it has no hook scripts and no shell scripts. All configuration lives in `plugin.json`, where it registers LSP server definitions. Claude Code launches each server at startup if its binary is available on PATH. Missing servers are silently skipped, so the plugin never fails on a missing tool. @@ -59,7 +65,7 @@ Servers activate only when their binary is found on PATH: |--------|--------|--------------------------| | Pyright | `pyright-langserver` | Yes (via `npm i -g pyright`) | | TypeScript LS | `typescript-language-server` | Yes (via `npm i -g typescript-language-server typescript`) | -| gopls | `gopls` | Yes (via `go install golang.org/x/tools/gopls@latest`) | +| gopls | `gopls` | Requires Go feature enabled (Go is disabled by default) | If you need LSP for additional languages, you can add server definitions to the plugin's `plugin.json` following the same pattern. diff --git a/docs/src/content/docs/plugins/dangerous-command-blocker.md b/docs/src/content/docs/plugins/dangerous-command-blocker.md index 164ef09..347b2cf 100644 --- a/docs/src/content/docs/plugins/dangerous-command-blocker.md +++ b/docs/src/content/docs/plugins/dangerous-command-blocker.md @@ -43,17 +43,26 @@ Commands that destroy or overwrite git history in ways that are difficult to rec Even `git push -f` without specifying a branch is blocked, because it could unintentionally force-push to the current branch. The blocker requires you to be explicit about what you're doing. ::: -### System Modification +### Dangerous Permissions -Commands that modify critical system directories or create security vulnerabilities: +Commands that create security vulnerabilities through overly permissive file modes: | Pattern | Example | Why It's Blocked | |---------|---------|-----------------| -| `chmod 777` | `chmod 777 app.py` | Creates world-writable files | -| `chmod -R 777` | `chmod -R 777 /var/www` | Recursively weakens permissions | -| Write to system dirs | `> /usr/local/bin/script` | Modifies system binaries | -| Write to `/etc/` | `echo "config" > /etc/hosts` | Modifies system configuration | -| Write to `/bin/` or `/sbin/` | `> /bin/script` | Modifies core system binaries | +| `chmod 0777` / `chmod a=rwx` | `chmod 0777 app.py` | Creates world-writable files | +| `chmod u+s` / `chmod g+s` | `chmod u+s script` | Sets setuid/setgid bits, privilege escalation risk | + +### Additional Git Safety + +Commands that rewrite or destroy git history beyond basic force pushes: + +| Pattern | Example | Why It's Blocked | +|---------|---------|-----------------| +| `--force-with-lease` | `git push --force-with-lease` | Safer force push but still rewrites history | +| `--force-if-includes` | `git push --force-if-includes` | Conditional force push still rewrites history | +| `git filter-branch` | `git filter-branch --tree-filter ...` | Rewrites entire repository history | +| Plus-refspec push | `git push origin +main` | Force push via refspec syntax | +| Branch deletion | `git push origin :branch` or `--delete` | Deletes remote branches | ### Disk and Device Operations @@ -73,6 +82,8 @@ Commands that could break container isolation: | `docker run --privileged` | `docker run --privileged ubuntu` | Allows container escape | | Mount host root | `docker run -v /:/host ubuntu` | Exposes host filesystem | | Destructive docker ops | `docker rm container_id` | Stops, removes, or kills containers and images (`docker rmi`) | +| `docker system prune` | `docker system prune -a` | Removes all unused containers, images, networks | +| `docker volume rm` | `docker volume rm data` | Deletes persistent volume data | ## What Happens When a Command Is Blocked @@ -86,14 +97,14 @@ The command never executes. Claude receives the block message and can suggest a ## Fail-Safe Behavior -The blocker follows a "fail closed" principle for its own errors: +The blocker follows a strict "fail closed" principle: -- If it can't parse the hook input JSON, it blocks the command (exit code 2) rather than allowing something it couldn't inspect. -- If an unexpected error occurs during pattern matching, it logs the error but allows the command through to avoid blocking legitimate work on a hook bug. +- If it can't parse the hook input JSON, it **blocks** the command (exit code 2) rather than allowing something it couldn't inspect. +- If an unexpected error occurs during pattern matching, it **blocks** the command (exit code 2). The blocker never allows a command through when it cannot verify safety. ## Overriding Blocks -The blocker is designed to catch accidental destructive commands, not to prevent intentional operations. If you genuinely need to run a blocked command, you can use the Claude Code permission prompt to explicitly approve it. The blocker respects user intent -- it's a guardrail, not a cage. +The blocker uses exit code 2 to block commands, which is a **hard block** in Claude Code's hook system. Unlike exit code 1 (which can be overridden via the permission prompt), exit code 2 blocks cannot be bypassed through the UI. If you genuinely need to run a blocked command, you must either modify the plugin's `hooks.json` to adjust the patterns, or disable the plugin entirely in your `settings.json`. :::note[Complementary Guards] This plugin handles command-level safety. For file-path-level protection, see the [Workspace Scope Guard](./workspace-scope-guard/) and [Protected Files Guard](./protected-files-guard/), which cover different attack surfaces. diff --git a/docs/src/content/docs/plugins/index.md b/docs/src/content/docs/plugins/index.md index def8d6c..3580319 100644 --- a/docs/src/content/docs/plugins/index.md +++ b/docs/src/content/docs/plugins/index.md @@ -43,7 +43,7 @@ The `plugin.json` manifest is minimal — it identifies the plugin and its autho ```json { "name": "agent-system", - "description": "21 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement", + "description": "19 custom agents with built-in agent redirection and read-only bash enforcement", "author": { "name": "AnExiledDev" } @@ -96,7 +96,7 @@ See [Hooks](../customization/hooks/) for the full hook API and configuration det ## Installed Plugins -CodeForge ships with 13 local marketplace plugins plus 1 external Anthropic plugin, organized into two categories: **core plugins** that provide primary functionality, and **safety and integration plugins** that protect your work and connect to external tools. +CodeForge ships with 13 local marketplace plugins plus 4 Anthropic official plugins, organized into two categories: **core plugins** that provide primary functionality, and **safety and integration plugins** that protect your work and connect to external tools. ### Core Plugins @@ -104,7 +104,7 @@ These plugins deliver the headline features of CodeForge — intelligent delegat | Plugin | What It Does | |--------|-------------| -| [Agent System](./agent-system/) | 21 specialized agents with automatic delegation, CWD injection, and read-only enforcement | +| [Agent System](./agent-system/) | 19 specialized agents with automatic delegation and read-only enforcement | | [Skill Engine](./skill-engine/) | 23 domain skills with context-aware auto-suggestion | | [Spec Workflow](./spec-workflow/) | Full specification lifecycle from creation through implementation to as-built closure | | [Ticket Workflow](./ticket-workflow/) | GitHub issue integration with EARS-formatted tickets and automated PR reviews | @@ -142,27 +142,27 @@ Plugins are declared in `settings.json` under the `enabledPlugins` key. Every pl ```json { - "enabledPlugins": [ - "agent-system", - "skill-engine", - "spec-workflow", - "session-context", - "auto-code-quality", - "workspace-scope-guard", - "dangerous-command-blocker", - "protected-files-guard", - "codeforge-lsp", - "ticket-workflow", - "notify-hook", - "frontend-design", - "code-review", - "feature-dev", - "pr-review-toolkit" - ] + "enabledPlugins": { + "agent-system@devs-marketplace": true, + "skill-engine@devs-marketplace": true, + "spec-workflow@devs-marketplace": true, + "session-context@devs-marketplace": true, + "auto-code-quality@devs-marketplace": true, + "workspace-scope-guard@devs-marketplace": true, + "dangerous-command-blocker@devs-marketplace": true, + "protected-files-guard@devs-marketplace": true, + "codeforge-lsp@devs-marketplace": true, + "ticket-workflow@devs-marketplace": true, + "notify-hook@devs-marketplace": true, + "frontend-design@devs-marketplace": true, + "code-review@devs-marketplace": true, + "feature-dev@devs-marketplace": true, + "pr-review-toolkit@devs-marketplace": true + } } ``` -To disable a plugin, remove it from the list. To re-enable it, add it back. Changes take effect on the next container start. +To disable a plugin, set its value to `false`. To re-enable it, set it back to `true`. Changes take effect on the next container start. :::caution[Safety Plugins] Think carefully before disabling safety plugins like `dangerous-command-blocker` or `workspace-scope-guard`. These protect against accidental data loss and scope violations. diff --git a/docs/src/content/docs/plugins/prompt-snippets.md b/docs/src/content/docs/plugins/prompt-snippets.md index f175795..bdfc81b 100644 --- a/docs/src/content/docs/plugins/prompt-snippets.md +++ b/docs/src/content/docs/plugins/prompt-snippets.md @@ -29,7 +29,7 @@ Claude applies that snippet's instruction and follows it for the rest of the con | `ship` | Commit all staged changes, push to remote, and create a pull request. | | `deep` | Be thorough and comprehensive. Investigate in depth, consider edge cases, leave no stone unturned. | | `hold` | Complete the current task but do not commit, push, or publish. Await my review before any git operations. | -| `recall` | Search past session history with `ccms --no-color --project "$(pwd)"` to find prior decisions, discussions, and context relevant to the current task. Summarize what you find before proceeding. | +| `recall` | Search past session history with `codeforge session search --no-color --project "$(pwd)"` to find prior decisions, discussions, and context relevant to the current task. Summarize what you find before proceeding. | | `wait` | When done, stop. Do not suggest next steps, ask follow-up questions, or continue with related work. Await further instructions. | :::tip[When to Use Snippets] diff --git a/docs/src/content/docs/plugins/session-context.md b/docs/src/content/docs/plugins/session-context.md index 9171a89..6e57b85 100644 --- a/docs/src/content/docs/plugins/session-context.md +++ b/docs/src/content/docs/plugins/session-context.md @@ -16,7 +16,7 @@ The plugin registers hooks at two lifecycle points: | **SessionStart** | Git state injector + TODO harvester | Gives Claude full project awareness at the start of every session | | **Stop** | Commit reminder | Prompts about uncommitted changes before the turn ends | -The SessionStart scripts (git state injector and TODO harvester) are purely advisory -- they inject context without making decisions. The commit reminder is different: it uses a "block" decision to keep Claude from finishing a turn when there are uncommitted changes. +The SessionStart scripts (git state injector and TODO harvester) are purely advisory -- they inject context without making decisions. The commit reminder is also advisory -- it exits 0 with a `systemMessage` to inject a reminder about uncommitted changes, but it never blocks the turn. ## Git State Injection @@ -103,23 +103,25 @@ The harvester shows up to 10 items with relative file paths and line numbers, ca ## Commit Reminder -The `commit-reminder.py` script fires at the Stop hook when Claude finishes a turn. It checks for uncommitted changes and, if any exist, blocks the stop with a summary so Claude can suggest committing. +The `commit-reminder.py` script fires at the Stop hook when Claude finishes a turn. It checks for uncommitted changes and, if any exist, injects an advisory system reminder so Claude can mention them. ### What It Reports -The reminder counts staged and unstaged changes separately: +The reminder summarizes the session's edited files: ``` -[Uncommitted Changes] 5 files with changes (2 staged, 3 unstaged). +[Session Summary] 5 files modified in this session (2 staged, 3 unstaged). Consider asking the user if they'd like to commit before finishing. ``` +The reminder uses tiered thresholds: it fires when there are 3 or more changed files, or 2 or more source files modified. It also enforces a 5-minute cooldown to avoid repeated reminders within a short period. + ### Loop Prevention -The commit reminder uses the `stop_hook_active` guard to prevent infinite loops. If another Stop hook has already blocked (like the advisory test runner), the commit reminder skips itself rather than stacking blocks. +The commit reminder uses the `stop_hook_active` guard to prevent infinite loops. If another Stop hook has already fired (like the advisory test runner), the commit reminder skips itself rather than stacking reminders. :::note[Advisory, Not Mandatory] -The commit reminder blocks the Stop to give Claude a chance to mention uncommitted changes, but it doesn't force a commit. Claude will typically ask if you'd like to commit -- you can say no and continue. +The commit reminder injects a system-level reminder (exits 0 with a `systemMessage`) but never blocks the turn. Claude will typically ask if you'd like to commit -- you can say no and continue. ::: ## Hook Registration @@ -128,8 +130,13 @@ The commit reminder blocks the Stop to give Claude a chance to mention uncommitt |--------|------|---------| | `git-state-injector.py` | SessionStart | Injects git branch, status, and recent commits | | `todo-harvester.py` | SessionStart | Surfaces TODO/FIXME/HACK/XXX comment counts | +| `collect-session-edits.py` | PostToolUse (Edit, Write) | Tracks files modified during the session for the commit reminder | | `commit-reminder.py` | Stop | Reminds about uncommitted changes at turn boundaries | +:::note[Disabled by Default] +The `git-state-injector`, `commit-reminder`, `ticket-linker`, and `spec-reminder` hooks are disabled by default via the plugin's `disabled-hooks.json`. The TODO harvester and `collect-session-edits.py` remain active. +::: + ## Related - [Notify Hook](./notify-hook/) -- desktop notifications complement session context diff --git a/docs/src/content/docs/plugins/skill-engine.md b/docs/src/content/docs/plugins/skill-engine.md index 5aebfe3..244bfb4 100644 --- a/docs/src/content/docs/plugins/skill-engine.md +++ b/docs/src/content/docs/plugins/skill-engine.md @@ -79,6 +79,7 @@ Skills for working with Claude Code itself and extending CodeForge. | **ast-grep-patterns** | AST-grep pattern writing for syntax-aware code search | | **team** | Multi-agent team coordination, task decomposition, parallel workstreams | | **worktree** | Git worktree lifecycle, EnterWorktree tool, `.worktreeinclude` setup, parallel workflows | +| **agent-browser** | Browser automation patterns for agent-driven web interaction | :::note[Cross-Plugin Skills] The spec lifecycle skills (`/spec`, `/build`, `/specs`) live in the [Spec Workflow](./spec-workflow/) plugin, not the skill engine. However, the skill-suggester registers keywords for them so they are auto-suggested alongside skill-engine skills. diff --git a/docs/src/content/docs/plugins/workspace-scope-guard.md b/docs/src/content/docs/plugins/workspace-scope-guard.md index bdab9dc..2eb77b1 100644 --- a/docs/src/content/docs/plugins/workspace-scope-guard.md +++ b/docs/src/content/docs/plugins/workspace-scope-guard.md @@ -43,15 +43,19 @@ The blacklist: ### What's In Scope -Everything under the current working directory: +Everything under the resolved project root. The guard determines scope by walking up from the current working directory to find the nearest `.git` directory, then expands the allowed scope to the git repository root. This means the entire repository is in scope, not just the CWD: ``` -/workspaces/projects/MyProject/ -- project root (cwd) +/workspaces/projects/MyProject/ -- project root (git repo root) /workspaces/projects/MyProject/src/ -- in scope /workspaces/projects/MyProject/tests/ -- in scope /workspaces/projects/MyProject/.specs/ -- in scope ``` +### Worktree Support + +When working inside a `.claude/worktrees/` path, the guard recognizes the worktree structure and expands scope to the parent project root rather than scoping narrowly to just the worktree directory. This ensures agents working in worktrees can still access the full project. + ### What's Out of Scope Anything outside the project root is blocked: @@ -68,14 +72,14 @@ Anything outside the project root is blocked: When your current directory is `/workspaces` (the workspace root itself), the scope guard allows operations within `/workspaces/` — **except** for blacklisted paths. `/workspaces/.devcontainer/` remains blocked even from workspace root. ::: -### Allowlisted Paths +### Paths Outside `/workspaces/` -A minimal set of paths are always allowed: +Paths that fall entirely outside the `/workspaces/` tree are not subject to scope enforcement — they pass through because the guard only polices workspace-internal paths. Common examples: -| Allowed Path | Reason | -|-------------|--------| -| `~/.claude/` | Claude config, plans, rules | -| `/tmp/` | System temp directory | +| Path | Why It Passes Through | +|------|----------------------| +| `~/.claude/` | Outside `/workspaces/` — Claude config, plans, rules | +| `/tmp/` | Outside `/workspaces/` — system temp directory | ## Bash Enforcement @@ -85,7 +89,7 @@ Bash commands receive two-layer scope enforcement: 20+ regex patterns extract file paths from write operations: redirects (`>`), cp, mv, touch, mkdir, rm, ln, rsync, chmod, chown, dd, wget -O, curl -o, tar -C, unzip -d, gcc -o, sqlite3, and more. Each extracted target is resolved and scope-checked. -**System command exemption:** Commands like `git`, `pip`, `npm` get a Layer 1 exemption ONLY when ALL write targets resolve to system paths (`/usr/`, `/bin/`, etc.). Any `/workspaces/` write target outside cwd cancels the exemption. +**Paths outside `/workspaces/`:** Write targets that resolve to paths outside `/workspaces/` entirely (e.g., `/usr/`, `/bin/`, `/tmp/`) pass through Layer 1 without blocking, since they are outside the workspace and not the guard's concern. However, any `/workspaces/` write target outside the project root cancels this pass-through and triggers a block. ### Layer 2 — Workspace Path Scan diff --git a/docs/src/content/docs/reference/architecture.md b/docs/src/content/docs/reference/architecture.md index 656fab3..2223366 100644 --- a/docs/src/content/docs/reference/architecture.md +++ b/docs/src/content/docs/reference/architecture.md @@ -85,7 +85,7 @@ Additional hook points (`SessionStart`, `SubagentStart`, `TeammateIdle`, `TaskCo ### Agent System -The agent system provides specialized personas with constrained tools and focus areas. CodeForge ships 21 custom agents: +The agent system provides specialized personas with constrained tools and focus areas. CodeForge ships 19 custom agents: **How agent routing works:** @@ -99,7 +99,7 @@ The agent system provides specialized personas with constrained tools and focus 4. The custom agent's system prompt is loaded, restricting tools and focus 5. The agent executes within its constraints and returns results -**Agent tiers:** Agents are grouped by capability level. Tier 1 (generalist) has all instruction blocks. Tier 2 (write agents like refactorer, test-writer, doc-writer) have full blocks. Tier 3 (read-only agents like explorer, researcher) have compact blocks. +**Agent tiers:** Agents are grouped by capability level. Tier 1 (generalist) has all instruction blocks. Tier 2 (write agents like refactorer, test-writer, documenter) have full blocks. Tier 3 (read-only agents like explorer, researcher) have compact blocks. ### Skill Loading @@ -111,7 +111,7 @@ Skills are Markdown knowledge files loaded on demand during a session: 4. The skill content is injected into the conversation context 5. Claude uses the skill knowledge for the current task -CodeForge ships 38 skills across the skill-engine, spec-workflow, ticket-workflow, git-workflow, agent-system, and prompt-snippets plugins. +CodeForge ships 34 skills across the skill-engine, spec-workflow, ticket-workflow, git-workflow, agent-system, and prompt-snippets plugins. ## Directory Structure @@ -134,9 +134,9 @@ CodeForge ships 38 skills across the skill-engine, spec-workflow, ticket-workflo +-- plugins/ | +-- devs-marketplace/ | +-- plugins/ -| +-- agent-system/ # 21 agents + redirection hooks +| +-- agent-system/ # 19 agents + redirection hooks | +-- skill-engine/ # 23 skills + auto-suggestion -| +-- spec-workflow/ # 8 spec lifecycle skills +| +-- spec-workflow/ # 3 spec lifecycle skills | +-- session-context/ # Git state, TODOs, commit reminders | +-- auto-code-quality/ # Format + lint + test at Stop | +-- dangerous-command-blocker/ # Block destructive commands @@ -225,7 +225,7 @@ devcontainer.json 1. **Session start** -- User runs `cc`. Claude Code loads the system prompt, rules, CLAUDE.md files. SessionStart hooks fire (git state injection, TODO harvesting). 2. **Turn cycle** -- User input arrives. Claude selects tools. PreToolUse hooks gate each tool call. Tool executes. PostToolUse hooks enrich context. Claude generates a response. 3. **Turn boundary** -- Stop hooks fire: format edited files, lint them, run affected tests, check for uncommitted changes, remind about specs, send notifications. -4. **Session end** -- Session data is written to JSONL files for `ccms` search. +4. **Session end** -- Session data is written to JSONL files for `codeforge session search`. ### Context Assembly diff --git a/docs/src/content/docs/reference/changelog.md b/docs/src/content/docs/reference/changelog.md index 49f1192..7c5d6ef 100644 --- a/docs/src/content/docs/reference/changelog.md +++ b/docs/src/content/docs/reference/changelog.md @@ -47,30 +47,31 @@ For minor and patch updates, you can usually just rebuild the container. Check t ## Version History -## Unreleased +## v2.1.0 — 2026-03-25 + +### CLI + +- **`codeforge proxy`** — launch Claude Code through mitmproxy for full API traffic inspection. Starts mitmweb in the background, proxies all Claude API requests through it, and opens a browser UI at `http://localhost:8081` for real-time request/response inspection. Auto-installs mitmproxy via pipx on first use, handles CA certificate generation and system trust store installation. Supports `--no-web` for headless mitmdump output, `--setup` for install-only, and `-- ` passthrough. Useful for monitoring token usage, cache behavior, and rate limit utilization — the `anthropic-ratelimit-unified-*` response headers on `/v1/messages` requests show 5-hour and 7-day quota utilization even with long-lived auth tokens. +- **Version lock** — set `CLAUDE_VERSION_LOCK=` in `.env` to pin Claude Code to a specific version. The update script installs the exact version instead of updating to latest. Background auto-updater disabled via `DISABLE_AUTOUPDATER`. ### Dashboard + - **First-party dashboard** — replaced third-party `claude-session-dashboard` npm package with `codeforge-dashboard` (built from monorepo `dashboard/` package) - Auto-launch on container start via poststart hook (controllable with `autostart` option) - Install switched from npm to Bun (`bun install -g`) - Command renamed: `claude-dashboard` → `codeforge-dashboard` - Removed persistence symlink hook (dashboard DB now lives on bind mount at `~/.codeforge/data/`) -### Testing -- **Plugin test suite** — 241 pytest tests covering 6 critical plugin scripts that previously had zero tests: - - `block-dangerous.py` (46 tests) — all 22 dangerous command patterns with positive/negative/edge cases - - `guard-workspace-scope.py` (40 tests) — blacklist, scope, allowlist, bash enforcement layers, primary command extraction - - `guard-protected.py` (55 tests) — all protected file patterns (secrets, locks, keys, credentials, auth dirs) - - `guard-protected-bash.py` (24 tests) — write target extraction and protected path integration - - `guard-readonly-bash.py` (63 tests) — general-readonly and git-readonly modes, bypass prevention - - `redirect-builtin-agents.py` (13 tests) — redirect mapping, passthrough, output structure -- Added `test:plugins` and `test:all` npm scripts for running plugin tests +### Hooks -### Skills -- Added `agent-browser` skill to skill-engine plugin — guides headless browser automation with CLI reference, workflow patterns, and authentication +- **Per-hook disable mechanism** — add script names to `.codeforge/config/disabled-hooks.json` to disable individual hooks without disabling the entire plugin. Takes effect immediately, no restart needed. +- Disabled by default: `git-state-injector`, `ticket-linker`, `spec-reminder`, `commit-reminder` ### Scope Guard +- Fix `/dev/null` false positive — redirects to system paths (`/dev/`, `/proc/`, `/sys/`, etc.) are now allowed regardless of the primary command, not just for system commands like `git` or `pip` +- Fix CWD drift — scope root is now persisted on first invocation per session, preventing `cd` commands in Bash from silently changing the enforced scope boundary +- CWD context injector now uses the same persisted scope root, keeping advisory context aligned with enforcement - Fix false positives blocking writes to system paths (`/dev/null`, `/usr/`, `/etc/`, `$HOME/`) — scope guard now only enforces isolation between workspace projects - Remove complex system-command exemption logic (no longer needed) @@ -78,17 +79,43 @@ For minor and patch updates, you can usually just rebuild the container. Check t - Remove system directory write redirect blocks (`> /usr/`, `> /etc/`, `> /bin/`, `> /sbin/`) — caused false positives on text content in command arguments (e.g. PR body text containing paths); write location enforcement is the scope guard's responsibility -### CLI Integration +### Skills -- Add codeforge-cli devcontainer feature — installs the CodeForge CLI (`codeforge` command) globally via npm -- Remove dead `codeforge` alias from setup-aliases.sh (was pointing to obsolete `setup.js`) +- Added `agent-browser` skill to skill-engine plugin — guides headless browser automation with CLI reference, workflow patterns, and authentication + +### Configuration + +- Add `autoMemoryDirectory` setting — auto-memory now stored in project-local `.claude/memory/` instead of deep inside `~/.claude/projects/`, making it visible and version-controllable +- Enhanced system prompts with auto-memory system, hooks awareness, safety rules, and anti-over-engineering guidance + +### Status Bar + +- Replace `ccburn-compact` statusline widget with native `session-usage` and `weekly-usage` ccstatusline widgets — eliminates external command dependency and 8s timeout +- Comment out `ccburn` devcontainer feature (disabled by default) — functionality replaced by native widgets ### Windows Compatibility - Fix `claude-code-native` install failure on Windows/macOS Docker Desktop — installer now falls back to `HOME` override when `su` is unavailable - Remove `preflight.sh` runtime check — redundant with Docker's own error reporting and caused failures on Windows +### CLI Integration + +- Add codeforge-cli devcontainer feature — installs the CodeForge CLI (`codeforge` command) globally via npm +- Remove dead `codeforge` alias from setup-aliases.sh (was pointing to obsolete `setup.js`) + +### Testing + +- **Plugin test suite** — 241 pytest tests covering 6 critical plugin scripts that previously had zero tests: + - `block-dangerous.py` (46 tests) — all 22 dangerous command patterns with positive/negative/edge cases + - `guard-workspace-scope.py` (40 tests) — blacklist, scope, allowlist, bash enforcement layers, primary command extraction + - `guard-protected.py` (55 tests) — all protected file patterns (secrets, locks, keys, credentials, auth dirs) + - `guard-protected-bash.py` (24 tests) — write target extraction and protected path integration + - `guard-readonly-bash.py` (63 tests) — general-readonly and git-readonly modes, bypass prevention + - `redirect-builtin-agents.py` (13 tests) — redirect mapping, passthrough, output structure +- Added `test:plugins` and `test:all` npm scripts for running plugin tests + ### Documentation + - **DevContainer CLI guide** — dedicated Getting Started page for terminal-only workflows without VS Code - **v2 Migration Guide** — path changes, automatic migration, manual steps, breaking changes, and troubleshooting - Documented 4 previously undocumented agents in agents.md: implementer, investigator, tester, documenter @@ -97,29 +124,8 @@ For minor and patch updates, you can usually just rebuild the container. Check t - Added cc-orc orchestrator command to first-session launch commands table - Tabbed client-specific instructions on the installation page - Dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling - -### Configuration - -- Add `autoMemoryDirectory` setting — auto-memory now stored in project-local `.claude/memory/` instead of deep inside `~/.claude/projects/`, making it visible and version-controllable -- Enhanced system prompts with auto-memory system, hooks awareness, safety rules, and anti-over-engineering guidance - -### Status Bar - -- Replace `ccburn-compact` statusline widget with native `session-usage` and `weekly-usage` ccstatusline widgets — eliminates external command dependency and 8s timeout -- Comment out `ccburn` devcontainer feature (disabled by default) — functionality replaced by native widgets - -### Documentation - - Document `${CLAUDE_PLUGIN_DATA}` variable in CLAUDE.md for future plugin persistent storage -## v2.1.1 — 2026-03-13 - -### Workspace Scope Guard - -- Fix `/dev/null` false positive — redirects to system paths (`/dev/`, `/proc/`, `/sys/`, etc.) are now allowed regardless of the primary command, not just for system commands like `git` or `pip` -- Fix CWD drift — scope root is now persisted on first invocation per session, preventing `cd` commands in Bash from silently changing the enforced scope boundary -- CWD context injector now uses the same persisted scope root, keeping advisory context aligned with enforcement - ## v2.1.0 — 2026-03-13 ### Spec Workflow v2 — "Spec Packages" diff --git a/docs/src/content/docs/reference/commands.md b/docs/src/content/docs/reference/commands.md index 7fbb8e6..6903663 100644 --- a/docs/src/content/docs/reference/commands.md +++ b/docs/src/content/docs/reference/commands.md @@ -37,7 +37,7 @@ Commands for session analysis, usage tracking, and system monitoring. |---------|-------------|---------| | `ccms` | Search Claude Code session history. Supports boolean queries, role filtering, time scoping, and project isolation. _(currently disabled — replaced by `codeforge session search`)_ | `ccms --project "$(pwd)" "auth approach"` | | `ccusage` | View Claude API usage statistics | `ccusage` | -| `ccburn` | Analyze token burn rate and consumption patterns with pace indicators | `ccburn` | +| `ccburn` | Analyze token burn rate and consumption patterns with pace indicators _(disabled by default — uncomment in devcontainer.json to enable)_ | `ccburn` | | `ccstatusline` | Terminal status line displaying session metrics, git state, token usage, and burn rate | (runs automatically) | | `codeforge-dashboard` | Web-based session monitoring dashboard on port 7847 with cost estimates and activity heatmaps | `codeforge-dashboard` | | `claude-monitor` | Real-time Claude session activity monitor | `claude-monitor` | @@ -159,6 +159,7 @@ The `codeforge` command provides development workflow tools. When run outside th | `codeforge plugin` | `list`, `show`, `enable`, `disable`, `hooks`, `agents`, `skills` | Manage Claude Code plugins | | `codeforge config` | `show`, `apply` | View and deploy configuration | | `codeforge index` | `build`, `search`, `show`, `stats`, `tree`, `clean` | Build and search a codebase symbol index | +| `codeforge proxy` | — | Launch Claude Code through mitmproxy — inspect API traffic in browser (port 8081) | | `codeforge container` | `up`, `down`, `rebuild`, `exec`, `ls`, `shell` | Manage CodeForge devcontainers | ## GitHub CLI diff --git a/docs/src/content/docs/reference/environment.md b/docs/src/content/docs/reference/environment.md index 3206a05..3c415a1 100644 --- a/docs/src/content/docs/reference/environment.md +++ b/docs/src/content/docs/reference/environment.md @@ -15,7 +15,7 @@ Variables that control Claude Code's core behavior inside the CodeForge containe |----------|-------------|---------|--------| | `ANTHROPIC_MODEL` | Primary Claude model ID | `claude-opus-4-6` | settings.json | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus model ID | `claude-opus-4-6` | settings.json | -| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet model ID | `claude-sonnet-4-5-20250929` | settings.json | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet model ID | `claude-sonnet-4-6` | settings.json | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku model ID | `claude-haiku-4-5-20251001` | settings.json | | `CLAUDE_CONFIG_DIR` | Claude Code configuration directory | `/home/vscode/.claude` | devcontainer.json | | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Maximum tokens per response | `64000` | settings.json | @@ -100,6 +100,7 @@ These variables live in `.devcontainer/.env` and control what `setup.sh` does on | `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 | +| `CLAUDE_VERSION_LOCK` | (unset) | Pin Claude Code to a specific semver version (e.g., `1.0.33`). When set, the update script installs the exact version instead of updating to latest. | | `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/` | @@ -146,7 +147,7 @@ Applied when Claude Code starts. These are set inside the `env` block. ```json { "env": { - "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929", + "ANTHROPIC_MODEL": "claude-sonnet-4-6", "CLAUDE_CODE_EFFORT_LEVEL": "medium" } } @@ -157,7 +158,7 @@ Applied when Claude Code starts. These are set inside the `env` block. Add to `~/.zshrc` or `~/.bashrc`. Applied for every new shell session. ```bash -export CLAUDE_MODEL="claude-sonnet-4-5-20250929" +export ANTHROPIC_MODEL="claude-sonnet-4-6" ``` ### Per-Session (Highest Precedence) @@ -165,7 +166,7 @@ export CLAUDE_MODEL="claude-sonnet-4-5-20250929" Set on the command line when launching Claude Code. Overrides everything else. ```bash -ANTHROPIC_MODEL="claude-sonnet-4-5-20250929" cc +ANTHROPIC_MODEL="claude-sonnet-4-6" cc ``` ## Common Customizations @@ -174,7 +175,7 @@ Here are the environment variable changes you are most likely to make: | Goal | Variable | Value | |------|----------|-------| -| Use Sonnet instead of Opus | `ANTHROPIC_MODEL` | `claude-sonnet-4-5-20250929` | +| Use Sonnet instead of Opus | `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | | Increase Bash timeout for long builds | `BASH_DEFAULT_TIMEOUT_MS` | `600000` | | Reduce auto-compact aggressiveness | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `85` | | Disable extended thinking | (remove `alwaysThinkingEnabled` from settings.json) | -- | diff --git a/docs/src/content/docs/reference/index.md b/docs/src/content/docs/reference/index.md index 996ef2b..6ca5ce6 100644 --- a/docs/src/content/docs/reference/index.md +++ b/docs/src/content/docs/reference/index.md @@ -14,7 +14,7 @@ This section is a lookup resource for CodeForge internals. Use it when you need | [Commands](./commands/) | Every CLI command and slash command, grouped by category, with usage examples | | [Environment Variables](./environment/) | All environment variables with types, defaults, and where they are set | | [Architecture](./architecture/) | System overview, component relationships, data flow, and design principles | -| [Changelog](./changelog/) | Version history from v1.2.0 to current, with migration notes | +| [Changelog](./changelog/) | Version history from v1.0.0 to current, with migration notes | ## Most-Used Quick Reference @@ -68,9 +68,9 @@ These are the files you will interact with most often when configuring CodeForge | Component | Count | Details | |-----------|-------|---------| | DevContainer features | 22 | Runtimes, CLI tools, monitoring | -| Plugins | 14 (13 local + 1 official) | Safety, quality, workflow, intelligence | -| Agents | 21 | Specialized personas from explorer to security-auditor | -| Skills | 38 | On-demand knowledge across coding, testing, frameworks | +| Plugins | 17 (13 local + 4 Anthropic official) | Safety, quality, workflow, intelligence | +| Agents | 19 | Specialized personas from explorer to security-auditor | +| Skills | 34 | On-demand knowledge across coding, testing, frameworks | | Built-in rules | 3 | Workspace scope, spec workflow, session search | | CLI commands | 10+ | Session, analysis, code quality, intelligence | diff --git a/docs/src/content/docs/reference/port-forwarding.md b/docs/src/content/docs/reference/port-forwarding.md index 248c604..4cdbe9b 100644 --- a/docs/src/content/docs/reference/port-forwarding.md +++ b/docs/src/content/docs/reference/port-forwarding.md @@ -112,10 +112,10 @@ This requires SSH access to the container, which is available when connecting vi Port forwarding behavior is configured in `.devcontainer/devcontainer.json`: ```jsonc -"forwardPorts": [], +"forwardPorts": [7847], "portsAttributes": { "7847": { - "label": "Claude Dashboard", + "label": "CodeForge Dashboard", "onAutoForward": "notify" }, "*": { @@ -124,7 +124,7 @@ Port forwarding behavior is configured in `.devcontainer/devcontainer.json`: } ``` -- `forwardPorts` — static port list (empty by default; VS Code auto-detects dynamically instead) +- `forwardPorts` — static port list (dashboard port 7847 is pre-configured; VS Code also auto-detects dynamically) - `portsAttributes` — labels and behavior for auto-detected ports (VS Code / Codespaces only) These settings are ignored by non-VS Code clients. Use `dbr` or SSH tunneling instead. diff --git a/docs/src/content/docs/reference/troubleshooting.md b/docs/src/content/docs/reference/troubleshooting.md index 9c0431e..78f761d 100644 --- a/docs/src/content/docs/reference/troubleshooting.md +++ b/docs/src/content/docs/reference/troubleshooting.md @@ -187,7 +187,7 @@ Any local feature can be disabled without removing it from `devcontainer.json` b 2. **Restore default config sources** — run `git checkout .codeforge/config/` to discard any local edits to the source files, then restart the container to redeploy. -3. **Reset aliases** — delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash /workspaces/.devcontainer/scripts/setup-aliases.sh`. +3. **Reset aliases** — delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash .devcontainer/scripts/setup-aliases.sh` from your project root (or `/workspaces/.devcontainer/scripts/setup-aliases.sh` for workspace-scoped installs). 4. **Full reset** — rebuild the container from scratch (VS Code: **Dev Containers: Rebuild Container**). This recreates everything but still preserves `.codeforge/` user modifications since they live in the repository.