ForgeCode — Scoping & Rebrand Plan

ForgeCode

Repo: CMMD-Center/forge-code Status: v1 tagged. End-to-end verified through the /forge GitHub bot 2026-05-20. Role: CMMD’s AI coding agent harness — the engine inside Forge desktop, a standalone CLI for engineers, and the runtime for the /forge bot.

Why ForgeCode (not “build our own”)

Anthropic ships Claude Code with 33+ built-in tools, streaming UX, plan mode, MCP, IDE integrations, sandboxing — years of engineering. Building from scratch = months of work for an inferior product.

OpenCode is the best open-source coding agent (161K stars, MIT, native Anthropic API, MCP, LSP-feedback loop, multi-provider). Forking gives us the harness for free. Forge then puts a desktop UX around it. Apex models power it. Engineers and users both ride the same engine.

Architecture

        ┌────────────────────────────────────────────────────────────┐
        │                  THREE CONSUMER SURFACES                   │
        │                                                            │
        │  Forge desktop      /forge GitHub bot       Standalone     │
        │  (Mac/Win/Linux)    (CMMD-Center repos)     CLI (engineers)│
        │       │                  │                       │         │
        │       └──────────────────┴───────────────────────┘         │
        │                          ▼                                 │
        │            ForgeCode (the agent engine)                    │
        └──────────────────────────┼─────────────────────────────────┘
                                   ▼
                ┌─────────────────────────────────────┐
                │     https://apex.cmmd.ai/v1         │
                │     apex-think-shim + Cloudflare    │
                └──────────────┬──────────────────────┘
                               ▼
                ┌─────────────────────────────────────┐
                │  apex-core   (local / free, default)│
                │  apex-flash  (cloud / paid)         │
                │  apex-general (cloud / paid)        │
                │  apex-reason  (cloud / paid)        │
                └─────────────────────────────────────┘

The three surfaces share the same engine. Tools, prompts, model behavior, auth, and apex routing are identical regardless of where ForgeCode runs.

Repo state

Component	Status
User-visible brand pass	✅ All Forge/Apex on user-facing surfaces (CLI logs, banner-adjacent strings, action.yml, README, GitHub repo description, footer link text)
Internal env var + path rebrand	✅ 212-file sweep complete — OPENCODE_ env vars → FORGE_, .opencode paths → .forge, .config/opencode → .config/forge
LICENSE	✅ CMMD MIT (private repo, no external attribution)
Initial commit	✅ Clean orphan history, no shared ancestry with upstream
bun install validation	✅ Works on first run + cached on the /forge bot runner (CMMD-Homebase)
Apex endpoint integration	✅ provider.anthropic.options.baseURL = https://apex.cmmd.ai/v1, models registered, x-api-key header verified
Forge GitHub Action	✅ Tagged v1, end-to-end verified on CMMD-Center/CMMD — see /forge bot doc
GHA CI on forge-code itself	🛠 TODO (task #94)
apex-skills loader	🛠 TODO — port the CC plugin format to ForgeCode’s skill loader
Forge GitHub App for Forge[bot] author badge	🛠 TODO (task #110) — bot currently posts as github-actions[bot]
Logos / SVG assets	🛠 Deferred — internal use only, not user-visible in current surfaces
Internal LLM-routing arch docs (packages/llm/)	🛠 Task #111 — code-maintainer docs only, scrub when convenient

Phase plan

Phase 1 — Buildable baseline (this week)

• Run bun install from repo root, fix anything broken by the rename
• Smoke test bun dev (runs the CLI in dev mode)
• Smoke test single tool-use round-trip against apex.cmmd.ai with apex-core
• Wire a basic CI workflow (typecheck + test) on our Forgejo runners

Phase 2 — Apex-native integration (1-2 weeks)

• Add Apex as a first-class provider (alongside the 75 OpenCode shipped with)
• Default provider/model on first launch = apex-core via apex.cmmd.ai
• Authentication: bearer-token via the apex-token CLI flow
• Port apex-skills so ForgeCode auto-loads our 14 skills
• Strip provider definitions we don’t ship (OpenRouter, Google Vertex, etc. — keep only Anthropic + Apex + local Ollama)

Phase 3 — Branding pass (1 week)

• Replace logo SVGs in packages/ui/src/asset/ with Forge brand assets
• Replace favicon files in packages/*/public/
• Customize CLI banner / welcome message (“Welcome to ForgeCode”)
• Customize default system prompt — short, Apex-aware (drops the ~26K-token preamble that CC carries)
• Update docs site theme to CMMD brand

Phase 4 — Forge desktop integration (2-4 weeks)

• Inventory what’s in packages/desktop/ — what UX surface exists today
• Decide: ship desktop from this monorepo, or extract ForgeCode core as a library that Forge desktop imports?
• If extract: publish @cmmd-center/forge-code-core to a private npm registry
• Integrate into the Forge desktop shell (replace whatever agent harness it has now, if any)

Phase 5 — User-facing polish (ongoing)

• Auto-update flow (Forge can ship updates to bundled ForgeCode)
• Telemetry → homebase Grafana (opt-in)
• BYOMCP UX — let users add their own MCP servers with a per-MCP token-cost meter
• Model picker UX: apex-core (deep) vs apex-flash (fast) vs hosted Claude vs Bring-Your-Own

Out of scope (for now)

• Mobile / web-only ForgeCode (desktop and CLI only)
• Multi-language UI translations (English first; revisit when there’s demand)
• Forge desktop UX rebuild (separate workstream, owned by the Forge team)
• Apex-flash model (we shipped apex-core; harden that first per the brand decision)

Key technical decisions to make

Decision	Default	Rationale
Bundle desktop in same monorepo or separate?	Separate (Forge desktop is its own product)	Cleaner ownership, faster CI per-repo
OpenCode’s web/console packages — ship or archive?	Archive most	We don’t need a web playground; CMMD has internal-docs for docs
Keep sst.config.ts / SST AWS infra?	Archive	We use Cloudflare + Forgejo, not SST
Slack / Discord notifications?	Archive	Slack already in homebase, not the ForgeCode repo’s job
OpenAPI generation?	Keep	The HTTP-server mode is valuable for headless agents (CI bots, Forge backend)

Related notes

• [[apex-skills]] — the skills library that ForgeCode auto-loads
• [[apex-models]] — the Apex model line ForgeCode targets by default
• [[forge-product]] — the user-facing creative suite that wraps ForgeCode