Ollama Local, LM Studio, Codex, and Claude subscription mode do not require a provider API key. Codex uses the installed Codex CLI and its ChatGPT sign-in, while Claude subscription mode reuses the local Claude Code login; API providers use the secure key flow below.

On first activation with no provider key, CoderFriend AI shows a welcome message and opens the secure key picker automatically. If you later switch to an API-key provider without a key, a provider-specific message appears and the same picker opens with that provider first. Local Ollama, LM Studio, Codex, and Claude subscription mode are exempt.

1. Open the Command Palette with ⇧⌘P Windows & Linux: Ctrl+Shift+P.
2. Run CoderFriend AI: Set Provider API Key (Secure).
3. Choose the provider, then paste its key.
4. Select the same provider and a model in the chat input bar. All registered providers are shown by default; if one is missing, restore its enablement setting.

Provider enablement settings control whether individual registered providers are shown: enableCodexModels, enableOpenAIModels, enableGeminiModels, enableClaudeModels, enableOpenRouterModels, enableDeepSeekModels, enableXAIModels, enableGroqModels, enableMistralModels, and enableLMStudioModels. Codex is discovered on the extension-host PATH or inside the installed OpenAI Codex extension. Set codexBinary only for a custom installation that cannot be discovered automatically. Claude stays on the Anthropic Messages API by default; switch claudeConnectionMode to subscription to reuse a local Claude Code login, leave claudeEndpoint for API mode only, and set claudeCodeBinary only when claude is not found on PATH, in a home install, or inside an installed Anthropic Claude Code VS Code extension.

LM Studio: start the LM Studio server, load a model there, then select LM Studio (Local) in the provider selector. CoderFriend uses its OpenAI-compatible endpoint at http://localhost:1234/v1; LM Studio serves on the last port it used, so set lmStudioEndpoint when you changed it. No default model id ships, because LM Studio serves whatever you downloaded — pick one in the model picker. Embedding and reranker models are filtered out of that picker by name, since /v1/models reports no model type and lists every downloaded model together. Authentication is off by default and selecting LM Studio never prompts for a key; store an LM_API_TOKEN key only if you turned on the opt-in Require Authentication mode added in LM Studio 0.4. LM Studio serves no TLS and CoderFriend requires HTTPS for every non-loopback endpoint, so its Serve on Local Network mode is not supported: loopback only. Tool calling works but depends on the model — one not trained for tool use can answer Agent mode with prose where a tool call was expected.

Codex account maintenance: Codex authentication is shared with the Codex CLI and OpenAI extension. In a development checkout, make login-codex starts browser sign-in, make logout-codex removes the shared stored credentials, and make test-codex-e2e runs the one-request opt-in transport smoke test. The paid make test-codex-agent-e2e gate runs the production Agent loop against a disposable P4 fixture with real edits and verification. Login/logout commands do not consume a model request.

Claude subscription mode: install Claude Code, run claude once to complete the official login flow, then pick Anthropic Claude (Pro/Max Subscription) in the sidebar provider selector. The selector lists Claude twice, once per transport, and picking an entry writes claudeConnectionMode for you; setting it to subscription by hand does the same thing. Personal Claude Pro or Max logins work through that official flow. CoderFriend reuses the local Claude Code session, so no Claude API key is stored. Attached images work here: each one is written to a temporary file that Claude Code's own Read tool opens, and the file is removed when the request ends. A request whose trust profile withholds Read says the image cannot be viewed rather than guessing at it.

Keys entered through the command are stored in VS Code SecretStorage, not regular settings. Run the command again to replace a key, or submit an empty value to remove it.

Portable setup and backup: run CoderFriend AI: Export API Keys and Settings. It creates an editable JSON file containing explicit setting overrides and placeholders for every provider key. Extension defaults are omitted so old backups cannot freeze obsolete defaults. Fill the keys you use, then run CoderFriend AI: Import API Keys and Settings. The same file can transfer the setup between computers or back up an existing installation. Filled exports contain plaintext credentials, so keep them private and never commit them.

To delete every saved provider key, run CoderFriend AI: Remove Saved API Keys... and confirm the warning. When VS Code reports that CoderFriend AI was uninstalled, the extension also asks whether to remove or keep saved keys. Since VS Code cannot guarantee that an extension remains active long enough to show an uninstall prompt, run the removal command before uninstalling when cleanup must be guaranteed.

Live progress commentary: expand the Working card to follow concise findings and next actions while the Agent works. Codex commentary streams into replaceable rows in Chat, Plan, and Agent; other providers show the short narration returned with tool calls. If a provider stays silent for more than two seconds, CoderFriend shows a truthful operational fallback and replaces it when real commentary or output arrives, so an active request never looks abandoned. CoderFriend bounds and redacts these user-facing updates and never presents hidden model reasoning or private chain-of-thought. The final answer remains separate.

Select a conversation profile from the Profile control in the composer toolbar. It sets the assistant's stance for the request and changes nothing about what the Agent is permitted to do; the separate Trust control beside it decides that.

Select the review control or run CoderFriend AI: Review Code... to review the active selection/file, working tree, current branch, or a GitHub pull request. PR review uses an already authenticated gh CLI session and remains read-only. Issues are limited to evidenced correctness, security, race, performance, and missing behavioral-test defects with an exact changed-file line and confidence at or above codeReviewMinimumConfidence.

Open an issue's location, suppress its stable rule ID as a false positive, fix retained issues in a guarded foreground Agent, or start a confirmed isolated-worktree fix. Significant foreground Agent checkpoints are reviewed automatically when enableAutomaticCodeReview is enabled. That reviewer uses the original request's provider snapshot and shares its token and measurable-cost budgets plus its duration, model-call, and iteration safety limits. Secret files are omitted, common credential values are redacted, and truncated reviews report partial coverage.

Run CoderFriend AI: Open Settings Center to search and edit General, User Interface, Models & Providers, Context & Knowledge, Agent & Safety, Profiles & Guardrails, and Advanced settings in one view. The normal settings flow no longer opens VS Code's raw settings page.

User Interface also sets the panel’s fonts, one part at a time. Each section takes a font stack such as Inter, sans-serif and a size, and both start on Follow VS Code. They are separate so that enlarging the messages you read does not also inflate the activity log and the composer around them.

Size is a list of pixel sizes rather than a number box, so no value it offers can be saved and then ignored. A chosen size lands on that section’s own text and the smaller labels within it scale to match. The header, the version strip, and the debug pane are not settable and keep following VS Code.

User Interface chooses what the chat panel puts on screen. Every element around the chat input has its own toggle under Composer controls and starts visible: Conversation usage, Add context button, Mode selector, Model picker, Processing speed, Reasoning effort, Context compaction, Response detail, Conversation profile, Trust profile, Provider selector, Approval mode, and Steering hint. Turning one off removes it from the panel and nothing else changes — the setting behind it keeps its value and still applies to every request. Saving applies at once, without reloading the window. The chat input and Send have no toggle. Send also carries the stop role — while a request is running and the composer is empty it becomes a stop button, and typing turns it back into send — so hiding it would leave a running Agent with no way to be interrupted. If a control you remember is missing, it was switched off here rather than removed.

Profiles & Guardrails manages coderfriend-ai.policySettings. Choose one general default profile first, then add a provider exception or an exact-model exception only when a narrower source needs different approvals, sandboxing, tool access, context rules, or request budgets. Inheritance order: general default, provider exception, then exact-model exception. A profile's Secret files switch says whether the model may read likely secret files at all — on for Trusted Agent only, by default. A profile's Maximum Agent steps replaces the legacy agentMaxIterations setting rather than combining with it, so a run that stops at a profile's cap — including a Claude subscription run cut off inside one Claude Code call, whose notice names the profile — is given more room on the profile, not on the setting.

CoderFriend keeps stable system prompts and repository instructions at the front of supported provider requests so Anthropic Claude API mode, OpenAI, and DeepSeek can reuse cached prompt prefixes. Anthropic API requests use ephemeral cache control, and also place two rolling cache breakpoints inside the conversation so a long Agent run replays its accumulated transcript from cache rather than paying full input price for it on every turn. Cache availability and discounts still depend on the selected provider, model, and minimum prompt length. Instructions that change during a run — the read-stall nudge and the phase reminder — are appended at the end of the transcript and the previous copy is removed, rather than being rewritten where they first appeared. Rewriting in place ends the reusable prefix at that early index for the rest of the run, which on a 69-call run left roughly a tenth of the prompt cacheable.

The sidebar shows a compact Conversation Usage card above the composer, and the VS Code status bar mirrors total tokens, cache-hit percentage, cache-read and cache-write activity, separately reported billed thinking and tool-result input tokens, and estimated provider cost. Expand the card or click the status bar for recent-request and per-surface breakdowns. Accounting happens at the provider boundary and covers sidebar/native chat, inline chat and completion, generated actions, evaluations, background agents, planners, summaries, reviewers, retries, and subagents. Usage is saved with each conversation and restored when it is loaded again. Starting a new conversation, clearing one, deleting one, or selecting the explicit reset starts its counters from zero.

Sidebar Agent is the accounting-surface label for a request started from this sidebar in Agent mode; it is not a child or subagent. Recent Requests lists each root request separately. Selecting Continue after a pause creates another accounting request, so multiple Sidebar Agent rows can belong to one continuous task. By Surface aggregates those rows. Calls count provider/model attempts recorded under a request, including nested planning, summary, review, and retry work; iterations count passes through the root Agent loop, so they need not match. Recent-request duration covers one accounting round, while the Working card's Worked for time accumulates active execution across Continue rounds and excludes time spent paused.

Account, balance, and spending budget. Two different things get called a balance and only one can be fetched. DeepSeek publishes a real account balance and OpenRouter publishes what remains of a per-key cap, both readable with the stored API key; the other providers publish nothing, and Anthropic returns 404 for an organization balance.

A fetched balance is shown stamped with the instant it was fetched and is never carried forward by subtracting local spend: other clients spend the same account, the rate table goes stale on price changes, and unpriced calls contribute nothing, so every error would inflate what appears to be left. An OpenRouter key limit is labelled as a key limit rather than as the account behind it.

Everywhere else the honest figure is a spending budget set with spendBudgetUsd over the window in spendBudgetPeriod: what CoderFriend itself recorded, persisted per provider, tracked for session, day, and month at once so switching does not restart the count, and counting calls it could not price rather than dropping them. It reports and does not stop work; the root-request and delegation limits remain the mechanisms that stop a run.

Every provider also gets its console through Account in the usage card, Account and Usage... in the command palette, or /account.

An account out of credit is reported, not retried. Providers disagree on the status: Anthropic answers 400 insufficient_balance_error, OpenAI answers 429 insufficient_quota, and OpenRouter and DeepSeek answer 402. Because 429 is otherwise retryable, an unfunded OpenAI account used to spend three attempts and two backoff sleeps on every model call to reach the same refusal. The failure now names the provider, repeats its own sentence, and links the page to add funds. Ordinary rate limiting is still retried.

Debugging with the Agent. Start a debug session and pause where the failure is, and the Agent gets tools to work it out with you: it can read the stack and the paused frame's variables, set and clear breakpoints, step over, in and out, continue, and pause a running program. This works with any debugger that has a VS Code adapter — Xdebug for PHP, the built-in JavaScript debugger, debugpy, Delve, CodeLLDB — because it speaks the Debug Adapter Protocol rather than knowing about languages. The tools appear only while a session is running.

Breakpoints report whether the debugger actually bound them. An unverified breakpoint is drawn in the gutter and never hit, which when debugging a remote process nearly always means the path mapping is wrong rather than the line, and being told so is faster than watching a breakpoint that cannot fire. Anything that changes what the program does — a breakpoint, a step, a continue — asks for approval first; reading the stack does not.

Evaluating expressions is off by default. coderfriend-ai.enableDebugEvaluate lets the Agent evaluate an expression inside the paused program, which runs code in that process: if the debugger is attached to something in production, the expression runs in production. Everything else stays available without it. An expression naming a credential is refused rather than answered.

Where the prices come from. The rate table ships with the extension as data, so a fresh install prices correctly with no network. /priceupdate, or CoderFriend AI: Update Model Prices, downloads a newer table from https://coderfriendai.com/api/model-prices.json and reports what changed; the downloaded copy is cached in extension global storage and used from then on while it is newer than the bundled one. Set modelPriceUpdateIntervalHours above 0 to check on a schedule instead, or enableModelPriceUpdates to false to stop every price download including the manual one. A downloaded table is validated in full before it replaces anything: an unknown provider, a missing or negative rate, an unrecognised field, or a response that is not the expected schema version rejects the whole payload, and prices keep coming from the table already loaded. An unreachable server changes nothing.

Reading the result. Already current means the published table is the one you already have, which is the normal answer shortly after an update: your prices are correct and nothing needed downloading. Two dates can appear, and they answer different questions. The publication date is when the rates last changed; the verification date, when the feed carries one, is when the publisher last checked them against the providers. A table that has not changed for weeks is not thereby stale — provider prices simply had not moved — and the second date is what says so. Updated names the counts that moved. A failure quotes what went wrong — an HTTP status, a timeout, a validation reason — and says which table is still pricing your requests, because a refresh that cannot complete leaves your existing prices in place rather than degrading them.

Cost reporting fails closed. Provider-reported charges are used directly; otherwise an estimated provider cost requires an exact registered provider/model rate and complete billable usage. Known request tiers, long-context bands, and scheduled price changes are handled explicitly; mutable processing tiers must be identified by the provider response. There is no family/default or rolling-alias price fallback and no invented cache discount. If one request cannot be measured reliably, the complete session cost shows N/A with the reason while reported token counts remain visible. The HUD is not the provider account or API-key invoice.

Codex reports prompt, cache, visible output, and reasoning tokens through its app-server. A ChatGPT plan does not expose an exact per-request USD charge, so Codex token totals remain visible while cost correctly displays N/A.

Claude Code subscription mode normalizes prompt, output, and cache token counts when the local CLI returns them, but it still reports only a client-side estimate rather than an exact billed charge. CoderFriend therefore keeps the token totals and correctly fails closed on cost with N/A.

LM Studio reports streamed token usage from version 0.3.18 onward, so the usage HUD and context compaction work normally. Nothing is billed: it runs on your own machine, so it takes the same exemption as Ollama Local and never reaches the spend ledger or counts against a spend budget.

Root Agent requests share token and measurable-cost budgets plus wall-clock, provider-call, and iteration safety limits across planning, root work, reviewers, retries, and children.

Cache reads are not charged against the token budget. A cache read is the transcript the request already paid to process, replayed because the provider API is stateless; charging it again would spend the budget on repetition rather than on new work, and would make the ceiling scale with the square of the step count no matter how well the conversation cached. Reported usage is untouched, so Conversation Usage still shows the full traffic and cost still prices cache reads at their own rate — only the budget comparison excludes them. A subagent is treated the same way against its per-agent cap and the shared pool. A provider that reports no cache fields is unaffected.

The defaults—including 1,000,000 reported tokens, 90 provider calls, and 15 minutes—apply to every provider, including Codex ChatGPT and Claude Code subscription requests.

Reaching a configured limit—even while a provider call is active—changes the Working card to Paused; completed changes remain, and a bounded, redacted execution handoff is saved with the conversation. A multiline explanation names the limit and recovery path.

Continue resumes the original goal, completed operations, checkpointed files, diagnostics, and shared plan without restarting discovery. The Paused Agent ready to resume card restores after a VS Code or Extension Development Host reload; a natural please continue message also resumes it. Successful completion or an unrelated Agent task clears the handoff.

Reloading the window mid-run costs the call in flight, not the run. Tearing down the extension host during a request means the active provider call is already paid for and its answer never arrives. Everything else survives: the new host reopens the conversation with the same context, including tool results the lost call never replied to, and resumes the read-stall counters instead of granting a fresh exploration budget. Stop first when a call has been running a while; otherwise the reload is safe.

Private reasoning, raw tool output, attachments, screenshots, and provider calls are never persisted or replayed. Select Disable time limit beside Continue to set agentRequestTimeoutSeconds=0 immediately. Iteration, cancellation, and process-safety limits still apply. If cost becomes unknown, only the cost comparison becomes unavailable.

In the sidebar composer, type @ to select @web or @docs. Put @web <query> or @docs <query> on its own line before your request. @docs react: useActionState narrows the lookup to one docset. Matches are bounded, inserted only for that request, and labeled as untrusted reference data; never rely on retrieved page text as instructions.

Live web search is on by default. Run CoderFriend AI: Disable Web Tools to turn it off, or CoderFriend AI: Enable Web Tools to turn it back on.

Queries and selected URLs leave your machine while it is on. Under the default auto backend the web tools are offered only to providers that have native search — OpenAI, OpenRouter, Claude, and Gemini — so Codex, Ollama, LM Studio, and similar sources see no web tool rather than one that fails on every call; selecting brave, tavily, or searxng makes it available on any provider. Provider built-in search is always refused, separately from approval mode, so every query stays accounted for and address-checked.

The default webSearchProvider is auto, which uses native search from the active OpenAI, Claude, Gemini, or OpenRouter provider with the provider key already configured in CoderFriend AI. Unsupported providers fail explicitly. You can instead select brave, tavily, or an explicitly configured self-hosted searxng endpoint. Searches and public-page fetching leave the machine, so enable them only when appropriate.

Native search may add provider tool charges. OpenAI and Anthropic search-call fees are included when exact token rates are registered; OpenRouter's provider-reported total is used when present. Gemini search cost displays N/A when the API does not reveal whether a project-level free allowance applied. CoderFriend AI never silently treats an unknown search charge as zero.

Run CoderFriend AI: Add Documentation Site to crawl a public documentation root into global extension storage without a search API key. The crawler is same-origin, bounded by documentationIndexMaxPages and documentationIndexMaxDepth, cancellation-aware, and validates public URLs and redirects. Later @docs and docs_search requests are local BM25 lookups with no network call. Enable enableDocumentationFetching separately only when Agent should receive docs_index.

Nothing below is required. Each one gates a single capability, and the rest of the extension works without it — they are listed because a missing one surfaces late, inside a running Agent request, rather than at install time.

• uv — raster image generation. The imagegen CLI is a Python program that needs the openai SDK, and uv supplies it per run without touching your system Python. Install with brew install uv on macOS, curl -LsSf https://astral.sh/uv/install.sh | sh on Linux, or winget install --id=astral-sh.uv -e on Windows. Generated files go to generatedImageDirectory (default assets/generated) and can be shown directly in VS Code with open_file. Vector work — diagrams, wireframes, icons — needs none of this: those are written directly as SVG or HTML.

There is no built-in analytics or advertising telemetry. The selected provider receives the prompt context needed for the request, which may include retained conversation turns, repository instructions, attached source, images, and tool results. Sandboxed Agent commands receive a sanitized environment without provider credentials and have network access denied on macOS/Linux. Linux enforces this with a network namespace that has no interfaces. macOS enforces it with a sandbox-exec profile rule that blocks the command's own sockets; because that profile still permits unrestricted mach-lookup, a program can ask an unsandboxed macOS service to act for it, which defeats the write rules as well as the socket rules. macOS confinement is therefore a strong default rather than a hard boundary — it stops a command that misbehaves, not code written to defeat it. Keep coderfriend-ai.agentSandbox enabled in untrusted workspaces; setting it to off is an explicit escape hatch for trusted workspaces only.

Read PRIVACY.md and SECURITY.md before sending confidential code to a cloud provider.

The current conversation continues across model and provider changes. Changing a selector sends nothing by itself. When you submit the next message, the retained user/assistant conversation is sent to the newly selected provider and model.

Privacy: when retained context exists, changing providers asks whether to keep the context, start a new conversation first, or cancel. A local-to-cloud switch explicitly warns that the retained context leaves your machine on the next request.

• Auto/Shrink — the middle may be summarized; Full sends everything still retained under configured limits
• Default limits — 40 retained messages and 20,000 characters per saved message, both configurable
• Images and attached source — may continue in live memory, but are not restored from saved history after reload
• Not handed off — hidden reasoning, debug traces, completed agent tool internals, prior one-request skill instructions, and prior transient editor selections

Type / in the CoderFriend sidebar composer to open the searchable command menu.

Type / in the composer to open this list, then choose one with Tab or Enter.

Run /skills for a compact catalog grouped by workspace or provider. Filter it by name, description, or provider, then select a row to insert the skill into the composer. You can also type $ directly and send $skill-name your request. CoderFriend reads .agents/skills/, Codex/OpenAI .codex/skills/, Claude .claude/skills/, and Gemini .gemini/skills/ at workspace and user scope, including installed provider plugin and extension skills.

Use $skill-creator Describe the reusable workflow to create a portable project skill under .agents/skills/. Imported provider skills are read in place.

Repository instructions are automatic and separate from skills. CoderFriend adds applicable rules as system context to every request: sidebar Chat/Plan/Agent, native @coderfriend, inline chat, inline completion, and generated commit messages. Discovery happens before provider routing, so the same rules work with every selected provider.

Native chat now shares the sidebar request pipeline foundations. Native @coderfriend requests use the same request-time provider snapshot, automatic BM25 retrieval, context compaction, and Agent-loop bridge as the sidebar where those features apply, so switching entry points no longer drops back to an older request path.

• Agent files — AGENTS.override.md or AGENTS.md from workspace root to the active/referenced file
• Claude and Gemini — root and nested CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md, and GEMINI.md
• GitHub Copilot — .github/copilot-instructions.md and matching .github/instructions/**/*.instructions.md applyTo rules
• Cursor — nested .cursor/rules/**/*.mdc files with alwaysApply: true or matching globs, plus legacy .cursorrules
• User files — ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.gemini/GEMINI.md from your home directory apply to every workspace at the lowest precedence

Rules combine from broad to specific; deeper directories override broader ones. Agent mode rechecks before every path-based file tool. If a deeper rule is discovered, the first operation is withheld, the rule enters model context, and the model retries. Relative @path imports are bounded and cannot escape the workspace; instruction files are limited to 32 KB each and 64 KB combined.

Trust boundary: instruction files are trusted workspace content sent to the selected provider. enableRepositoryInstructions defaults to true; disable it before working in a repository whose instructions you do not trust.

Context can be named inline instead of through the + menu.

Open editors: the files open in the editor are sent with every sidebar request, active editor first, and show as dashed chips above the composer. The × on a chip leaves that file out for as long as its tab stays open; closing the tab removes it. They are rebuilt from the live buffers each time - unsaved edits included - and never retained as a conversation turn. Files outside the workspace, likely secret files, and files over 128 KB are skipped; at most 20 files and 256 KB are sent. Turn the feature off with coderfriend-ai.attachOpenEditors.

What you type stays until you delete it. Nothing but Backspace, Delete, or a selection you replace removes composer text: the arrow keys never overwrite or empty a draft, New Chat keeps it, Retry, Continue and Resume Agent put it back after sending their own line, and it survives a window reload. Sending it, or running a slash command, is what clears the box.

CoderFriend AI now preserves your existing VS Code main sidebar layout by default.

• Header Move Button — opens VS Code's native move-view picker for the currently focused CoderFriend AI Chat view; choose New Secondary Side Bar Entry
• Move Chat to Secondary Side Bar — Command Palette action for the same destination picker flow
• preferredSidebarSide — use preserve to keep Explorer on the left, or left/right to move the whole primary sidebar

When you choose left or right, CoderFriend AI updates VS Code's global workbench.sideBar.location setting, so the chosen side persists across restarts.

VS Code does not let extensions drop a view into the Secondary Side Bar silently, so CoderFriend AI opens the native move-view picker for that step.

Press ⌘I Windows & Linux: Ctrl+I in the editor to open inline chat. Type an instruction and the AI will edit your code in-place. Select code first to modify it, or use it at the cursor to generate new code. You can Accept or Reject the changes.

Hover any code block to see action buttons:

• Copy — copy code to clipboard
• Terminal — insert into active terminal (without executing)
• Apply — replace selection in editor, or insert at cursor

Right-click selected code for: Explain, Fix, Generate Tests, Refactor, Generate Documentation

When diagnostics appear (squiggly lines), click the lightbulb for:

• Fix with CoderFriend AI — sends the error + surrounding code to /fix
• Explain / Refactor / Gen Docs — on selected code

Generate Commit Message — reads your git diff and fills the SCM commit input box with a conventional commit message.

Generated messages and agent-created Git commits include the exact provider and model by default, for example OpenAI gpt-5.6-sol:. Set prefixCommitMessagesWithModel to false to turn this off everywhere, or add absolute paths, workspace-relative paths, or folder names to commitMessagePrefixExcludedFolders to turn it off only in matching folders.

Models in the picker show capability badges: [T] = supports tool calling, [V] = supports vision (image input). A model tagged [TV] supports both.

During Agent work, successful file reads are tracked by path and line range across the resumable task. Unchanged duplicate reads are blocked or removed from mixed read_files batches, while a structured mutation invalidates coverage only for files it actually changed. After an exact-edit mismatch, the named stale target must be refreshed before another exact edit can target it.

Implementation progress guard: after the shared task plan identifies unfinished implementation work, a roadmap-only status edit is blocked until the source changes and verification are complete. An item explicitly marked NOT DEVELOPED remains unfinished input for the next Agent run until implementation and verification exist.

Before the first source change, the read-stall guard nudges action after three consecutive non-mutating operations and blocks more reads, searches, plan replacements, and task-status calls after five. Marking a genuinely blocked task blocked stays available, because the block message directs the model to exactly that call. That message also names the unfinished task ids, since the call needs one and listing the tasks is inspection the same block refuses.

After a real workspace mutation, caller mapping receives a phase-aware nudge after five and a hard gate after eight. Failed reads consume the active window, while a checkpointed edit resets it only when a net workspace diff remains; adding and removing a temporary marker cannot restart discovery. Successful read-only shell audits—including Git branch, remote, merge-base, status, and diff queries—remain inspection and cannot reset the counter or unlock the wider post-mutation window.

An explicit no-edit request such as a PR review uses separate read-only investigation pacing: mutation tools are withheld and one progress nudge occurs after eight operations, but the mutation-driven read-stall hard gate does not apply. The current evidence task then enters review consolidation: broad reads, searches, directory/Git discovery, new delegation, and plan replacement are withheld while exact declared project checks, existing child/artifact results, task completion, and final reporting remain.

Identical successful shell inspections cannot repeat, and a fully-read unchanged file cannot be searched again. Listing the same unchanged directory twice is answered from the listing already returned, and any checkpointed edit drops those retained listings because a write or delete changes what a directory holds.

One tool result is capped at 16,000 characters in the conversation, above the 14,000 a file read will produce, so a read that succeeded is never shortened again on the way in. A file too large for one read is truncated once, by the read tool, which names the lines it delivered and lets the rest be requested. What counts as "already in context" is what actually reached the model. Long tool results are shortened to a head and a tail before they enter the conversation, so a read can arrive with its middle missing; only the part that survived that cut is treated as delivered, and the rest can be requested again. A listing that was shortened is not remembered at all, and one later compacted away is forgotten, because telling the model to reuse entries it can no longer see leaves it no way to ask.

Read-only shell inspections now count as reads: an unambiguous sed -n, cat, or head records the lines it printed, so a later read_file of those lines is answered from context, and a command that does nothing but reprint content already in context is refused. Piped, redirected, globbed, and byte-counted forms claim nothing, and a compound command that also echoes, numbers, greps, or runs a check still executes.

The read-stall nudge names the consequence it is warning about—how many non-mutating operations remain before non-mutating tools stop working—and is written to the instance log only when it first appears and again near the block, because it is refreshed in place on every step. Normal request/model-call limits remain active. Each evidence-only task completion resets that review window only after fresh successful inspection or check evidence. Blocked activity is labeled as an inspection or bookkeeping limit rather than a failed file operation.

When no shared plan exists, the first non-empty plan remains available at the initial implementation gate so discovery cannot force premature finalization, and establishing it also starts a fresh discovery window. A stalled run that never made a plan at all is held at that block rather than sent to a tool-free summary turn: an empty task list means finished work only when a plan existed and was closed, and withdrawing the edit tools of a run that never started guarantees the request produces nothing.

Working out what was asked and working out how to build it are separate discovery problems, and one window cannot serve both: a run that spends its allowance locating the request arrives at the plan with nothing left for mapping the change, is blocked mid-enumeration, and can only escape by editing something before it knows what to edit. This cannot be replayed for more budget, because a replacement plan submitted while work is still outstanding is charged like any other non-mutating call. Continue gives a non-zero implementation inspection streak at most one more non-mutating operation before that gate instead of restarting discovery.

An implementation task can be marked done only after a new workspace mutation and later project verification since the previous completed implementation task. Clearly non-mutating review, investigation, and verification tasks instead require fresh successful work evidence, allowing honest no-edit completion without letting one inspection close several tasks; completing one leaves the implementation evidence untouched. An authorized task completion passes the pacing gate.

When an unverified mutation reaches the final six iterations, inspection and bookkeeping tools are removed until a project check succeeds; only structured edits and run_command remain available. Failed or pacing-blocked tool calls do not reset no-tool recovery; only a successful operation or repository-instruction handoff does. An explicit verification blocker such as an unavailable command stops retries even while a failed check remains unresolved. Unfinished plan state cannot exceed the two no-tool recovery continuations, and rejected intermediate final drafts are not shown as duplicate output. Unified-diff hunk counts are safely normalized when their declared and actual net line delta agrees and exact source context matches; other failed or malformed patches preserve the accumulated streak, so cosmetic status changes and rejected edits cannot buy another inspection cycle.

Foreground Agent requests can keep approved dev servers and watchers alive with start_process. CoderFriend detects logged localhost URLs, opens a fresh Chrome/Chromium/Edge profile, returns bounded DOM, console, network, and crash observations to the Agent, and shows screenshots and pass/fail signals in a visible Runtime verification card. The Agent can click, type, submit, inspect, and ask you to select a broken element in the visible preview.

Processes stay inside the first workspace folder, use the configured filesystem sandbox, receive no provider credentials, and are terminated with their complete process tree at request completion, cancellation, timeout, or extension disposal. Background operators, detachment, elevation, and explicit public binds are blocked. Runtime processes deliberately retain host networking so localhost previews work; approved programs are therefore not outbound-network isolated.

Browser navigation is localhost-only by default. A foreground Agent can open a user-requested public HTTP(S) page or form under the selected approval policy.

Ask/Workspace mode prompts for external navigation, interaction, and exact page-requested CDN/API origins; Always Allow authorizes and executes each path immediately with no approval prompt or hidden denial. Additional origins remain non-document-only, while cross-origin navigation and access from a public page to localhost are reported capability blocks. Console warnings remain visible, but warning-only output does not fail verification.

The Agent must never request, read, or type credentials; sign in yourself in the visible fresh profile when authentication is required. If a model incorrectly claims external browser access is unavailable before calling open_preview, CoderFriend grants one bounded recovery turn; a real capability or tool failure remains a valid blocker. Typing into a request-owned process follows the same approval policy. The isolated profile contains no personal cookies or saved sessions.

Use enableRuntimeVerification to disable the feature, runtimeBrowserPath when browser autodetection fails, and runtimeBrowserVisible for visible or headless operation. Runtime tools are not exposed to background agents or subagents.

Select the key-shaped SSH control or run CoderFriend AI: Connect Live Server.... The picker lists up to 10 successful recent connections first, then aliases from ~/.ssh/config, and supports manual user@host entry. Choose a Structured File-Tools Root, an environment label, Safe Tools Only or Full Shell Access, and an approval mode. Successful targets are remembered without credentials; use Forget recent connections... in the picker to clear them. CoderFriend uses your system OpenSSH configuration and ssh-agent; it never stores SSH passwords or private keys. LIVE identity, capability, root, and trust remain visible.

Large remote files are investigated on the server, not downloaded. ssh_read_file accepts tailLines or a startLine/endLine range and selects that window remotely, and ssh_search_file runs grep on the host and returns only matching lines with a total match count. A multi-megabyte log is therefore searchable without transferring it.

Remote commands return an interleaved stdout/stderr view for the messages you see, because a failing remote command explains itself on stderr. Structured tools read stdout only, so a login banner or shell warning cannot be decoded as file content or displace the recorded hostname. Remote content that is not valid base64 fails the read instead of decoding short.

Safe Tools Only provides root-confined file/search/edit tools, fixed runtime inspection, and recovery, but omits and runtime-blocks ssh_exec. Full Shell Access requires a separate modal warning and adds unrestricted ssh_exec; the file-tools root is only its starting directory, and commands may access the whole server or invoke sudo. Trust removes prompts only within the chosen capability and expires on disconnect or reload. After a reload the banner reads DISCONNECTED, names the server and what it was (was FULL SHELL, files /var/www), and carries a Reconnect link where Disconnect sat: one click brings it back with the same capability, untrusted unless the profile answers everything, replacing the picker and the Full Shell warning. A server you disconnected on purpose is not offered. Once the connection ends the banner remains, reading DISCONNECTED and naming the server, because a header that goes blank is indistinguishable from one that never had a server and the ssh_ tools are gone from the next request. A paused Agent request that had reached the server refuses to resume while nothing is connected, before spending a provider call: the saved progress is kept, and reconnecting then choosing Continue resumes it. The local workspace is never used as a substitute for the server.

Shell commands cannot reach another machine. run_command refuses any command that opens a session on another host (ssh, scp, sftp, or rsync naming one): it would run outside the Live Server connection, with no live-server approval, no backup records, no file-tools root, and no guarded cleanup of the processes it starts there. This is a capability boundary rather than a prompt, so it holds under Always Allow, where no approval would have appeared. Local ssh-keygen, ssh-add, and git push are unaffected. Under a profile whose approval mode is Always Allow the connection flow skips its approvals question, because the answer cannot change the outcome, and the sidebar trust indicator reads approvals off with that profile's name rather than the connection's own setting. Only prompting is removed: a Safe Tools connection keeps root confinement, atomic writes, backups, and the sensitive-path filter.

The ssh_* tools are the only way the Agent reaches the server. A shell command cannot: the command sandbox denies network access, so ssh or curl run through run_command fails with Operation not permitted or an unresolvable hostname — neither of which names the sandbox, so both look like a fault on the server. Claude Code's own Bash tool is offered only under Always Allow with the sandbox off, so under every other trust profile it goes through the sandboxed run_command and inherits the same denial. Only agentSandbox: off gives shell commands direct network access.

Stop and remote process cleanup: pressing Stop requests cancellation; the control changes to Stopping and stays disabled while cleanup is in progress. For ordinary ssh_exec calls, CoderFriend begins independent remote lease cleanup without waiting for the active SSH channel to return, terminates the local OpenSSH process tree through a bounded escalation, and rechecks remote cleanup after the channel settles. Leave the live-server connection intact while Stopping is shown; Disconnect is not required for normal cancellation. Because ssh_exec commands may use sudo, remote cleanup retries its liveness check and both signals under sudo -n when the SSH account cannot signal a surviving member: kill -0 reports "not permitted" and "no such process group" identically, so a root-owned survivor would otherwise read as a group already gone. A group that even sudo cannot clear keeps its lease and is reported as a cleanup failure rather than recorded as stopped.

Guarded foreground process groups receive TERM, then KILL if needed, and cleanup failure prevents a successful completion.

Temporary servers that must survive across tool calls use ssh_start_process; they belong to the exact request, expose bounded status/output, reject elevation and detachment, have a hard lifetime, and are stopped before the request or connection finishes. Detected persistent escapes such as shell &, setsid, tmux, screen, or detached containers are blocked unless allowPersistentProcesses=true receives a separate user approval, even in a trusted SSH session.

After write_file, edit_file, edit_files, or apply_patch, Agent mode automatically checks touched files, waits briefly for relevant VS Code diagnostic updates, and also captures newly introduced downstream workspace diagnostics in dependent files so the model can keep self-healing without waiting for manual feedback.

File-lock conflict protection: once a sidebar Agent request or rooted/background run starts mutating a file, that path stays locked to the same request or run until it finishes. Another active Agent trying to write the same file gets an explicit file-lock conflict instead of silently overwriting it.

Local codebase retrieval: CoderFriend builds a bounded local-only BM25 index and updates it after file changes. Automatic context removes duplicate and explicitly attached files, stays within automaticCodebaseContextTokenBudget, honors workspaceIndexExcludePatterns, and fails softly if the index is unavailable. Use search_codebase for proactive conceptual search or rebuild the index after a large external change.

Approvals and secrets: Always Allow means always allow: every Agent approval callback returns authorization immediately, including irreversible commands, Docker access, MCP tools, live-server actions, external navigation, browser interaction, and page-requested CDN/API origins. It never opens an approval prompt and never converts a missing prompt into a hidden refusal. The Trusted Agent maximum-access profile also enables all Agent tools, writes, commands, and subagents and turns the command sandbox off. Tool protocol and capability validation remain separate and any block is returned visibly. In Ask/Workspace modes, an irreversible command such as npm test && rm -rf src is classified so the prompt explains the risk. Likely secret files — .env, credentials, .netrc, SSH identities, *.pem and their kin — are a profile rule rather than a prompt: Secret files under Profiles & Guardrails is on for Trusted Agent and off for every other profile, and off means the read tools refuse the file outright with no question asked, in Claude subscription mode as well, where the CLI is handed the same names as deny rules. RAG, searches, and approval-less subagents omit or block them in every profile; search_workspace reports how many likely secret files it excluded without naming them. Common credential values and private-key blocks are redacted before logs, debug traces, or conversation history are retained.

The approval prompt: it shows the whole command, wrapping rather than clipping so a long remote command cannot be authorised half-read, with a Copy button beside it. A command the sandbox will not let through — ssh, curl and similar, while agentSandbox is not off — carries a warning before you decide, naming the key-shaped SSH button in the panel header as the way to reach a live server instead. Stopping the request settles any open prompt as a denial and withdraws it, so a cancelled run never waits for an answer about work it is abandoning.

Sandbox: agentSandbox defaults to workspace-write. Built-in mutations stay inside workspace roots, while shell commands use macOS sandbox-exec or Linux Bubblewrap. Missing backends fail closed. Select read-only for inspection or off to permit unrestricted commands; Trusted Agent selects off. Every Agent command receives CODERFRIEND_AI_COMMAND_BOUNDARY; sandboxed commands additionally receive CODERFRIEND_AI_COMMAND_SANDBOX.

Under off a command runs in your real environment - your HOME, your tool configuration, your credentials - because that mode exists to permit unrestricted commands and a substituted environment is a restriction. A tool that keeps durable state in HOME, such as mkcert, therefore finds it. Every sandboxed mode still builds a disposable home per command and passes an allowlisted environment, and so does a host Docker command forced outside the sandbox from a sandboxed profile. The exact platform user temporary directory remains writable for compiler and Apple toolchain caches.

Each command owns its process group, so the 60-second routine-command timeout or 180-second recognized project-check timeout, an output overflow, and Stop end the complete process tree and escalate from TERM to KILL; direct Codeception and Playwright invocations count as project checks even through Docker Compose. A command that ignores TERM cannot hold the request open.

CoderFriend's host-only integration checks that need nested isolation, unrestricted process-tree behavior, or loopback networking are reported as skipped inside any Agent command boundary and run outside it. test:extension-host and test:vsix check that boundary before starting nested VS Code/Electron, preventing an Agent verification from crashing a temporary Code process.

Host Docker daemon access can bypass workspace confinement and runs outside the OS command sandbox; Ask/Workspace mode prompts once and Always Allow proceeds immediately. From a sandboxed profile CoderFriend adds only the system Compose plugin to that command's disposable home and keeps personal Docker configuration and credentials hidden.

Agent uses declared Make targets such as make up and make unit instead of reconstructing their Docker recipes. Guessed targets such as make e2e are rejected when absent from a statically readable Makefile, with the available declared targets returned. Missing file reads include bounded nearby exact names, allowing direct recovery from docker-compose.yml to compose.yaml.

Review and undo: each Agent run that changes files through built-in mutation tools creates a recoverable checkpoint outside the repository. Its compact card shows added, modified, and deleted files; select one to open its exact native VS Code side-by-side diff, expand longer lists, or use Review Changes for the complete checkpoint. The overflow menu copies or reveals the bounded raw unified patch only when needed. Restore checks for newer edits and asks before overwriting conflicts. Generic shell editing is blocked outside Maximum Trust. In Maximum Trust, recognized shell-edit commands capture a best-effort before-state for explicitly named files; unidentified command side effects remain outside restore claims.

Overlapping requests: sending a new sidebar request cancels the old one, keeps its stale progress or completion events from overwriting the current run, and rejects only the superseded request's pending inline approvals.

Queued follow-ups and live Agent steering: while a sidebar Agent is working, Enter or Send adds a row above the composer and lets the current work continue. A steering row can carry pasted screenshots — up to four waiting at once — which is usually what the correction is about; context-file attachments still need a separate request.

Select Steer on a row to apply it to the active request now, or use its trash action to remove it. Untouched rows continue in order as normal Agent turns after successful completion. Use Stop to cancel the active request; Stop, errors, and limits leave the queue for explicit action instead of silently starting paid work. Reaching agentMaxIterations always shows the visible Agent stopped notice, including when the final turn was truncated or needed another recovery continuation. Every accepted steer is also rendered as a durable standalone user turn tagged steer, independently of the temporary queue row, and the Working card keeps the exact applied text as an expandable, copyable activity row. Steering keeps the active request's captured provider, model, approvals, and budgets. During a model call, the stale result is discarded before its tools run. During a tool or approval, the current operation finishes safely, remaining unstarted calls in that stale batch are skipped, and the update is applied before the next model call. Applied steering updates are saved as steer conversation turns.

Run CoderFriend AI: Run Agent Evaluation... to measure the currently selected provider and exact Agent model. Smoke runs 6 tasks, Standard runs 24, and Full runs all 72 tasks across bug fixing, features, refactoring, tests, documentation, and safety/repository instructions.

Generated code and hidden deterministic checks run in a temporary Docker or Podman container with network disabled, dropped capabilities, resource limits, and sanitized environment variables. Cloud evaluations can make many paid calls, so CoderFriend asks before starting. Run CoderFriend AI: Open Evaluation Scorecard to compare retained provider/model results.

Create Worktree Session... creates an isolated coderfriend/... branch and worktree from committed HEAD. Run Agent in Background... starts an independent task context, captures the selected provider and exact Agent model, keeps changes inside a clean worktree, and continues when the sidebar is hidden. Current chat history and attachments are not copied. Use View Background Agent Runs... for status, cancellation, reports, diffs, and opening the worktree.

Agent mode can use spawn_subagent, list_subagents, and get_subagent_result after a per-request approval. A child can use the researcher (default), architect, reviewer, or tester role preset. Each preset has focused instructions and an enforced capability policy; every role remains depth-one, read-only, commandless, concurrency-limited, and cancelled with the parent. In interactive requests, those role policies can also expose root-scoped semantic helpers such as search_codebase, get_diagnostics, find_definitions, find_references, get_workspace_symbols, and get_hover_info.

Broader multi-step requests can start with an automatic task plan, and that preloaded plan is also inserted back into Agent context so the model can coordinate around it immediately. Parent/child agents can then use shared write_artifact/read_artifact scratchpads plus a Shared task plan via set_task_plan, get_ready_tasks, task_status, and dispatch_ready_tasks. Dispatched specialist tasks write their findings into shared task-results/<task-id>.md artifacts automatically. While the parent is still running, bounded collaboration updates about dispatched and settled child work are also fed back into that Agent so it can react without polling get_subagent_result first.

The Working card includes a live subagent activity panel with collapsible per-child role, status, elapsed time, iteration count, recent tool summaries, and child/shared token and cost usage. The expanded row names the concrete assignment, shows the latest safe operation, previews bounded final findings, and explains failures or cancellations; all four fields are redacted and never expose private chain-of-thought.

Per-child and global delegation budgets stop work when reported tokens, exact-rate/provider cost, or wall-clock time reach their configured limits. If cost is unknown it shows N/A and cost enforcement is unavailable without treating the request as free; token, iteration, and time safeguards continue. Delegated usage is included in the Conversation Usage HUD. Background state survives for inspection, but a VS Code reload marks active work interrupted rather than replaying paid calls.

Background Agent runs also retain the Shared task plan, scratchpad artifacts, subagent summaries, and a reviewer verdict in their Markdown report. While a background run is active, ready specialist tasks from that shared plan can now start automatically, the running implementer loop receives those bounded collaboration updates too, and the persisted state updates so an interrupted job still shows its latest shared plan, scratchpad artifacts, subagent progress, and automatic dispatch events. After a background run edits files, the reviewer role can trigger a bounded self-heal round before the run is marked complete or failed.

With coderfriend-ai.remoteControl on, an Agent session can be followed from a phone: read the transcript as it happens, send a steering message, stop the run, and start one. That is the whole feature. There is no remote file browser, no diff, and no approval prompt, because approving a command means reading a command line and judging it, and someone who cannot see the workspace cannot judge one.

It requires Trusted Agent. Any other approval mode is refused by name rather than quietly ignored: a run that pauses for approval would give the phone a transcript that stops dead with nothing able to answer it. The light will not come on under another profile — pressing it shows a notice in the panel saying to choose Trusted Agent in the Trust dropdown under the chat box — and if the profile changes while it is on, the next run turns it off and says so on the desktop and on the phone, rather than staying lit over a run the phone never sees. The setting is off by default and sits beside agentApproval under Permissions and runtime.

What crosses the wire is an allowlist, not a filtered copy of the sidebar. Twelve message types are sent; a type nobody has classified sends nothing at all, so a new one is inert rather than leaking until someone remembers it. Workspace diffs, the debug trace, rendered help, review findings that quote file contents, and a tool's output are absent by construction; a tool's command line travels whole, redacted, with the machine's paths cut out — from Claude subscription mode too, whose steps once carried only an eighty-character clip. Text that is sent is redacted before it is truncated, never after, because truncating first can cut a credential in half so the pattern no longer matches and then ship the front of it. The task you typed travels with the start of a run, cut to 500 characters and redacted like everything else, so the phone shows the question as well as the answers.

Content is sealed end to end, and the relay that carries it holds no key at all: the two ends agree one directly through an X25519 exchange the relay merely forwards. Pair once with Pair a New Phone, which shows an eight-character code you type into the phone. The code is not a secret — it names a session — so what protects the content is the fingerprint: both ends show eight hex characters and both ask you to confirm they match before anything is sent. Both, because if only the phone asked, somebody who guessed the code would pair with your sidebar and the two would genuinely match.

After that the phone reconnects on its own, with nothing to type and nothing to compare, because each end has recorded the other's identity key and a relay in the middle holds neither. Those keys only authenticate; session keys are fresh every time, so a phone stolen later cannot decrypt anything recorded before. Paired Phones... lists what is trusted and revokes it, which is the only way a pairing ends.

Once a phone is paired, every window with the setting on turns remote control on for itself when it opens, so the phone's list of sessions is simply the windows you have open. A window meets every paired phone, not only the one paired last: it opens one relay session per phone, because a session is named by a key only that phone knows, so pairing a second phone never hides the window from the first. Session names change with the hour, and the window moves with them a moment after each hour turns, so a window armed in the morning is still found in the afternoon. Two windows opened in the same hour take different slots: the second is refused the first's and walks to the next. The Remote Control button in the composer bar shows which it is — lit when this window can be watched — and switches it off and on. A phone that connects is shown the session as it stands, including the last run if nothing is going, rather than an empty screen it has to wait at; a phone that was away when a run was stopped is shown how that run ended before the next one begins.

Before anything reaches a network, each run is written as a JSONL record of exactly what a remote client would have received, under the extension's global storage rather than the workspace, so it can be read and grepped first.

Watching from another VS Code. Any VS Code with this extension can be the phone. On the computer you want to watch from, run CoderFriend AI: Pair with a Remote Desktop and type the code the other computer shows from Pair a New Phone; both sides show the same eight-character fingerprint and both confirm. From then on Watch a Remote Session lists the other computer's armed windows — every paired desktop, this hour and last — and opens the one you pick in an editor tab: the transcript as it happens, a box to steer or start a run, and Stop. The other side sees this computer in its Paired Phones list and can revoke it there; Forget Remote Desktops is the same from this side. Sealed end to end like the phone, and the pairing lives in this computer's keychain.

CoderFriend Desktop, the board that ships with the phone app, follows up to four windows on one screen — one pane per editor window, on any computer it is paired with. It pairs the same way (the code from Pair a New Phone, the same fingerprint on both sides) and appears in Paired Phones like a phone. One device watches a window at a time, so a window on the board is not also on the phone.

CoderFriend starts with a short first-message title, then asks the selected model to review that automatic title after the conversation has enough request and outcome context. It waits for meaningful thread growth before reviewing again and never overwrites a title you renamed manually. Conversation usage is saved with the thread and restored when you reopen it.

• Rename — use the history picker or Rename Current Conversation command
• Bookend retention — message-count limits keep the opening task pair and newest messages
• Saved text — conversations and bounded debug traces are workspace-scoped
• Screenshots — opening and recent images can remain in the live session, but base64 image data is never written to saved history
• Attached source — file and folder contents stay in the live session and are not written to saved conversation history
• Backup into the project — mirror this workspace's conversations into the repository as readable documents; see below
• External storage — keep all but the most recently used conversations on another disk, and have one come back when opened; see below
• Migrate from Claude Code or Codex — bring the sessions those tools keep on this machine into history; see below

Conversation backup. Saved history lives in the extension's global storage, keyed by a hash of the workspace path, where nothing in the repository can see it. coderfriend-ai.conversationBackup mirrors it into the open project: off writes nothing, manual (the default) writes only when asked, and auto also writes on a schedule and whenever a long Agent request compacts its context.

Each conversation becomes a Markdown document to read and review in a diff, a JSON sidecar so it can still be imported back, and an attachments directory holding the screenshots it links. Write a backup with Export All Conversations or /backup; read one back with Restore Conversation Backup, which loads a single conversation or all of them. Restoring is safe to repeat: a conversation already in history is skipped rather than duplicated. maxConversationHistory still applies, so restoring more than that limit discards the oldest as it goes; the restore reports how many were dropped, and raising the limit first is what keeps them.

Set the location with coderfriend-ai.conversationBackupDirectory (default docs/chat-history, relative to the workspace) and the schedule with coderfriend-ai.conversationBackupIntervalMinutes (0 disables it; values below 5 are raised to 5). Context compaction only shortens what is sent to the model and never edits the stored transcript, so that trigger is a safety net rather than a rescue.

Keeping most of the history on another disk. Saved history lives on the disk VS Code lives on, and every conversation of the open folder is held in memory while the window is open. coderfriend-ai.conversationExternalStorage names a directory on another disk for the rest: the most recently used conversations (coderfriend-ai.conversationsKeptLocally, default 20; the open one always counts) stay local, and everything beyond that moves there after each save, screenshots included. Pick it with Choose External Conversation Storage…. An external conversation stays in the history picker, marked as such, and opening it brings it back on its own while the least recently used local one makes room. The folder is created if it does not exist yet, as long as its disk is there; a path naming a disk itself is not, because while that disk is unplugged the folder would land on the internal one. The list works with the disk unplugged — such entries say it is not connected — and nothing is ever moved to a disk that is away. Deleting works on either disk, maxConversationHistory counts both, and backups read external conversations from where they are.

Migrating chats from Claude Code and Codex. Both tools keep every session on this machine (~/.claude/projects and ~/.codex/sessions), so there is nothing to export first. Migrate Chats from Claude Code or Codex, also in the history picker, finds them and offers them in one list: the sessions run in the open folder come first and are ticked, and sessions from other folders are listed below unticked. Each entry names its tool, its last use, and its prompt count (a Codex thread shows its size instead, because those are not read to be listed). Threads Codex spawned for its own subagents are left out, and so are headless claude -p runs a program drove rather than a person — CoderFriend's own Claude-subscription requests among them, which are already in history.

An imported chat is an ordinary conversation afterwards, named after where it was had (Claude Code: …, Codex: …) so it stands out beside CoderFriend's own. Prompts and replies become turns, the commands the assistant ran fold under each reply as the same activity record a CoderFriend run leaves, screenshots are kept beside the transcript, and a stopped turn is shown as stopped. Editor wrappers around a prompt are stripped so it reads as typed, private reasoning is not carried, and bodies are bounded and redacted as history's own are.

Running the migration again skips what is already there, so a chat renamed or continued since is untouched. A selection larger than maxConversationHistory asks first and offers to raise the limit. Nothing is read from or sent to either tool's service.

• File & Folder Context — use the + menu to add workspace files or bounded folder contents; generated directories, symbolic links, binary files, and likely secrets are skipped
• Image Support — paste or drag-and-drop images into the chat (up to 5); click any picture in a conversation to see it full size, click it again for its real pixels, Esc to close
• Inline Completion — enable in settings (coderfriend-ai.enableCodeCompletion)
• MCP Servers — connect external MCP tool servers via settings
• Conversation History — browse, load, rename, import, export, back up into the project, restore, migrate from Claude Code or Codex, clear, or delete conversations
• Conversation Usage HUD — view current-conversation tokens, prompt-cache activity, and provider-reported or exact-rate cost; uncertain totals display N/A
• Provider API Keys — stored securely in VS Code SecretStorage
• Model Aliases — define custom model name shortcuts in settings
• Favorite Models — select a model and click the star beside the model picker; favorites are remembered per provider and shown first
• Local BM25 Retrieval — automatically find relevant workspace code without an external embedding service

Open Command Palette → CoderFriend AI: Open Settings Center, or click the settings button. The center provides searchable pages for every active extension setting.

Use Profiles & Guardrails for trust and request budgets. It writes coderfriend-ai.policySettings and supports one general default plus provider and model exceptions.

Key settings: modelSource, provider enablement and endpoints, chatModel, planModel, agentModel, codeCompletionModel, favoriteModels, modelSpeed, reasoningEffort, responseDensity, agentSandbox, allowedExactCommands, allowedPathPrefixes, allowedExactPaths, enableAutomaticCodeReview, codeReviewAutoMinChangedLines, codeReviewMinimumConfidence, codeReviewSuppressedRules, enableRuntimeVerification, runtimeBrowserPath, runtimeBrowserVisible, generatedImageDirectory, providerCallTimeoutSeconds, enableRepositoryInstructions, enableWorkspaceIndex, automaticCodebaseContext, automaticCodebaseContextTokenBudget, workspaceIndexExcludePatterns, enableWebTools, webSearchProvider, searxngEndpoint, enableDocumentationLibrary, enableDocumentationFetching, documentationIndexMaxPages, documentationIndexMaxDepth, externalContextTokenBudget, prefixCommitMessagesWithModel, commitMessagePrefixExcludedFolders, contextCompaction, contextCompactionThresholdCharacters, composerShowUsage, composerShowAttach, composerShowMode, composerShowModel, composerShowSpeed, composerShowReasoning, composerShowContext, composerShowDetail, composerShowProfile, composerShowTrust, composerShowProvider, composerShowApproval, composerShowSteerHint, agentMaxIterations, agentRequestMaxTokens, agentRequestMaxCostUsd, agentRequestTimeoutSeconds, agentRequestMaxModelCalls, backgroundAgentMaxIterations, backgroundAgentReviewMaxRounds, backgroundAgentMaxConcurrentRuns, agentMaxSubagents, agentMaxConcurrentSubagents, subagentMaxIterations, subagentMaxTokens, subagentMaxCostUsd, subagentTimeoutSeconds, agentSubagentTotalTokenBudget, agentSubagentTotalCostUsd, agentSubagentTotalTimeSeconds, maxTokens, maxResponseCharacters, maxConversationMessages, maxConversationMessageCharacters, maxDebugEntryCharacters, modelAliases

Watch four runs in one view Keep up to four independent editor sessions visible as separate panes on one desktop screen.

Search and assign a session to a pane Find an armed editor window and place it deliberately on the board.

Use the board as a paired device Pair the desktop board with the same verified-code and fingerprint flow used by a phone.

Keep a window focused on one viewer Prevent simultaneous viewing conflicts by reserving each watched window for a single remote device.

Fold streaming assistant output into readable updates Grow consecutive assistant text in place instead of flooding the transcript with token-sized rows.

Keep progress compact Update one live status line rather than adding a new transcript entry for every progress change.

Respect your reading position Pause automatic following when you scroll back through an active run.

Jump back to the live run when ready Return to the newest Agent activity with a dedicated live-position action.

Restore a coherent session after reconnecting Reconcile snapshots and completed runs without duplicating stale status entries.

Resume the encrypted remote transport Reconnect the remote viewer and continue from the correct sealed frame sequence after a network interruption.

Copy any transcript row Press and hold a remote update to copy its text without needing to select from a scrolling list.

Share updates through the phone system sheet Send a selected row to the installed sharing destinations on iPhone or Android.

Keep desktop sharing useful Copy the selected update and confirm the result when a desktop build has no mobile share sheet.

Send steering only to the active run Direct a clarification to the session currently being watched.

Refuse stale delivery instead of queuing it Show that an unsent correction was not deferred to a later point in the run.

Preserve deliberate human control Let you review and resend a correction when the current run can receive it.

Watch the agent transcript as it happens Follow live progress away from the editor while the desktop remains the source of workspace context.

Send steering messages to an active run Redirect or clarify the current task from the paired phone without opening a separate conversation.

Stop a run remotely when needed End the active agent run from the phone when its direction or timing no longer fits.

Discover armed editor windows Search for available Remote Control sessions and choose the intended repository, computer, and VS Code window.

Limit remote control to Trusted Agent Keep the feature unavailable in modes that can pause for approvals the remote viewer cannot safely judge.

Verify pairing on both devices Compare the same fingerprint on the phone and desktop before trusting the connection.

Seal remote session traffic Protect transcript, steering, and stop messages between the paired desktop and phone.

Keep the relay blind to content Route ciphertext through infrastructure that cannot read the remote session.

Reject incompatible protocol versions Refuse a mismatched wire contract during the WebSocket handshake instead of misreading later frames.

Control multiple desktops from one phone Pair once for each CoderFriend installation, then use the phone’s desktop board to move among the computers and workspaces available to you.

See each VS Code window as its own session Keep simultaneous projects distinguishable instead of collapsing every open editor on a computer into one ambiguous destination.

Watch a session from another VS Code window Open the shared board on a second desktop window to follow an active remote conversation without taking over its editor.

Keep pairing changes synchronized Phones paired or revoked in one window are reflected across the other participating windows, so the board stays current.

Open a focused desktop board Use a dedicated board with recognizable window identity, built-in help, and a maximized view for monitoring several sessions.

Excluded folders stay out of model context Apply workspace exclusions before attached folders, automatic context, and repository-search evidence are assembled for a provider request.

Use project-specific exclusion rules Respect the workspace’s configured ignore and exclusion patterns instead of relying on one hard-coded directory list.

Filter nested files before transmission Remove matching descendants while walking folder trees so selecting a parent folder does not bypass its protected children.

Keep local-only material on disk Avoid silently including dependencies, build artifacts, private working directories, and other intentionally excluded files in hosted-model prompts.

See which model handled the request Show the resolved model with the conversation response or run details rather than making you infer it from the answer.

Identify the provider route Distinguish API, local, Codex, Claude subscription, and other configured transports when comparing results.

Confirm profile-selected models Make the effective choice visible when a guardrail or runtime profile supplies provider and model settings.

Trace fallbacks without guesswork Preserve the actual route used when availability or configuration causes execution to differ from the composer’s initial choice.

Include open editors only when useful Add the currently open documents to an individual request instead of sending every open tab automatically.

Review the exact files before sending Surface the selected editor context with the other request attachments so stale or sensitive tabs can be removed.

Keep later requests lean Treat open-editor context as request-scoped evidence rather than silently carrying it into the rest of the conversation.

Choose a dedicated conversation folder Store chats outside the active repository when project-local history is not the right fit.

Create storage only when it is needed Avoid leaving an empty CoderFriend history folder behind before the first conversation is actually saved.

Keep repositories free of personal chat data Separate reusable or private conversation history from files intended for source control.

Continue using normal history controls Browse, reopen, rename, and search stored conversations through the same CoderFriend interface.

Discover supported local chat histories Find conversations written by the installed Claude Code and Codex tools without requiring a cloud export.

Name imports after their source Label migrated conversations with the tool they came from so imported and native chats remain distinguishable.

Review before continuing Open imported messages in CoderFriend history and decide which context is still relevant before asking for more work.

Keep the original records intact Copy supported history into CoderFriend storage rather than rewriting the source tool’s own conversation files.

Inspect images without leaving VS Code Open supported image files in the editor instead of translating visual output into an unreadable text payload.

Review generated visual artifacts Display an image result at its workspace path so you can inspect what a tool produced before accepting the work.

Use the visible result in follow-up requests Keep the image available for comparison while asking the Agent to refine the surrounding code or asset.

Upload one named local file deliberately Use the dedicated SSH upload tool rather than hiding a transfer inside a generic shell command.

Validate both ends of the transfer Apply workspace path policy to the local source and live-server safety rules to the remote destination.

Keep server identity visible Tie the upload to the active live-server connection so the destination host is not inferred from an arbitrary command.

Respect the current approval mode Route file transfer through the same resolved authority and confirmation controls as other live-server changes.

Inspect the active debug state Read threads, stack frames, scopes, and bounded variables from the paused session before choosing an action.

Continue, pause, step, or stop deliberately Use dedicated debugger operations instead of trying to drive the adapter through shell commands.

Evaluate a focused expression Query the current paused frame when an exact runtime value is needed to test a diagnosis.

Keep debugger activity visible Record the requested operation in the Agent run so runtime control is not hidden from review.

Keep a disconnected server visible Preserve the live-server row and its last known state when the connection ends instead of making the target disappear.

Offer reconnection where work can continue Surface a reconnect action in the composer and status banner when an interrupted task still has a usable server target.

Refuse unsafe blind resumes Do not resume remote work when no live-server connection exists to establish where later commands would run.

Report the failed remote stage Identify the SSH or remote execution step that interrupted the run so recovery starts from concrete evidence.

Protect an unfinished prompt while navigating Arrow keys move the caret inside a non-empty draft instead of replacing it with prompt history. History recall begins only when the composer is empty.

Keep drafts across conversation changes Starting a new chat leaves the current draft available so you can return to it instead of reconstructing the prompt.

Restore text used by follow-up actions Retry, Continue, and Resume Agent can submit their generated line without permanently overwriting what you were already composing.

Remove text only through deliberate editing Backspace, Delete, replacing a selection, sending, and running a slash command remain the explicit ways to clear composer content.

Research the web from Claude subscription runs Claude Code WebSearch and WebFetch are available alongside its normal tool loop when web tools are enabled.

Use the same web-tools preference across providers The existing web-tool setting governs Claude subscription access as well as other provider transports, keeping the control in one place.

Keep web access opt-in Turning web tools off removes those Claude Code tools, so a local or restricted workflow stays restricted.

Deny likely secret files without an approval loophole When Secret files is off, file-reading tools refuse recognized credential and private-key paths instead of presenting a prompt that could be accepted accidentally.

Resolve real paths before applying the rule Canonical-path checks prevent a symbolic link from disguising a protected file under a harmless-looking name.

Extend the boundary to Claude subscription mode Equivalent Claude Code read deny rules cover its Read, Grep, and Glob operations when secret-file access is disabled.

Let policy and team roles enforce the restriction Managed policy and viewer or developer roles can deny secret-file reads even when a local preset would otherwise permit them.

Name the active limit when a run stops A cut-off Agent run reports whether its ceiling came from the selected guardrail profile or the legacy Agent iteration setting.

Point to the control that can change the outcome When a profile maximum replaces the legacy setting, the notice directs you to that profile rather than suggesting an ineffective setting change.

Keep completed work available for continuation Reaching the step ceiling preserves the work already produced and leaves the run ready to continue.

Capture terminal output when you enable it Turn on terminal capture to retain bounded command output from VS Code terminals with shell integration. Capture is off by default, applies redaction, and clears its retained records when disabled.

Ask about the last captured command Open an explanation request with the command, working directory, available exit code, and retained output together. This keeps the question attached to the actual terminal operation instead of an isolated error sentence.

Start a repair from a captured failure Fix Terminal Failure opens a repair request for the latest captured command with a reported nonzero exit code. It requires terminal capture and shell integration; when no failure was captured, the command explains what is missing.

Save facts through an explicit memory command Remember for This Project saves text you deliberately enter, with its scope and provenance. Project memory is optional and redacts sensitive-looking values before retaining bounded records locally.

Inspect, edit, disable, or delete saved memories Manage Project Memories provides a searchable list with edit, enable or disable, mark verified, and delete actions. A remembered fact remains visible and removable instead of becoming an invisible permanent instruction.

Add active memories within a context budget Enabled sidebar requests can include active applicable memories inside a bounded context allowance. The model receives them as user-approved context, while disabled, expired, or stale records are excluded.

Export or clear the memory collection Export Project Memories writes a portable JSON record for inspection and archiving. Delete All Project Memories removes the saved collection after an explicit confirmation.

Share file reading, directory listing, and workspace search Compatible VS Code AI integrations can call the exported readFile, listDirectory, and searchWorkspace tools. They use CoderFriend file boundaries and bounded workspace results without selecting a separate CoderFriend model.

Keep exported tools read-only The exported tool set provides reads and search; file writes and shell execution remain outside this integration. External calls have a session call ceiling and do not create provider token charges themselves.

Control tool availability from settings The exportLanguageModelTools setting enables or disables registrations. Sharing requires a VS Code host with the Language Model tool API; an older host leaves these exports unavailable.

Restrict providers, tools, and request resources A managed policy can withdraw capabilities, restrict provider sources, and lower request token, cost, time, call, or iteration ceilings. It is applied after user, provider, and exact-model policy resolution.

Tighten approvals and sandbox boundaries Managed approvals and sandbox choices can make an existing policy more restrictive. A machine policy cannot silently grant a tool, remove a stricter user restriction, or widen the workspace boundary.

Choose Viewer, Developer, Maintainer, or Admin roles Organization roles provide named starting restrictions: Viewer withdraws Agent tools, Developer requires per-action approvals and disables subagents, and Maintainer retains the workspace sandbox. Admin adds no role restriction; explicit managed policy still applies.

Use administrator-declared credential sources An administrator can name the environment variable that supplies a provider key. When that declared source is empty, the connection explains the missing managed credential and does not fall back to a personally stored key.

Set retention periods for local records Managed retention can prune old conversations, memories, completed run reports, and audit entries according to separate day limits. This controls the extension’s local records; exported copies and provider-side data remain separate.

Enable repository hooks deliberately Lifecycle hooks are optional and repository hooks require their own trust setting. Hook definitions live in .coderfriend/hooks.json, so accepting a repository does not silently authorize its command checks.

Apply pre-tool checks that can narrow a request Connected preToolUse hooks can deny a tool call, request the existing approval flow, or attach a reason. A hook cannot grant authority that the resolved request policy already withholds.

Bound hook execution and report failures Hook execution limits time, output, environment, and the number of checks. A failed deciding hook asks for a decision through the current approval policy instead of being treated as a successful check.

Record activity only after audit logging is enabled Audit logging is off by default. Enabling it records connected activity from that point onward in the extension’s local storage, with redacted and bounded detail rather than a retroactive history claim.

Verify the retained audit chain Verify Audit Log checks the sequence and linked entry hashes and reports where verification first fails. This helps reveal an altered or missing retained entry; a local file is not an independently authenticated or tamper-proof service.

Export the log with its verification result Export Audit Log writes the retained JSON chain and reports whether it verifies. This gives support or internal review a concrete local artifact without uploading it automatically.

Bound retention without blocking coding work The recorder limits retained entries and honors the managed audit-retention period. Disk writes are best effort, so recording does not become a guarantee that every action is durably logged or a reason to stop a coding request.

Connect to a local LM Studio server Start the LM Studio server and select LM Studio (Local). The default endpoint is http://localhost:1234/v1; configure the matching loopback port when your server uses another one. Plain HTTP on a non-loopback LAN address is not supported.

Choose from the models your server provides The picker reads the running server’s model list and filters embedding and reranking names from chat choices. No model is assumed to be installed: select one you have downloaded and made available in LM Studio.

Use no key unless local authentication is enabled LM Studio works without an API key by default. If its optional Require Authentication setting is enabled, supply the token through secure provider setup or LM_API_TOKEN; an unsecured local server needs neither.

Use model-dependent Agent tools and completion LM Studio can serve Chat, Plan, Agent, and completion requests. Tool calling and image understanding depend on the selected model; CoderFriend does not offer an LM Studio reasoning-effort control or native web-search capability that the server cannot honor.

Track local tokens without charging a spending budget Supported LM Studio versions report streamed usage, allowing token totals and context controls to work. Local inference is excluded from the spending ledger; monetary cost remains N/A rather than an invented provider charge.

Continue compatible runs after closing VS Code Enable detachedBackgroundRuns to launch supported background Agent tasks independently of the editor window. API-backed routes, Ollama Local, and LM Studio can use this workflow; Codex and Claude subscription sessions stay in the editor because their login belongs to the desktop session.

Inspect recorded progress from another window A detached run writes a bounded progress journal and final outcome that another CoderFriend window can inspect. The UI distinguishes completed, failed, cancelled, and interrupted work instead of silently replaying an abandoned task.

Stop or steer a run from another window Background run controls can address the current owner to request cancellation or send steering. Directions are applied at safe work boundaries, preserving the task’s isolated worktree and its resource limits.

Review the worktree before integration Detached execution belongs to the existing background-worktree workflow. Its result and diff remain reviewable before integration, so closing the foreground editor does not implicitly approve changes to the primary workspace.

Inspect a paused debug session Explain Paused Debug Session reads the active debug adapter’s threads, stack frames, scopes, and top-frame variables. A running session without a paused stack is reported explicitly.

Keep debugging inspection read-only The snapshot workflow does not step, resume, evaluate expressions, or change the debugged program. It prepares context for a repair explanation while the developer keeps control of the debugger.

Bound and redact captured variables The snapshot limits frames, variables, and value length, skips expensive scopes, and withholds credential-shaped variable names. The resulting request includes useful failure context without deliberately collecting the whole process state.

Read numbered code and Markdown cells The notebook tool presents .ipynb files as numbered cells with bounded source and text outputs. Non-text outputs are identified rather than embedded as large payloads.

Replace, insert, or delete a selected cell Agent notebook edits target an explicit cell index and operation, preserving the surrounding document and metadata. The normal file-write policy and path checks still apply.

Clear outdated results when code changes Replacing a code cell clears its stored outputs and execution count so old results are not presented as proof of the new source. Editing a cell does not execute the notebook kernel.

Review and restore notebook changes Notebook mutations use the same change session and checkpoint path as other Agent edits. Open the result in VS Code’s notebook editor and inspect or restore the changed file through the usual review workflow.

Start a task from a GitHub issue Provide an issue number or GitHub issue URL to load its context and create or reuse a task branch. A signed-in GitHub CLI and an open workspace are required; an existing related pull request can be reused deliberately.

Inspect the connected account and task status GitHub connection and status commands show the authenticated account and scopes, repository, branch, available pull request, checks, and current authority summary. These views keep external work tied to a visible account and repository.

Turn pull-request feedback into a repair request Load review comments and failed checks from the current branch’s pull request into an Agent repair request. The prompt keeps push, commenting, and check reruns as separate external actions.

Re-run failed checks with explicit confirmation The failed-check command asks before starting GitHub workflow runs. It then reports the actual rerun result rather than treating a local repair as proof that remote checks passed.

Push and open a draft pull request deliberately On a non-default branch, the draft command checks for an existing pull request, then asks before pushing the branch and opening a draft against the repository default. The draft can be reviewed before later merge decisions.

Watch the run as it happens The phone shows the same run the sidebar does: what the model is doing now, each tool call with the command it actually ran, and the assistant’s own text. Connecting shows the session as it already stands, including the last completed run, rather than an empty screen that waits for the next event.

Steer, stop, or start work Type to steer a run in progress, or to start one when nothing is running, through the same path the sidebar composer uses. Stopping asks first, because a run stopped from a phone cannot be resumed from one.

Trusted Agent only, and no approvals on the phone Remote control is refused for any approval mode that can pause and ask, because there is no way to answer an approval from a phone: judging a command means reading it beside the workspace it will change. The setting is off until you turn it on.

Pair once, then reconnect until you revoke it Pair a phone with a desktop by reading an eight-character code off the sidebar, comparing a fingerprint at both ends, and confirming. After that it reconnects on its own with nothing to type. The paired-phones list shows what is trusted and revoking is the only way a pairing ends.

Pick which editor window to watch Every window with remote control on offers itself by its project name, so a phone lists the work you have open and you choose. A window turns remote control on for itself when it opens, and the composer shows a Remote Control switch for turning it off and on.

Encrypted so the relay cannot read it The two ends agree keys directly through a key exchange the relay only forwards, so the service that carries the traffic holds nothing that can decrypt it. Identity keys authenticate the pair and never derive session keys, so a phone lost later cannot decrypt anything recorded before.