Package Scope

This page states why each packages/ directory exists, what it owns, and what it must not absorb. Use it when deciding where a feature belongs and what the product should grow into.

The Portuguese product-planning inventory lives at packages/README.md. Source code remains the implementation reference. Hosted control plane, Cloud Agent, billing, App Builder, and cloud (external repo) live in CFactory-Org/cloud, not here.

Product map

Clients
  CFactory IDE (cfactory-ide) embeds the VS Code extension
  CFactory Console                   Zed (ACP only)
           │                              │
           └──────── HTTP + SSE ──────────┘
                      ▼
Local runtime
  factory-cli (`packages/opencode`) = CLI + daemon + serve + TUI + session + tools
       ├── core, plugin, plugin-atomic-chat
       ├── indexing, gateway, telemetry
       └── sdk (generated client of serve)
                      ▼
Cloud (other repo; local stand-in is cfactory-gateway-server)

Three local layers:

1. Runtime — one agent engine per machine (opencode).
2. Clients — editors and Console; they do not run the agent, they talk to cfactory serve.
3. Shared platform — SDK, UI, gateway client, indexing, i18n.

Runtime and contracts

opencode (factory-cli) — @cfactory/cli

Objective. Local CFactory engine. This is the CLI product and the backend of every editor client.

Does not own. Editor UI, VS Code inline autocomplete, IDE desktop build, hosted gateway, hosted model catalog.

Product role. The spine. Agent capabilities (skill, command, tool, session) start here so every client inherits them. Clients add editor-only UX.

The directory is still named opencode; the published package is @cfactory/cli.

core — @cfactory/core

Objective. Shared process primitives with no session logic.

Owns. Filesystem, flags, glob, log, npm install, XDG paths, schema helpers, Effect runtime/logger, version.

Does not own. Session, serve HTTP, UI, CFactory auth.

Product role. Internal library. Grow it only when two or more packages need the same primitive.

llm — @cfactory/llm

Objective. Effect-first LLM core: one request/event model and protocol routes (OpenAI Chat/Responses, Anthropic, Gemini, Bedrock, compatibles).

Owns. Canonical schema (LLMRequest, LLMEvent), protocols, transports, built-in providers, typed tool runtime, cassette tests.

Does not own. CFactory session, permissions, file/bash tools, UI, billing.

Product role. Platform investment. The live CLI still uses a different provider stack. Destination: back or replace CLI model routing. Do not turn this into a second agent runtime.

plugin — @cfactory/plugin

Objective. Public contract to extend the CLI: tools, hooks, providers, workspaces, TUI.

Owns. PluginInput / Plugin types, tool definition, optional TUI hooks.

Does not own. Concrete plugins (except sibling packages) or session execution.

Product role. Ecosystem surface. Version it carefully; breaks third-party plugins.

plugin-atomic-chat — @cfactory/plugin-atomic-chat

Objective. Detect and expose models from a local Atomic Chat (OpenAI-compatible) server.

Product role. Point integration. New local LLM servers should be similar plugins, not core forks.

sdk (sdk/js) — @cfactory/sdk

Objective. TypeScript client of cfactory serve. The contract between runtime and clients.

Owns. Generated v1/v2 client from the server OpenAPI, createCFactoryClient, spawn/server helpers.

Does not own. Route implementation (opencode) or UI.

Product role. The contract. Clients must not invent a parallel fetch layer. Console, IDE, and automations depend on this remaining the only entry door.

Clients

cfactory-vscode — cfactory (VSIX)

Objective. CFactory inside VS Code / VSCodium / CFactory IDE.

Owns. Chat webview, settings, marketplace, Agent Manager. Inline autocomplete, browser automation, commit message, code actions. Per-window cfactory serve lifecycle. HTTP + SSE bridge into the webview.

Does not own. Agent engine, VSCodium build, hosted gateway.

Owns. shared / frontend / backend (Swing only). CLI spawn, RPC, native session UI.

Does not own. Solid webview, VS Code-style autocomplete (unless implemented natively), gateway.

cfactory-ide

Objective. Branded desktop IDE: VSCodium with CFactory preinstalled (cfide).

Owns. Fetch/brand/build scripts, product.json overlay, icons, IDE defaults, packaging.

Does not own. Workbench source (VSCodium), extension logic (cfactory-vscode), CLI (bundled by the extension).

Product role. Distribution, not runtime. IDE roadmap = extension + branding. Do not add cfide-only features in the VSCodium overlay beyond defaults and layout.

cfactory-console — @cfactory/cfactory-console

Objective. Local browser UI for projects, PTY terminals, and config (models, agents, MCP, permissions, formatters).

Owns. Solid/Vite app. Daemon discovery on ports 4097–4116. Settings and project-console screens.

Does not own. The daemon (CLI), cloud auth, hosted control plane.

Product role. Developer local console — not factory.cfly.ai. Candidate shared settings UI. Console vs extension settings is an open product decision.

cfactory-admin — @cfactory/cfactory-admin

Objective. Organization SaaS admin panel (teams, projects, skills, commands, rules, models, MCP, usage).

Owns. React + Vite + Tailwind + shadcn-style UI, dark-first, CFly brand pink (#EC4899). Talks only to VITE_CFACTORY_API_URL.

Does not own. Local cfactory serve, Solid design systems, CLI sync apply.

Product role. Control plane UI for the SaaS IDE. See Organization Sync.

extensions/zed

Objective. Minimal Zed extension via ACP (cfactory acp).

Owns. extension.toml and icon. Downloads the binary and starts the agent server.

Does not own. Custom Zed UI, webview, CFactory marketplace.

Product role. Editor presence, not parity. Grow only if ACP + CLI cover the flow.

Cloud integration and intelligence

cfactory-gateway — @cfactory/cfactory-gateway

Objective. CFactory Cloud client: device-auth login, provider, profile, balance, models, embeddings, editor headers.

Owns. Auth plugin, createCFactory(), profile/balance/models APIs, CFACTORY_API_URL resolution.

Does not own. Gateway server, billing, cloud orchestration.

Product role. Only local → cloud bridge. The local gateway-server must stay API-compatible with this client.

cfactory-gateway-server — @cfactory/cfactory-gateway-server

Objective. Local stand-in for cloud so development works without api.factory.cfly.ai: Keycloak SSO, Bifrost completions, Postgres state.

Owns. Device auth, tokens, /api.json (models.dev-shaped catalog), chat/embeddings proxy. Non-essential endpoints return empty shapes.

Does not own. Production, real billing, Cloud Agent. Requires Docker (dev:stack).

Product role. Dev tool. Production gateway is in the cloud repo. Value is contract compatibility with cfactory-gateway.

cfactory-telemetry — @cfactory/cfactory-telemetry

Objective. CLI telemetry (PostHog) tied to CFactory login identity.

Does not own. Extension analytics or marketing-site analytics.

Product role. Local usage observability. Must stay opt-out and free of source PII.

cfactory-indexing — @cfactory/cfactory-indexing

Objective. Async codebase index and semantic search (semantic_search).

Owns. Engine (tree-sitter, embeddings, Qdrant/LanceDB/pgvector), CLI plugin, HTTP status, file watch.

Does not own. Chat. VS Code autocomplete ranking (the extension has its own complete index).

Product role. “The agent knows the repo.” Open decision: one engine vs. a parallel complete-index in the extension.

UI and i18n

ui — @cfactory/ui

Solid design system inherited from CFactory CLI: chat parts, markdown, diffs, theme, icons. Base library. Overlaps cfactory-ui.

cfactory-ui — @cfactory/cfactory-ui

CFactory-branded Solid components (logo, spinner, session-turn, dock). Intended CFactory design system.

cfactory-web-ui — @cfactory/cfactory-web-ui

Console/settings pieces (config-row, status-tag, shell, forms). Stops the Console from inventing a fourth design system.

cfactory-i18n — @cfactory/cfactory-i18n

Extension/product translation bundles. New locales land here, not scattered in the webview.

Docs and tooling

sdk/ is a folder wrapper; the npm package is sdk/js. extensions/ holds non-bun editor extensions (Zed). containers/ has no package.json.

Dependency direction

cfactory-ide ──────────► cfactory-vscode ──► sdk, ui, cfactory-ui, gateway, i18n, indexing
cfactory-console ──────► sdk, cfactory-web-ui ──► cfactory-ui ──► ui
opencode ──────────────► core, plugin, gateway, indexing, telemetry, sdk, plugin-atomic-chat
indexing / telemetry ──► gateway
llm ───────────────────► http-recorder (tests)
gateway-server ────────► isolated (Hono + pg)

New agent features go into opencode or the SDK. Clients consume.

Open product decisions

2. Three Solid design systems. Healthy path: one CFactory DS (cfactory-ui) plus a thin web layer. Treat ui as CFactory CLI legacy to absorb.
3. Two indexes. Agent semantic search vs. extension autocomplete. Unify embeddings/store unless complete latency forces a split.
4. Settings in two places. Console and the extension webview both edit cfactory.json. Unify on CLI APIs plus one UI.
5. llm vs CLI providers. Do not add a third way to call a model. Decide when the runtime switches to LLMClient.
6. Local vs hosted gateway. This repo guarantees the client contract. Do not reimplement billing or Cloud Agent here.
7. IDE vs extension. cfactory-ide is packaging. Do not grow cfide-only product features in the VSCodium overlay.
8. Outside this repo. If it runs in the cloud (control plane, Cloud Agent, App Builder, cloud (external repo), Gas Town, billing), it belongs in CFactory-Org/cloud.

Quick table