Quick Start · Providers · Clients · Integrations · Manage

What AgentSwitchboard is

AgentSwitchboard is a provider-independent runtime, compatibility gateway, and local tool plane for coding agents. It keeps the Claude Code client and terminal experience while routing requests through a local FCC compatibility gateway:

Claude Code / fccdanger -> FCC -> selected provider protocol -> model

The current release path is terminal-first. fcc-server opens the Textual control center in an interactive terminal and reports local health and control endpoints; it never opens a desktop browser or launches a terminal-browser presentation. The verified Muse path is opencode_go/muse-spark-1.2-contributor over OpenCode Go's Responses protocol.

This repository is the AgentSwitchboard project, substantially evolved from the upstream Free Claude Code codebase. The local release head is version 4.62.4; examples below describe this checkout, not every feature proposed in the open design backlog. The installed distribution and fcc* commands remain the legacy compatibility surface for now. Live smoke receipts retain the package version that was installed when each receipt was captured; read the receipt's own metadata before treating it as evidence for a later release head.

AgentSwitchboard is an independent open-source project. It is not affiliated with or endorsed by Anthropic, OpenAI, or the Free Claude Code upstream project. Claude and Claude Code are trademarks of Anthropic. Codex and OpenAI are trademarks of OpenAI. See upstream attribution and third-party notices.

What You Get

• Use Claude Code in the terminal. Run the legacy-compatible fcc-claude or fccdanger launcher through the local FCC gateway.
• Choose a configured model. Set an exact provider/model reference or a stable alias in FCC's managed environment file.
• Preserve coding-agent behavior. The release path covers streaming text, file tools, repeated tool calls, provider receipts, and one compact/resume cycle with the literal Claude client.
• Save time and tokens. Five built-in optimizations handle quota probes, command-prefix detection, title generation, suggestion mode, and filepath extraction locally instead of calling your provider; optionally enable RTK to filter noisy terminal output before it reaches the model.
• Keep provider boundaries visible. FCC records metadata-only usage, fault-attribution receipts, and pre-network provider-policy decisions; it does not silently select a different provider when the configured native route is unsupported.

Release status

Status	Current scope
Current-source verified	Textual terminal fcc-server/fccdanger, the local repo/profile control center with next-launch isolation and bundle transfer, fuzzy provider/model selection, secret-safe custom OpenAI-compatible provider CRUD, independent FCC provider and Codex Tool Account management, FCC routing, OpenCode Go native protocols, text and file-tool loops, the settings-layer proxy-routing firewall, bounded client context and artifact-backed text-tool-result governance, global context-discipline policy, reasoning capability/visibility receipts, model catalog visibility, stable aliases, and the compatibility wrapper/certification path.
Live receipt evidence	The checked-in receipts prove a literal Claude 2.1.228 Muse auto-compact/tool/resume path, managed fresh/resume/fork inheritance, the five-level reasoning matrix, the direct off/minimal Messages boundary, foreground Agent/subagent execution, and top-level --bg attach/tool execution. Each receipt records its own capture version and boundary; they are metadata-only and do not claim that every adjacent feature is certified.
Partial or unverified	Live native-vs-FCC economic parity, deep semantic compaction torture, and the installed Claude CLI's unsupported --effort off/minimal flags. Image/Appshot, learning/memory/skills, Codex/Pi, and messaging remain boundary-specific integrations.
Partial / explicit opt-in	A loopback-only Chrome/Chromium CDP bridge exposes bounded tab, DOM, navigate, click, type, scroll, and query primitives for injected local tool planes; it is not enabled by default and does not replace the planned end-to-end Claude tool integration.
Planned or design-only	Provider-independent computer use, full capability-aware helper execution, and exhaustive Claude-version/subagent compatibility. See #66.

Claude Code running with AgentSwitchboard's FCC compatibility gateway.

Quick Start

1. Install or update

From this checkout, install the current local code into uv's tool environment:

uv tool install --editable . --force

The repository installers remain available for a full machine setup: install.sh and install.ps1. Review them before running. Re-run the editable uv command after local changes so the installed fcc-server, fcc-claude, and fccdanger commands use this release head.

Local test loop

The local test configuration runs pytest in one process so a full run leaves normal CPU capacity available on a developer Mac. Use the fast loop for the ordinary edit/check cycle:

./scripts/ci.sh --fast

It uses quiet pytest output and excludes tests marked integration, live, interactive, or installer. The pytest process is also launched with a small macOS utility-QoS/priority reduction (or nice -n 5 on other POSIX systems), and child processes inherit that policy. Run the complete local sequence with ./scripts/ci.sh; it runs the lightweight set serially and then runs the safe marked tier serially. Installer and uninstaller tests are intentionally not part of that routine loop because they exercise process discovery and machine-install surfaces. Run them only when needed with:

./scripts/ci.sh --only pytest --installers

Run the explicit marked integration/live/interactive tier alone with:

./scripts/ci.sh --only pytest --integration

Use --only pytest when iterating on tests without rerunning formatting, linting, or type checks.

2. Start FCC

Run:

fcc-server

Keep this terminal open. In the current AgentSwitchboard release, use the terminal command as the canonical server lifecycle on macOS, Linux, and Windows. Desktop/tray support may exist in the package, but it is not the documented release path and does not change the terminal-only browser policy.

To print the installed AgentSwitchboard compatibility version without starting the server, run fcc-server --version. The output still uses the legacy distribution name until the package migration is complete.

Long-lived FCC commands publish descriptive process titles on macOS. Activity Monitor can therefore identify the AgentSwitchboard server, desktop, and client launcher that owns a local session instead of showing only the embedded Python interpreter name. The title is observability metadata; existing compatibility installations may still expose legacy FCC labels until the runtime/packaging migration is completed. Child clients and parallel test workers remain separately measurable processes.

Startup never launches a desktop browser or a terminal-browser child. The server reports its local control endpoint for explicit local clients:

INFO:     FCC control endpoint: http://127.0.0.1:8082/admin (terminal-only; browser launch disabled)

Use the port shown in your terminal if it differs from 8082.

The control center provides the normal client handoff plus explicit local repository/profile selection, selective learning-bundle transfer, provider status, independent account surfaces, model, usage, route-diagnosis, settings, logs, and restart actions. Provider and model lists accept a typed picker; custom providers can be added, edited, tested, enabled or disabled, and removed through the canonical loopback Admin API. Home redraws use the local snapshot; Admin/provider requests only happen after selecting one of those actions. API keys are entered through hidden prompts and are never echoed back. Repository discovery scans the current working directory and the standard local project roots for Git checkouts; GitHub or other remote metadata is optional. The Repositories page marks the default checkout for the next launch, keeps the selected row after refresh, and lets you open a path outside those roots. A selected repository and profile apply only to the next Claude/Danger launch and never mutate a running session. FCC keeps two account surfaces independent. The FCC OpenAI/Codex provider uses ~/.fcc/auth/openai.json; installed Codex, Computer Use, and Browser helpers use $CODEX_HOME/auth.json plus local snapshots under $CODEX_HOME/accounts/profiles. Neither selector copies credentials into the other store. The separate fcc accounts command manages the Codex Tool Accounts: it can list, switch, refresh, add, or forget local snapshots, and it never logs out an upstream account when forgetting one. Account selection applies only to new Codex/helper sessions. You can still verify the local server explicitly before using a separate client terminal:

curl -fsS http://127.0.0.1:8082/health
fcc-learning claude-compat --binary "$(command -v claude)"

The expected health response contains "status":"healthy"; the compatibility check should report Claude 2.1.228 as certified for the default release configuration. If a different FCC process already owns the port, inspect it and use that healthy instance rather than starting a second server.

fcc-server --terminal and fcc-server --no-browser are accepted as explicit terminal-only compatibility flags. Browser-opening flags and presentation environment variables are intentionally unsupported. If another FCC server is already healthy on the configured port, a second fcc-server invocation reports that instance and exits instead of attempting a second bind.

3. Configure the provider and model

The terminal-first configuration source is ~/.fcc/.env. Copy the relevant entries from .env.example, set the provider credential, and choose an exact model reference. For the verified Muse path:

OPENCODE_API_KEY=your-opencode-key
MODEL=opencode_go/muse-spark-1.2-contributor
ANTHROPIC_AUTH_TOKEN=freecc

Restart fcc-server after changing configuration. The local /admin endpoint is an explicit local control/API surface; startup only reports it and never opens it in a browser.

Model discovery is controlled by MODEL_CATALOG_MODE and MODEL_CATALOG_ALLOWLIST in ~/.fcc/.env. Use all to expose discovered provider models, or curated with exact provider/model refs separated by commas or new lines. Curated mode also accepts provider/* and * wildcards. Explicitly configured MODEL routes remain usable even when hidden from discovery. Optional stable client-facing aliases use MODEL_ALIASES=fast=opencode_go/minimax-m2.7; the alias is accepted by the gateway while receipts and provider dispatch retain the exact target ref. See Configuration for the complete policy.

Discovered models are enriched from one cached models.dev snapshot per TTL window. The metadata includes modalities, context/output limits, and pricing signals and is stored at ~/.fcc/model-metadata-catalog.json; it never enables providers or changes model visibility. The terminal Models page can order free models first or show only models with explicit free evidence. Missing pricing stays unknown and is excluded from Free only; model names are never treated as proof of a free offer. Disable it with MODEL_METADATA_CATALOG_ENABLED=false or tune MODEL_METADATA_CATALOG_TTL_HOURS in ~/.fcc/.env.

4. Run Your Coding Agent

Claude Code:

fcc-claude

For AgentSwitchboard's terminal-only, skip-permissions workflow:

fccdanger

fccdanger is only a convenience alias for fcc-claude that adds --dangerously-skip-permissions; it still uses the FCC proxy and never opens a browser or starts a second server.

Codex:

fcc-codex

Pi:

fcc-pi

The launchers use the current ~/.fcc/.env settings. Normal CLI arguments still work, for example:

fcc-codex exec "hello"

fcc-pi registers FCC only for that Pi process; your existing Pi settings, sessions, credentials, and extensions remain unchanged.

For a cheap global context-discipline leash, explicitly install FCC's bounded read/output guidance into Claude's global instruction file:

fcc-learning context-policy install
fcc-learning context-policy status

The operation is idempotent, preserves unrelated CLAUDE.md text, and creates one recovery copy before its first mutation. Remove only the managed block with fcc-learning context-policy uninstall. This is advisory guidance; the launcher context cap remains the actual client budget.

Oversized text-only tool results are redirected to private local artifacts by the hard ingress governor. Retrieve a bounded follow-up slice from the terminal, without dumping the artifact back into the session:

fcc-learning context-artifact slice /path/from-the-locator.txt \
  --start-line 1 --line-count 80 --max-bytes 16384

The compact/resume claim is backed by the current sanitized Muse receipt. It records the literal Claude Code version, the effective 50K context window, an automatic compact boundary, a post-compact tool turn, resume success, and the OpenCode Go Responses route. The local debug trace and prompt content are intentionally not published.

The managed-session inheritance slice is separately recorded in the sanitized managed fresh/resume/fork receipt. It proves one fresh managed Claude task, one resume, and one forked continuation through FCC with the 256K policy. Background and subagent inheritance remain outside that receipt. That receipt also records Muse's current reasoning shape: opaque provider state and reasoning-token usage, with no fabricated visible summary or raw reasoning text.

The reasoning effort matrix also covers Claude's max level. OpenCode Go's Responses protocol currently accepts xhigh as its highest wire value, so FCC translates only that provider request while receipts preserve both the client requested effort and the upstream effective effort.

The five-level live matrix is recorded in the sanitized reasoning receipt.

The direct Anthropic Messages control boundary is recorded in the sanitized reasoning-boundary receipt. FCC preserves an explicit off request for output suppression and receipts; because Muse rejects effort=none, the OpenCode Go adapter sends Muse's lowest supported minimal effort. Both requests completed with opaque provider reasoning hidden from the Anthropic stream.

The foreground Agent/subagent route is separately recorded in the sanitized subagent receipt. The literal top-level --bg route is recorded in the sanitized background-subagent receipt: Claude 2.1.228 returns a handle, attaches through the native terminal path, and completes a Bash marker through FCC/OpenCode Go/Muse. The earlier background-session receipt is retained as historical failed-probe evidence. The complete PASS/UNVERIFIED/SKIPPED map is in the Claude compatibility matrix.

CI execution

Protected push, pull-request, merge-group, and manual-dispatch CI uses only GitHub-hosted ubuntu-latest runners. It does not depend on a Mac runner, Codespaces, a self-hosted label, or the HARNESS_RUNNER repository variable. No package command provisions a self-hosted runner, Codespace, or remote CI job. For local development, the default scripts/ci.sh pytest tier is serial and excludes subprocess-heavy installer, integration, live, and interactive tests; those tiers are explicit.

Inspect usage and model labels

FCC's local usage ledger records requests, input/output tokens, cache reads, daily activity, failures, and model breakdowns over the last 7, 30, or 90 days. FCC records the final Anthropic-compatible usage event in ~/.fcc/usage.db; prompt and response content is never stored. The graph starts recording after this version is installed, so older requests are not retroactively reconstructed.

Model labels are cosmetic: the exact provider model id remains the value sent to the router, and custom model ids remain supported. Use the generated local catalog at ~/.fcc/codex-model-catalog.json when a client needs discovery.

Choose a provider

1. Obtain the provider credential from the provider's normal account page.
2. Put the credential and exact MODEL reference in ~/.fcc/.env.
3. Restart fcc-server and verify the route with a terminal client and the local receipts/logs. If a provider cannot list models, an exact <provider-id>/<provider-model-id> value remains supported.

Provider catalog

Provider	Configuration	Example MODEL
NVIDIA NIM	NVIDIA_NIM_API_KEY	nvidia_nim/nvidia/nemotron-3-super-120b-a12b
OpenAI / ChatGPT	FCC connected-account state	openai/<model-id>
Azure OpenAI	AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL	azure_openai/<deployment-name>
OpenRouter	OPENROUTER_API_KEY	open_router/openrouter/free
B.AI	BAI_API_KEY	bai/deepseek-v4-flash
Google AI Studio (Gemini)	GEMINI_API_KEY	gemini/models/gemini-3.1-flash-lite
Google Vertex AI	VERTEX_PROJECT_ID + ADC	vertex/google/gemini-3.5-flash
DeepSeek	DEEPSEEK_API_KEY	deepseek/deepseek-chat
Mistral La Plateforme	MISTRAL_API_KEY	mistral/devstral-small-latest
Mistral Codestral	CODESTRAL_API_KEY	mistral_codestral/codestral-latest
OpenCode Zen	OPENCODE_API_KEY	opencode_zen/gpt-5.3-codex
OpenCode Go	OPENCODE_API_KEY	opencode_go/muse-spark-1.2-contributor
Vercel AI Gateway	AI_GATEWAY_API_KEY	vercel/openai/gpt-5.5
Amazon Bedrock	AWS_BEARER_TOKEN_BEDROCK	bedrock/openai.gpt-oss-120b
Hugging Face Inference Providers	HUGGINGFACE_API_KEY	huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest
Cohere	COHERE_API_KEY	cohere/command-a-plus-05-2026
GitHub Models	GITHUB_MODELS_TOKEN	github_models/openai/gpt-4.1
Wafer	WAFER_API_KEY	wafer/DeepSeek-V4-Pro
Kimi API	KIMI_API_KEY	kimi/kimi-k2.5
Kimi Code	KIMI_CODE_API_KEY	kimi_code/k3
MiniMax	MINIMAX_API_KEY	minimax/MiniMax-M3
Cerebras Inference	CEREBRAS_API_KEY	cerebras/gpt-oss-120b
Groq	GROQ_API_KEY	groq/llama-3.3-70b-versatile
SambaNova	SAMBANOVA_API_KEY	sambanova/Meta-Llama-3.3-70B-Instruct
Kilo.ai	KILO_API_KEY	kilo/kilo-auto/free
Fireworks AI	FIREWORKS_API_KEY	fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct
Cloudflare Workers AI	CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID	cloudflare/@cf/moonshotai/kimi-k2.6
Z.ai	ZAI_API_KEY	zai/glm-5.2
Ollama Cloud	OLLAMA_API_KEY	ollama_cloud/qwen3-coder:480b
LM Studio	LM_STUDIO_BASE_URL	lmstudio/<model-id>
llama.cpp	LLAMACPP_BASE_URL	llamacpp/<model-id>
Ollama	OLLAMA_BASE_URL	ollama/<model-tag>

Provider-specific setup

• OpenAI uses your ChatGPT subscription rather than an API key. Complete the local FCC connected-account flow, use device code on headless systems, and restart an already-running agent after connecting.
• Azure OpenAI uses the deployment names from your resource. Set AZURE_OPENAI_BASE_URL to its complete v1 endpoint, such as https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/, and select a deployment that supports Chat Completions. Enter the deployment name as a custom model slug if it does not appear in the model dropdown.
• Mistral Codestral uses a separate key from Mistral La Plateforme.
• Kimi Code subscription keys use kimi_code/; Kimi API credit keys use kimi/. Kimi Code plans are for personal interactive coding-agent use under Kimi's community guidelines.
• OpenCode Zen and OpenCode Go share OPENCODE_API_KEY but use the explicit opencode_zen/ and opencode_go/ model prefixes.
• B.AI uses BAI_API_KEY with its OpenAI-compatible API at https://api.b.ai/v1. FCC discovers exact B.AI model IDs from the provider's /v1/models response. If that response omits pricing, FCC shows the model as unknown rather than claiming it is free. B.AI's time-limited promotions are intentionally not hardcoded; Free only requires explicit zero-price or is_free metadata.
• For Amazon Bedrock, set BEDROCK_BASE_URL to the URL for the same region as the API key and select one of the listed models.
• Vertex AI uses Google Application Default Credentials instead of an API key. Locally, run gcloud auth application-default login once; service-account files and attached service accounts also work. Set VERTEX_PROJECT_ID, and optionally change VERTEX_LOCATION from its global default.
• Cloudflare requires both its API token and account ID.
• For Ollama Cloud, use the exact model IDs returned by discovery or listed by the provider. Local Ollama uses the separate ollama/ prefix.
• Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.

Local provider setup

LM Studio

Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the lmstudio/ prefix. The default URL is http://localhost:1234/v1.

llama.cpp

Start llama-server with its OpenAI-compatible Chat Completions API and enough context for the model. Use the local model ID with the llamacpp/ prefix. LLAMACPP_BASE_URL defaults to http://localhost:8080/v1; FCC accepts either the server root or an explicit /v1 suffix.

Ollama

ollama pull llama3.1
ollama serve

Use the tag shown by ollama list with the ollama/ prefix. OLLAMA_BASE_URL defaults to http://localhost:11434; FCC accepts either the root URL or an explicit /v1 suffix.

Optional model-tier routing

MODEL is the fallback for every request. Claude Code subagents inherit the parent request's resolved provider/model by default, so a child that asks for a different logical tier cannot silently switch providers. The session route is generation-scoped and requires the client to send its stable session header. The first logical parent request still honors its matching MODEL_* setting; when no session route is available, logical model names use that same normal tier resolution.

Set FCC_SUBAGENT_MODEL_INHERIT=false only when you intentionally want MODEL_FABLE, MODEL_OPUS, MODEL_SONNET, or MODEL_HAIKU to override an individual Claude Code child tier even when a parent route is available; select None to use MODEL. A direct provider/model request and a configured model alias remain explicit routes.

For example, route Opus to nvidia_nim/nvidia/nemotron-3-super-120b-a12b, Sonnet to open_router/openrouter/free, Haiku to lmstudio/qwen3.5-coder, and keep MODEL on zai/glm-5.2.

Reasoning control

Set REASONING_POLICY and its optional tier overrides in ~/.fcc/.env.

Selection	Behavior
From client (default)	Use the effort sent by Claude Code, Codex, or Pi. If none is sent, keep the provider default.
Off	Suppress reasoning output and request the provider's no-reasoning behavior. Providers without a native disable value use their lowest supported effort and retain off in FCC receipts.
Low, Medium, High, X-High, or Max	Override the client with the selected reasoning level.
Inherit (Fable, Opus, Sonnet, and Haiku only)	Use the root Reasoning selection.

Provider adapters translate a selected control to the highest documented wire value when a provider uses a smaller vocabulary. OpenCode Go accepts xhigh but not max; FCC preserves the client request as max and records the upstream effective value as xhigh.

Connect Your Client

For the supported release path, start fcc-server, then run fcc-claude, fccdanger, fcc-codex, or fcc-pi in a terminal. The editor/App examples below are reference-only integrations; they are not part of the terminal-only Muse release proof and have not been used to establish the stable product gate.

FCC owns Claude's gateway routing for fcc-claude, fccdanger, and managed sessions. Do not set ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, or ANTHROPIC_API_KEY in an active Claude settings env block for those launchers: user CLAUDE_CONFIG_DIR/settings.json, project .claude/settings.json, project-local .claude/settings.local.json, or an explicit --settings overlay. Claude Code applies those settings over the process environment. The FCC launchers fail closed with the source and conflicting key names instead of launching a session that could bypass FCC. If you use --setting-sources to disable a layer, FCC honors that explicit filter. Direct editor integrations must be treated as separate, experimental clients because they configure their own environment rather than using the FCC launcher firewall.

Visual attachments and Appshots

FCC validates PNG, JPEG, and WebP image bytes before forwarding them and exposes metadata-only attachment receipts (hash, dimensions, size, and media type). The model catalog exposes explicit vision support and accepted image types. Vision capable models receive the complete original image block by default, including images nested in tool results; unknown metadata is preserved and delegated to the provider rather than treated as a rejection. An explicitly non-vision model is rejected before provider I/O. Set FCC_CONTEXT_GOVERNOR_PRESERVE_MEDIA=false only when you explicitly want oversized media to fail closed. Text/tool requests do not require visual metadata. The terminal fallback is a compact [img ... · attached] card; Kitty and iTerm2 capability detection is available to the wrapper without emitting escape codes to unsupported terminals. fcc-appshot exposes a demand-only macOS focused-window capture helper backed by free_claude_code.cli.visuals.capture_focused_window; it requires the user to grant Screen Recording permission and never sends a model request itself. Accessibility permission is not required for this capture path.

For an explicit session-scoped capture, use fcc-appshot --session-id <id> (or set FCC_CLAUDE_SESSION_ID). The helper writes the PNG and a metadata-only receipt to the local Appshot queue, renders a bounded local preview when the terminal supports it, and prints the compact metadata card otherwise. Use --no-preview for receipt-only output or --list to list pending receipts for the session. A wrapper/session consumer can read a receipt and attach the image without injecting keystrokes into the Claude TUI.

Optional local browser bridge

The source tree also contains a loopback-only ChromeCdpBrowserBridge for applications that explicitly inject a BrowserBridgePort. It never launches a browser, contacts a model provider, or attaches to an existing browser session without allow_existing_session=True; tab discovery strips cookies and URL queries, DOM output is bounded, and arbitrary JavaScript execution is not exposed. This is an opt-in tool-plane primitive, not a browser-based FCC UI or part of the default terminal launcher. For terminal-only experiments, the installed fcc-browser command exposes the same bounded operations: list-tabs, snapshot-dom <tab_id>, and action <tab_id> <navigate|click|type|scroll|query>. Every invocation requires --allow-existing-session; without it, no browser network call is attempted.

Claude Code in VS Code

Reference-only: this configures the editor extension directly and is not part of the supported terminal-only release gate. Use fcc-claude or fccdanger for the verified path.

Install the Claude Code extension. Open VS Code's user settings as JSON and add:

"claudeCode.disableLoginPrompt": true,
"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },
  { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "256000" },
  { "name": "DISABLE_AUTOUPDATER", "value": "1" },
  { "name": "DISABLE_FEEDBACK_COMMAND", "value": "1" },
  { "name": "DISABLE_ERROR_REPORTING", "value": "1" }
]

Match the port and authentication token to ~/.fcc/.env, then reload the extension.

Codex App

Start FCC, then edit your Codex configuration:

• Windows: %USERPROFILE%\.codex\config.toml
• macOS: ~/.codex/config.toml

Add the matching model-catalog path and replace YOUR_USERNAME.

Windows:

model_catalog_json = "C:/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"

macOS:

model_catalog_json = "/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"

Then add the shared FCC settings:

model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"

[model_providers.fcc]
name = "AgentSwitchboard"
base_url = "http://127.0.0.1:8082/v1"
http_headers = { Authorization = "Bearer freecc" }
wire_api = "responses"

Match the model, port, and bearer token to ~/.fcc/.env. Restart the Codex App after setup or model changes, then select an FCC model from its model picker.

Codex in VS Code

Install the Codex extension. Create or edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"

[model_providers.fcc]
name = "AgentSwitchboard"
base_url = "http://127.0.0.1:8082/v1"
http_headers = { Authorization = "Bearer freecc" }
wire_api = "responses"

Match model, the port, and bearer token to ~/.fcc/.env, then restart VS Code. For WSL-backed Codex, edit the file inside WSL.

Claude Code in JetBrains ACP

Reference-only: this configures JetBrains' external ACP process directly and is not part of the supported terminal-only release gate. Use fcc-claude or fccdanger for the verified path.

Edit the installed Claude ACP configuration:

• Windows: C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
• Linux/macOS: ~/.jetbrains/acp.json

Set the environment for acp.registry.claude-acp:

"env": {
  "ANTHROPIC_BASE_URL": "http://localhost:8082",
  "ANTHROPIC_AUTH_TOKEN": "freecc",
  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "256000",
  "DISABLE_AUTOUPDATER": "1",
  "DISABLE_FEEDBACK_COMMAND": "1",
  "DISABLE_ERROR_REPORTING": "1"
}

Match the port and token to ~/.fcc/.env, then restart the IDE.

Claude Code still asks you to log in

If Claude Code asks you to log in after you configure the FCC URL and token, open its state file:

• Windows: %USERPROFILE%\.claude.json
• macOS/Linux/WSL: ~/.claude.json

Merge this property into the existing JSON without removing its other fields:

"hasCompletedOnboarding": true

If the file does not exist, create it with a complete JSON object:

{
  "hasCompletedOnboarding": true
}

Restart Claude Code or the IDE after saving the file.

Optional Integrations

Optional integrations remain configured through the local settings surface. They are outside the minimal terminal-only Muse release proof and should be enabled only after the core fccdanger path is healthy.

Discord bot

1. Create a bot in the Discord Developer Portal.
2. Enable Message Content Intent and invite it with read, send, message-history, and Manage Messages permissions so /clear can remove user prompts.
3. Set Messaging Platform to discord.
4. Enter Discord Bot Token, Allowed Discord Channels, and an absolute Allowed Directory.
5. Apply the settings and restart the server if requested.

Telegram bot

1. Create a bot with @BotFather.
2. Get your numeric user ID from @userinfobot. In groups, grant the bot permission to delete messages.
3. Set Messaging Platform to telegram.
4. Enter Telegram Bot Token, Allowed Telegram User ID, and an absolute Allowed Directory.
5. Apply the settings and restart the server if requested.

Messaging commands

Usage	Behavior
/stats	Show session state.
Standalone /stop	Cancel all work.
Reply with /stop	Cancel only the selected request while other queued requests continue.
Standalone /clear	Reset all FCC state and remove every tracked message in that chat, including user prompts, voice notes, FCC replies, Telegram's online notice, and the clear command itself.
Reply with /clear	Delete the selected message and its literal platform reply subtree while preserving its ancestors and siblings.

Voice notes

Choose the voice backend you want, then re-run the installer with its option.

Voice backend	macOS/Linux option	Windows option
NVIDIA NIM transcription	--voice-nim	-VoiceNim
Local Whisper on CPU or CUDA	--voice-local	-VoiceLocal
Both backends	--voice-all	-VoiceAll
Local Whisper with CUDA 13.0	--voice-local --torch-backend cu130	-VoiceLocal -TorchBackend cu130

The examples below install NVIDIA NIM transcription. To use another backend, replace the final option with the matching one from the table.

From this checkout, install the optional extra with the local installer:

./scripts/install.sh --voice-nim

On Windows, run scripts/install.ps1 -VoiceNim in PowerShell.

Restart fcc-server. Set VOICE_NOTE_ENABLED, WHISPER_DEVICE, and WHISPER_MODEL in ~/.fcc/.env. Local gated models need HUGGINGFACE_API_KEY; NVIDIA NIM transcription needs NVIDIA_NIM_API_KEY.

Manage Your Installation

Update

Re-run the matching command from Install Or Update.

Uninstall

Stop every running FCC command before uninstalling.

Removes

• AgentSwitchboard's installed legacy FCC commands and managed state
• ~/.fcc/

Keeps

• uv and Python
• Claude Code, Codex, Pi, and RTK
• Shared PATH entries

From the checkout, use the matching local uninstaller:

./scripts/uninstall.sh

On Windows, run scripts/uninstall.ps1 in PowerShell.

Project Links

• Report bugs or request features
• Documentation catalogue
• Documentation maintenance policy
• Architecture and extension guide
• Configuration reference
• Claude context policy
• Learning, memory, and skills
• Terminal-only startup contract
• Troubleshooting
• Contributing guide

License

MIT License. See LICENSE for details.