CodeForge Usage Guide

Everything you need to know once you're inside the devcontainer. These instructions apply regardless of which client you used to start the container — VS Code, the devcontainer CLI, JetBrains Gateway, DevPod, or GitHub Codespaces.

Quick Start

Authenticate (first time only)
```
claude
```
Follow the prompts to authenticate via browser or API key.
Start Claude Code
```
cc
```

Claude Code Authentication

Claude Code supports multiple authentication methods. On first run, you'll be prompted to choose:

Browser Login (Recommended)

claude

Select "Login with browser" and complete authentication in your browser. This uses your Claude.ai account.

API Key

For programmatic access or environments without browsers:

export ANTHROPIC_API_KEY="sk-ant-..."
claude

Get an API key from console.anthropic.com.

Credential Persistence

Authentication credentials are stored in ~/.claude/ and persist across container rebuilds via a Docker named volume.

Long-Lived Token Authentication

For headless or automated environments, you can use a long-lived auth token instead of browser login:

Generate a token: claude setup-token

Add to .devcontainer/.secrets:

CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here

On next container start, setup-auth.sh will create ~/.claude/.credentials.json automatically.

You can also set CLAUDE_AUTH_TOKEN as a Codespaces secret for cloud environments.

For more options, see the Claude Code documentation.

GitHub & NPM Authentication

Automatic Auth via `.secrets` (Recommended)

CodeForge can automatically configure GitHub CLI, git identity, and NPM auth on every container start. Copy the template and fill in your tokens:

cp .devcontainer/.secrets.example .devcontainer/.secrets

Edit .devcontainer/.secrets:

GH_TOKEN=ghp_your_token_here
GH_USERNAME=your-github-username
GH_EMAIL=your-email@example.com
NPM_TOKEN=npm_your_token_here

On the next container start (or rebuild), setup-auth.sh will:

Authenticate gh CLI and configure git credential helper
Set git config --global user.name and user.email
Set NPM registry auth token

The .secrets file is gitignored at two levels (root .* + .devcontainer/.gitignore) and will never be committed.

Environment variable fallback: For Codespaces or CI, set GH_TOKEN, GH_USERNAME, GH_EMAIL, and/or NPM_TOKEN as environment variables (e.g., via Codespaces secrets or localEnv in devcontainer.json). Environment variables take precedence over .secrets file values.

Disable automatic auth by setting SETUP_AUTH=false in .devcontainer/.env.

Interactive Login (Alternative)

GitHub CLI (gh) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.

gh auth login

Follow the prompts:

Select GitHub.com (or your enterprise server)
Choose your preferred protocol: HTTPS (recommended) or SSH
Authenticate via browser (easiest) or paste a personal access token

Token-Based Login

For automated setups or environments without browser access:

# From a file
gh auth login --with-token < ~/github-token.txt

# From environment variable
echo "$GITHUB_TOKEN" | gh auth login --with-token

Generate a token at github.com/settings/tokens with appropriate scopes (typically repo, read:org).

Verifying Authentication

gh auth status

Expected output shows your authenticated account and token scopes.

Credential Persistence

GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in /workspaces/.gh/ (via GH_CONFIG_DIR), which is part of the bind-mounted workspace. Claude Code credentials persist via a Docker named volume mounted at ~/.claude/.

You only need to authenticate once. After running gh auth login or configuring .secrets, your credentials will survive container rebuilds and be available in future sessions.

Using Claude Code

The `cc` Command

The cc command is an alias that launches Claude Code with the project's system prompt and plan-mode permissions. For Agent Teams split-pane support, use the "Claude Teams (tmux)" terminal profile in VS Code (dropdown next to the + button) or connect via .codeforge/scripts/connect-external-terminal.sh.

cc                    # Start Claude Code in current directory
cc "explain this"     # Start with an initial prompt

Direct CLI

For more control, use the claude command directly:

claude                        # Basic invocation
claude --help                 # View all options
claude --resume               # Resume previous session

Available Tools

Languages & Runtimes

Tool	Description
Python 3.14	Base language runtime
Node.js LTS	JavaScript runtime
TypeScript	Via Node.js
Go	Optional — uncomment Go feature in `devcontainer.json` to enable
Rust	Latest stable via devcontainer feature
Bun	Fast JavaScript runtime and toolkit

Package Managers

Tool	Description
`uv`	Fast Python package manager (pip alternative)
`npm`	Node.js package manager
`pip` / `pipx`	Python package installers

Development Tools

Tool	Description
`gh`	GitHub CLI for repository operations
`docker`	Container CLI (connects to host Docker)
`git`	Version control
`jq`	JSON processor
`curl`	HTTP client
`tmux`	Terminal multiplexer for Agent Teams split-pane sessions
`biome`	Fast JS/TS/JSON/CSS formatter and linter
`ruff`	Fast Python linter and formatter (replaces Black + Flake8)
`shfmt`	Shell script formatter
`dprint`	Pluggable formatter for Markdown, YAML, TOML, Dockerfile
`shellcheck`	Static analysis tool for shell scripts
`hadolint`	Dockerfile linter
`agent-browser`	Headless browser automation for AI agents

Code Intelligence

Tool	Description
tree-sitter	AST parsing for JavaScript, TypeScript, Python
ast-grep	Structural code search and rewriting
Pyright	Python language server
TypeScript LSP	TypeScript/JavaScript language server

Claude Code Tools

Tool	Description
`claude`	Claude Code CLI
`codeforge`	CodeForge CLI (experimental) — session search, plugin management, indexing
`cc`	Wrapper with auto-configuration
`ccusage`	Token usage analyzer
`ccburn`	Visual token burn rate tracker with pace indicators
`ccstatusline`	Status bar display (integrated into Claude Code, not standalone CLI)
`claude-monitor`	Real-time usage tracking
`codeforge-dashboard`	Session analytics dashboard — auto-launches on start (port 7847)

Configuration

Environment Variables

Copy .devcontainer/.env.example to .devcontainer/.env and customize:

Variable	Default	Description
`CLAUDE_CONFIG_DIR`	`/home/vscode/.claude`	Claude configuration directory
`SETUP_CONFIG`	`true`	Copy config files during setup (per `file-manifest.json`)
`SETUP_ALIASES`	`true`	Add `cc`/`claude`/`ccraw` aliases to shell
`SETUP_AUTH`	`true`	Configure Git/NPM auth from `.secrets`
`SETUP_PLUGINS`	`true`	Install official plugins + register marketplace
`SETUP_UPDATE_CLAUDE`	`true`	Auto-update Claude Code on container start
`SETUP_TERMINAL`	`true`	Configure VS Code Shift+Enter keybinding for Claude Code terminal
`SETUP_PROJECTS`	`true`	Auto-detect projects for VS Code Project Manager
`SETUP_POSTSTART`	`true`	Run post-start hooks from `/usr/local/devcontainer-poststart.d/`
`PLUGIN_BLACKLIST`	`""`	Comma-separated plugin names to skip

Claude Code Settings

Default settings are in .codeforge/config/settings.json. File copying is controlled by .codeforge/file-manifest.json, which specifies per-file overwrite behavior ("if-changed", "always", or "never").

To add a custom config file, append an entry to file-manifest.json:

{
  "src": "my-config.json",
  "dest": "${WORKSPACE_ROOT}",
  "overwrite": "if-changed"
}

Key defaults:

Model: Claude Opus 4-6
Default mode: Plan (prompts before executing)
Max output tokens: 64,000

Keybindings

Default keybindings are in .codeforge/config/keybindings.json (empty by default — Claude Code defaults apply). Customize by adding entries to the bindings array.

VS Code Terminal Passthrough: Ctrl+P and Ctrl+F are configured to pass through to the terminal (via terminal.integrated.commandsToSkipShell) so Claude Code receives them. Other VS Code shortcuts that conflict with Claude Code:

Shortcut	VS Code Action	Claude Code Action
`Ctrl+G`	Go to Line	`chat:externalEditor`
`Ctrl+S`	Save File	`chat:stash`
`Ctrl+T`	Open Symbol	`app:toggleTodos`
`Ctrl+O`	Open File	`app:toggleTranscript`
`Ctrl+B`	Toggle Sidebar	`task:background`
`Ctrl+R`	Open Recent	`history:search`

For conflicting shortcuts, use Meta (Alt) variants or add custom keybindings.

System Prompt

The default system prompt is in .codeforge/config/main-system-prompt.md. Override it by creating a .claude/main-system-prompt.md in your project directory.

Custom Features

CodeForge includes custom devcontainer features. Any feature can be disabled by setting "version": "none" in devcontainer.json — the entry stays in place for easy re-enabling. Each feature's README documents its options and dependencies.

Feature	Description
`tmux`	Terminal multiplexer with Catppuccin theme for Agent Teams
`agent-browser`	Headless browser automation for AI agents
`claude-monitor`	Real-time token usage monitoring with ML predictions
`ccusage`	Usage analytics CLI
`ccburn`	Visual token burn rate tracker with pace indicators
`ccstatusline`	Status bar display (integrated into Claude Code, not standalone CLI)
`ast-grep`	Structural code search using AST patterns
`tree-sitter`	Parser with JS/TS/Python grammars
`lsp-servers`	Pyright and TypeScript language servers
`biome`	Fast JS/TS/JSON/CSS formatter (global install)
`ruff`	Fast Python linter and formatter
`shfmt`	Shell script formatter (disabled by default)
`shellcheck`	Static analysis for shell scripts (disabled by default)
`hadolint`	Dockerfile linter (disabled by default)
`dprint`	Pluggable formatter for Markdown/YAML/TOML (disabled by default)
`ccms`	Claude Code session history search
`claude-session-dashboard`	Local session analytics dashboard with web UI
`notify-hook`	Desktop notifications on Claude completion
`mcp-qdrant`	Qdrant vector database MCP server (optional)

Safety Plugins

Plugin	Description
`dangerous-command-blocker`	Blocks destructive bash commands (rm -rf, sudo rm, chmod 777, force push)
`protected-files-guard`	Blocks modifications to .env, lock files, .git/, and credentials
`workspace-scope-guard`	Enforces working directory scope — blocks writes and warns on reads outside the project

auto-code-quality

Combined auto-formatter, auto-linter, and advisory test runner plugin at plugins/devs-marketplace/plugins/auto-code-quality/. Three-phase pipeline: collect edited files (PostToolUse), batch format + lint (Stop), and advisory test runner (Stop). Supports all languages from the former auto-formatter + auto-linter plugins. Replaces the separate auto-formatter and auto-linter plugins.

Alias Management

Features create shell aliases during container build (e.g., ccusage, ccburn). Separately, setup-aliases.sh creates a managed block in ~/.bashrc and ~/.zshrc on every container start for cc, claude, ccraw, ccw, and cc-tools. Both coexist without conflict — feature aliases are installed at build time while setup aliases are refreshed at start time.

Credential Management

Three methods for providing GitHub/NPM credentials, in order of precedence:

Environment variables — Set GH_TOKEN, GH_USERNAME, GH_EMAIL, NPM_TOKEN as environment variables (e.g., via Codespaces secrets or localEnv in devcontainer.json)
.secrets file — Create .devcontainer/.secrets with token values (see template at .secrets.example). Auto-configured by setup-auth.sh on container start
Interactive login — Run gh auth login for GitHub CLI, then set git identity manually

All methods persist across container rebuilds via the bind-mounted /workspaces/.gh/ directory.

.secrets file with CLAUDE_AUTH_TOKEN — Long-lived Claude auth token from claude setup-token. Auto-creates ~/.claude/.credentials.json on container start.

Agents & Skills

Agents and skills are distributed across focused plugins (replacing the former code-directive monolith).

Custom Agents (17) — `agent-system` plugin

Agent definitions in plugins/devs-marketplace/plugins/agent-system/agents/ provide enhanced behavior when spawned via the Task tool. The redirect-builtin-agents.py hook transparently swaps built-in agent types to these custom agents.

Agent	Purpose
`architect`	System design and implementation planning
`bash-exec`	Command execution specialist
`claude-guide`	Claude Code feature guidance
`debug-logs`	Log analysis and error diagnosis
`dependency-analyst`	Dependency analysis and upgrades
`documenter`	Documentation, specs, and spec lifecycle
`explorer`	Fast codebase search and navigation
`generalist`	General-purpose multi-step tasks
`git-archaeologist`	Git history forensics
`migrator`	Code migration and upgrades
`perf-profiler`	Performance profiling
`refactorer`	Code refactoring with regression checks
`researcher`	Research and information gathering
`security-auditor`	Security vulnerability analysis
`spec-writer`	Specification and requirements authoring
`statusline-config`	ccstatusline configuration
`test-writer`	Test authoring with pass verification

General Skills (23) — `skill-engine` plugin

Skills in plugins/devs-marketplace/plugins/skill-engine/skills/ provide domain-specific coding references:

agent-browser · api-design · ast-grep-patterns · claude-agent-sdk · claude-code-headless · debugging · dependency-management · docker · docker-py · documentation-patterns · fastapi · git-forensics · migration-patterns · performance-profiling · pydantic-ai · refactoring-patterns · security-checklist · skill-building · sqlite · svelte5 · team · testing · worktree

Spec Skills (3) — `spec-workflow` plugin

Skills in plugins/devs-marketplace/plugins/spec-workflow/skills/:

spec · build · specs

Specification Workflow

CodeForge includes a specification-driven development workflow using directory-based "spec packages." Every non-trivial feature gets a spec package before implementation begins.

Quick Start

/spec auth-flow                  # Create, refine, and approve a spec package
/build auth-flow                 # Implement from spec — plan, build, review, close
/specs                           # Dashboard: spec health across the project

The Lifecycle

Backlog — feature ideas live in .specs/BACKLOG.md
Spec — /spec <feature> creates a spec package. The AI drafts everything, presents only genuine trade-off decisions to the human, and makes obvious decisions itself.
Approve — human reviews decisions + AC completeness in index.md (~50-80 lines). Once confirmed, spec is approved.
Build — /build <feature> implements autonomously: plan, build with spec-first testing, self-healing review loop, closure with summary report.
Review — human reads the Completion Summary Report, smoke tests, and reviews AI decisions.
Health check — /specs audits all spec packages for staleness, drafts, and unresolved AI decisions.

Approval Workflow

Specs use spec-level approval:

draft — not ready for implementation. /build rejects it.
approved — human has reviewed decisions and scope. Ready to build.

The AI makes obvious decisions (tagged "Already Decided") and presents genuine trade-offs ("Needs Your Input"). No per-requirement [assumed]/[user-approved] tagging.

A spec-reminder advisory hook fires at Stop when code was modified but specs weren't updated.

Commands Reference

Command	Purpose
`/spec <feature>`	Create, refine, and approve a spec package
`/spec constitution`	Create or update project-level Constitution
`/build <feature>`	Implement from spec — plan, build, review, close
`/specs`	Dashboard: spec health across the project

Directory Structure

.specs/
├── CONSTITUTION.md           # Project-level cross-cutting decisions
├── BACKLOG.md                # Feature idea parking lot
├── auth/                     # Domain folder
│   └── login-flow/           # Spec package (directory)
│       ├── index.md          # Human-facing entry point
│       ├── context.md        # AI-facing shared context
│       └── groups/           # AC groups for parallel build
│           ├── a-credentials.md
│           └── b-sessions.md
└── search/
    └── full-text/
        ├── index.md
        ├── context.md
        └── groups/
            └── a-indexing.md

Every spec is a directory package. index.md is the human review surface. Everything else is for the AI.

Project Manager

The setup-projects.sh script auto-detects projects under /workspaces/ and maintains a projects.json file for the Project Manager VS Code extension. It watches for new projects via inotifywait and updates the project list automatically.

Essential Gotchas

Authentication required: Run claude once to authenticate before using cc
Plan mode default: The container starts in "plan" mode, which prompts for approval before making changes
Config is managed by manifest: .codeforge/file-manifest.json controls which files are copied and when — default overwrite: "if-changed" uses sha256 comparison. Persistent changes go in .codeforge/config/settings.json
GitHub auth persists: Run gh auth login once or configure .secrets; credentials survive container rebuilds
Agent Teams needs tmux: Split panes only work inside tmux. Use the "Claude Teams (tmux)" VS Code terminal profile or .codeforge/scripts/connect-external-terminal.sh from WezTerm/iTerm2

Troubleshooting

Common issues and solutions. For detailed troubleshooting, see the Troubleshooting page on the docs site.

Problem	Solution
`cc: command not found`	Run `source ~/.bashrc` or open a new terminal
`claude` fails during startup	Background update may be in progress — wait 10s and retry
GitHub push fails	Run `gh auth status` to check authentication
Plugin not loading	Check `enabledPlugins` in `.codeforge/config/settings.json`
Feature not installed	Check `devcontainer.json` for `"version": "none"`
Tool version/status	Run `cc-tools` to list all tools with version info
Full health check	Run `check-setup` to verify setup status

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

CodeForge Usage Guide

Quick Start

Claude Code Authentication

Browser Login (Recommended)

API Key

Credential Persistence

Long-Lived Token Authentication

GitHub & NPM Authentication

Automatic Auth via .secrets (Recommended)

Interactive Login (Alternative)

Token-Based Login

Verifying Authentication

Credential Persistence

Using Claude Code

The cc Command

Direct CLI

Available Tools

Languages & Runtimes

Package Managers

Development Tools

Code Intelligence

Claude Code Tools

Configuration

Environment Variables

Claude Code Settings

Keybindings

System Prompt

Custom Features

Safety Plugins

auto-code-quality

Alias Management

Credential Management

Agents & Skills

Custom Agents (17) — agent-system plugin

General Skills (23) — skill-engine plugin

Spec Skills (3) — spec-workflow plugin

Specification Workflow

Quick Start

The Lifecycle

Approval Workflow

Commands Reference

Directory Structure

Project Manager

Essential Gotchas

Troubleshooting

Further Reading

Automatic Auth via `.secrets` (Recommended)

The `cc` Command

Custom Agents (17) — `agent-system` plugin

General Skills (23) — `skill-engine` plugin

Spec Skills (3) — `spec-workflow` plugin