You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/content/docs/features/agents.md
+57-5Lines changed: 57 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ CodeForge **entirely replaces** all six built-in agents with enhanced custom spe
30
30
31
31
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.
32
32
33
-
Beyond the six replacements, CodeForge adds **11 entirely new specialists** that have no built-in equivalent: architect, researcher, test-writer, refactorer, doc-writer, migrator, security-auditor, dependency-analyst, git-archaeologist, perf-profiler, debug-logs, and spec-writer. These are available only in CodeForge.
33
+
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.
34
34
35
35
:::tip[Why This Matters]
36
36
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.
@@ -122,6 +122,18 @@ A technical writing specialist that creates and maintains README files, API docu
122
122
"Document the public API for the user service module. Include usage examples and parameter descriptions."
A documentation and specification lifecycle agent. Handles READMEs, API docs, inline documentation, and architectural guides alongside the full spec workflow — creating, refining, reviewing, and closing specifications. Carries 7 frontloaded skills covering both documentation patterns and all spec operations. Unlike doc-writer, the documenter works directly (no worktree isolation) and owns the spec lifecycle. Never modifies source code logic.
130
+
131
+
**When activated:** "Document this module," "write a README," "create a spec and document the feature," specification lifecycle tasks that combine docs and specs.
132
+
133
+
:::tip[documenter vs doc-writer]
134
+
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-new, spec-refine, spec-review, spec-update, spec-check) built in.
A full-stack implementation agent that handles all code modifications: writing new features, fixing bugs, refactoring existing code, and executing migrations. Runs tests after every edit via a Stop hook to catch regressions immediately. Works in a git worktree so your main branch stays clean. The broadest-scope implementation agent — use the more focused refactorer, migrator, or test-writer when the task is clearly within one domain.
178
+
179
+
**When activated:** General implementation tasks, feature building, bug fixes, "implement this," multi-file changes that span domains.
180
+
181
+
:::tip[Try this]
182
+
"Implement the user notification preferences feature. Add the database model, API endpoints, and update the settings page."
A comprehensive read-only research agent that consolidates six analysis domains: codebase exploration, web research, git history forensics, dependency auditing, log analysis, and performance profiling. Carries 6 frontloaded skills — more than any other agent — making it the go-to for complex investigations that cross domain boundaries. Never modifies files.
190
+
191
+
**When activated:** Complex multi-domain investigations, "investigate why," "research and analyze," tasks that combine codebase analysis with git history or dependency research.
192
+
193
+
:::tip[investigator vs specialists]
194
+
Use the **investigator** when an investigation spans multiple domains (e.g., "why is this slow" might need codebase analysis, git history, and performance profiling). Use a focused specialist (researcher, debug-logs, git-archaeologist, perf-profiler, dependency-analyst) when the domain is clear.
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 spec-update skill for closing the spec loop after writing tests.
286
+
287
+
**When activated:** "Write tests for," "add test coverage," "create integration tests," test creation tasks.
288
+
289
+
:::tip[tester vs test-writer]
290
+
These agents are nearly identical. **tester** includes the spec-update 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.
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.
@@ -291,10 +343,10 @@ Agents use different Claude models based on task complexity. Opus handles the mo
291
343
292
344
Several agents include built-in safety hooks:
293
345
294
-
-**Read-only bash guard** — The architect, explorer, security auditor, dependency analyst, and git-archaeologist all have a PreToolUse hook that blocks any Bash command that could modify files or state.
346
+
-**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.
295
347
-**Git-readonly guard** — The git-archaeologist has a specialized guard that only permits read-only git subcommands (log, blame, show, diff, reflog, etc.).
296
348
-**Post-edit test verification** — The refactorer runs tests automatically after every single Edit operation. If tests fail, the change is immediately reverted.
297
-
-**Stop verification** — The test-writer has a Stop hook that verifies all written tests pass before the agent completes.
349
+
-**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.
description: Run CodeForge from the command line without VS Code — build, connect, and manage containers using the devcontainer CLI.
4
+
sidebar:
5
+
order: 4
6
+
---
7
+
8
+
The DevContainer CLI lets you build and run CodeForge containers without VS Code. Use it when you prefer terminal-only workflows, work on headless servers, or need DevContainer support in CI/CD pipelines.
9
+
10
+
## Install the CLI
11
+
12
+
```bash
13
+
npm install -g @devcontainers/cli
14
+
```
15
+
16
+
Requires Node.js 16.13+ or 18+ (when installing via npm). Verify the installation with `devcontainer --version`.
17
+
18
+
## Build and Start
19
+
20
+
From your project root (where `.devcontainer/` lives):
21
+
22
+
```bash
23
+
devcontainer up --workspace-folder .
24
+
```
25
+
26
+
The first build takes several minutes — it pulls the base image, installs all features, and runs post-start setup. Subsequent starts reuse cached layers and complete in seconds.
27
+
28
+
:::caution[Don't interrupt the first build]
29
+
If the build is interrupted, Docker may cache a partial state. Rebuild from scratch:
30
+
```bash
31
+
devcontainer up --workspace-folder . --remove-existing-container
32
+
```
33
+
:::
34
+
35
+
## Connect to the Container
36
+
37
+
The recommended way to get a shell inside the container:
38
+
39
+
```bash
40
+
devcontainer exec --workspace-folder . zsh
41
+
```
42
+
43
+
This uses the devcontainer CLI's exec command, which respects the container's configured user and environment. You can also use `docker exec` directly — run `docker ps` to find the container name:
44
+
45
+
```bash
46
+
docker exec -it <container-name> zsh
47
+
```
48
+
49
+
## Run Commands
50
+
51
+
Execute commands without entering an interactive shell:
VS Code auto-forwards container ports to your host automatically. **The CLI does not.** You need an explicit forwarding mechanism.
67
+
68
+
:::caution[No automatic port forwarding]
69
+
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.
70
+
:::
71
+
72
+
**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:
73
+
74
+
```bash
75
+
# On your host machine
76
+
dbr host-daemon
77
+
```
78
+
79
+
**Alternative:** Use SSH tunneling for specific ports:
See [Port Forwarding](/reference/port-forwarding/) for the full setup guide and comparison of all forwarding mechanisms.
86
+
87
+
## Key Differences from VS Code
88
+
89
+
| Capability | VS Code | DevContainer CLI |
90
+
|------------|---------|------------------|
91
+
| Port forwarding | Automatic | Manual — use `dbr` or SSH tunneling |
92
+
| Extensions panel | GUI in sidebar | Not available |
93
+
| Ports panel | Visual port management | Not available — use `docker port` or `dbr`|
94
+
| Terminal management | Integrated tabs | Manual — use tmux for parallel sessions |
95
+
| File editing | Built-in editor | Use your preferred editor (vim, nano, etc.) |
96
+
97
+
## Rebuilding
98
+
99
+
When you change `devcontainer.json` or feature configurations, rebuild:
100
+
101
+
```bash
102
+
# Rebuild using cached layers (fast)
103
+
devcontainer up --workspace-folder .
104
+
105
+
# Full rebuild from scratch (slow, but fixes cache issues)
106
+
devcontainer up --workspace-folder . --remove-existing-container
107
+
```
108
+
109
+
## Stopping the Container
110
+
111
+
The devcontainer CLI doesn't have a dedicated stop command. Use Docker directly:
112
+
113
+
```bash
114
+
# Find the container name
115
+
docker ps
116
+
117
+
# Stop the container
118
+
docker stop <container-name>
119
+
120
+
# Or stop and remove it
121
+
docker rm -f <container-name>
122
+
```
123
+
124
+
## Tips
125
+
126
+
-**Use tmux** for parallel sessions inside the container. CodeForge installs tmux by default — run `tmux` after connecting to get split panes and persistent sessions.
127
+
-**Connect external terminals** using the scripts in `.codeforge/scripts/` — `connect-external-terminal.sh` (macOS/Linux) or `connect-external-terminal.ps1` (Windows PowerShell).
128
+
-**Combine with `dbr`** for the closest experience to VS Code — automatic port forwarding without needing VS Code running.
129
+
130
+
## Next Steps
131
+
132
+
-[Your First Session](/getting-started/first-session/) — start using CodeForge with Claude Code
Copy file name to clipboardExpand all lines: docs/src/content/docs/getting-started/first-session.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: First Session
3
3
description: Walkthrough of your first Claude Code session inside a CodeForge DevContainer.
4
4
sidebar:
5
-
order: 4
5
+
order: 6
6
6
---
7
7
8
8
You've installed CodeForge and the container is running. Now it's time to launch your first Claude Code session and see everything in action. This guide walks you through what happens when you start a session, what to try first, and how the different systems work together.
@@ -24,6 +24,7 @@ The `cc` command is a CodeForge alias that launches Claude Code with the correct
24
24
|`cc`| Full CodeForge session with system prompt, plugins, and all configuration |
25
25
|`claude`| Same as `cc` — an alias for convenience |
26
26
|`ccw`| Writing-focused session using the writing system prompt (great for documentation) |
0 commit comments