# Nock overview Nock brings voice, conversations, desktop actions, and small useful tools into a notch at the top of your screen. Dictate into a text field, ask about something on screen, or hand a focused task to an agent without making a chat window your whole workspace. > Note: > > These guides describe the current Nock candidate. Check [Availability](/nock/availability) for the current public download and service status before installing. ## Choose your first workflow Curious about the system underneath the notch? Start with [How Nock works](/nock/how-nock-works). ### [Speak instead of typing](/nock/dictation)Hold the dictation shortcut, speak, and put your words into the focused text field. ### [Ask the agent](/nock/agent-mode)Have a conversation or ask for an action, with visible results in the notch. ### [Work with your screen](/nock/pointing)Point out a region so an explanation has the context you meant. ### [Make something useful](/nock/widget-builder)Describe a small widget, test its behavior, and choose whether to keep it. ## Two shortcuts, two different jobs On macOS, **Fn** is the default hold-to-dictate shortcut. **Left Control + Option** is the default hold-to-talk shortcut for the agent. Dictation inserts words; agent mode can answer, use enabled tools, or ask for more information. You can change these in Settings. For a first test, use an empty document and a simple sentence. Then try an agent question that does not change anything, such as “Explain the difference between dictation and agent mode.” See the [quickstart](/nock/quickstart). ## Find your work - The [notch](/nock/notch) contains Chat, Tasks, Apps, Studio, Web, and Settings. - [Chats](/nock/chats) lets you revisit conversations or begin a new one. - [Background tasks](/nock/background-tasks) separates running work from your next question. - [Studio](/nock/studio) gathers previews and widgets you have made. - [Glass Canvas](/nock/glass-canvas) is an optional board for notes, diagrams, web cards, and screen clips. ## Set up deliberately The guides primarily describe the macOS candidate. Platform support and account entitlements vary; do not assume a feature available in source is available in every build. Start with [permissions](/nock/permissions), check [account access](/nock/account), and review [privacy](/nock/privacy) before enabling screen-aware or cloud-connected features. Nock is not entirely offline. Local UI and saved work coexist with model requests and connected services. Review generated text, proposed actions, and coding changes before relying on them. # How Nock works Nock keeps the conversation in the notch while different parts of the system do the work. These four layers explain where a request goes and which parts you can configure. ```text You speak or type ↓ Voice (speech recognition and spoken replies) ↓ Brain (model selected for the conversation) ↓ Hands (local V3Code Terminal, workers, and task board) ↘ Delegates (connected coding agents, when chosen) ``` ## Voice Hold the dictation shortcut to put words into the focused text field, or hold the agent shortcut to ask Nock for help. Hosted speech recognition and spoken replies can use xAI through Nock's account relay; the selected recognizer may instead use Apple's speech service, including on-device recognition when that capability is supported. Voice settings, permission state, and the active recognizer determine the path for a given request. [Voice settings](/nock/voice-settings) and [Privacy](/nock/privacy) explain the choices. ## Brain The model handling a conversation interprets your request and decides whether to answer or use tools. The current included DeepSeek route passes through V3Code's account relay to DeepSeek's API. The exact model can vary with configuration and account access; Settings → Providers shows the model choices available in your build. Choosing another provider changes where model context is sent. See [Models and providers](/nock/providers). ## Hands For local project work, Nock can use its bundled V3Code Terminal engine. It searches and indexes a project, uses code intelligence where available, edits files, and runs commands. Longer work can involve background workers and appears on the Tasks board while you continue talking. Check the project's scope, progress, diff, and result: a completed task is a report of what ran, not a guarantee that every change is correct. See [Coding agents](/nock/coding-agents), [Background tasks](/nock/background-tasks), and [Coding permissions](/nock/coding-permissions). ## Delegates Nock can hand a bounded task to a supported agent you already use, such as Claude Code, Codex, or Grok Bot, when that integration is connected and available. Those agents have their own installation, sign-in, permissions, and provider data handling. A Nock named agent is a separate local persona, not the same thing as an external coding agent. See [Coding agents](/nock/coding-agents), [Grok Bot](/nock/grok-bot), and [Named agents](/nock/named-agents). For a first run, start with a question that does not change files. Then choose a project, ask for a small review, and inspect the task result before giving an edit request. [Quickstart](/nock/quickstart) walks through the first steps. # Availability Nock is in launch preparation. These pages describe the product and its implemented workflows so you can learn how it works before public downloads are ready. ## Check before installing Use the [Nock download page](https://v3code.dev/nock/download) to check availability. If it says **Coming soon**, there is no public installer available through that page yet. Documentation, a website demonstration, or an account button does not mean a desktop build has been released. Once downloads open, use the platforms and requirements listed on that page for the released build. ## What may differ between accounts Features depend on your app version and the capabilities enabled for your account. The account interface can show a feature as locked even if you have read about it here. - On-device dictation is the free fallback described by the product's account model. - Agent conversations, cloud transcription, and spoken replies require the appropriate account access. - Background-worker limits vary by access level. - Cloud agents are not publicly available at launch preparation. A plan description is not confirmation that cloud access is enabled. ## Preview versus desktop The website demonstration introduces Nock's interface. It cannot establish that the installed app has your microphone, Accessibility, connected accounts, or local project permissions. Complete the desktop setup when an installer becomes available. For the first steps, read [Downloads and updates](/nock/downloads-updates) and [Sign in](/nock/sign-in). For the product introduction, see [Nock overview](/nock/overview). # Downloads and updates ## Get the official build Open the [Nock download page](https://v3code.dev/nock/download). This is the stable entry point for available installers. Choose a build only when the page lists it for your operating system and computer. **Launch preview:** public downloads are still being prepared. A **Coming soon** message is expected until a release is published. Do not substitute a V3Code editor or terminal installer; they are separate products. ## Platform support Nock's desktop setup includes operating-system permissions and local helpers. Availability on one platform does not imply identical capabilities on another. Follow the requirements next to the released installer; these docs do not promise that every preview feature is available on every platform. The account interface may contain a download button before an installer is published. The destination download page remains the place to check actual availability. ## Updating an installed preview When a released app offers an update, finish or save your current work before installing it. Keep a note of the version you were running if you are investigating a regression. If no update appears, revisit the official download page. An update cannot be offered until a build has been published for your platform. Avoid deleting your settings or reinstalling repeatedly to force an unpublished release to appear. ## Report a download problem Include your operating system, computer architecture if known, installed Nock version, the download URL, and the exact message you see. Say whether the failure occurs before download, while opening the installer, or after starting Nock. Do not include account tokens or private project content. See [Availability](/nock/availability) for launch status and [Troubleshooting](/nock/troubleshooting) for setup checks. # Platform support Nock's launch-preview desktop workflow is centered on macOS, including its notch interface, global voice shortcuts, and native speech helpers. Public installers are still being prepared. Use the [download page](https://v3code.dev/nock/download) for the platforms and requirements of an actual release. Do not assume that a Windows build reference or a website demo means every macOS feature works on another platform. These instructions describe the macOS implementation; availability and parity must be checked for each released build. ## Permissions on macOS Open **Settings → Permissions** to inspect the capabilities Nock needs: | Permission | What it enables | | ------------------ | ------------------------------------------------------------------------------ | | Microphone | Hearing speech during a voice request. | | Accessibility | Inserting dictated text, selected-text access, and parts of shortcut handling. | | Input Monitoring | Detecting supported global voice shortcuts. | | Speech Recognition | The Apple on-device speech fallback. | | Screen Recording | Optional screen context when you request it. | Screen access supports visual assistance. The current guided onboarding tour also requires Screen Recording, alongside microphone and keyboard permissions; do not expect to complete that tour with screen access denied. Ordinary text-only requests do not themselves need a screen capture. The Apple recognition fallback prefers on-device recognition when the selected recognizer supports it. It is not an unconditional offline guarantee for every language or system configuration. ## Grant or revisit a permission A permission row shows states such as Granted, Denied, Restricted, or Not asked yet. Use **Grant** when available. Otherwise choose **Open System Settings**, review the relevant Privacy & Security panel, and enable the intended app entry. Return to Nock and check the state again. If macOS requires an app restart, save current work and follow that instruction. Do not assume repeatedly pressing a shortcut will trigger a prompt after permission has already been denied. ## Why Nock Speech appears Microphone and on-device recognition use a helper named **Nock Speech**. It can appear alongside Nock in the corresponding system privacy lists. Check the relevant helper entry if the main app appears permitted but speech still fails. Keyboard shortcuts involve their own listener. If the menu-bar item says **hotkey blocked by a missing permission**, inspect Accessibility and Input Monitoring first. Its permission refresh and listener restart controls can help after you have changed a grant. ## After replacing or updating the app macOS associates permissions with application identity and signing. A differently signed development copy can be treated as a different app, so old grants do not prove the current copy has access. Inspect the installed copy and its current permissions before changing audio or model settings. Likewise, an app run from source may not have the self-update controls offered by a release. That is a build distinction, not necessarily a networking problem. ## Narrow the failure No audio suggests microphone/input selection; no on-device transcript suggests recognition access; recognized words that are not inserted suggest focus or Accessibility; missing visual context suggests Screen Recording or the action's screen setting. Use a short test in an ordinary text field to distinguish these cases. See [Downloads and updates](/nock/downloads-updates), [Troubleshooting](/nock/troubleshooting), and [Support](/nock/support). # Your first few minutes Start with a short dictation and a simple question. These instructions describe the macOS controls in the launch candidate; check [Nock overview](/nock/overview) for release availability. ## Get ready Open Nock and follow its welcome steps. Grant the permissions requested for the features you want to try, then complete the account and access steps shown by your build. The guided demo has a limited allowance; ending the demo does not unlock unrestricted use. The defaults below can be changed in **Settings → General**. If you already changed them, use the shortcuts shown in your settings and tour. ## Dictate into another app 1. Open a note or message and click inside its text field. 2. Hold **Fn / Globe** and say a sentence. 3. Release the key and wait for the words to appear. Nock displays a live caption while you speak and inserts the finished text after release. Read the result before sending a message. If it landed in the wrong place, click the intended field and press **Control + Command + V** to paste your last transcript again. ## Ask Nock Hold **left Control + left Option**, ask a short question, then release. For example: “Give me three ideas for organizing today's work.” The response appears in the notch and can be spoken aloud. A quick tap of those keys opens the chat box for typing. ## Add context Highlight a sentence, then ask “Make this more concise.” For a visual question, hold the agent keys and circle the relevant part of your screen. Selected text and captured images may be sent to the model answering your request, so choose the context deliberately. ## If the first try fails Check [microphone input](/nock/microphone) when no words appear, and [permissions](/nock/permissions) when keys or text insertion do not work. Press **Escape** to cancel a recording. Keep the first test short so it is easy to tell which step failed. Continue with [dictation](/nock/dictation), [agent mode](/nock/agent-mode), or [onboarding](/nock/onboarding). # Choose a workflow Start with the result you want: text in a field, an answer, a file change, a small interactive tool, or a visual board. Nock exposes different workflows for those outcomes. The examples below are instructions to try when the feature is available in your build; they are not recorded demonstrations or guarantees of a particular result. ## Put your words into another app Choose [Dictation](/nock/dictation) when you already know what to write. Click a text field, hold **Fn / Globe**, speak a short sentence, and release. The expected result is a transcript inserted into that field. Review the words before submitting them. Dictation is not an instruction to the agent to carry out the sentence. If text misses the field, use [Paste last transcript](/nock/paste-last) after restoring focus. ## Improve text that already exists Choose [Selected text](/nock/selected-text) when the source text is already in a supported editable field. Select a paragraph, use Agent Mode, and ask for a specific change such as “Make this paragraph shorter while keeping the dates.” Check the replacement in the original app. If it is wrong, use that app's Undo. For a message draft, inspect whether Nock produced a draft card or performed an edit; neither should be confused with a confirmed send. ## Ask a question or investigate what you see Choose [Agent Mode](/nock/agent-mode) for explanation or a task. Hold the configured agent shortcut, ask the question, and release. If the subject is a particular screen element, use [Pointing](/nock/pointing) and describe what you need to understand. Look for a response or result card, and answer any pending approval deliberately. If screen access is unavailable, provide the relevant text yourself. A voice acknowledgment is not proof that an external action completed. ## Change a code project Use [Coding agents](/nock/coding-agents) for a bounded project task. Name the project, describe the desired change, and specify checks, for example: “In this project, investigate why the settings test fails, propose a focused fix, and run that test.” Expect a task surface with progress, questions, and a result. Inspect the actual diff and test output before accepting the work. Use the task's stop control to interrupt work; starting a new conversation does not automatically stop a running worker. ## Make a small interactive tool Use [Widget builder](/nock/widget-builder) for a compact utility such as a timer or calculator. Describe the controls and expected behavior, inspect the preview, test it, and keep it when satisfied. A preview with sample data is not evidence of a live service connection. For a richer saved preview, explore [Studio](/nock/studio). Verify data sources and connection access separately from the appearance of the generated interface. ## Arrange information visually Use [Glass Canvas](/nock/glass-canvas) for a board containing notes, links, drawings, and other supported items. Make a board, add a small set of content, then use [Canvas workflows](/nock/canvas-workflows) to organize or export it. Inspect exported content before sharing; it may include private material or remote embeds. Choose a saved copy before a large revision when you need to preserve the earlier board. If an expected step is unavailable, check [Account](/nock/account), [Availability](/nock/availability), and the workflow's troubleshooting guide before switching modes at random. # Welcome and guided setup Nock's welcome introduces the notch, asks your name, and walks through a few real interactions. The tour uses your configured shortcuts, so the keys on its cards are the ones to follow. ## Work through the setup 1. Start the introduction and enter the name you want Nock to use. 2. Review the macOS permission prompts. Microphone and keyboard access support voice input; screen access supports the visual examples. 3. If Fn opens emoji or Apple's dictation, use the tour's Keyboard settings button and set **Press 🌐 key to → Do Nothing**. 4. Try dictation in the practice field, then ask the agent a question. 5. Try the weather and circle-it examples. Review the capabilities cards to see the other workflows. 6. Sign in when prompted, then follow the plan and access choices shown for your account. Some steps are omitted when they do not apply. An account that already has access does not need the same unlock flow as a new account. ## Demo allowance and recovery The demo uses a limited allowance. When it ends, Nock shows **Sign in to continue**. Signing in and choosing access are separate steps; the current offer and checkout explain the terms that apply to you. A failed agent example can retry once. If it still cannot complete, use the recovery or skip action on the card. Check your microphone and permissions before repeating the same attempt. The tour is practice, so start with a brief request and a small, clear screen region. ## Replay or leave Open **Settings → About** and choose **Replay tour** to repeat the guided steps, or **Replay intro** for the introduction and tour. Replaying does not reset your chats or preferences. Escape or the close button ends the tour; leaving early does not bypass account or plan requirements. ## If a practice step does not complete Identify which part failed. No response to the keys calls for checking the shown shortcut and keyboard permissions. A recording with no transcript calls for checking the microphone. A visible transcript followed by an unavailable-service message is an agent or account problem, rather than a reason to change keyboard bindings. For the circle example, capture one clear item and make a short request. If a capture is blank, check Screen Recording before repeatedly circling the same area. Use the card's recovery action when offered. Moving to the next step does not establish that the skipped feature is working; return to it after setup using the focused troubleshooting guide. The account and plan cards reflect the offer available to your build and account. Read the trial terms and checkout before accepting them. A replay is for practicing the interface and does not replenish a spent demo allowance. See [quickstart](/nock/quickstart), [permissions](/nock/permissions), and [keyboard shortcuts](/nock/keyboard-shortcuts). # Sign in Nock uses your V3Code account. Sign-in begins in the desktop app and completes through your browser. **Launch preview:** the public Nock account handoff is still being prepared. Use the steps below when sign-in is enabled for your build. If the browser page is unavailable, check [Availability](/nock/availability) before retrying. ## Connect the app 1. Keep Nock open and choose **Sign in** inside the app. 2. Complete the sign-in options offered by the browser page. 3. If asked to continue to Nock, confirm that the displayed account is yours and that you just started this request from the app. 4. Choose **Continue to Nock** and return to the desktop app. 5. Check the app's account state and enabled features before starting a task. If you just signed in through the same browser flow, the handoff may continue without a second confirmation. If you opened the account page directly, it may show your account rather than connect a desktop app. ## If the handoff stops Keep Nock running while the browser completes the request. If nothing happens, return to Nock and start a fresh sign-in attempt. An old browser tab may belong to an earlier attempt. If you see **Too many attempts**, wait a minute before choosing Sign in again. Repeatedly refreshing the page can prolong the problem. If the service is unavailable, retry later and record the message for support. ## Account access after sign-in Successful sign-in identifies your account; it does not automatically activate every capability. Review your plan and unlocked features in [Account](/nock/account). For expired or exhausted access, see [Plans and trials](/nock/plans-trials) and [Usage and limits](/nock/usage-limits). # Dictation Hold **Fn / Globe**, speak, and release. Nock turns your recording into text and pastes the finished result into the app that has focus. ## Use dictation 1. Click inside the destination text field. 2. Hold your dictation shortcut and speak naturally. 3. Watch the live caption below the notch. 4. Release and allow a moment for recognition and insertion. 5. Review the words before sending or submitting them. Text is inserted after the recording finishes. Nock keeps listening briefly after release to capture the final word. **Escape** cancels without inserting text. To speak without holding a key, use [hands-free recording](/nock/hands-free). ## Recover a missing paste Nock uses the clipboard to insert text and normally restores what was there before. If it cannot confirm the paste or insertion fails, it can leave the transcript on your clipboard temporarily and show a notice. Click a real text field and press **Control + Command + V** to paste the latest transcript again. This is useful when focus changed during recording. A terminal receives a paste too: dictation does not decide whether the text is safe to execute, so review it before pressing Return. ## Recognition and cleanup Recognition may use a cloud speech provider. Audio sent for cloud recognition leaves your Mac. [Polishing](/nock/dictation-polish) and [replacements](/nock/replacements) happen locally after recognition. Add unusual names to your [dictionary](/nock/dictionary) to improve supported recognizers' spelling. ## A reliable daily workflow Keep focus in the destination field until insertion finishes. Switching to another window immediately after release can send the paste somewhere unintended. For longer text, dictate a paragraph at a time and check names, dates, and punctuation between paragraphs. The maximum recording length is a ceiling, not a requirement to make one long recording. If you prefer reviewing text before it becomes an agent request, use the [composer mic button](/nock/dictation-button). If you need to recover a recording, do that before making another: [Paste Last Transcript](/nock/paste-last) keeps only the latest recognized recording, including agent requests. ## Limits and troubleshooting The desktop recording ceiling is 20 minutes, with a warning before the limit. At that ceiling the app finishes the recording and attempts insertion. This is not a guarantee that a speech service accepts one recording of that length: hosted recognition has separate duration and request-size limits and can end or reject a recording earlier. Prefer short recordings, especially when testing. Your account must have access to dictation. No caption: check [microphone input](/nock/microphone). Caption but no insertion: check Accessibility in [permissions](/nock/permissions) and confirm the destination field has focus. Fn doing something else: review [keyboard shortcuts](/nock/keyboard-shortcuts). # Hands-free recording Hands-free keeps a recording active after you release the shortcut. You still choose when to start and finish; it is not an always-listening wake-word mode. ## Start a recording - **Double-tap Fn** for hands-free dictation. - **Double-tap Control + Option** for a hands-free agent request. - **Fn + Space** starts hands-free dictation when idle. During a held recording, it can keep that recording active so you can release the keys. These are the macOS defaults. The double-tap switches and hands-free shortcut are in **Settings → General**. A double tap needs to be quick: the current recognition window is about half a second. ## Finish or cancel Press your dictation shortcut, agent shortcut, or hands-free shortcut again to finish. A dictation is inserted; an agent recording becomes a request. Press **Escape** to discard it. Return does not finish a hands-free recording. Watch the recording state before moving on. Releasing your hands does not stop capture while hands-free is active, so nearby speech may become part of the recording. ## Recording limits The desktop dictation ceiling is 20 minutes, then it finishes and attempts insertion. Hosted speech services have separate duration and request-size limits and may stop or reject a recording earlier; the desktop ceiling does not guarantee a 20-minute cloud session. An agent recording can run up to 5 minutes; reaching that limit discards the request instead of submitting it. Both desktop ceilings have a warning before the limit. Cloud recognition sends audio while the recording is active. Use short recordings when trying a new microphone or shortcut. ## If taps feel delayed With double-tap enabled, Nock waits briefly to distinguish one tap from two. Disable the relevant double-tap option if you prefer single-tap behavior. For key conflicts, see [keyboard shortcuts](/nock/keyboard-shortcuts); for missing speech, see [microphone input](/nock/microphone). ## Practice the stop action first Before a long recording, start hands-free, say one sentence, and finish it using the same configured trigger. Confirm the recording state goes away and that the result is inserted or submitted as expected. Repeat once with Escape so cancellation is familiar too. Do not rely on switching apps, releasing modifier keys, or pressing Return to finish. Hands-free intentionally survives key release. If you are unsure whether it remains active, check Nock's recording state before continuing a nearby conversation. When modifier-and-character combinations fail in a password or secure-input context, test again in an ordinary note. macOS can hide ordinary keys from other apps in those contexts. Change your focus rather than weakening system security to make a shortcut work. # Dictate into Nock's composer The mic button in Nock's own text boxes turns speech into an editable draft. It is useful when you want to review a request before sending it, or when holding a global shortcut is inconvenient. This is distinct from holding the agent shortcut, which submits a request after release. ## Where to find it Look beside the send button in Nock's chat composer. The same composer appears in supported agent threads. The widget builder also has a mic button in its request and change fields; it can be disabled while a build is working. If it is missing, open **Settings → Dictation** and enable **Show mic button in Nock's composers**. This switch controls the button across those Nock surfaces. It does not add microphone buttons to other applications; use [ordinary dictation](/nock/dictation) there. ## Draft a message 1. Click where the new text belongs. Select existing words if you want the recording to replace them. 2. Press the mic button and speak. 3. Watch the transcript arrive in the text box. 4. Press the mic again to finish. Allow the brief recording tail and final recognition to complete. 5. Read and edit the result, then press Send or Return when ready. The finished draft applies your dictation polish and replacement settings. Recognition can revise the live words when the final transcript arrives, so wait for recording to finish before correcting the text. Nock inserts spacing around the recording so it can fit into an existing sentence. ## Cancel or switch input Press **Escape** during the mic session to restore the box to its previous contents. The notch stays open. A session stopped immediately after starting can also count as a cancelled tap. Only one speech session runs at a time. **Already listening** means another recording is active. Pressing a global dictation or agent shortcut during a composer recording cancels the composer recording and starts the held mode instead. Finish or cancel one mode before intentionally switching to another. ## Access and limits The button uses the same recognition and dictation access as Fn. It is not an alternative way around a plan or permission requirement. The desktop recording ceiling is 20 minutes; reaching it finishes the draft without sending it. Hosted speech services impose separate duration and request-size limits and can stop or reject a request earlier, so use shorter recordings. The completed text also becomes the [last transcript](/nock/paste-last). Cloud recognition sends audio while the button is recording. The draft does not become an agent request until you send it, but transcription itself can already involve a cloud provider. ## Read the button's message An amber crossed-out mic indicates microphone access is missing; clicking it opens the relevant system settings. **Speech is still starting** or **Transcription is not connected yet** means the listening service is not ready. Wait briefly, then use [voice troubleshooting](/nock/voice-troubleshooting) if the condition persists. A missing button is a display preference; an unavailable recognizer is a separate issue. # Polish dictated text Open **Settings → Dictation** to choose **Off** or **Light** polishing. This cleanup uses local text rules and does not make an additional AI request. It changes dictated text; requests to the agent are sent as recognized. ## Choose a style **Off** keeps the recognizer's wording. Use it when you want to inspect recognition directly or preserve deliberate repetition. **Light** is the default. It removes common hesitation words, reduces accidental repeated words, tidies spacing around punctuation, and corrects a standalone lowercase “i” in ordinary English prose. It preserves some intentional doubles such as “had had” and “very very.” The English word rules apply when English is the default language. Spacing cleanup can apply in other languages. Light is not a grammar editor and does not understand every spoken correction: “Thursday, no wait, Friday” is not guaranteed to become “Friday.” ## Test a change 1. Open a scratch note and dictate a short sentence with the current setting. 2. Switch the polish style. 3. Dictate a similar sentence and compare the inserted text. 4. Keep the setting that best matches your normal writing. Polishing runs before your [replacements](/nock/replacements). The final result is also the text kept for paste-last-transcript, so re-pasting does not restore the unpolished version. ## When a word is wrong If a name is misheard, add it to [Your words](/nock/dictionary). If a phrase should always expand into fixed text, use a replacement. Turn polishing off temporarily to determine whether a problem comes from recognition or cleanup. For rewritten meaning, tone, or structure, select the text and make an explicit [agent request](/nock/selected-text). ## Choose cleanup for the task For informal notes, Light can remove hesitation without a separate rewrite. For a quotation, command, identifier, or deliberately repeated phrase, Off makes the recognizer's output easier to inspect. Recognition itself can still introduce punctuation or mishear a word, so Off is not a guarantee of a verbatim transcript. When testing a replacement, turn off unnecessary rules and try its trigger by itself first. Then put the same trigger inside a sentence. This helps distinguish local cleanup from the recognizer failing to hear the words. Keep an example of the actual recognized text when reporting a rule that changes something incorrectly. # Your words Use **Settings → Dictation → Your words** for names and specialist terms that Nock often mishears. These entries are recognition hints, not mandatory substitutions. ## Add useful terms 1. Open **Settings → Dictation**. 2. Add the correctly spelled name or phrase under **Your words**. 3. Start a new dictation and use that term in a normal sentence. 4. Review the result in the destination app. Start with a few words that matter in your daily work: a project name, a colleague's surname, or an abbreviation. Avoid adding whole documents; the list is intended for short terms. ## What the dictionary changes Supported cloud recognizers receive these terms as hints alongside the selected language. Recognition still depends on the audio and surrounding sentence, so a hint cannot guarantee a particular spelling. Apple's speech fallback does not use this word list in the current implementation. Nock includes its own name in the hints. The combined list is limited to 100 terms, each up to 50 characters. Keep entries concise and remove obsolete terms if you reach the limit. ## Privacy and troubleshooting Your saved list is local, but hints are sent to the cloud recognizer when that recognition path is used. Do not add confidential text merely as a spelling test. If a term is still wrong, check the default language and [microphone input](/nock/microphone), then test a short sentence. If you need an exact phrase every time, a [replacement](/nock/replacements) is the better tool. For cleanup after recognition, see [dictation polish](/nock/dictation-polish). ## Dictionary or replacement? Use a dictionary hint when the output should depend on what you actually said. For example, adding a surname helps the recognizer prefer that spelling while still producing the rest of the sentence normally. Use a replacement when a special phrase should always expand into a fixed block, such as “my standard signoff.” The dictionary does not expand snippets, and a replacement cannot fix a trigger the recognizer never heard. If you need both, first test that the trigger is recognized, then add its expansion. After changing Primary language, retest the terms you rely on. The same saved hint can have different results with another recognizer or language; keep important names under review in the final text. # Spoken text replacements In **Settings → Dictation**, a **When I say … / Type …** rule replaces a recognized phrase with text you choose. It is useful for repeated signatures, links, and snippets. ## Create and test a rule 1. Add a distinctive phrase, such as “my meeting signoff.” 2. Enter the exact text it should insert. 3. Dictate the phrase into a scratch note. 4. Check punctuation and spacing before using it in a message. Choose phrases you would rarely say accidentally. A short, common word could trigger the replacement in otherwise ordinary dictation. ## Matching behavior Matching ignores capitalization and looks for whole words. A comma introduced between the words can still match. Longer phrases are considered first, and a replacement's output is not fed back through the rules again. If your whole dictation is just the trigger phrase, with or without a final period, the inserted result is the replacement text. If the phrase appears inside a sentence, review how the surrounding punctuation reads. Polishing happens first, then replacements. Rules run locally and affect dictation only; they do not rewrite questions spoken to the agent. ## Limits and fixes The current implementation supports up to 200 rules. A trigger can contain up to 80 characters and its replacement up to 4,000 characters. If a rule does not fire, first check the recognized caption: the trigger must be heard correctly. Add unusual terms to [Your words](/nock/dictionary), or choose a less ambiguous phrase. If the wrong rule fires, review overlapping triggers and remove the broader one. See [dictation](/nock/dictation) and [polish settings](/nock/dictation-polish). ## Build a small set you can trust Start with one or two distinctive triggers rather than a large list of ordinary words. For each rule, test the phrase alone and within a longer sentence, then check its behavior with punctuation. A signature that works at the end of a message may read awkwardly when expanded in the middle of a paragraph. Treat replacement text as something you could paste into the wrong app accidentally. Avoid using a casually spoken trigger for a password or other secret. Review the result before sending, especially when an expansion contains a link or contact details that might become outdated. If a rule becomes confusing, remove or revise that rule rather than resetting all dictation preferences. The last-transcript command retains the already-expanded result, so re-pasting will not recover the original trigger phrase. # Languages and recognition The **Languages** control in **Settings → General** lets you keep a list of languages and choose a **Primary** language. In the current candidate, Primary is the language sent to supported cloud recognition for each recording. Selecting several languages does not make Nock automatically alternate between them. ## Set a primary language 1. Open **Settings → General → Languages**. 2. Search for a language by its name, native name, or language code. 3. Select it in the list. 4. Mark that language **Primary**. 5. Close the picker and test a short sentence in a scratch document. At least one language remains selected. If you remove the primary language, another selected language takes its place. Check the Primary label after reorganizing the list; the presence of a checkmark alone does not mean the recognizer is using that language. The next recording uses the changed setting without restarting Nock. This applies to both dictation and spoken requests to the agent. It controls recognition of your speech, rather than guaranteeing the language in which an agent will answer. For a reply in a particular language, include that request explicitly. ## A practical multilingual workflow Suppose you dictate English work notes and Spanish personal messages. Keep both in the picker, but change Primary before switching tasks. Record one short sentence and inspect it before dictating a long message. If the recognizer keeps replacing a familiar word with an unrelated English word, first check Primary rather than adding many dictionary entries. Mixed-language sentences depend on the speech provider's support. These docs do not promise automatic language detection or equal accuracy for every listed language. Language choices in the interface and capabilities of the active recognition provider are different things. ## Dictionary and polishing [Your words](/nock/dictionary) supplies short recognition hints to supported cloud providers. Use the correct spelling for names and specialist terms; hints do not force a transcription. [Light polishing](/nock/dictation-polish) applies English filler-word and repeat rules when English is primary. With other languages it performs spacing cleanup, rather than applying English word rules to foreign-language text. [Replacements](/nock/replacements) are useful for exact phrases after recognition. ## Local recognition and privacy The current macOS speech fallback is configured for US English and does not consume the custom-word list. Selecting another Primary language does not establish support for that language in the fallback. Cloud recognition sends the chosen language and supported vocabulary hints with audio to the speech service. Apple recognition prefers on-device processing when supported, but can use Apple's speech service otherwise. A fallback label should not be read as a promise that all recordings stay offline. ## When results are wrong Confirm Primary, check the [microphone](/nock/microphone), and test without polishing or replacements. If a short clean sentence fails repeatedly, record the language, input device, recognition status, and a non-sensitive example for support. Do not include private recordings or account keys. See [dictation troubleshooting](/nock/dictation-troubleshooting) for separating recognition from insertion failures. # Recover the last transcript Use **Paste Last Transcript** when Nock heard you but the text landed in the wrong app, no text field had focus, or you want to reuse the words. The macOS default is **left Control + left Command + V**. ## Recover words before recording again 1. Stop and inspect where the first paste went. 2. Click the intended destination field so its text cursor is visible. 3. Press Control + Command + V, then release every key. 4. Wait for the paste and review the result. Nock waits for the shortcut keys to be released so they do not interfere with the simulated paste. Keep focus in the destination until the text appears. If the first paste reached another editable field, undo or remove that copy in the original app after you have secured the desired text. Avoid starting another recording before recovery: this command retains only the most recent transcript. A new spoken agent request can replace it too, even though the Settings description refers to your most recent dictation. ## What text is retained For dictation, the retained text is the finished version after polishing and replacements. For an agent recording, it is the recognized request. A completed composer-mic recording can also become the last transcript. The command does not retrieve an earlier sentence, reverse polishing, or search your chat history. An empty finished recording can replace the retained text with nothing. The in-memory transcript is also lost when Nock quits, so this shortcut is a prompt recovery tool rather than a transcript archive. ## Clipboard recovery is different If Nock shows **Couldn't type it here — it's on your clipboard**, you can click the target field and press ordinary **Command + V**. The recovery clipboard is held temporarily, currently for about a minute, before the previous clipboard is restored if you have not copied something else. By contrast, Control + Command + V asks Nock to paste its remembered transcript. That can help even after the normal clipboard was restored. Both approaches require an editable destination and working text-insertion access. ## Change the shortcut Open **Settings → General → Paste Last Transcript** and choose **Change**. Record a combination accepted by the shortcut editor. It allows modifiers with at most one ordinary action key, and refuses reserved or unsafe combinations. Use [keyboard shortcuts](/nock/keyboard-shortcuts) for the broader rules. ## Nothing appears Finish any recording first; paste-last is ignored while listening. Use the left-side modifiers for the default binding. Check that a recording has completed since Nock started, then verify the destination field and Accessibility permission. If the retained words exist but insertion still fails, follow [dictation troubleshooting](/nock/dictation-troubleshooting). Do not repeat recordings indefinitely when the underlying problem is focus or permission. # Work with selected text Highlight text before holding the agent shortcut to give Nock a specific passage to work with. You can ask for an explanation, a summary, a translation, or a rewrite. ## Use a selection 1. Highlight the relevant text in another app. 2. Hold **Control + Option** and describe the result you want. 3. Check the selection chip under the notch. Use its close button if you do not want that text included. 4. Release and review the response. Selection capture belongs to spoken agent requests. Typing in the chat box does not automatically read the other app's selection. ## Replace text in place For an edit, enable **Settings → Agent → Actions → Edit selected text** and ask for the change explicitly. The captured selection must be recent and inside an editable field. A selected webpage paragraph may be readable without being replaceable. After the edit, inspect the destination app before sending or saving. If focus or the selection changed, select the intended text again and retry. Password fields are excluded from editable targets. ## App compatibility Nock first uses macOS Accessibility to read the selection. Where supported, it can briefly copy selected text and restore the clipboard. It avoids the copy fallback in recognized terminal apps because Command + C could interrupt a running command there. Some apps do not expose a useful selection, so no selection chip may appear. You can paste the text into Nock's chat instead. ## Limits and privacy The current selection limit is 100,000 characters, and an inserted rewrite is limited to 50,000. Use a smaller passage when an oversized-selection message appears. Selected text and the source app's name can be sent to the model answering your request. See [agent mode](/nock/agent-mode), [permissions](/nock/permissions), and [pointing](/nock/pointing). ## Ask for an explanation before an edit “Explain this paragraph” should lead to an answer; “replace this paragraph with a shorter version” asks for a change. Say which you want. When working in an important document, begin with an explanation or suggested rewrite, then apply a reviewed change deliberately. Keep the original selection in place while the agent prepares an in-place edit. If you move to another field or the passage changes, select it again for a fresh request. A selection has a limited lifetime, so an old captured passage is not a dependable target for a later edit. If the result is wrong, use the destination application's Undo where available. Nock's chat response is not a replacement for checking the actual document. For passages too large to send, select a smaller coherent section and describe how it relates to the rest. # Ghost typing Ghost typing is a macOS **Beta** feature, off by default. It suggests the rest of a line near your cursor when you pause typing. Enable it in **Settings → Agent → Ghost typing** only after reviewing its data access. ## Try a suggestion 1. Enable the feature and ensure the required model connection is available to your account or build. 2. Open a simple editable field, such as a TextEdit document. 3. Type a few words at the end of a line and pause. 4. Press **Control + F** to accept a visible suggestion, or keep typing to ignore it. You can choose **Tab** as the accept key in Settings. When no suggestion is visible, the key keeps its ordinary behavior. Nock checks that the field and surrounding text still match before inserting a suggestion. ## What context is used The current implementation reads nearby text through macOS Accessibility and sends context to the completion provider. This can include text before and after the cursor, not just the last word. Ghost typing is not an entirely on-device feature. It skips password fields, secure-input contexts, and selected-text states, and excludes known password-manager and security windows. Those safeguards are not a reason to enable it in every sensitive workflow: turn it off when you do not want nearby text used for completions. ## Where suggestions may be absent The feature needs a readable field and a usable caret position. Not every app exposes those. The current candidate does not show suggestions in VS Code when it cannot locate the cursor. It also avoids mid-line completions when text remains after the cursor. If it works in TextEdit but not your other app, check app compatibility before reinstalling or changing credentials. If it works nowhere, check Accessibility permission, the toggle, and model/account availability. Own-key settings do not bypass account access requirements. See [Permissions](/nock/permissions), [Account](/nock/account), and [Privacy](/nock/privacy). # The notch The notch is Nock's compact home at the top of the primary display. It expands when you interact with it and shows recording, progress, responses, and controls without permanently covering a large part of the screen. ## Open and close Hover over the resting notch and click it to open Chat. A quick tap of the agent shortcut, **Control + Option** by default on Mac, also opens it. Holding that shortcut starts voice input instead. Use the close button or **Escape** to collapse it. Ordinary chat surfaces also close when you click outside. Settings and the widget builder stay open across outside clicks; close those explicitly. The header's stop control stops the current agent response or speech. A separate coding task has its own **Stop task** control. ## Pick a surface | Tab | Use it for | | -------- | ------------------------------------------------------------------------------- | | Chat | Read answers, type a message, and continue a conversation. | | Tasks | Check background work and requests that need your attention. | | Apps | Review connections and control enabled app access. | | Studio | Open saved previews and build widgets. | | Web | Open a page in Nock's separate browser. | | Settings | Adjust shortcuts, voice, appearance, permissions, and account-related controls. | Tabs may be hidden while a response is presented automatically. Collapse the notch and open it manually to return to the tab row. ## Understand the state **Listening** means input is being captured. **Thinking** or a tool progress line means Nock is processing a request. **Speaking** means a response is playing. A visible result is not proof that an external action succeeded: read the result card and any error before repeating the action. Plain dictation uses a caption while you speak; it does not need to reopen an old agent response. ## If you cannot find it Use the menu-bar item to open Settings. Check **General → Hide top notch**, and check the primary display rather than assuming it follows the pointer. The Chats and Agents side panels also belong to the primary display. Continue with [Chats](/nock/chats), [Background tasks](/nock/background-tasks), or [Appearance](/nock/appearance). # Chats and history The Chats panel lives on the left edge of the primary display. Hover at the middle of that edge or click its slim handle to open it. Your next question continues the current chat until you choose another or start a new one. ## Start or resume 1. Open the Chats panel. 2. Select **+** for a new conversation, or select an existing chat to continue it. 3. Read the conversation shown in the notch before sending a follow-up. You can also type “new chat” or “start over” by itself. Spoken commands can be interpreted as an ordinary agent request when accompanied by selected text or screen context; **+** is the reliable explicit control. A new conversation does not necessarily erase long-term information the agent has saved. It is a fresh conversation, not an account or memory reset. Use the lock control to keep the panel open while switching apps. Unlock it to restore outside-click dismissal. ## Find older work Search matches content in the chats currently loaded. Use **Show older chats** to load more before concluding that a conversation is missing. Long conversations may show only their most recent messages. Dictations and background worker results are not ordinary saved chat messages, so look for task output in the appropriate task surface. ## Retention and deletion In **Settings → Agent → Keep chats for**, choose the retention period that suits your work. The current candidate offers 30 days, 90 days, one year, or Forever, with 90 days as its default. To delete a specific chat, use its context menu and review the confirmation. Deleting removes that chat and its saved cards from Nock's history; it does not promise deletion from a separate coding agent, model provider, or durable memory store. Copy anything important to a document before deleting it. ## If history seems incomplete Check whether you are in the intended chat and whether older chats have been loaded. A resumed conversation may be reconstructed from recent exchanges when its original engine session is no longer available. Restate critical requirements rather than assuming every old detail is in context. See [Privacy](/nock/privacy) and [Background tasks](/nock/background-tasks). # Memory and context Nock can use several kinds of context. They help with continuity, but they are not interchangeable and none guarantees perfect recall. ## Three things to distinguish | Kind | Purpose | What a new chat does | | -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | | Current conversation | The exchanges used to answer your next question. | Starts a fresh conversation. | | Saved chat history | The conversations you can reopen from the Chats panel. | Leaves older saved chats available according to retention. | | Durable memory | Facts or preferences the agent saved and can retrieve later. | Does not automatically erase them. | Settings → Agent → **About you** supplies your name as another source of context. Review it separately from chats if you want to change how Nock addresses you. ## Continue a conversation Select the intended chat from the side panel before asking a follow-up. The main engine can resume a stored conversation when it is still available. Otherwise, recent exchanges may be used to reconstruct context rather than replaying the entire history. For an important task, restate the target, constraints, and desired outcome. “Do the same thing as last time” is less reliable than naming the project or artifact and explaining what should stay the same. ## Start fresh without losing work Use **+** in Chats or the new-chat command. This is useful when changing subjects, separating projects, or recovering from a confused conversation. It does not cancel every background worker; use the task's stop control for that. If you want automatic separation after inactivity, check **Settings → Agent → Start a new chat after**. The candidate offers Never and several idle durations. This is a conversation preference, not a retention or privacy control. ## Correct a remembered fact State the correction clearly and ask the agent to forget the specific old fact when appropriate. Check its response and behavior. Do not treat a verbal acknowledgment as a universal deletion receipt covering saved chats, coding-agent sessions, provider records, and backups. Use the appropriate history and retention controls for saved conversations. For a wider data-removal request, consult [Data and history](/nock/data-and-history) and [Support](/nock/support). Deleting application files or changing internal identifiers is not a supported substitute for understanding what each store contains. ## Limits and privacy Memory behavior depends on the active engine. A fallback may retain less context or lose it on restart. Background task summaries can also be shorter than their full results; open the task when exact details matter. Context retrieved for an answer becomes part of the model request. Locally stored history does not imply that none of its contents can be sent to a cloud model during use. Avoid storing secrets as conversational preferences. See [Chats](/nock/chats), [Agent personalization](/nock/agent-personalization), and [Privacy](/nock/privacy). # Talk to the agent Hold **left Control + left Option**, say what you want, then release. Nock sends the recognized request to the selected agent and presents the answer in the notch. Spoken replies depend on your voice settings and available access. ## Make a clear request Start with an action and enough context: “Summarize this paragraph in three bullets” or “Help me understand this error.” Highlight text or circle the relevant screen area when the request depends on something visible. A quick tap opens the chat box for typing. In that box, Return sends and Shift + Return adds a line. The mic button can dictate into the composer without sending immediately, which gives you a chance to review the words. ## During a voice request Beginning a new recording interrupts Nock's spoken reply. **Escape** cancels the recording. Releasing finishes recognition; silence does not become an empty request. If an approval card is waiting, a simple “yes” or “no” can answer it. Read the pending action before responding. For work that changes something, inspect the resulting card or output rather than assuming a spoken acknowledgement proves completion. ## Context and boundaries Selected text and screenshots can accompany a request. A plain hold without drawing does not automatically attach a drawing screenshot. Some actions can request screen context when you ask about the screen and the feature is permitted. Your words and attached context go to the agent and its model. Remote agents may support different context types; avoid assuming that every connected agent receives screen images. ## If it stalls Check whether the notch is waiting for approval, whether your account has access, and whether recognition produced the intended words. Try a short text question to separate speech problems from agent connectivity. An agent recording is limited to five minutes and is discarded at the limit. See [selected text](/nock/selected-text), [pointing](/nock/pointing), and [voice settings](/nock/voice-settings). ## Continue the right conversation Before referring to “that result” or “the previous file,” check the chat currently shown in the notch. Selecting another chat or agent can change the context that receives the next request. State the target again when switching between unrelated tasks. For a request that could change something outside the chat, name the intended destination and desired result. “Draft a reply I can review” and “send this reply” have different consequences. Review any approval card and the final result, particularly when using a connected app or a separate coding agent. If work continues in the background, a short spoken response may only acknowledge that it started. Open its task or result card to see whether it completed, needs input, or failed. Repeating an action before checking can create duplicate work. # Quick commands Nock recognizes some short, self-contained requests directly before asking the conversation model. This can make routine actions more immediate. Recognition still needs to hear the intended words, and desktop actions still depend on platform support and enabled action settings. ## Try a simple command On a supported Mac, hold the agent shortcut and say one command, such as “open Safari,” “pause the music,” or “volume 40.” Release without drawing and check the result. The direct route expects a short request without selected text, a drawing, or an attached screenshot. If context is attached, or the phrase is more complex, the request can go to the agent instead. That is not necessarily a failure: the agent may perform the same action through its tools. It does mean the request is no longer the same direct-command case. ## Open apps and sites Use an installed application's name: “open Calendar” is clearer than “open that thing.” The direct route also recognizes a limited set of common website names. When a name is ambiguous or unsupported, provide the address or explain the target to the agent. Requests that involve a file, folder, multiple steps, or an unclear pronoun are better expressed as a complete agent task. Check which application or website actually opened, especially if a requested browser was unavailable and a default browser was used. ## Playback and volume Try “pause the music,” “resume the music,” “next song,” or “previous track.” Playback requires an available supported player or system control. For volume, use a level such as “volume 40,” or a relative instruction such as “turn the volume down.” Bare words such as “stop,” “next,” or “resume” can mean other things in a conversation, so use a fuller phrase when you want media control. Quick actions obey the corresponding **Settings → Agent → Actions** switches. Turning an action off is not bypassed by using a short phrase. ## Navigate the notch “Show my tasks,” “open the studio,” “show my apps,” and “open the browser” can open those surfaces. Here, “the browser” means Nock's browser surface. To open a particular desktop browser, use its application name. In the current candidate, “open settings” and “show permissions” open the compact permission setup surface. To reach the complete Settings interface, use the notch's **Settings** tab or **Settings…** in the menu-bar menu. ## Start a new chat Type just “new chat” or “start over,” or say it without attaching screen context or a text selection. The main engine can interpret that as the new-chat command. **+** in the Chats panel is the most explicit alternative. Starting a new chat does not erase durable memory or cancel every background task. If a command does not behave as expected, inspect the recognized words and result before repeating it. Remove unintended context, make the request more precise, or use the relevant visible control. See [Desktop actions](/nock/actions), [Chats](/nock/chats), and [Agent mode](/nock/agent-mode). # Circle it and ask Use pointing when a spoken “this” needs a picture: an error dialog, a chart, or a part of an interface. Screen capture requires permission and sends the captured visual context to the model handling the request. ## Circle during a voice request 1. Hold **Control + Option**. 2. Move the pointer around the relevant item while speaking. 3. Look for the drawing trail or captured-region thumbnail. 4. Release to submit the request with its context. Movement draws while the agent keys are held; holding a mouse button continues a normal drag instead. A plain hold with little or no pointer movement does not attach a drawing screenshot. Keep gestures focused. A screenshot can include surrounding visible content, so close or move private material before capturing the area. ## Select a region from chat In Nock's own chat composer, choose **Point at something** when available. Drag a box around the item. The attached-context chip confirms a capture; remove it with its close button if you selected the wrong area. Escape cancels the selection. The region is used for the next request and expires after a few minutes. Capture it again if the screen changed or you waited before asking. ## Limits and recovery The current drawing path supports multiple displays and a limited number of captures per turn. Screenshots are resized, so small text on a large display may lose detail. Zoom the source content or select a smaller region if the answer misses it. No trail usually means the dictation shortcut was used instead of the agent shortcut. Blank captures usually call for checking Screen Recording in [permissions](/nock/permissions) and reopening Nock if macOS requests it. Selected remote agents may not accept images. For words already selectable in an app, [selected text](/nock/selected-text) often gives clearer context than a screenshot. ## Make the picture useful Pair the gesture with a precise question: “Explain the error inside this dialog” or “Compare these two buttons.” A large scribble over the entire display gives less guidance than a focused circle. With multiple captures, describe what each one represents instead of relying only on “this” and “that.” For code and exact error strings, attach or paste the text as well if possible. The screenshot supplies layout and visual context, while selectable text avoids recognition mistakes in punctuation and identifiers. If the interface changes after capture, attach a new image before asking about the new state. A captured image shows a past moment, not a live stream of everything on the desktop. Use [screen troubleshooting](/nock/screen-troubleshooting) to isolate missing attachments from images that are merely hard to read. # Desktop actions On supported macOS builds, **Settings → Agent → Actions** controls native desktop actions. These include editing selected text, drafting replies, creating prompts, reminders, music and volume, opening apps, and screen context. ## Enable only what you need Review the switches before your first action. **Draft replies** starts off in the current candidate; other actions have their own defaults. Turning off an action removes that capability from the intended agent tool path. It does not revoke an unrelated app's operating-system permissions. ## Know what the result means | Request | Expected result | | ------------------- | ------------------------------------------------------------------------------- | | Draft a reply | An editable draft/card and clipboard text, not an automatically sent message. | | Create a prompt | A staged prompt you can inspect and paste yourself. | | Edit selected text | Replacement in the selected editable field; review it in the destination app. | | Open an app or site | An attempt to open the named installed app or address. | | Control music | Playback or volume action against a supported running player or system control. | | Explain the screen | Screen context for the model when permission and feature access allow it. | For edits, use the destination app's Undo if the replacement is wrong. For a drafted message, review the recipient and text before you send it yourself. ## When an action fails Read the card's error. Confirm the app is installed, the intended field has focus, and the necessary permissions are granted. If screen context is unavailable, give a description rather than assuming Nock saw it. Repeating a request without checking the previous outcome can cause duplicate actions. Native execution happens on the computer, but your request, relevant selected text, or a requested screenshot can be sent to the model. See [Privacy](/nock/privacy). Continue with [Selected text](/nock/selected-text), [Pointing](/nock/pointing), and [Reminders](/nock/reminders). # Reminders On supported macOS builds, ask the agent for a reminder with a clear time and message: “Remind me in twenty minutes to check the draft.” Confirm the time on the result, especially for ambiguous requests such as “at five.” Nock reminders are separate from Apple Reminders. Their schedule is stored locally. Interpreting your voice request can still use a model service; local scheduling does not make the entire interaction offline. ## Manage a reminder Ask what reminders you have, move a named reminder to another time, or cancel it. Supported repeat patterns include daily, weekdays, and weekly. Times use the computer's current time zone, so check important reminders after travel or time-zone changes. When a reminder appears, dismiss it or ask to snooze it. Dismissing a repeating reminder does not cancel its future schedule. To stop future occurrences, explicitly cancel or pause it. ## If it is late Nock must be running to present reminders. It does not supply a separate system notification while the app is closed. When it starts again, it checks for missed reminders. A repeating schedule does not replay every missed occurrence as separate alerts. Presentation can also wait while you are recording or in an active agent turn. Use a dedicated alarm or calendar for safety-critical or time-critical alerts rather than treating Nock as a guaranteed alarm service. ## If creation is unavailable Check **Settings → Agent → Actions → Set reminders**. Turning it off blocks new reminders and edits; management operations such as listing or cancelling existing reminders can remain available. Read an error before retrying, and check the current reminder list to avoid duplicates. See [Desktop actions](/nock/actions) and [Voice input](/nock/agent-mode). # Web search Ask Nock to look something up when the answer depends on current public information. A useful request includes the subject, location, and time period: “Find the opening hours for this museum this Sunday, using its official website.” Those details reduce ambiguous results and make the answer easier to verify. Web search is a built-in lookup tool. It does not require connecting a personal search account. The surrounding agent conversation still depends on Nock account access and usage limits; a built-in search tool is not a separate promise of unlimited AI use. ## Ask for an answer you can check Name the kind of source you need, such as an official support page, a product manual, or the venue itself. Ask Nock to include the source and date when freshness matters. If a snippet is incomplete, ask it to open and read the result before drawing a conclusion. For comparisons, give the criteria: “Compare these two products for weight, battery life, and supported operating systems.” Check that each fact refers to the same product generation. Search can surface outdated pages alongside current ones. Search results appear as sources associated with the answer. Open the underlying page for exact wording, eligibility, pricing, or a decision that matters. A fluent summary can still misread a source or combine incompatible dates. ## Search and browsing are different Search returns titles, links, and short snippets. Reading a full result is another step. It does not use your usual browser's signed-in session and cannot retrieve private account content just because you are signed in elsewhere. Use [The browser](/nock/browser) when you want a visible page you can navigate. Use an available [App connection](/nock/app-connections) for supported account data. Weather has its own [forecast tool](/nock/weather), which provides structured location and forecast information. ## Understand freshness and failures The search implementation tries Nock's hosted service and can fall back to another public search service. It returns a bounded set of results, not every matching page. Repeated queries can use an in-memory result cache for up to 30 minutes. Repeating exactly the same request immediately may therefore produce the same sources. If results are empty, first check internet access. Try a more precise query with the organization or product name. If you already know the correct page, provide its address and ask Nock to read that page. An empty search is not evidence that the information does not exist. ## Know what is shared Search words go to the search service and its upstream sources. Visited pages receive normal web requests. Your question and retrieved information can become model context. Avoid putting private records, passwords, or access tokens into a public search query. For signed-in material, review [Privacy](/nock/privacy) before requesting a summary. # Weather and home location Ask “What's the weather?” for your saved home location, or name a place explicitly: “Will it rain in Portland, Oregon tomorrow afternoon?” Include the region when several towns share a name. Nock uses a forecast tool rather than relying on a general web-search snippet. ## Set what home means Open **Settings → Agent → Weather**. In **Home location**, type the town and choose the intended result. **Use my current location** estimates the place from your internet connection and saves it; it is not a GPS reading. Once a home location is saved, requests such as “here” and “home” refer to that place. This is useful when a VPN or your internet provider makes automatic detection choose the wrong town. When traveling, name the destination in the question or update the saved home location deliberately. If no home is saved, the app can estimate a location from your public IP address. That location is approximate and may be a nearby city or a VPN exit point. Check the place shown on the result before relying on the temperatures. ## Choose units Use **Units** in the Weather settings to select Celsius or Fahrenheit. The automatic option follows system temperature or region preferences where available. You can also request a unit explicitly for a particular answer. After changing units, ask a fresh weather question and check the displayed symbol. A screenshot or an old conversation card is historical output; it need not change just because your preference changed. ## Read the forecast Open the weather card's **Details** to inspect the forecast, hourly conditions, sunrise and sunset, and available alerts. Compare the hour with the forecast location's time. Hourly precipitation information describes an interval, not an exact minute when rain will begin. Forecasts come from MET Norway. US locations can also include National Weather Service alerts. An alert lookup failure must not be read as “there are no alerts,” and the US alert feed does not cover every country. Check the relevant local authority for safety-critical warnings. ## Fix an unexpected result For the wrong town, add the state or country and check Home location. For wrong units, inspect the setting and repeat the request explicitly. For unavailable weather, check the connection and retry after the service recovers. The forecast can use a previously fetched copy when a refresh fails; pay attention to any reported age. Place-name matching starts with a bundled list. Unknown places may require an online lookup. Forecast services receive the location coordinates, while automatic IP detection contacts a location service. Setting a home location avoids that automatic location lookup, but forecast requests still contact the weather services. See [Privacy](/nock/privacy). # Background tasks The notch's **Tasks** tab shows work delegated to background workers. This lets you ask another question without treating every piece of work as a new blocking conversation. Available concurrency and capabilities depend on your build and account; background work does not mean a cloud computer is available. ## Read the status - **Working:** the task is still running. Open it for activity rather than launching a duplicate. - **Needs your approval:** inspect and answer the pending request. - **Complete:** open the result and verify the requested outcome. - **Needs attention:** read the error or incomplete result before deciding whether to retry. Select an item for details and use **All tasks** to return to the list. A task that requires a connected service may remain blocked even though ordinary chat works. ## Stop deliberately Use the task's own stop control, especially for [coding work](/nock/coding-agents). Stopping speech, collapsing the notch, hiding a browser, or asking a different question is not equivalent to cancelling a worker. Cancellation cannot undo external actions already completed. If a task sent, created, or changed something, verify that state in the destination service before retrying. ## Keep work separate Give each task a clear target and result. For coding, avoid simultaneous edits to the same project files. For connected apps, check whether a previous attempt already completed before asking again. Local background workers require the relevant local runtime. Do not assume work will continue with the app quit or the computer asleep. Public cloud-agent availability is a separate launch gate described in [Availability](/nock/availability). See [The notch](/nock/notch), [Usage and limits](/nock/usage-limits), and [Coding permissions](/nock/coding-permissions). # Named agents A named agent gives a recurring kind of work a familiar place. You might create a research helper that gives short answers, or a writing partner that asks questions before revising a draft. Its description guides its behavior; it does not grant new permissions or connect services by itself. ## Create an agent Open the [Agents panel](/nock/agents-panel) at the right edge of the screen and choose **New agent**. Pick an orb color, then fill in the fields: - **Name:** a short name you will recognize in the panel. - **Character:** its role in one line. - **Personality:** the tone and working style you prefer. - **What it can do:** the kind of tasks you expect to give it. - **Instructions:** concrete rules, such as asking before changing a draft's meaning. Choose **Agent** or **Bot** under **Mode**. Bot emphasizes a persistent character, short turns, progress updates, and handing longer work to workers. It does not make the agent a hosted computer or enable scheduled routines. Choose a **Voice**, then **Save agent**. The automatic voice option assigns a consistent voice distinct from Nock's current voice. You can choose a specific available voice instead. Keep **Notifications** on if you want a completion or attention notice while another conversation is visible. ## Give it a first task Select its orb and confirm the notch shows its name before speaking. Start with a small task: “Summarize this paragraph in three bullets and preserve the numbers.” Check the answer against the text. Refine one instruction at a time if its style is wrong. For useful instructions, describe observable behavior: “Ask which audience I mean when it is unclear” is easier to check than “Always be perfect.” Put credentials into the designated connection controls, never into an agent's personality or instructions. ## Edit its character Open its orb and choose **Edit agent**. These fields become its `SOUL.md`, which accompanies its messages. **Open SOUL.md** opens the file for direct editing. Nock manages a marked portion of that file; additional text outside that portion is preserved on save. Keep additions concise and avoid conflicting rules. If saving says to finish or stop running turns, resolve active agent work first. Changing the character while work is running is deliberately restricted. Reopen the editor afterward and save again. ## Understand persistence Named agents use local workspaces and separate memory. They share the tools available to Nock under the current account, connections, and access settings. A request written in **What it can do** cannot bypass those limits. Local agents require the computer and runtime to remain available. **Remove agent** requires a second press. It disables the agent configuration rather than erasing its workspace. Do not interpret removal as deletion of all associated data. For conversation and data questions, see [Chats](/nock/chats) and [Privacy](/nock/privacy). # Agents panel The Agents panel is the narrow surface at the right edge of the primary display. It provides a place to select named agents and inspect supported coding tasks without mixing up their conversations. It complements the Chats panel on the opposite side. ## Open and keep it visible Hover over the thin resting line or click it. Use the lock control to keep the panel open while you work. If the resting line is missing, check **Settings → General → Hide side notch**. Also check the primary display; the panel does not follow every window to another monitor. Choose **New agent** to create a character. Existing agents appear as orbs with a name and status. Local agents and coding integrations occupy different groups. A cloud group appearing in an owner or development build does not establish public cloud availability; see [Availability](/nock/availability). ## Select the recipient before speaking Click an agent's orb. Its conversation opens on the notch and a chip identifies the selected agent. For agents that support voice, your next hold-to-talk request goes to that agent. The recipient is fixed when the hold begins, so switching orbs in the middle of a recording does not redirect that recording. When uncertain, release the shortcut, choose the intended agent, and start a new hold. To return to the main assistant, choose **Back to Nock**, dismiss the selection with Escape, or toggle the selected orb. Confirm the chip and displayed thread before issuing a consequential instruction. Some integrations show a task but do not accept voice as a named agent. Opening their card is not proof that a new spoken message will reach them. Use the card's available follow-up controls and read the recipient indicator. ## Read the state **Needs you** means the task requires attention. Open it and read the question or approval; sending the same task again usually creates confusion. **Listening**, **Thinking**, and **Working** describe activity. **New result** means a result is available to read, rather than proof that every requested check succeeded. Unread indicators distinguish an unanswered question, an error, and a new result. Open the item to learn what actually happened. A short status label cannot explain a partial result or a failed external action. ## Work with threads A named agent can show a list of conversations, with **New thread** and **Edit agent** controls. Start a new thread for a separate subject; reopen an existing one when its context still matters. A coding integration instead opens its live task card, which has its own progress and stop controls. When an agent asks a question, select an answer or use **Type your own answer**, then **Submit**. For an approval, inspect the requested operation before answering. Hiding the panel does not stop its work. See [Task approvals](/nock/task-approvals) and [Background tasks](/nock/background-tasks). # Agent access modes **Settings → Agent → Agent access** controls when Nock's agent waits for approval. The current choices are **Autopilot**, **Full**, and **Ask**. These are separate from [Coding agent permissions](/nock/coding-permissions), which govern supported external coding agents. ## Choose a mode | Nock mode | Behavior | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Autopilot | The default. Ordinary work proceeds automatically; classified consequential actions and other applicable checks can still request approval. | | Full | More restrictive than Autopilot despite its name. Broader risk checks apply to commands, writes, desktop actions, and unclassified tools. | | Ask | Reads, searches, and Nock's own supported tools can proceed; other actions generally require approval. | Nock's **Full** is not the external coding-agent **Full access** option. Choosing Full in Nock increases approval checks compared with Autopilot; the similarly named coding option grants broader access to that separate agent. ## Change it in Settings 1. Open Settings → Agent → Agent access. 2. Select the mode and read the description beneath it. 3. If changing to a less restrictive mode, review the native confirmation dialog and choose Allow only if intended. 4. Check that the selected state changed before starting new work. A Settings choice persists until changed. If the interface reports that it could not change the mode, retain the current assumption and retry deliberately; do not assume a failed control changed policy. ## Temporary voice changes Saying **“yolo”** as the whole request enables Autopilot for the day, returning to the previous mode at local midnight. If Autopilot was already permanent, it remains permanent. Saying **“ask me first”** switches to Full. These phrases must be the whole request. “Ask me first about this email” is an ordinary task instruction, not the mode-switch command. Check the spoken response and Settings if the result is unclear. ## Running work and waiting approvals A mode change does not cancel an action or request already running. Existing work keeps the rules under which it started. The engine applies updated rules between requests; background workers can delay a full reload. During that interval a stricter policy can refuse new actions until the transition finishes. Switching to Autopilot can immediately release waiting approvals for actions that Autopilot would allow automatically. Review pending work before making that change. Use a task's stop control if your intention is to stop work rather than change future approvals. ## Checks that remain The policy includes checks for recognized sends, deletes, commands with consequential effects, unrequested computer use, and app actions configured to ask first. Additional context and tool rules can also block or ask. These checks depend on the tool path and classification; they are not a guarantee that every possible risky action is detected. Actions disabled in Settings and apps with Agent access off remain restricted. A broader mode does not grant a missing operating-system permission, provider authorization, or unavailable account capability. For each approval, read the actual action and scope. Inspect the result afterward, particularly for external writes. See [App access controls](/nock/app-access-controls) and [Privacy and data](/nock/privacy). # Task approvals An approval is a pause before an operation proceeds. Read what the action will change, which account or destination it targets, and why Nock is asking. A task can remain active while waiting for this decision. ## Review one action The approval queue lists pending operations with **Accept** and **Reject** controls. Selecting the explanatory text can provide more detail. With multiple operations, **Accept all** and **Reject all** apply to the queue; use an individual row when you want to authorize only one. For a connected-app action that exposes editable fields, check the recipient, subject, body, or other destination information. Edit the fields before confirming. The app can show **Applying your edits…** while the agent prepares the revised action, followed by its execution state. Wait for the result and check the destination service for consequential changes. The presence of an approval UI does not mean a service is connected or available. A request can still fail after approval because of authentication, account access, provider restrictions, or an unavailable integration. ## Answer by voice While a request is pending, a plain “yes” or “no” can answer it. Without an “all” qualifier, the response applies to the oldest pending action. When several unrelated tasks are waiting, using the visible row is the clearest way to choose the intended one. “No, send it somewhere else” is a new instruction rather than a simple confirmation. If you want to change the task, decline the original operation and state the new target clearly. General praise is not reliable authorization; use the explicit controls for actions that matter. ## Decline, stop, or let it expire Declining refuses the operation and ends the associated request rather than inviting the agent to find another way around the decision. Stopping a request also cancels its pending actions. It cannot undo operations that already completed externally. Ordinary agent approval cards expire after ten minutes. An expired card displays **Expired — declined for you** and can no longer be accepted. Ask again if you still want the operation, after checking whether any earlier step already changed something. Coding integrations have their own question and permission lifecycle. Do not apply the ordinary card's ten-minute rule to every coding prompt; see [Coding task troubleshooting](/nock/coding-troubleshooting). ## Settings and widget actions Some changes use a native operating-system confirmation dialog, including selected permission changes and installing a local program as an integration. Read that dialog even if an earlier conversational card was already approved. Widget buttons that perform actions can also require confirmation. Review them as operations, not decorative interface controls. Changing access preferences does not make every operation available, and a named agent's instructions do not override account or tool restrictions. See [Permissions](/nock/permissions) and [Widget builder](/nock/widget-builder). # The browser Nock's **Web** tab opens a separate browser surface. It is not a view of your existing Safari or Chrome tabs. Sign-ins in your everyday browser do not automatically appear here. ## Open a page 1. Open the notch and choose **Web**. 2. Enter a secure website or a local development preview address. 3. Select **Open page**. 4. Choose **Mobile preview** or **Desktop preview** for the layout you want to inspect. Use **PiP** to float the page separately and **Dock** to bring it back. **Expand** gives a docked page more room. **Hide** changes visibility; it does not mean an ongoing browser task has stopped. ## Work with the agent Ask a specific question, such as “Read the headings on this page” or “Find the contact link.” The browser tools can read, click, type into supported fields, navigate, scroll, and take a page screenshot. If the page changes, the agent needs a fresh read before acting on its elements. Enter passwords yourself. The typing tool does not fill password fields. Check destinations and review important submissions rather than assuming a successful click completed the intended transaction. ## Restrictions The current browser accepts HTTPS sites and local development addresses. It blocks ordinary remote HTTP addresses. Downloads and site requests for camera, microphone, location, and notifications are disabled. A mobile preview is a browser layout simulation, not a physical-phone compatibility test. Cookies persist in Nock's browser profile. Glass Canvas web cards use that same profile. Page content and screenshots read by the agent may be sent to its model; avoid opening sensitive material you do not want included. ## A page will not open Check the address, network connection, certificate, and whether a local server is actually running. Try opening the address in your normal browser to distinguish a site problem from Nock's restrictions. Do not disable certificate checks as a workaround. See [Glass Canvas](/nock/glass-canvas) and [Privacy](/nock/privacy). # Studio and previews Open **Studio** in the notch to find work made for you. Its gallery includes saved previews, widgets, and builds still in progress. Select a tile to open it, or use the build control to begin something new. ## Start with a small preview Ask for one clear outcome, such as “Make a simple countdown card for Friday.” For connected data, first confirm that the required connection and execution access are available. Connecting an account alone does not establish that every tool can run in your build. A preview can use simple blocks such as a heading, list, chart, clock, or countdown, or an interactive widget. Keep the first request small enough that you can check its behavior yourself. ## Inspect before relying on it Open the preview and review **What it can do**, **Checks**, and any **Try it** actions. Distinguish: - **Sample data:** examples built into the preview, not current account information. - **Live data:** results from an available connected service. - **Failed checks:** evidence of a problem, not a successful empty result. Do not treat a visually complete card as proof of a working integration. Try a read-only action and compare it with the original service. ## Revise and find it again Use **Ask for changes** for a focused revision, such as “Use larger numbers.” Check the task state if the old version remains visible while a revision runs. You can change an icon without rebuilding the whole preview using its icon control. Settings → Apps → **My Apps** provides management controls, including removal for supported saved items. Keep any important result before removing it. Building and revising uses AI services. A live preview can also contact connected apps; its data boundaries are not the same as those of a static local image. Continue with [Widget builder](/nock/widget-builder), [App connections](/nock/app-connections), and [Background tasks](/nock/background-tasks). # Widget builder The **Beta** widget builder turns a description into a small tool that lives in Nock's notch and Studio. You can use that tool without switching to a separate full-screen app. Open the builder from Studio's build control or **Settings → Apps → My Apps → Make a widget**. ## Build one useful thing 1. Describe its purpose and the information it should show. Start with a simple, read-only tool. 2. Answer the builder's clarification questions, or choose to proceed with your original description. 3. Watch the build and checks. A finished layout does not guarantee every action works. 4. Try the draft using **Ask your widget…**. 5. Review any required settings or service credentials through the intended setup controls. 6. Request a focused change and test again. 7. Choose **Keep widget** when satisfied, or **Throw away** to discard the draft. Closing the builder while a build runs does not cancel it. Its Studio tile can show **Building**; reopen that tile to return to the same work rather than starting a duplicate. ## Approvals and trust Under **Advanced → Actions and approvals**, inspect the actions the widget exposes and their confirmation settings. Generated code runs locally and may install packages or contact the services it uses. Treat a widget as software, not as a harmless picture. Do not put credentials into the plain-language build request. Use the widget's designated configuration fields and connect only services you trust. Test changes with non-sensitive data first. Account access and service execution may be limited in launch-preview builds. ## Keep and maintain Kept widgets appear in Studio and in Settings → Apps → My Apps. Reopen a widget to edit it. Advanced controls can expose server output and restart or repair actions when a widget fails. Record the error before retrying repeatedly. The current app does not provide a general public widget-sharing marketplace. Do not assume another computer has your widget, connection, or credentials just because you kept it locally. See [MCP connections](/nock/mcp), [Studio](/nock/studio), and [Privacy](/nock/privacy). # Glass Canvas Glass Canvas is a **Beta** feature and starts turned off. Enable it in **Settings → Agent → Glass Canvas**. On Mac, its default shortcut is **Option + Command + G**; the Settings control also opens it. ## Make a board Open the canvas, then choose a tool: Select, Note, Writing, Pen, Paint, Shapes, Connect, Web card, or Screenshot. Hover over a tool for its shortcut. You can paste or drop images and double-click supported shapes to add labels. Use **Boards → New board** for a separate workspace. **Save a copy** gives you a second version before a large change. Boards save as you work; an exported page is a separate snapshot. ## Capture and connect The Screenshot tool lets you drag a region or capture a display. On Mac it needs Screen Recording permission. The canvas hides itself during capture so its own glass and controls do not become the picture. Web cards load supported secure sites or local previews. They share Nock's browser profile, including its sign-ins. A card can show a still image while you move around and become interactive when focused. ## Ask for a diagram Try “Make a three-step diagram of this workflow” or “Arrange these notes into two columns.” The agent can work with board text, positions, shapes, and connections. Check labels and arrows: a neatly arranged diagram can still contain an incorrect explanation. Removing items or clearing a board needs confirmation. Use Undo for an unwanted change and keep a separate copy before a substantial rearrangement. ## Export **Export** saves an HTML page in your **Documents/Nock Canvases** folder. Use **Open** or **Show in Finder** in the result to inspect it. Exporting the same board name again replaces that exported page, so rename or copy an earlier export if you need both versions. Embedded content that depends on a remote website still needs that website to be reachable. Board files stay local, but web cards contact their sites and board text shared with the agent becomes model context. Closing the canvas is different from turning the feature off in Settings. See [Permissions](/nock/permissions), [The browser](/nock/browser), and [Privacy](/nock/privacy). # Canvas workflows Use Glass Canvas when a task benefits from arranging information spatially. A board can hold notes, shapes, screenshots, and supported web cards. It is useful for comparing references or explaining a process without putting every detail into one chat message. First enable the Beta feature under **Settings → Agent → Glass Canvas**. Follow [Glass Canvas](/nock/glass-canvas) for its opening controls and platform shortcuts. ## Gather a small set of references Create a **New board** with a descriptive name. Add a note for the question you are trying to answer, then paste an image or use **Screenshot** to capture a relevant screen region. Check the clip for private information before asking the agent to interpret it. Add a **Web card** for a supported secure page when the source needs to remain accessible. Web cards share Nock's browser profile. A signed-in page can therefore contain private account information even though the board itself looks like a simple collection of cards. Keep each reference identifiable. A short label explaining what a screenshot shows is more useful than several nearly identical unlabeled images. ## Explain a process Ask for a bounded diagram: “Show these four steps from left to right and label the two possible outcomes.” Provide the actual facts rather than relying on the agent to invent the process. It can create shapes and connections, arrange items, and update labels. Review the words and arrow directions before judging the appearance. A clean diagram can still reverse a dependency or omit a condition. Ask for a precise correction such as “Connect approval to publication only on the yes branch.” Use selection and direct editing for small changes. Double-click supported shapes to change their labels. **Connect** adds relationships; layout requests can arrange a row, column, grid, or other supported pattern. Hover over tools to learn their shortcuts. ## Preserve a useful version Use **Boards → Save a copy** before a substantial rearrangement. Boards save while you work, so a separate copy is useful when you want to explore a different structure. Undo can recover an unwanted immediate edit, but it is not a substitute for keeping versions you need later. Removing items or clearing a board needs confirmation. Read whether the action targets selected items or the whole board. If a requested change produces the wrong layout, undo it and make the next instruction more specific. ## Export and check **Export** creates an HTML page in **Documents/Nock Canvases**. Open that file and inspect it before sharing. An export is a snapshot, and embedded web content may still depend on a reachable external site. Exporting the same board name again replaces that exported page, so keep a separately named copy when you need both versions. Board text read by the agent becomes model context. Screenshots and exports can also contain private information. Review the complete board before sharing it, including content outside the portion you were most recently viewing. # Coding agents Nock's built-in engineering engine is V3Code Terminal. It can work in a project without installing another coding agent. You can also hand a task to an agent you already use, including Claude Code, Codex, or Grok Bot when connected. Selecting a coding agent is different from choosing the model for Nock's voice conversation. ## Start with the built-in engine V3Code Terminal runs locally with Nock. It can index the project, search for relevant code, use language-server information where supported, edit files, and run commands and tests. For larger tasks it can coordinate workers; the Tasks board shows progress and questions while the notch remains available for another conversation. Give it a specific project and outcome, then inspect the files and test results it reports. [Background tasks](/nock/background-tasks) explains how to follow or stop work. ## Bring your own agent Install and sign in to a supported external agent through its setup process. Confirm its account and billing mode there; an eligible subscription may cover work, but limits and any saved API billing configuration still belong to that provider. Availability and exact controls vary by integration and build. Use a specific project folder. Save or commit work you need to preserve before requesting edits. Avoid two agents editing the same files at once. ## Give a bounded task Try “Have Codex review the tests in my project without changing files.” If you want a particular external agent, name it; otherwise Nock can use its built-in engine. Identify the folder and say whether you want investigation or implementation. Read the selected project path on the task before proceeding if more than one folder has a similar name. For an edit, define the outcome and verification: “Fix the failing parser test, run that test, and summarize the diff.” A request to explain a bug should not silently become a request to change the project. ## Follow the work The task card reports progress, questions, and results. For a connected agent, choose model and effort using the coding card's available options; changes apply to a subsequent task or follow-up. Available options come from the integration and can change. Use **Stop task** to stop coding work. Sending another voice message does not necessarily interrupt the running task. Follow-ups can queue behind it. If Nock quits, a task may be marked interrupted rather than resumed automatically. ## Review before keeping Check the file diff, tests, and any remaining failures. A “complete” task status describes the run, not a guarantee of correct code. Built-in and connected coding agents can send relevant project content to their configured model providers; the exact destination depends on your settings. ## Let an external agent drive If your build offers an external agent as the active conversation, choose it in the agent picker and check the name shown in the notch before speaking. That agent handles its own turns until you switch back. Do not assume that selecting an agent grants it new permissions or makes it the default for every future task. If your build only offers task handoff, use the bounded task flow above; voice control for that integration is not available there. See [Coding permissions](/nock/coding-permissions) and [Background tasks](/nock/background-tasks). # Coding permissions Open **Settings → Agent → Coding agent permissions** to choose how a supported coding agent handles work launched through Nock. The current candidate offers **Auto**, **Ask me**, and **Full access**. | Mode | What to expect | | ----------- | ---------------------------------------------------------------------------------------------------------------- | | Auto | The integration uses the coding agent's own reviewer and supported restrictions; escalated requests come to you. | | Ask me | A more interactive approval mode. Exact prompts depend on the coding agent and action. | | Full access | Removes major approval and sandbox protections. The agent can run commands and change files with broad access. | Start with a constrained mode and a specific project. Do not choose Full access simply to make a failing or blocked task continue. Read the requested action and its consequences first. ## When a change takes effect The setting applies to a coding run Nock next starts or resumes. It does not retroactively undo a command that already ran. Read-only work remains read-only in the intended integration path, but verify the task's scope and results rather than relying on a label alone. ## Questions are not permissions The separate **Answer for me after 2 minutes** control can answer eligible clarification questions. It is not a blanket approval for risky operations and does not answer permission prompts. If a task needs your authorization, review the card yourself. For a permission request, inspect the action, project, and scope of any persistent approval. **Allow once** and session-wide choices are not equivalent. Decline when the request exceeds the task you intended. ## Recover from a blocked task Read the prompt or error, decide whether the action belongs in scope, and answer explicitly. If it does not, stop the task and give a narrower request. After any unexpected modification, inspect the diff before starting another run; do not discard unrelated local changes. Continue with [Coding agents](/nock/coding-agents) and [Troubleshooting](/nock/troubleshooting). # App connections The Apps experience lets Nock discover supported services and manage connections for your account. A connection grants access according to the provider's authorization flow; it does not by itself confirm that every agent action is enabled. **Launch preview:** hosted app-tool execution is not publicly enabled yet. Catalog and connection workflows may be present before execution becomes available. Check the status and messages shown in your build. ## Connect a supported app When Apps is available: 1. Open the Apps catalog and find the service you want. 2. Open its details and review the available tool descriptions and setup guidance. 3. Start the connection and complete the provider's sign-in or authorization flow. 4. Return to Nock and check the connection status before asking it to use that service. Use the correct provider account, especially when you have both personal and work accounts. Some services need additional setup or an organization administrator's approval. ## Connection status and action access A connection can be pending, inactive, or connected. If the sign-in window closed early, reopen the connection flow and inspect the provider's confirmation. Even a connected account can have restricted permissions, unavailable tools, or plan-dependent access. If Nock says tool execution is unavailable, reconnecting repeatedly will not enable a feature that has not launched. ## Disconnect Use the connection's disconnect control when you no longer want it available to Nock. You can also review and revoke the integration from the provider's own account settings. Disconnecting does not undo actions already completed in the connected service. ## Before retrying an action If a network error interrupts a task, check the destination app first. A message or record might have been created even if Nock did not receive a clear result. Review the outcome before asking it to repeat a write. See [Privacy and data](/nock/privacy) and [Troubleshooting](/nock/troubleshooting). # Control app access The Apps tab distinguishes connecting a service from allowing the agent to use it. The per-app **Agent access** switch pauses use while keeping the connection available for later. **Launch preview:** hosted app-tool execution is not publicly enabled yet. These controls describe the desktop connection workflow; turning a switch on does not bypass account, provider, or release availability limits. ## Pause an app 1. Open **Settings → Apps** and locate the connected service in the App Store. 2. Open its details if you want to review its available tools first. 3. Turn **Agent access** off. 4. Confirm the row says **Connected · agent access off**, or the details explain that the connection is kept and the agent will not use the app. This is useful when you want to focus on one service, temporarily exclude a work account, or stop a connected app from participating in new tasks without signing out of it. ## When the change applies The access preference is checked before the next app action. If disabled, that action is refused and the agent is told the app is turned off in Apps. The setting also covers supported app-data access used by previews built in the notch. Do not treat the switch as an undo button. It cannot retract a message already sent, reverse a completed edit, or guarantee cancellation of an external request that has already started. Stop the current task when appropriate and inspect the destination service if an action may be in progress. ## Restore access Turn Agent access back on when you want to use the service again. The saved connection remains, so a fresh sign-in is normally unnecessary unless the provider expired or revoked it. Check the row's status and try a small read request before a write. App access is enabled by default for connected apps. Review it after connecting a new service rather than assuming every connection starts paused. ## Choose the right control Use **Agent access off** to pause Nock's use of a service while keeping its connection. Use **Disconnect** to remove the connection from Nock's connection list. Use the provider's security settings to review or revoke the authorization held by that integration. These controls are separate from operating-system permissions such as microphone or screen access. Disabling an email connection does not change screen permissions, and removing screen permissions does not disconnect email. For an app that says connected but fails, check Agent access first, then account availability and provider permissions. Avoid asking the agent to work around a disabled switch. See [Disconnect apps](/nock/disconnect-apps), [App connections](/nock/app-connections), and [Privacy and data](/nock/privacy). # Disconnect apps Disconnect a service when you no longer want its account connected to Nock. If you only want to pause the agent temporarily, use [Agent access](/nock/app-access-controls) instead; that keeps the connection for later. ## Before disconnecting Review any task currently using the service. If a request may already have reached the provider, disconnecting cannot reverse it. Check messages, records, or other affected data in the destination before retrying or starting a replacement task. Confirm which provider account is connected. A personal account and a company account can have similar names. If the connection details are unclear, verify them with the provider before removing access. ## Remove the connection 1. Open **Settings → Apps**. 2. Find the service marked Connected in the App Store. 3. Use its connected switch or open the detail sheet and choose the disconnect control. 4. Wait for the list to refresh and confirm that the service is no longer shown as connected. The desktop refreshes the agent's app session after connection changes, so the new state applies to subsequent requests. If the list does not update, reopen the Apps view and inspect the error rather than assuming the request succeeded. ## Provider-side authorization You can also review the provider's own connected-app or security settings. Revoking there is useful when the Nock interface is unavailable or you want to confirm which permissions the integration holds. Provider interfaces differ; follow that service's instructions. Disconnecting does not delete your provider account, erase messages created earlier, or reverse changes made by a tool. It is also separate from deleting a locally built preview in **My Apps**. A saved preview and a service connection are different objects. ## Reconnect later Find the service in Available and choose Connect. Complete authorization in the browser and return to Nock to confirm the status. The desktop checks the pending sign-in for a limited period; if it expires, begin a fresh connection instead of continuing to refresh an old authorization tab. Only one app sign-in runs at a time in the interface. Finish or leave the current flow before starting another. If the service requires a developer-app setup that is unavailable for your account, the setup message is an availability limit, not a password failure. ## If access still seems possible Check whether the action actually used the disconnected integration, a separate connected account, or a browser session. Disconnecting one route does not sign you out of unrelated apps or websites. Review the route used and pause the task before changing additional settings. Hosted app-tool execution remains unavailable publicly during launch preparation. See [Availability](/nock/availability) and [Support](/nock/support) if the shown state conflicts with a task result. # MCP connections MCP connects an agent to tools supplied by another service or local program. In Nock's current candidate, the widget builder also accepts a supported MCP server address or launch command instead of a widget description. ## Before connecting Get the server's setup instructions from its maintainer. Understand whether it runs on your computer or contacts a remote service, what credentials it requires, and what its tools can read or change. A local launch command can execute software; a remote URL can send information outside your computer. Do not paste a command you have not reviewed. Prefer an explicitly versioned, trusted package when the server supports it. Never include a private token in a screenshot or a support message. ## Connect and test 1. Open the [widget builder](/nock/widget-builder). 2. Enter the server's supported HTTPS address or local launch command. 3. Complete the connection's required configuration using the provided fields. 4. Review available actions and approval behavior. 5. Try a read-only request and verify the result in the original service. Authentication success and tool execution success are separate checks. If the build or account does not allow a required operation, connecting the server does not override that restriction. ## Manage carefully The current candidate has a management limitation: servers connected this way do not have the same complete list-and-remove interface as kept widgets. Do not assume the absence of a tile means a server is disconnected. If you cannot find a connection's management control, stop using it and ask support for guidance; revoke its service authorization through that provider if needed. Avoid deleting app configuration files to remove one connection. That can affect unrelated saved work or settings. See [App connections](/nock/app-connections) for the separate catalog flow and [Privacy](/nock/privacy) for data boundaries. # Models and providers Nock separates the model that talks with you from models that do background work. **Settings → Providers** brings model choices and available provider connections together. Availability depends on your build and account; a provider catalog is not a promise of included access or unrestricted use of your own keys. ## The three sections **Voice** covers speech services. Its connection states describe whether a service is configured or provided through your account. **Models** selects the Notch voice model and Worker model. **Providers** lists the model services known to the running terminal engine. The phrase **Notch voice model** means the language model conducting the conversation. It is separate from the voice used to speak its reply. Changing a model does not select a different speaking voice. ## Where the included model runs The current included DeepSeek route goes from Nock through V3Code's metered account relay to DeepSeek's API. DeepSeek is the model provider for that route; the relay does not make the model local or keep the request solely on V3Code infrastructure. The configured model and any alternative provider can change with your account and the choice shown in Settings. See [Privacy and data](/nock/privacy) for what context a request can contain. **Planned for paid launch:** V3Code intends to move its included DeepSeek model routes to providers running those models on US infrastructure when Nock starts selling. This is a plan, not the current routing. We will update the provider destination here after the change is implemented and verified. ## Change a model 1. Open Settings → Providers and locate Models. 2. Choose a **Notch voice model**, a **Worker model**, or both. 3. Select **Save**. The button becomes available when a choice changes. 4. Read the confirmation. **Switched. The next turn uses it.** means the running engine accepted the change. **Restart Nock to apply.** means the choice was saved but needs a restart. 5. Test with a small new request before starting a long task. **Terminal default** lets the engine choose its configured default. The other choices come from connected providers. Selecting a model does not grant access to it; provider credentials, account permissions, and service availability still apply. ## Connect a provider when available Search the Providers catalog. Available entries offer supported methods such as **Add key** or **Sign in**. Follow that provider's flow; some sign-ins open a browser and require an authorization code to be entered back in Nock before **Finish**. Connected entries show their source. A key entered in this interface can show **Remove**. Other entries may say **From env**, **From config**, or **Signed in**. These labels explain why a credential may not be editable through the same control. Only use key controls exposed for your access level. Your own provider key may incur charges under that provider's account and does not unlock Nock features that are unavailable for your plan. Never paste keys into chat or a support screenshot. ## When models disappear **The terminal engine is not connected.** means Models and Providers cannot query the engine. It does not necessarily mean every voice setting is broken. Finish starting the app, check for an engine error, and try again. Restart after saving current work if the engine remains unavailable. A connected provider with no usable model may need refreshed authentication or have a provider-side access restriction. Verify the account and the exact error before replacing credentials. See [Usage troubleshooting](/nock/usage-troubleshooting) and [Support](/nock/support). # Grok Bot integration Nock's Grok Bot integration sends a task to your external bot and displays its reports in the notch. It is off by default and requires a working external bot, connection setup, and report-back service. It is distinct from Nock's own named agents, a local coding CLI, and Nock cloud agents that are not publicly available during launch preparation. ## Set up the connection When the integration is available in your build, open **Settings → Agent → Grok Bot**: 1. Choose **Copy setup message** and open Grok Bot. 2. Paste the setup message into its chat. Review the requested setup-file access before approving it. The setup file contains connection information needed to report back; treat it as sensitive. 3. Follow the setup to create the **Nock tasks** routine. In the external bot's computer panel, open **Routines → Nock tasks** and locate its webhook details. 4. Copy the **POST to** address and **key** into Nock's corresponding fields. Keep the key out of chat, screenshots, and support reports. 5. Choose **Connect and test**. Read both the test result and the **Reports back** state. The test starts a real, small external run whose instruction is to report **Connected**. An accepted request alone does not prove the report-back path works. The test waits up to three minutes for the return report. The setup file is removed after a successful report, and **Remove setup file** is available separately. ## Send a task Name **Grok Bot** explicitly, for example: “Send this to Grok Bot: investigate these three public links and return a comparison.” This is an example request, not a claim that a test has run. Nock sends a task description rather than forwarding the whole conversation or automatically attaching project files. Include the goal and necessary context explicitly. The external bot uses its own environment and model selection. **Start tasks → Background** uses the configured routine. **Window** opens the external app and types the task; that path needs appropriate macOS automation access. If the intended app is not in front, Nock can leave the task on the clipboard instead. Inspect what actually started before retrying. ## Reports and errors Progress, questions, and the final result return through the connection. A long quiet period may mean the external bot is waiting for approval in its own app; check there. Nock cannot answer every external permission prompt. For a failed test, inspect **Last test**, **Reports back**, and relay status. A rejected key, missing routine, inactive routine, and unavailable report-back service are different problems. Recheck the saved routine and credentials without publishing them. If Copy setup message is disabled because reporting is unavailable, wait for the service rather than inventing a connector address. ## Stop and disconnect **Stop** stops following the run and requests cancellation through the report-back channel. It is not an immediate remote kill: the bot receives that request when it next reports. Quitting Nock can leave the external run active. Check the external app when you need to confirm work stopped. **Disconnect** removes Nock's saved webhook connection and remaining setup file. Review the external routine separately. See [Coding agents](/nock/coding-agents), [Named agents](/nock/named-agents), and [Privacy](/nock/privacy). # AIWebPad handoffs AIWebPad coordination lets Nock read an existing shared ticket and post a completed-step update when you ask. It is optional and off by default. It does not automatically forward every coding-agent message or continuously watch the ticket. ## Connect an existing ticket 1. Sign into Nock and open **Settings → Agent → AIWebPad**. 2. Enter the existing **Ticket ID** and **Access code** in their designated fields. 3. Choose **Save connection**. 4. Enable **Use AIWebPad**. 5. Ask “read my AIWebPad handoff” to check that the saved connection can access the ticket. Saving a connection and successfully reading a ticket are different checks. If a read fails, inspect the ticket's status and credentials instead of assuming the connection was verified when it was saved. The code uses system credential storage; saving can fail if that storage is unavailable. Do not paste the access code into an ordinary chat message, URL, screenshot, or handoff. Keep it in the connection fields or another appropriate credential channel used by the other participant. ## Set up another agent **Copy setup note** provides a note you can give another agent to explain the coordination workflow. Supply the ticket credentials separately. The note asks that agent to read current ticket messages, post short factual updates only when instructed, and treat received messages as unverified information. A copied setup note does not establish that the other agent connected correctly. Have it perform an authorized test read and compare the expected ticket before relying on the handoff for real work. ## Read and act deliberately Ask Nock to read the handoff when you need an update. Outside-agent content appears for review. A message on the ticket is not automatically your instruction to execute its requested actions. Read it, decide what you want, and ask Nock explicitly. For example, “Read the latest handoff and summarize what remains” is a review request. Follow with a separate instruction naming the work you want performed. This makes it clear which parts of an outside update you accepted. ## Share a completed step Ask “post this completed step to AIWebPad” and describe the concise update. Nock shows an approval card with the exact outgoing text. Check it for accuracy and unintended content before approving. Share a result, relevant limitation, and next step rather than full transcripts or private files. Everyone holding the ticket code can read and write. Sender names are unverified labels; they do not establish identity. This integration is not end-to-end encrypted messaging. ## Failures and disconnection Tickets can expire and reads are bounded to recent messages. A failed send may still have reached the service, so read the ticket before retrying to avoid duplicate updates. **Disconnect** removes Nock's saved connection and disables the integration; it does not retract text already posted or revoke credentials held by another participant. See [Task approvals](/nock/task-approvals), [Privacy](/nock/privacy), and [Coding agents](/nock/coding-agents). # Settings reference Open Settings from the notch's **Settings** tab or **Settings…** in the menu-bar menu. If you show Nock in the Dock, its Dock entry also opens the settings view. It remembers the last section you used. This reference describes controls present in the mapped launch candidate. Platform, account access, and release availability can affect what your build exposes; see [Nock overview](/nock/overview). ## Find a section | Section | Use it for | | ----------- | ------------------------------------------------------------------------------------ | | Home | See current shortcuts and available walkthroughs. | | General | Change voice keys, languages, startup, visibility, and audio behavior. | | Dictation | Set polishing, custom words, replacements, and composer mic visibility. | | Insights | Review locally recorded speaking and dictation statistics. | | Appearance | Set Auto, Light, or Dark and supported surface finishes. | | Agent | Choose voice and actions, conversation preferences, and supported agent features. | | Providers | Review supported model/provider connections. | | Usage | Review displayed account usage or locally counted activity. | | Apps | Review available connected-app and created-app surfaces. | | Permissions | Inspect macOS access needed for recording, shortcuts, insertion, and screen context. | | About | Check the app version, available update status, and replay the introduction or tour. | ## Changes take effect as you make them Most preference switches save immediately; there is no overall Save Settings step. A specific dialog, such as shortcut editing, can have its own confirmation button. Finish that dialog before testing its result. Change one setting at a time when diagnosing a problem. For example, if dictation starts but text does not land, changing the voice, theme, and language together will make it harder to isolate the cause. Use [dictation troubleshooting](/nock/dictation-troubleshooting) to choose the relevant control. ## Navigate with the keyboard The Settings section rail supports Up and Down arrows, with Home and End to move to its ends. Select the section rail first, then move among its tabs. Use Tab to continue into controls in the selected section. Individual dialogs may use their own keyboard behavior. If a shortcut editor is open, global voice shortcuts are temporarily paused to let you record the new combination. Finish or cancel the editor before expecting dictation to start. ## Preferences, permissions, and access are different A setting can express what you want Nock to do without granting macOS permission to do it. Likewise, enabling a feature does not create provider access or change your account entitlement. If a control appears enabled but the action fails, read the displayed message and check the relevant permission or access page. Prefer the interface to editing preference files by hand. Nock keeps preferences in memory while running; an external file edit may be overwritten by the next setting change. There is no need to delete your settings to troubleshoot a single control. For focused guides, see [General](/nock/general-settings), [Appearance](/nock/appearance), [Voice](/nock/voice-settings), and [Permissions](/nock/permissions). # General settings **Settings → General** contains the controls that affect everyday use across Nock. It is organized into Shortcuts, General, Visibility, and Audio & Speech. The labels below describe the current macOS interface. ## Shortcuts **Agent Mode** and **Dictation Mode** show your held voice triggers. Choose **Change** to add or edit accepted combinations. The two modes need distinct triggers; Nock refuses combinations that conflict with protected system shortcuts or the hands-free binding. **Hands-Free Dictation** offers the double-tap switch and a press-once shortcut. **Hands-Free Agent** controls double-tapping the agent trigger. Turn off double-tap if waiting to distinguish one tap from two feels inconvenient. This changes how a tap is interpreted rather than changing recognition speed. **Paste Last Transcript** changes the recovery shortcut. It is particularly useful if you dictate into several apps and occasionally switch focus too early. Read [keyboard shortcuts](/nock/keyboard-shortcuts), [hands-free](/nock/hands-free), and [paste-last recovery](/nock/paste-last) before choosing an unfamiliar combination. ## General **Languages** selects your available languages and marks one Primary for recognition. The current implementation uses Primary for each request; it does not automatically rotate through every checked language. See [languages](/nock/languages). **Launch at Login** controls whether Nock starts when you sign into the computer. **Show app in dock** controls the macOS Dock entry for easier access to Settings. These preferences are independent of whether you hide the resting notch. **Share usage data** controls optional product usage reporting, including feature use, setup progress, timing, and limited error labels. Setup events use a random installation identifier; signed-in usage events can be associated with your account. Do not treat every event as anonymous. The event fields are designed to exclude your spoken or typed content, clipboard contents, screenshots, files, and pages. Switching the preference off also stops setup-tip emails that depend on those events. This is distinct from the audio or context required to fulfill a cloud-backed request. See [Data and history](/nock/data-and-history). ## Visibility **Hide side notch when minimized** hides the resting side-edge indicator. **Hide top notch** hides the resting top surface and its hover effect. These do not quit the app. Use the menu-bar item or configured chat shortcut to reach Nock if you can no longer see its resting surface. Other platform builds can show taskbar or top-bar-face controls instead. Their presence in source does not establish that a download is available for that platform. ## Audio & Speech **Interaction sounds** controls dictation and notice sounds. **Intro music** controls the original score during the welcome. **Lower media volume while talking** reduces system output during recording and restores it afterward. These switches are separate from spoken agent replies in **Settings → Agent**. There is no active microphone selector here: choose the macOS input in System Settings. See [microphone](/nock/microphone) and [sound and media](/nock/sound-and-media). Test changed preferences with a short recording, and keep the previous shortcut noted until you are comfortable with the replacement. # Keyboard shortcuts Open **Settings → General** to see and change your shortcuts. The welcome tour and shortcut cards follow your saved choices. | Action | Default on macOS | | --------------------- | ------------------------------- | | Dictate | Hold Fn / Globe | | Ask the agent | Hold left Control + left Option | | Open the chat box | Tap Control + Option | | Hands-free dictation | Double-tap Fn, or Fn + Space | | Hands-free agent | Double-tap Control + Option | | Paste last transcript | Control + Command + V | | Cancel recording | Escape | ## Change a voice trigger 1. Choose **Change** beside Agent Mode or Dictation Mode. 2. Edit an existing trigger or choose **Add shortcut**. 3. Press the combination you want and save it. 4. Test it in a scratch document before relying on it elsewhere. Each mode supports up to five triggers. On macOS, voice triggers use modifier keys or supported mouse buttons; normal character keys are not accepted for these hold shortcuts. Left and right mouse clicks are excluded. Reserved system combinations and conflicting triggers are refused. Nock pauses its voice shortcuts while you record a replacement combination. Saving re-registers them without an app restart. ## Fn opens emoji Open **System Settings → Keyboard** and set **Press 🌐 key to → Do Nothing**. Nock's tour can take you there. This changes macOS's action for the key so it does not compete with dictation. ## A shortcut does nothing Check Accessibility and Input Monitoring in [permissions](/nock/permissions). Use the configured side of modifier keys; the default agent combination uses the left keys. Check for a competing app shortcut and try another combination. These defaults describe macOS. Other platform builds can have different controls; consult the availability guidance in [overview](/nock/overview). ## Avoid confusing taps with holds Fn needs a deliberate hold to start dictation; a very brief touch is ignored. A brief Control + Option tap opens the composer instead of submitting a spoken question. When double-tap is enabled, a small delay lets Nock distinguish one press from two. If you press Escape while still holding the voice keys, release them before trying again. Also finish or cancel any shortcut-editing dialog: its temporary suspension of global shortcuts is intentional. ## Secure input and recovery keys macOS can hide ordinary keys while a password field or another secure-input context is active. A modifier-only voice trigger and a combination containing Space or a letter may therefore behave differently. Move to a normal editable field to test hands-free and paste-last shortcuts. For a microphone problem after a shortcut has clearly started recording, use [voice troubleshooting](/nock/voice-troubleshooting) rather than continuing to change the binding. # Microphone and recognition On macOS, Nock's voice helper records from the system's current input device. The current Settings interface does not provide a separate microphone picker. ## Choose the input 1. Open **System Settings → Sound → Input**. 2. Select the microphone you want to use. 3. Speak and check the input level. 4. Return to Nock and try a short dictation in a scratch note. If a headset was connected or disconnected, check the system input again. Test the built-in microphone to determine whether a recognition problem follows the external device. ## Check permissions Microphone access is required. Nock's speech helper can appear as **Nock Speech** in macOS privacy settings. Apple's speech fallback also needs Speech Recognition permission. See [permissions](/nock/permissions) for the differences. ## Language and vocabulary Choose the default language in **Settings → General → Languages**. Supported cloud recognition uses that default; ticking several languages does not guarantee automatic switching between them. The current Apple fallback is configured for US English. Add short specialist terms under [Your words](/nock/dictionary). Better input audio and the correct language usually matter more than adding many hints. ## What happens to audio Nock records during an active hold or hands-free session, including a brief tail after release. Cloud recognition sends that audio to the speech service used by your configuration. The microphone is closed between recordings. A cloud recognition failure does not guarantee an automatic switch to local recognition in the same recording. Apple's fallback prefers on-device recognition where that capability is supported. It is not an unconditional offline guarantee: Apple's service may process speech when on-device recognition is unavailable. Check the recognition path before relying on a recording remaining entirely on the computer. ## Troubleshoot in order No system input level: fix the device or macOS input first. System level but no Nock caption: check Microphone permission and the configured shortcut. Caption with wrong words: check language and device quality. Correct caption but missing insertion: use the recovery steps in [dictation](/nock/dictation). ## Keep a simple comparison test Use the same short, non-sensitive sentence when comparing input devices. Check that the system input actually changed, then repeat the sentence once in Nock. Changing the microphone, language, polishing, and provider together makes the result difficult to interpret. If Nock's composer mic and global dictation both fail to recognize the same sentence, they share enough of the speech path that fixing the input or service is more useful than changing the destination app. If the composer recognizes correctly but another app receives no paste, focus and insertion permissions are the better next checks. For repeating **speech paused** or helper-retry messages, follow [voice troubleshooting](/nock/voice-troubleshooting). Keep typed chat available while diagnosing voice input instead of repeatedly issuing the same spoken task. # Nock's spoken voice Open **Settings → Agent → Agent voice** to control spoken responses. Voice output is separate from transcription: Nock can hear a request successfully while spoken replies are disabled or unavailable. ## Choose and preview a voice 1. Enable **Agent voice**. 2. Open the voice picker. 3. Use a play button to preview an available voice. 4. Select the voice you prefer and ask a short question. The available list and custom-voice controls depend on the build and provider access. A successful preview checks voice playback; it does not prove an unrelated agent task completed. ## Change speed Choose **Slow**, **Normal**, or **Fast** on the same card. The current presets are 0.85×, 1.2×, and 1.5×. The new setting applies to subsequent speech and previews. Starting another voice recording interrupts a spoken response so you can continue the conversation. If replies seem repeatedly cut off, check whether you are triggering another recording or pressing a voice shortcut unintentionally. ## Custom voices Where **Make a custom voice** is available, you can record or choose a sample, name it, and confirm that you own the voice or have the speaker's permission. Creation sends audio to the voice provider and requires supported provider access; a Nock plan does not guarantee that the provider permits custom-voice creation. Follow the limits and messages shown in the dialog. ## No spoken response Check the voice switch, system output volume, and selected audio output. Try a preview at Normal speed. If text answers work but previews fail, inspect the provider or account message shown by Nock rather than repeating the whole task. For input problems, see [microphone and recognition](/nock/microphone). For sending a new request, see [agent mode](/nock/agent-mode). ## Understand the spoken summary The voice normally gives a compact answer while the notch holds the fuller response. It may omit code, paths, and long details from playback. Read the visible answer when exact instructions or a task result matter; a shorter spoken line does not mean the text is missing. If you want quiet interaction, turn Agent voice off and keep visible responses. Interaction sounds and welcome music are separate controls under General, so disabling speech may leave a dictation tick or notification cue audible. See [sound and media](/nock/sound-and-media). ## Before removing a custom voice Review the confirmation in the voice picker. Where supported, deletion removes the voice from the provider as well, rather than merely hiding a local entry. If the selected custom voice becomes unavailable, choose a built-in voice and test a preview before diagnosing the entire agent connection. # Custom voices Where available, **Settings → Agent → Make a custom voice** creates a spoken voice from a recording or audio file. The voice provider processes the sample. This feature requires supported provider access and is not guaranteed by the presence of a Nock subscription or the button alone. Use your own voice or a speaker who has given you permission. The creation form requires an explicit confirmation before submitting the sample. ## Check access first Review the relevant voice-provider connection in **Settings → Providers**. Custom voices belong to the provider account or team that creates them. Nock's candidate uses an eligible personal provider connection for custom-voice management rather than assuming a shared plan credential can create a voice for you. Provider eligibility, limits, and availability can change. Follow the actual response shown by the form; these docs do not promise creation for every provider account or a particular price. ## Record or choose a sample 1. Open **Make a custom voice**. 2. Choose **Record** and read the displayed script, or choose **Choose a file…** for an existing sample. 3. Stop the recording and use playback to inspect it. 4. Use **Record again** or **Choose another** if the wrong speaker, background noise, or a clipped ending is present. 5. Enter a name, confirm the consent statement, and choose **Create voice**. The current recording limit is two minutes. The file picker supports common audio formats and enforces size and duration limits. A recording uses Nock's microphone path; finish any active voice interaction first. Pressing a global voice shortcut can interrupt sample recording, so avoid it while making the clip. Creation sends the sample to the provider. Review it before submitting: a recorded conversation may contain more than the voice sample you intended to share. Choosing a file reads it; it does not move the original file. ## Preview the result A created voice appears under **Your voices** and can become the selected agent voice. Play a preview, then try a short ordinary request. Use [voice settings](/nock/voice-settings) to change speed or return to a built-in voice. **Find my xAI voices** can refresh the list from that connected provider account, including voices created through the provider's own interface when supported. If you switch provider accounts, do not assume the same voice identifiers remain usable. ## Remove a voice carefully Use the voice picker's delete control and read the confirmation. Deletion can remove the voice at the provider, affecting other uses of that voice, rather than just hiding a Nock entry. Choose another voice and test a preview if the selected one has been removed elsewhere. ## When creation fails An expired draft requires recording or choosing the clip again. An unsupported-account message requires resolving provider eligibility, not repeatedly resubmitting the sample. For microphone problems, see [Microphone](/nock/microphone). If creation succeeded but playback fails, test a built-in voice and use [Voice troubleshooting](/nock/voice-troubleshooting) to separate account, output-device, and playback issues. # Sounds and media volume Nock's sounds give brief feedback about recordings and results. Its media-volume preference helps the microphone hear you over other audio. These are separate controls under **Settings → General → Audio & Speech**, and separate again from the agent's spoken voice. ## Interaction sounds With **Interaction sounds** enabled, dictation can play a start tick once a recording actually begins and a stop tick when you finish. A brief tap that never becomes a recording does not play the same sequence. A notice tone can draw attention to text left on the clipboard after an unconfirmed paste. An answer-ready tone can signal completion of a foreground request. These cues supplement the visible state; they do not prove that text reached the intended field or that a result is correct. Agent holds do not use the same dictation start/stop ticks. Nock can also skip cues while you are recording or while speech is playing, so missing a tick alone does not establish failure. Watch the caption or recording state when checking a new shortcut. Turning Interaction sounds off silences those main cues. The mapped candidate has a separate agents-panel completion/attention tone, so this switch should not be treated as a universal mute for every agent notification. ## Intro music **Intro music** controls the short score in the first-run welcome. The introduction also has a speaker control. Replay from **Settings → About** if you want to check its level after changing the preference. Muting welcome music does not disable the agent's regular spoken replies. ## Lower media volume while talking On macOS, this option lowers the system output volume during a dictation or agent recording. Because it acts on overall output, it can quiet audio from several apps, not just a music player. The current target is roughly one fifth of the previous level when the system reports a usable volume. Finishing or cancelling restores the previous level. Nock avoids changing an already muted or zero-volume output. If you explicitly ask Nock to set a new volume while recording, that newer request takes priority over restoring the old level. ## Choose the right combination For silent feedback, disable interaction sounds and agent speech separately. For spoken answers without lowering a call or other media, leave Agent voice enabled and turn media lowering off. Use [voice settings](/nock/voice-settings) for reply speed and voice selection. ## Volume did not come back Restore the Mac's output volume yourself. Starting another recording may simply lower and restore the already-low value, so it is not a repair. Quitting during a recording or an output that macOS cannot control can interrupt the expected restoration. If the behavior repeats, test with media lowering off and note the output device, whether the recording ended normally, and the visible Nock state. For silent spoken responses rather than low system volume, use [voice troubleshooting](/nock/voice-troubleshooting). # Appearance and visibility Open **Settings → Appearance** to adjust the interface. Changes apply immediately, so you can compare them against your desktop without restarting. ## Choose a theme - **Auto** follows the Mac's appearance. - **Light** keeps opened surfaces light. - **Dark** keeps opened surfaces dark. The resting notch and recording band remain dark so they fit the top edge of the display. Changing the theme mainly changes the expanded notch, panels, and Settings. ## Choose a finish **Top notch** controls the expanded top surface. **Side notch** controls the side panels. Choose **Frosted** or **Solid** where those options are enabled. Frosted uses platform-specific blur. The current settings control requires macOS 26 or later for that choice and shows an explanation when unavailable. Use Solid when the option is disabled or when a more opaque surface is easier to read. Other platform builds can present different appearance controls. The interface may briefly open a panel when you change its finish so you can inspect it. This does not change your conversation. ## Show or hide Nock Visibility preferences live in **Settings → General**, separately from theme. Check **Hide top notch** and **Hide side notch** if a surface seems missing. You can also access Settings through the menu-bar item. ## Troubleshoot a surprising result Switch explicitly to Light or Dark to check whether Auto is following an unexpected system setting. Try Solid if desktop content behind Frosted makes text harder to see. Appearance preferences do not resize or redesign the notch's shape. See [quickstart](/nock/quickstart) to open the main surfaces, or [keyboard shortcuts](/nock/keyboard-shortcuts) to open chat without moving the pointer. # Alternative input and readability Nock offers several ways to make a request: held shortcuts, hands-free recording, an in-app mic button, and typed chat. Choose the combination that is comfortable for you. This guide describes available controls; it is not a claim of a completed accessibility certification or compatibility with every assistive technology. ## Reduce the need to hold keys Use [hands-free](/nock/hands-free) when holding a modifier key throughout a recording is difficult. Double-tap the configured voice shortcut or use the hands-free trigger, then press the appropriate shortcut again to finish. Watch the recording state so you know when listening remains active. Escape cancels. For a draft you can review before sending, use the [composer mic button](/nock/dictation-button). One click starts and another stops; the text stays in the composer until you send it. If global shortcuts conflict with another tool, this button can provide a useful input path while you adjust the bindings. ## Use typed chat A quick tap of the default agent shortcut opens the chat box. Type a request, press Return to send, and use Shift + Return for a new line. Typed chat can remain useful when the microphone or speech helper is unavailable. It does not automatically capture another app's selected text; paste the relevant passage or attach screen context deliberately. You can turn spoken Agent voice off while keeping visible answers. Conversely, choose a slower voice and keep the full text on screen if following a spoken summary alongside the written result is easier. ## Customize the keys Open **Settings → General** to change voice triggers and the paste-last shortcut. The current macOS hold triggers accept supported modifiers and mouse buttons, with restrictions to avoid reserved shortcuts. They are not arbitrary character-key bindings. Choose a combination that does not compete with your existing assistive software. Test it in a scratch note before relying on it in another app. The default agent trigger distinguishes left from right Control and Option, so use the saved combination shown by Nock. ## Navigate Settings and improve readability The Settings rail supports Up/Down arrows and Home/End after focus reaches it. Use Tab to move onward to controls. Individual dialogs and native system settings can behave differently. In **Appearance**, compare Light, Dark, and Auto. Try Solid when content behind a frosted surface makes reading harder. You can hide the resting notch or side indicators in General while retaining access through the menu-bar item. The current settings do not offer arbitrary notch resizing. ## Permission is a separate meaning of Accessibility macOS's **Accessibility** permission allows actions such as text insertion and selection reading. It is not a statement about Nock's usability with a screen reader. Follow [permissions](/nock/permissions) when an operation is blocked, and describe assistive-technology problems separately when reporting them. For a useful report, include the control, input method, expected behavior, and what happened. Mention the app version and assistive software if relevant. Avoid including private dictation or screenshots unless needed and reviewed. # Personalize your agent Personalization has several separate controls. Your name helps Nock address you, voice settings change spoken delivery, and named-agent instructions shape a particular agent's behavior. Changing one does not automatically change the others. ## Set your name Open **Settings → Agent → About you**. Edit **First name** and **Last name**, then leave the field so the change saves. The first-run introduction may already have filled these values. Check the saved field if the greeting uses the wrong name. The Home greeting uses your first name. Your name can also accompany agent turns as context, so choose the information you are comfortable sharing with the model. These fields are not a complete memory editor, and changing them does not erase previous conversations. Words you want dictated accurately belong in the [Dictionary](/nock/dictionary). Automatic text substitutions belong in [Replacements](/nock/replacements). Adding a project name to About you will not train the transcription system to spell it correctly. ## Tune spoken delivery Use the Agent voice controls to select an available voice and speed. Try a short question and listen to a full response before making another adjustment. A slower voice can improve clarity without requiring the agent to produce a longer answer. For a custom character, open **Edit agent** and select its own voice. The automatic option assigns a consistent voice. A named agent's voice and Nock's main voice are separate settings, so confirm which conversation is selected when comparing them. ## Write useful instructions In a named agent, use **Character** for its role, **Personality** for its tone, and **Instructions** for observable working rules. For example: “Give me the recommendation first, then two reasons. Ask before changing the intended audience.” Test that instruction on a small task and revise it if necessary. Avoid making the same rule conflict across several fields. Keep private credentials out of personality text and `SOUL.md`; those instructions travel with messages and are not a secret-storage mechanism. An agent description cannot add a missing connection, grant a permission, or enable a restricted account feature. Use the corresponding Settings section when you need to change access. See [Named agents](/nock/named-agents). ## Ask Nock to change a preference **Settings → Agent → Let the agent change settings** lets you request supported preference changes conversationally, such as changing voice speed or weather units. Each change asks for approval. Read the proposed value before accepting it and confirm the setting afterward. The tool is limited to supported preferences. It does not change keys, operating-system permissions, keyboard shortcuts, or the rules governing what actions the agent may take. When a change is outside that scope, use the Settings control Nock identifies. Turning the preference tool off still allows Nock to explain where a setting is. See [Voice settings](/nock/voice-settings), [Task approvals](/nock/task-approvals), and [Privacy](/nock/privacy) for related controls. # Insights **Settings → Insights** summarizes voice activity such as dictated words, speaking pace, sessions, and activity patterns. It is separate from **Usage**, which reports account allowances. ## Reveal your metrics The current candidate unlocks the detailed view after 100 recorded voice sessions. Before that, it shows progress toward the threshold. Once unlocked, choose **Reveal insights** to display your numbers. Empty transcripts do not count as successful voice sessions, and typed chat is not a dictated session. If pace is not shown yet, keep using ordinary dictation. A tiny sample is not enough for a meaningful rate, so the page waits for sufficient speech rather than reporting a number from a few words. ## Interpret the numbers Word counts and session activity come from local records. **Time saved** uses assumed typing and speaking speeds; it is an estimate, not a stopwatch measurement of your personal productivity. The **Top %** badge is based on a fixed activity scale, not a measured ranking against other users. Do not use Insights to infer remaining plan allowance, provider charges, or task concurrency. Check [Usage and limits](/nock/usage-limits) for those concepts. ## Privacy and missing activity The metrics are calculated locally, but their source records can include spoken transcript text. “Local insights” does not mean that the original transcription or agent request never used a cloud service. If activity seems missing, first check that transcription produced words and that the session was a voice interaction. Do not delete app data to refresh the view: it can remove records you wanted to keep. Report a persistent mismatch with your app version and a non-sensitive example. See [Dictation](/nock/dictation) and [Privacy](/nock/privacy). # Your Nock account Nock shares your V3Code account. When the Nock account experience is available, open [your account](https://app.v3code.dev/account?tab=nock) to review Nock access. **Launch preview:** account pages and desktop sign-in may not yet be available publicly. A missing Nock section is not a reason to create multiple accounts. ## Read the account page The Nock account view is organized around: - **Plan:** your current access state, including trial or subscription status when applicable. - **Unlocked:** the capabilities enabled for this account. Use these indicators when deciding whether a feature should work. - **Usage:** the share of an available allowance already consumed. - **Get the app:** a download entry point, subject to release availability. - **Cloud agents:** shown as coming soon unless access has been specifically enabled. If your account is signed in but the agent remains locked, check the Plan and Unlocked areas first. A signed-in session and an active plan are separate states. ## Billing and product email An eligible billed account can use **Manage billing** to reach the plan-management area. Complimentary or beta access may not have a subscription to manage. Product-email consent is separate from signing in. Review the email choice shown in the Nock account or checkout flow rather than assuming that account access requires marketing emails. ## Wrong account or missing access Compare the account shown in the browser with the account used by the desktop sign-in flow. If they differ, restart [Sign in](/nock/sign-in) using the intended account. If a completed checkout has not appeared yet, see [Billing](/nock/billing). For allowance indicators, see [Usage and limits](/nock/usage-limits). # Plans and trials Nock separates the free Apple dictation fallback from account-enabled agent and cloud features. The offer shown in your account is the source for current availability, price, trial duration, and included usage. Apple recognition prefers on-device operation when supported; this is not a universal offline guarantee. **Launch preview:** paid checkout and account access are still being prepared. These docs explain how the planned account experience works; they do not announce that plans are on sale. ## Compare access On-device dictation is the free fallback. Agent actions, cloud transcription, and spoken replies require suitable access. Plans can also differ in how many background workers may run at once and how much usage is included. Cloud agents have a separate availability gate and are not publicly available during launch preparation. Do not purchase based on an assumption that a cloud feature is already open. ## Starting a trial When a trial is offered, review its duration, card requirement, renewal terms, and usage allowance before continuing. A trial can end when its time expires, and hosted usage can also pause when the trial allowance is consumed. If checkout says a plan is **not on sale yet**, wait for availability. If the page says your trial has already been used, it may offer a subscription instead of another trial. ## After access ends The account model retains the Apple dictation fallback when agent access ends. Hosted agent work, cloud speech recognition, and spoken replies can become locked. Check the app's enabled features rather than assuming a previous trial remains active. ## Your own provider keys Bring-your-own-key access is not enabled for every account mode. Use it only if your account and app expose it. Adding a provider key does not automatically unlock a subscription feature or cloud agents. See [Usage and limits](/nock/usage-limits) and [Billing](/nock/billing) before starting longer tasks. # Usage and limits Nock's hosted services have usage limits. When enabled for your account, the Usage panel shows the percentage of an allowance consumed and any available reset information. ## Understand the meters Different access modes can show different windows, including a five-hour window, a week, a rolling month, or a total trial allowance. A percentage is a share of that allowance; it is not a dollar balance or a count of messages remaining. A longer task can use more than a short conversation. Cloud transcription, spoken replies, model work, and available connected tools can involve different services. Avoid estimating remaining work from message count alone. ## When a limit is reached Read the message attached to the exhausted allowance. If a reset time is shown, wait until that window opens again. If trial usage is exhausted, the account may remain paused until the subscription starts according to the checkout terms. On-device dictation is distinct from hosted agent usage. Check which feature is locked rather than treating a hosted limit as a failure of every part of Nock. ## Usage cannot be checked A temporary service problem can prevent Nock from safely checking or recording hosted usage. In that case, a request may stop before work begins. Wait briefly and try again; do not launch many duplicate requests to force it through. If a task might already have performed an external action, inspect the destination before retrying. This avoids creating duplicate messages or records. ## Background workers Concurrent-worker limits control how many background tasks can run at once. They are separate from usage allowances. If you cannot start another worker, review existing tasks and your account's enabled limits. See [Your Nock account](/nock/account), [Plans and trials](/nock/plans-trials), and [Troubleshooting](/nock/troubleshooting). # Billing and cancellation Nock billing is managed through your V3Code account when paid plans are available. The checkout page provides the actual price, trial terms, and renewal details for your offer. **Launch preview:** public paid checkout is still being prepared. Do not interpret a documentation page or plan name as an available purchase. ## Before checkout Confirm the signed-in account and selected plan. Read whether a card is required, when any trial ends, and when billing begins. If you change plans while a checkout is already open, complete or leave that flow before starting another one. Payment is handled through the checkout provider. Do not send payment details, account tokens, or screenshots containing them in a support request. ## Manage or cancel Open [your Nock account](https://app.v3code.dev/account?tab=nock) and choose **Manage billing** when that option is available. Review the cancellation confirmation and effective date shown there. Closing Nock, signing out, or deleting the app is not a subscription-management action. Use the account billing flow and retain the confirmation for your records. ## Checkout completed but access is missing The account update can arrive after the checkout page finishes. Give it a minute, refresh your account, and return to Nock. Confirm that checkout and Nock use the same account. If access is still missing, report the time of purchase, account email through a private support channel, and the message shown. Include a transaction reference if requested, but never full card details. Avoid completing a second checkout just to refresh the first purchase. ## Trial usage versus billing An exhausted trial allowance does not necessarily mean its calendar duration has ended. Read the displayed trial and renewal dates. See [Plans and trials](/nock/plans-trials) and [Usage and limits](/nock/usage-limits). # macOS permissions Open **Settings → Permissions** to inspect the current permission state and open the relevant macOS settings. Grant access for the features you intend to use. | Permission | Purpose | | ------------------ | -------------------------------------------------------------------------------- | | Microphone | Capture a voice recording. | | Accessibility | Insert text, read supported selections, and support the voice shortcut listener. | | Input Monitoring | Detect configured voice keys while another app is active. | | Screen Recording | Capture visual context for pointing and screen-aware requests. | | Speech Recognition | Use Apple's speech-recognition fallback. | Screen access is needed for the visual tour and pointing features. Speech Recognition applies to the Apple fallback; cloud recognition still requires Microphone access. ## Grant access 1. Open a permission row in Nock. 2. Use **Grant** if a system prompt is available, or **Open System Settings** otherwise. 3. Enable the relevant Nock entry under **Privacy & Security**. 4. Return to Nock and allow its status to refresh. 5. Reopen the app if macOS says a restart is required. After a denial, use System Settings rather than waiting for the same prompt to appear again. Keyboard access can require both Accessibility and Input Monitoring. ## Why Nock Speech appears The helper that captures audio and performs speech recognition can appear as **Nock Speech**. It has its own microphone and speech permissions. Review that entry when Nock itself looks permitted but recording produces nothing. ## Permissions changed after an update macOS associates grants with an app's identity and signature. Moving between development, test, and distributed copies can lead to fresh prompts. Check the installed copy you actually opened and grant access through the normal system interface. Do not disable macOS security protections to resolve a permission issue. If keys do nothing, see [keyboard shortcuts](/nock/keyboard-shortcuts). If recording starts without words, see [microphone](/nock/microphone). If words appear but are not inserted, see [dictation](/nock/dictation). ## Check the permission for the failing feature Use a short test after each change. For keyboard access, check whether the notch reacts to your saved shortcut. For the microphone, check whether words appear. For insertion, dictate into a basic note. For screen access, capture a small non-sensitive window and inspect whether it is visible. Granting Screen Recording will not repair a microphone connection; granting Microphone will not make a paste work. This separation also helps explain why typed chat can work while a voice or desktop feature remains blocked. If System Settings says a permission is enabled but Nock reports otherwise, first confirm which installed or test copy you opened. Use Nock's refresh control where available, and follow any macOS request to quit and reopen. Avoid installing multiple copies or resetting all privacy permissions as a first troubleshooting step. # Privacy and data Nock combines local desktop features with account-enabled cloud services. The data involved depends on the feature you use. On-device dictation and hosted agent work have different boundaries. | When you use… | On your Mac | Sent to a service when needed | | -------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------- | | On-device recognition, when supported and selected | Speech processing and transcript | Do not assume an unsupported recognizer stays offline. | | Hosted recognition or spoken replies | Recording or reply text before upload | Audio for recognition, or reply text for speech synthesis. | | Agent chat | Local conversations and selected context | Your request and context included in that turn. | | Circle-and-ask or an attached screen region | The capture you select | The image sent with the request to the configured model. | | Project work | Local index, file edits, and commands | Relevant code and results needed by the model or connected agent. | | Connected apps | Connection controls in Nock | Data read or written through the app provider when a permitted task uses it. | The exact model and speech services depend on your selected provider, build, and account settings. Review those settings before using Nock with confidential material. ## Where hosted model requests go The current included DeepSeek route sends model requests through V3Code's account relay to DeepSeek's API. Prompts and any context attached to a request can reach that provider; do not treat the account relay as a US-only model host. If you choose another supported model or connect your own provider account, the destination and applicable provider policy change with that choice. [Models and providers](/nock/providers) explains how to inspect the available settings. V3Code plans to move the included DeepSeek model routes to US-hosted providers when paid Nock plans launch. That change has not been verified as live. Until this page is updated with a confirmed destination, assume the current DeepSeek route can send request content to DeepSeek's API. ## On-device and hosted features The Apple speech fallback prefers on-device recognition when the selected recognizer supports it. The current implementation does not require an on-device recognizer when that support is absent, so do not treat the fallback as an unconditional offline guarantee. Hosted transcription sends audio to a speech service. Spoken replies use a text-to-speech service. Agent requests can send your prompt and the context needed for the task to the configured model service. Do not assume that all Nock activity stays on the computer because one dictation mode works on device. Check the active mode and provider before sharing sensitive material. ## Context and permissions The desktop app can require operating-system permissions for features such as microphone capture or interacting with other apps. Grant the permissions needed for the workflow you intend to use and review them in your system settings. Consider what is visible or selected before asking for help with on-screen or project content. Keep unrelated private material out of the context you provide. When you use a screen-aware action such as circling an area or attaching a region, Nock captures that visual context on demand and sends the image to the model handling the request. A capture can include private material visible in or near the selected area. See [Circle it and ask](/nock/pointing). This page does not promise automatic redaction of sensitive content. ## Connected services Connecting an app authorizes access through that provider. Review the requested permissions and use the intended personal or work account. Connected tools can read or change service data when execution is available and permitted. You can disconnect through Nock and review the integration in the provider's own security settings. Disconnecting does not reverse earlier actions or delete data already created in that service. ## Account and usage information The account service tracks access and hosted usage so it can apply plan limits. Product-email consent is a separate choice. This page describes feature boundaries; it does not establish a blanket retention period or promise that third-party providers retain no data. For policies that apply to your account, consult the current [V3Code privacy policy](https://v3code.dev/privacy) and relevant provider policies. See [App connections](/nock/app-connections) for connection controls. # Data and history Nock keeps several kinds of local information: conversations, settings, dictation activity, saved previews, and feature-specific data. These have different controls. Removing one conversation is not a universal erase operation for every kind of data. ## Chat retention Open **Settings → Agent → Keep chats for**. The available choices are **30 days**, **90 days**, **1 year**, and **Forever**; the default is 90 days. Retention uses the newest message in a conversation. A chat started months ago but used recently is treated according to that recent message. When a chat reaches the selected age, its stored messages and cards are removed together. Shortening the period can delete conversations immediately if they already exceed the new limit. Review what you want to keep before changing it. Choosing Forever prevents age-based removal going forward; it cannot restore conversations already deleted. ## Delete one conversation The chats panel provides a right-click delete action for an individual chat. Use it only when you intend to remove that conversation and its cards. Deleted chats cannot be recovered through the history panel. Starting a new chat is different from deleting the old one. Likewise, the idle setting that starts a fresh chat does not itself define how long older conversations are retained. ## History and memory are separate Deleting a conversation does not change information the agent saved to long-term memory. Do not use chat deletion as proof that the agent has forgotten a fact. Review the appropriate memory workflow when the goal is to change retained knowledge. Saved previews, boards, reminders, and app connections are also separate from chat history. Their own controls determine whether they remain. For example, removing a locally built item from My Apps is different from disconnecting an external service. ## Insights and usage data Insights calculates activity statistics from the local session log. Hosted allowance meters answer a different question: how much account usage is available. These displays should not be expected to match one-for-one. **Settings → General → Share usage data** controls optional app-usage and setup events. It is on by default in the launch candidate. Turning it off stops new optional events and clears pending event queues. It also requests withdrawal from setup-tip emails. If the service cannot be reached, that withdrawal waits for a later retry; use an email's unsubscribe link if you need to act from the email service directly. Those usage events are designed around limited feature names, durations, counts, and error labels. Signed-in events can be associated with your account; do not assume they are anonymous. This switch does not turn hosted model, speech, billing, or connected-app requests into local operations. ## Sharing diagnostic material Check logs and screenshots before sending them to support. Remove conversation text, private paths, account tokens, and unrelated information. Local storage does not mean content can never leave: context needed for a hosted task is sent to the relevant service. Read [Privacy and data](/nock/privacy) and [Support](/nock/support). # Troubleshooting Start by identifying which part is failing: download, desktop setup, sign-in, account access, or a particular task. A working website demonstration does not verify your installed app's permissions or account state. ## Download says Coming soon This is expected during launch preparation. Use the [official download page](https://v3code.dev/nock/download) and wait for a platform-specific installer to appear. Reinstalling another V3Code product will not install Nock. See [Availability](/nock/availability). ## Sign-in page is missing or unavailable The public Nock account handoff is still being prepared. Check availability before treating an unavailable route as a desktop configuration problem. When enabled, begin sign-in inside Nock rather than reusing an old browser tab. If the browser is waiting to hand control back, keep Nock open. Confirm the account shown, return to the app, and start a fresh sign-in attempt if needed. For **Too many attempts**, wait a minute before retrying. See [Sign in](/nock/sign-in). ## Signed in, but the agent is locked Open the account's Plan and Unlocked areas. Sign-in identifies you; it does not guarantee an active trial, paid access, or availability of every feature. Check trial status and usage. Cloud agents remain restricted during launch preparation. If you just completed checkout, allow a minute for the account update and refresh. Confirm the browser and desktop use the same account before attempting another purchase. ## Hosted work stops with a limit or service error Read the allowance and reset time in Usage. Wait for the stated window, or follow the account options offered. A temporary inability to check usage can also pause hosted work; retry later rather than starting duplicate tasks. For an interrupted external action, inspect the destination before retrying. See [Usage and limits](/nock/usage-limits). ## App connected, but a tool will not run Review connection status, provider permissions, and any setup guidance. A connected service does not guarantee execution availability. Hosted app-tool execution is not publicly enabled during launch preparation; reconnecting does not remove that gate. ## Dictation is not landing where expected Confirm the intended text field is focused and that the app has the system permissions required by your build. Check whether you are using on-device dictation or a hosted speech mode, since account and connectivity requirements differ. Try a short, non-sensitive sentence in a plain text field to isolate the problem. ## What to include in a report Provide the Nock version, operating system, feature used, expected result, actual message, and a short reproduction. Include whether the problem happens every time and whether it began after an update. Remove tokens, payment information, private conversation content, and unrelated file paths from logs or screenshots. Related: [Downloads and updates](/nock/downloads-updates), [Your account](/nock/account), [App connections](/nock/app-connections), and [Privacy and data](/nock/privacy). # Troubleshoot dictation A failed dictation can happen before the microphone starts, while words are being recognized, or when the finished text is inserted. Find the last step that worked before changing several settings at once. ## Preserve a transcript first If you saw the right words in the caption, avoid making another recording immediately. Click a scratch note and use [Paste Last Transcript](/nock/paste-last). If a notice says the text is on your clipboard, try Command + V there. Once the words are safe, investigate why the intended destination failed. ## Nothing reacts to Fn Check **Settings → General** for the actual Dictation Mode binding. Test a deliberate hold rather than a quick tap. If Fn opens emoji, change macOS's Globe-key action or choose another supported binding. Open Nock's menu-bar menu. A **hotkey blocked by a missing permission** message points to Accessibility or Input Monitoring. Grant those through [Permissions](/nock/permissions), then refresh permission status or restart the listener if that menu action is available. Restart listener is for keyboard detection; it does not fix a disconnected microphone. If the app displays an unlock card, the key reached Nock. Review account/access status rather than repeatedly changing shortcuts. ## Recording starts, but no words appear Check **System Settings → Sound → Input** and confirm that speaking moves the input level. Nock's macOS voice path uses that system input. Then check Microphone access, including the **Nock Speech** helper entry where present. A cloud connection may fail without producing a transcript. Check the message in Nock and the account/provider configuration. The current recording does not necessarily fall back to local recognition after a cloud failure. See [microphone](/nock/microphone) and [voice troubleshooting](/nock/voice-troubleshooting). ## Caption is correct, but the field is empty Stay in the intended app until insertion finishes after release. Nock uses a clipboard paste into the app in front; it cannot reliably prove that the correct text field accepted it. A desktop or webpage with no editing cursor can receive no text without a useful insertion error. Try the same short sentence in a basic note. If that works, focus or compatibility in the original app is the likely difference. If no app accepts text, check Accessibility. A paste that fails can leave the words on the clipboard with a recovery notice. ## Words appear, but are changed Check [Primary language](/nock/languages), then test with polishing off and review replacement rules. Recognition hints address misheard names; replacements address exact expansions. Neither makes every dictated sentence correct. Review terminal commands, addresses, and messages before submitting them. ## Report a reproducible problem Record Nock's version, macOS version, input device, destination app, shortcut, and whether the caption was correct. Include the exact non-sensitive error and a short example. A clear “correct caption, no text in app X, works in Notes” report is more useful than “dictation is broken.” Keep private transcripts, screenshots, and keys out of the report. # Troubleshoot voice input and replies Voice input and spoken output use different paths. Start by asking whether Nock recognized the request, whether an answer appeared, and whether that answer was audible. A text answer with no sound is different from a request that never reached the agent. ## Test each part separately 1. Type a short question in Nock's chat. If it answers, the agent path is working for that request. 2. Make a short recording and check the transcript. This tests input and recognition. 3. Open **Settings → Agent → Agent voice** and play a voice preview. This tests spoken playback. These small checks avoid repeating a long task while the failing component remains unknown. Do not interpret a successful voice preview as proof that the agent completed work. ## No recognized speech If the notch does not react, check [shortcuts](/nock/keyboard-shortcuts) and keyboard permissions. If recording starts, inspect the Mac's input device and Microphone grant, including **Nock Speech** where shown. Speech Recognition permission applies to Apple's fallback. The menu-bar status can distinguish a missing grant from a helper that is down or temporarily paused. **Speech is still starting** and **Transcription is not connected yet** ask you to wait for initialization. **Already listening** means another recording is active; finish or cancel it first. When the speech helper repeatedly crashes, Nock spaces out restart attempts and displays a retry message. Typing can remain usable while speech recovers. Restarting the keyboard listener will not restart this separate speech service. If the state persists, quit Nock normally, reopen it, and check the permission status before another test. ## An answer appears, but Nock is silent Enable Agent voice and try Normal speed. Check the Mac's output device and mute state. Review account or provider access if the voice picker cannot play a sample; the current voice service requires supported credentials/access and an available connection. If media lowering left the output quiet, restore the system volume manually. Another recording can lower the already-low level again, so it is not a useful recovery step. See [sound and media](/nock/sound-and-media). ## The reply stops or says less than the screen Starting a new voice recording or request interrupts current speech. The stop control deliberately silences playback and can stop work still in progress. Check whether a shortcut is being pressed accidentally. Nock generally speaks a short response while showing the detail on screen. It does not read every code block, path, or long result aloud. Read the visible response before assuming that a short spoken answer means the rest is missing. ## Useful support information Share the app version, input/output devices, whether typed chat worked, whether transcripts appeared, and whether a voice preview played. Include the visible error without secrets or private recording content. If the problem follows one voice or speed, name that choice and try another preset as a comparison. # Troubleshoot screen context Screen context needs three things: the intended capture gesture, access to capture the screen, and an agent path that accepts the image. Check the attachment you can see before assuming the model received it. ## No drawing trail appears Use the agent shortcut, **Control + Option** by default, rather than Fn dictation. Hold it long enough to start a voice request and move the pointer. On the current macOS gesture path, movement draws while no mouse button is held; pressing a button preserves dragging instead. Check your configured Agent Mode keys in **Settings → General**. If the notch itself does not react, diagnose the [keyboard shortcut](/nock/keyboard-shortcuts) first. Screen Recording permission cannot fix a key event that never reached Nock. ## The request has no image A nearly stationary pointer does not count as a drawing. This keeps an ordinary spoken request from attaching a full-screen picture. Make one clear circle or use **Point at something** in Nock's own composer to select a region deliberately. Look for the captured-region thumbnail or attached-context chip. If you clicked its close button, that attachment was removed. Region context is used once and expires after a few minutes, so make a fresh capture after waiting or changing the page. Do not rely on an old screenshot to describe the current state of a dialog. Capture again after an error changes, a page scrolls, or an app navigates. ## Captures are blank or incomplete Open **Settings → Permissions** and review Screen Recording. Follow macOS's instructions if it requires reopening Nock after a grant. Test a normal window with non-sensitive content before trying a protected or unusual surface. If you use several displays, put the pointer on the display containing the target before drawing. Keep the first reproduction to one display and one small area. The implementation limits captures per turn and may omit a capture that was not ready in time. ## Small text is misread Nock resizes images before sending them. Tiny text on a high-resolution display can become difficult to read even when capture worked. Zoom the source app, crop to the relevant area, or use [selected text](/nock/selected-text) when the text can be highlighted. For exact identifiers or error strings, paste the text with your question. ## A connected agent ignores the picture Different agent paths can accept different context. The macOS drawing behavior does not promise that every external or remote agent receives screenshots. Retry in Nock's own chat and confirm the attachment there; describe essential details in text if that integration cannot consume an image. ## Report the smallest safe example Include your app/macOS version, display arrangement, gesture used, whether an attachment appeared, and whether the image was blank or merely unreadable. Remove private content from any example screenshot. See [pointing](/nock/pointing) for the intended flow and [permissions](/nock/permissions) for grants. # Sign-in troubleshooting Nock sign-in has three stages: the desktop starts a request, the browser authenticates your account, and the result returns to the app. Identify where it stopped before changing settings. ## The browser page is unavailable During launch preparation, public Nock account routes may not be deployed yet. A missing page can therefore be expected even when the marketing site loads. Check [Availability](/nock/availability). Reinstalling, clearing browser data, or creating another account will not publish an unavailable service. When sign-in is available for your build, always start with **Sign in** inside Nock. A saved bookmark or old tab does not necessarily contain a current desktop connection request. ## The browser is signed in, but Nock is waiting 1. Confirm Nock is still running on the same computer. 2. Check whether the browser asks **Continue to Nock**. Verify the displayed account and continue only if you initiated this request. 3. Return to Nock and inspect its account state. 4. If nothing changes, start a fresh sign-in from the desktop app and use the new browser flow. The handoff uses a temporary local callback. Old tabs can belong to requests that have already ended. Do not copy callback addresses between computers or send them to support. ## Too many attempts For **Too many attempts**, wait a minute, then choose Sign in in Nock again. Avoid rapid refreshes or starting several simultaneous flows. If the service continues to fail, record the exact message and time and retry later. Other messages such as **Could not reach V3Code** or **Nock couldn't be signed in** indicate a failed step, not proof that your password is wrong. Check connectivity and whether the account service is available before changing credentials. ## The wrong account appears The browser may already be signed in to another V3Code account. Cancel an unexpected confirmation rather than continuing. Use the intended account in the browser and restart the Nock flow. Compare the account shown in the desktop with the one used for any checkout or access invitation. ## Signed in but still locked Authentication and feature access are separate. Check the Plan and Unlocked sections of [Your account](/nock/account). Trial status, usage exhaustion, and feature rollout can all affect access after successful sign-in. If checkout just completed, allow a minute for the account update and refresh. Do not complete another purchase solely to force access to refresh. Cloud-agent availability and hosted app-tool execution remain restricted during launch preparation. ## Report without exposing the handoff Provide app version, operating system, browser, approximate time, the step that failed, and the visible error. Remove full callback URLs, authorization codes, tokens, and private account details from screenshots. See [Support](/nock/support). # Usage troubleshooting A paused task can result from an allowance limit, unavailable account checks, a provider error, or a background-worker limit. Those cases need different responses. Start with the exact message and the account Usage view. ## An allowance is at 100 percent Check which window is exhausted and whether a reset time is shown. Accounts can expose several windows; one available meter does not override another exhausted allowance. A rolling window also need not reset at your local midnight. Wait for the displayed reset or use the account options offered. Do not infer a number of remaining messages from a percentage. Requests differ in length and can involve model work, speech, and other services. ## The trial has time left but work is paused Time and usage are separate trial limits. The trial allowance can be used before its end date. Read the message that explains when access opens again, and review the checkout terms for when a subscription starts. On-device dictation is separate from hosted agent work. Test the intended mode rather than assuming an exhausted hosted allowance should disable every local feature. See [Plans and trials](/nock/plans-trials). ## Usage or account status cannot be checked Messages such as **Could not safely check your usage allowance**, **Could not safely record this call**, or **Could not check your Nock plan** describe a temporary service failure. They do not necessarily mean you have consumed your allowance. Wait and retry a small request. Avoid repeatedly launching expensive or duplicate tasks. If the error persists, record the time and message for support. Do not delete local history or reconnect every provider to repair a server-side check. ## A worker will not start Worker concurrency controls how many background tasks may run at once. Review current workers and wait for one to finish, or stop a task you no longer need through its normal controls. This limit is different from usage consumption; an account can have allowance left but no free worker slot. ## A provider rejects the request Inspect the model or voice service involved. A connection can exist while its credentials are expired, its account has insufficient access, or the service is unavailable. Check [Models and providers](/nock/providers) for connection states. Adding your own key is only an option where supported by your account and interface. It can create charges with the provider and does not remove Nock's separate availability gates. ## A task stopped after changing something Before repeating a send, create, or update action, inspect the destination. An external service may have accepted work even when the result did not reach Nock. Continue from the observed state rather than issuing the entire request again blindly. For a report, include the affected feature, visible allowance/reset information, exact error, time, and whether anything completed. Never include provider keys. See [Support](/nock/support). # Coding task troubleshooting Start with the task card's exact state. A task that is **Queued** needs a different response from one that is **Waiting for you** or **Couldn't finish**. Read the existing task before dispatching another copy of the same request. ## The task never starts Name the integration explicitly: “Have Codex review this project” or “Ask Claude Code to explain this test failure.” Identify the project folder and whether edits are allowed. Without that distinction, Nock may answer the question in its own conversation. If the command-line agent cannot be found, open a new system terminal and check that its normal launch command works. Install and sign in through that provider's supported process. Quit and reopen Nock after installation so its command lookup can refresh. Do not replace Nock's application files or paste credentials into a task description. A working command in one old terminal session does not prove that a newly launched desktop app can find it. Include the command name and installation method when reporting a detection problem. Account or credit errors from the coding provider should be resolved in that provider's own interface. ## The folder is missing or ambiguous Give the full project path when several folders have the same name. Check that the selected path is the current checkout, not a stale copy. Nock deliberately avoids using the entire home directory or disk root as the coding project. Before allowing edits, preserve existing work and check which other tasks use the folder. A successful run in the wrong checkout will not fix the project you are looking at. ## Queued or waiting Coding tasks are limited by available worker slots and project ownership. Only one task runs in a project folder at a time. A chained task can wait for its predecessor and may not start if that earlier task fails. Inspect that dependency before retrying. For **Waiting for you**, open the question or permission request and answer it directly. Automatic answers, when enabled, do not cover every sensitive decision. They are not a substitute for a missing approval. See [Coding permissions](/nock/coding-permissions). ## Stopped or interrupted work The runtime can stop a task after prolonged silence or its overall time limit. Tasks interrupted by quitting Nock are not automatically resumed. Inspect the project diff and task output before starting a follow-up, because partial changes can remain. Use **Stop task** to interrupt a running coding task. A voice follow-up can queue behind the existing work instead of stopping it. If you opened the session in the coding provider's application, continue there and check its state before launching a second session in Nock. For a support report, include the task state, integration, app version, and sanitized error. Remove secrets and private project contents. Distinguish “process completed” from “tests passed” when describing the result. # Widget troubleshooting The widget builder is Beta. Treat the first build as a draft to inspect and test. A finished visual layout and a running integration are separate results; a card can look correct while its data request or action fails. ## The builder closed or appears stuck Open **Studio** and look for the existing tile. Closing the builder while it works does not cancel the build. A tile marked **Building** can return you to the same draft. Reopening it avoids creating multiple attempts when the first one is still active. Read the current build stage and checks. If there is an error, record its first useful message before retrying. A focused revision such as “Keep the layout and fix the date calculation” is easier to verify than repeatedly requesting an entirely new widget. ## It looks right but shows the wrong information Check whether the preview uses sample data. Compare a small, read-only result against its original service. For example, confirm a displayed date or item title before relying on a larger summary. If the widget needs an account or setting, use **What it needs** and the designated configuration controls. Do not paste keys into the builder's conversation. A connected account alone does not guarantee that a generated widget uses the correct service or that its execution path is enabled in your build. Use **Ask your widget…** to try one bounded operation. If it fails, distinguish a wrong input, an unavailable service, and an authorization error. Rebuilding the visuals will not resolve a missing account permission. ## Inspect the running widget **Advanced → Server output** exposes diagnostic output and supported restart or repair controls. Read the output before choosing **Restart** or **Fix it**. A restart can restore a stopped local process but cannot fix an invalid credential or a service outage by itself. Under **Actions and approvals**, check the available actions and their confirmation settings. Sending or deleting actions remain consequential even when reached through a small widget. Verify external state before retrying an action whose result is uncertain. ## Keep, revise, or discard Choose **Keep widget** only after testing the draft. Kept widgets are available through Studio and **Settings → Apps → My Apps**. Reopen the existing item for revisions so you can compare the changed behavior with what already worked. **Throw away** discards the draft and removes its draft folder. Preserve anything important first. For an icon-only problem, use the icon control instead of rebuilding the widget; changing the picture should not require changing its actions. A kept widget is local software. There is no general public sharing marketplace in the current app, and another computer will not automatically have the same widget or credentials. See [Studio](/nock/studio), [MCP connections](/nock/mcp), and [Privacy](/nock/privacy). # Browser troubleshooting Nock's Web surface is a separate browser. Begin by identifying whether the problem is loading a page, showing it, signing in, or asking the agent to operate it. Each has different controls and restrictions. ## The address will not open Check the exact URL. Nock accepts HTTPS websites and local development addresses. An ordinary remote HTTP site is blocked. Use the site's secure address when available; do not disable certificate checks to force a page open. For a local preview, confirm the development server is running and that the host and port match. Open that same address in your normal browser. If both fail, inspect the local server before changing Nock. If only Nock fails, note its displayed error and whether a redirect changes the destination. DNS failures, an offline connection, timeouts, and untrusted certificates are different failures. Save the message so a support report identifies the actual condition. ## The agent says it opened a page, but nothing appears Check **Settings → Agent → Show browser while working**. When off, pages opened by the agent can remain in the background. Open **Web** and use **Show** to reveal the page. Also check whether the page is floating in **PiP** or docked under the notch. **Dock** returns a floating page; **Expand** changes the docked size. Hiding or collapsing the surface affects visibility, not whether its task has finished. ## Sign-in or site features differ Your normal browser's cookies and open tabs are not imported. Sign in yourself in Nock's browser where the site supports it. The agent's typing tool does not enter passwords. Glass Canvas web cards share Nock's browser profile, which can explain why a card is already signed in after using Web. Downloads and website requests for camera, microphone, location, and notifications are disabled. A site depending on those features may not work here. Use your normal browser for those actions instead of repeatedly granting unrelated system permissions. ## Clicking or typing fails The agent operates elements identified by its latest page read. Navigation, a dialog, or a dynamic refresh can invalidate those targets. Ask it to read the current page again before retrying. Describe the visible label and intended outcome rather than asking it to repeat an unexplained failed click. After a submit action, inspect the resulting page or service state. A click completing is not proof that a purchase, upload, or form submission succeeded. Avoid repeating an uncertain transaction until you check. ## Mobile preview is different from a phone Switch between **Mobile preview** and **Desktop preview** to inspect responsive layout. Mobile mode changes browser presentation and identification, but does not reproduce every physical phone capability. Test important mobile behavior on an actual device as well. See [The browser](/nock/browser) and [Privacy](/nock/privacy). # Getting help A useful report explains the action you took, what you expected, and what happened instead. Start with the smallest example that reproduces the problem, using non-sensitive text or a disposable test item where possible. ## Find your version Open **Settings → About**. Record the version and build number shown there. Include whether you are running a released installer or a development/preview copy; update behavior and operating-system permissions can differ. For an update problem, also record the message under **Check updates**. A copy that cannot update itself can say **This copy of Nock doesn't update itself**. That state is different from an update-service outage. Public downloads are still being prepared. If the official download page says Coming soon, report a broken page only if something else failed; the holding message itself is expected. See [Availability](/nock/availability). ## Build a clear reproduction Include: - Your operating system, Nock version, and affected feature. - The starting state, including the selected voice/model mode when relevant. - The steps you took in order. - The expected result and the actual result. - The exact visible error and approximate time. - Whether it happens every time, and whether it began after an update or settings change. For dictation, say whether Nock heard words but failed to insert them, or produced no transcript at all. For sign-in, identify whether the browser failed to open, authentication failed, or the return to Nock stalled. For a connected app, include whether the action completed at the destination. ## Screenshots and logs Capture the relevant control and message. Crop unrelated windows and review visible account details. Never send provider keys, sign-in codes, callback URLs, session tokens, full payment details, or private project content in a public issue. If asked for diagnostics, review them first and share only through the indicated support channel. Do not change or delete configuration files as a first troubleshooting step; that can remove evidence and saved state without solving the cause. ## Revisit onboarding Settings → About includes **Replay tour** and **Replay intro**. Use the tour to review the interface and first-run workflow. Replaying it does not guarantee that a denied system permission has been granted; check permissions separately. ## Optional setup tips Where the service is available, About offers setup tips by email. Entering an address alone is not enough: the interface requires the consent checkbox and an email confirmation. **Stop emails** and the unsubscribe link withdraw that choice. Setup tips depend on **Share usage data**, because they respond to incomplete setup steps. Turning sharing off requests withdrawal from the tips too. If Nock cannot reach the service, that withdrawal is retried later; the email's unsubscribe link is another way to withdraw. Tips are optional and are not a substitute for reporting a reproducible error. Start with [Troubleshooting](/nock/troubleshooting), [Sign-in troubleshooting](/nock/sign-in-troubleshooting), or [Usage troubleshooting](/nock/usage-troubleshooting) before collecting a larger report. # Introduction V3Code brings code editing, agent conversations, project memory, and code intelligence into one local editor. Start with your own API key, a supported provider subscription, or an available free model. Choose the workflow that fits what you want to do. ## Find your next step ### [Make your first change](/get-started/quickstart) Open a project, connect a model, and review a small change before keeping it. ### [Use a plan you already have](/models/connected-plans) Connect a supported provider account and find its models in the picker. ### [Bring your agent](/connect/agent-client-protocol) Open a compatible external agent in native chat, with its own conversation. ### [Understand a bug](/editor/debug-mode) Reproduce the problem, examine the evidence, and verify a focused repair. ## Your workspace at a glance ![V3Code with an empty Explorer, welcome actions, new chat, and agent sidebar](/images/editor-overview-0098.png) The editor with no folder open. Personal project details were removed by the screenshot contributor; the controls and layout are shown for orientation. ## Your agents, inside your editor ![V3Code Agents settings with per-agent Memory / Index and Browser controls](/images/agent-settings-0098.png) Agents settings in the 0098 interface. Each external agent has its own setup and access controls. Screenshot supplied September 17, 2026. There are three different ways to connect. Choose the one you actually need: | You want to… | Start here | | --------------------------------------------- | ------------------------------------------------------------------------------------ | | Use a provider's models with the V3Code agent | [Connect a provider plan](/models/connected-plans) or [add an API key](/models/byok) | | Run another agent in the editor's chat | [Set up ACP](/connect/agent-client-protocol) | | Share tools between V3Code and another client | [Connect through MCP](/connect/other-agents) | ## Keep useful context close - **[Context Bridge](/editor/context-bridge):** give compatible agents access to structural code intelligence, including references and call relationships. - **[Semantic index](/editor/semantic-index):** retrieve relevant project context. Wait for the index to report ready before relying on semantic results. - **[Memory](/editor/memory):** carry project context between conversations. Review important decisions rather than assuming everything is remembered correctly. Local tools and remote model calls have different data boundaries. Read [Privacy](/account/privacy) and the connection guide for the provider or external agent you choose. ## The rest of the toolkit - **[Quick Edit](/editor/quick-edit)** — select a bounded region, press `Ctrl/Cmd + K`, and describe the rewrite directly inside the editor. - **[V3Code Tab and V Go](/editor/tab-and-v-go)** — local-first autocomplete at the cursor plus next-edit prediction that follows your work to the next change point. - **[Turbo Draft](/editor/turbo-draft)** — infer the unfinished intent in a file, draft the complete change, and review it hunk by hunk before anything is kept. - **[Choose a mode](/editor/modes)** — Agent, Chat, Plan, Debug, Multitask, or Read. Design and Cyber Protection are separate composer options, not extra modes. - **[Design](/editor/design-mode)** — browse design directions and keep a consistent set of visual choices. - **Any model, your way** — [bring your own keys](/models/byok) for OpenAI, Anthropic, xAI, Google, DeepSeek, Mistral, Groq, OpenRouter and more; run fully local models (bundled, Ollama, LM Studio, vLLM); or use [hosted tiers](/models/overview) on a paid plan with an auto-router tuned to preserve caching. - **[Documentation for agents](/llms)** — give a model the plain-text docs index or complete documentation. ## Next steps ### [Install](/get-started/installation) Download V3Code for macOS, Windows, or Linux. ### [Quickstart](/get-started/quickstart) Open a project and make your first edit with the agent. ### [How V3Code compares](/get-started/how-we-compare) What's actually different from other AI editors. ### [Connect your agent](/connect/other-agents) Give Claude Code the same view of your code V3Code has. # Installation Grab the latest build from [v3code.dev/download](https://app.v3code.dev/download). The page always lists the newest public build; the current release is **1.4.9-0098**. ### macOS ### Apple Silicon (M-series) 1. Download the `.zip` and open it — it unpacks to `V3Code.app`. 2. Drag `V3Code.app` into **Applications**. 3. Launch it. The app is **signed and notarized** by Apple's process, so it opens without any security warnings. ### Intel Macs Intel Macs use the same `.zip` flow. Download the **Mac · Intel** build, replace the existing `V3Code.app` in **Applications**, then open it. The Intel build is signed and notarized, but updates are currently **manual**: return to the download page when a new version is announced. ### Windows **Windows 10 / 11, x64.** 1. Download the current Windows x64 installer. 2. Double-click it and follow the installer prompts. 3. Launch V3Code from the Start menu. The installer is **code-signed**. To inspect it, right-click the `.exe`, choose **Properties**, then open **Digital Signatures**. ### Linux **x64, early beta.** Download the `.tar.gz`, extract it, then launch the included executable: ```bash tar -xzf V3Code-linux-x64-*.tar.gz ./VSCode-linux-x64/bin/v3code ``` Linux is early access. It does not auto-update; download and extract a new archive when you want to update. Keep your existing archive until the new one opens normally. ## Updates **Apple Silicon Macs** and **Windows x64** check the stable update channel and prompt you to restart when an update is ready. The update uses the same signed release path as the installer. **Intel Macs** and **Linux x64** use manual downloads today. Use the platform card on the [download page](https://app.v3code.dev/download), quit V3Code, then replace the app or extract the new Linux archive. This does not require deleting your existing project or settings. ## I do not see an update 1. Compare the version shown in V3Code with the version on the [download page](https://app.v3code.dev/download). 2. Quit V3Code and download the current installer or archive for your platform. Running the Windows installer or replacing `V3Code.app` is a safe manual route if an automatic prompt did not appear. 3. If the download page lists a newer build but the update still will not apply, email [support@v3code.dev](mailto:support@v3code.dev) with your operating system, CPU (Apple Silicon, Intel, Windows x64, or Linux x64), installed version, and a screenshot of any update message. Do not include API keys, account tokens, or project files. ## Next ### [Quickstart](/get-started/quickstart) Open a project and make your first edit. # Quickstart Start with a small, disposable project or a clean branch. You will ask for a bounded change, review the proposed edit, and check the result. A model connection is required; a V3Code account is not required for BYOK. ### Open a project Launch V3Code and open a folder. On first open, V3Code builds a local semantic index of the codebase — this is what lets the agent answer without reading every file. ### Connect a model Use [your existing provider plan](/models/connected-plans), [your own API key](/models/byok), or an available free model. Free-model capacity can change. A V3Code account is used for V3Code account features and hosted usage; it is separate from provider sign-in. ### Pick a mode Open the chat panel. Choose **Read** to inspect without changing files, **Plan** to outline the work, or **Agent** to make a change. **Design** is a separate composer option. See [Modes](/editor/modes). ### Make a change Try: *"Read this project's README and existing setup files. Propose one correction to the README's setup instructions. Explain your evidence before editing, and leave all other files unchanged."* Review approval requests before allowing the edit. ### Review and check Inspect the changed lines. Ask the agent to check the instructions against the actual project configuration and report what it verified. Keep the edit only if it is correct; do not treat the model's confidence as proof. ### Try the in-editor prediction layers Start typing and press `Tab` to accept a V3Code Tab completion. Then make a small edit and pause: [V Go](/editor/tab-and-v-go) can prepare the likely next change point. For a whole-file draft, put the cursor near a `TODO` and press `Shift + Tab` to open a reviewable [Turbo Draft](/editor/turbo-draft). ### Let it remember Ask the agent to record a confirmed project decision. In your next conversation, check that the retrieved context is accurate. See [Memory](/editor/memory). ![Composer mode picker listing Agent, Chat, Plan, Debug, Multitask, and Read](/images/mode-picker-0098.png) Open the mode picker in the composer to choose the kind of work. Screenshot supplied September 17, 2026. ## What success looks like You have one reviewed README change, no unrelated modified files, and an explanation of what was checked. If the model cannot connect, fix the connection first using the [provider guide](/models/connected-plans); repeatedly submitting the same edit request will not resolve sign-in or capacity problems. ## Where to go next ### [Models & tokens](/models/overview) Choose a connection and understand where usage is billed. ### [Design mode](/editor/design-mode) Lock a brand system and generate on-brand UI. ### [V3Code Tab & V Go](/editor/tab-and-v-go) Autocomplete at the cursor, then predict the next edit. ### [Turbo Draft](/editor/turbo-draft) Draft a complete file-level change and review every hunk. # Sign in V3Code uses a single account across everything — the editor, your hub dashboard, and any hosted features. ## Signing in Sign in at [v3code.dev/login](https://v3code.dev/login) with **Google**, **GitHub**, or **email**. After you authenticate, you land on your account page — profile, plan, usage, and referrals. ## From the editor From the desktop editor, **Sign in** opens the same login page in your browser. Hosted-plan features and the cloud [semantic index](/editor/semantic-index) use this account. > Note: > > The editor itself is free and works on [your own keys](/models/byok) without signing in — you sign in when you want hosted models, the auto router, or cloud indexing. Provider subscriptions have their own sign-in path. If you already use a supported Claude, ChatGPT, Gemini, Grok, Copilot, or Cursor plan, see [Use your existing provider plans](/models/connected-plans) to make its available models appear in V3Code's picker. # How V3Code compares Most AI editors are a chat box bolted onto VS Code. V3Code is built around the parts that actually make an agent good at *your* codebase: local structural intelligence, memory that survives, and tools that go past autocomplete. The editor itself is **free**. ## The short version | | Typical AI editor | V3Code | | --------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Where your code lives** | Often uploaded to the cloud to be indexed | **Indexed locally on your machine**; nothing uploaded | | **How the agent sees code** | Text + grep, then guesses | **Context Bridge** — LSP-backed symbols, callers, call graphs, types | | **Across sessions** | Starts cold, you re-explain | **Remembers** — pull-on-demand memory that never loses anything | | **In-editor prediction** | Autocomplete and, in some products, next-edit prediction | **V3Code Tab + V Go + Turbo Draft** — cursor completion, next-edit prediction, and reviewable whole-file drafts | | **Models** | Usually one provider's models | **BYOK + hosted + an auto router** that escalates when needed | | **Browser** | None, or basic click/screenshot | **Playwright-grade browser** that can inspect, clone pixel-perfect, and drive flows | | **Design** | — | **Discover + web builder** — hundreds of designs any agent can build | | **Your other agents** | Locked out | **Any agent can borrow V3Code's brain** — index, call graphs, memory, served over MCP | | **Theming** | Install a theme extension | **Built-in color picker**, no extension | | **Price of the editor** | Subscription to use it | **Free** — you pay only for hosted extras | ## What actually makes the difference **Your code stays yours.** V3Code indexes locally and is BYOK-friendly. Ask "what breaks if I change this?" and it answers from a local structural map — see [Context Bridge](/editor/context-bridge) and the [semantic index](/editor/semantic-index). **It remembers.** Close it, come back, and the agent still knows your project — without stuffing the context window. See [Memory](/editor/memory). **It keeps the small work in flow.** [V3Code Tab and V Go](/editor/tab-and-v-go) cover autocomplete and next-edit prediction; [Turbo Draft](/editor/turbo-draft) turns the unfinished intent already in a file into a complete diff you review hunk by hunk. **It reaches past the editor.** A [browser](/studio/browser) the agent drives like a developer, a [design platform](/studio/web-builder) to build from, and the ability to expose all of V3Code's tools to [any other agent over MCP](/connect/other-agents). **You're not locked to one model.** Bring your own keys, or let the [auto router](/models/overview) pick and escalate — tuned to keep prompt caching intact so it stays cheap. ## The sentence nobody else can say Other AI editors compete on whose agent is smarter. **V3Code also makes every other agent smarter.** The intelligence layer — the local index, the call graphs, the persistent memory — is served over a local MCP endpoint, so Claude Code, Cursor, or any MCP client can use *V3Code's brain with their own hands*: they bring their editing and terminal tools, and borrow the structural understanding of your codebase. Write tools are deliberately not exposed — brains out, hands stay home. See [Bring V3Code to any agent](/connect/other-agents), including the drop-in skill that makes an agent actually reach for it. ## On pricing The editor is free. Paid plans add the hosted pieces — the auto router and cloud indexing — with more coming over time. And if your local index ever breaks, cloud indexing kicks in **free** so you're never stuck. See [Plans](/models/plans-and-trials). # Coming from VS Code V3Code is a fork of VS Code, so it should feel like home from the first launch — your muscle memory, keybindings, and the extension ecosystem all carry over. And you don't have to rebuild your setup by hand. ## Transfer your setup In **Settings → Transfer**, pull your extensions and settings from an editor you already use: - **Transfer from VS Code** - **Transfer from Cursor** - **Transfer from Windsurf** One click brings your existing configuration into V3Code, so you start where you left off instead of from a blank slate. ## What's different The editor is familiar; the intelligence is what's new. Once you're in, the parts worth learning are the agent [modes](/editor/modes), [Context Bridge](/editor/context-bridge), and [memory](/editor/memory) — the things a plain VS Code fork doesn't have. # Modes V3Code's mode picker changes what the agent is allowed to do with a turn. Your selected model, keys, and project stay the same; the tool and approval boundaries change. Open the picker in the chat composer to switch modes. ## Built-in modes | Mode | What it does | Reach for it when | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | **Chat** | Conversation without callable tools. | You want a quick answer or want to discuss attached context without the agent taking action. | | **Read** | Read-only investigation with search, index, memory, and structural tools but no source edits or terminal commands. | You want the agent to inspect the real project and report back. | | **Plan** | Read-only investigation plus Markdown plan documents. | You want a grounded implementation plan before execution. | | **Debug** | Reproduces, localises, proves, fixes, and guards one bug with a bounded tool surface. | A failure needs evidence and a minimal verified repair. See [Debug mode](/editor/debug-mode). | | **Multitask** | Acts as a foreman: plans, dispatches work agents, and reconciles their results. The coordinator does not directly edit source or run terminal commands. | A larger job can be divided into independent pieces. | | **Agent** | Full execution — reads, edits, runs commands, the whole tool set. | You're ready to ship a change end to end. | Custom agents appear below the built-in modes. **Configure Custom Agents** opens the agent setup screen, including compatible ACP agents. See [External agents in native chat](/connect/agent-client-protocol). ## Approvals: what needs your OK Modes control *what class* of action the agent takes; **approvals** control whether a given action runs automatically. Reads are automatic. Actions that change things ask first, grouped into a few classes: - **Edits** — creating, deleting, rewriting, or editing files, renaming symbols, generating images. - **Terminal** — running commands, the test runner, the sandbox, and any git write (commit, push, checkout…). - **Browser & notes** — navigating/typing/clicking in the browser, and saving persistent notes. Read-only tools (reading files, searching, structural lookups, git status/diff) do not prompt. Modes can narrow the available tools further. Debug, for example, allows a small approval-gated repair surface but withholds deletes, git writes, browser mutation, and MCP tools. ## Modes vs. the V3 / IDE layout Don't confuse the agent's modes with the **V3 / IDE** pill in the title bar — that switches the *layout* (full-screen chat vs. classic editor), not the agent's behavior. > Note: > > **Design** and **Cyber Protection** are composer options, not modes. Design activates > the [design workflow](/editor/design-mode); Cyber Protection activates the > [security workflow](/editor/cyber-protection). # Plan mode ## Start with a question Choose **Plan** from the chat composer's mode picker. Describe the outcome, constraints, and what needs deciding. Include the relevant files or project context. For example: > Investigate how sign-in works. Propose the smallest change that adds a retry state. > Identify affected files, risks, and tests. Save the plan; do not implement it yet. ## What Plan can do Plan has read-only investigation tools plus file-writing tools intended for Markdown plans. These writes still pass through approval handling. It can save a plan such as `PLAN.md` or `docs/plans/sign-in-retry.md`. Non-trivial plans can open in a rendered preview alongside chat. Plan is not a promise that nothing is written: plan documents and memory can be updated. Source-code changes and terminal execution belong in an implementation mode. Delegated work in Plan uses the read-only research profile. ## Review before implementation A useful plan names the files involved, explains alternatives, identifies risks, and defines how the result will be tested. Read the saved document and correct assumptions. Then explicitly switch to **Agent** and ask it to implement the approved plan. A saved plan is not an executed change. Check the actual diff and test results afterward. See [Modes](/editor/modes), [Debug](/editor/debug-mode), and [Subagents](/editor/subagents). # Skills ## What a skill contains A skill is a named set of instructions for a repeatable task. V3Code reads a Markdown body and a small frontmatter block. A skill guides the agent; it does not install new tools, grant permissions, or guarantee that its instructions will be followed. ## Add a project skill Create `.v3code/skills/review-change/SKILL.md` in your workspace: ```markdown --- name: review-change description: Review a proposed change for correctness and missing tests. keywords: - review globs: - "**/*.ts" --- Read the relevant source and diff before making claims. Identify behavior changes and edge cases. Report findings with file references and a suggested verification step. Do not change files unless asked. ``` Keep the body concrete. Explain inputs, expected outputs, checks, and stopping conditions. Do not include secrets. ## Where skills come from Skills load from bundled product skills, then `~/.v3code/skills`, then workspace `.v3code/skills`. A later skill with the same name overrides an earlier one. The loader also checks immediate child folders for workspace skill directories. It accepts skill folders containing `SKILL.md` and individual `.md` or `.mdc` files. ## Supported metadata | Field | Purpose | | ----------------- | --------------------------------------------------------- | | `name` | Skill name; filename or folder name is the fallback | | `description` | Short task description for the catalog | | `globs` or `glob` | File-pattern triggers | | `keywords` | Keyword triggers | | `alwaysApply` | Request always-active instructions | | `loadOnDemand` | Use a pointer so the full skill can be loaded when needed | | `catalog: false` | Omit from the visible skill catalog | Ask the agent to use the skill by name and verify that it loaded the expected instructions. The native agent has a `read_skill` tool for retrieving a skill by name; bundled skills are not necessarily accessible as workspace files. ## Troubleshooting Check the folder location, frontmatter, non-empty body, and duplicate names. The loader caches skills, so newly created files may not appear immediately. Reopen the editor if necessary. An ACP agent may use its own skill discovery instead of V3Code's native catalog. See [Project instructions](/editor/project-instructions) for rules that apply across tasks. # Project instructions and AGENTS.md ## Add repository guidance Create `AGENTS.md` at the workspace root. Describe how to work in the project, not a transcript of everything that has happened. ```markdown # Project guidance ## About This repository contains the web application and its tests. ## Working rules Keep changes scoped to the requested feature. Preserve unrelated work. Do not deploy without explicit approval. ## Verification Read package.json for the available scripts. Run the tests relevant to the files changed. Report checks that could not be run. ``` These instructions help the agent understand conventions. They are not a security boundary and do not replace tool approvals. ## Files the native agent reads The shipped editor loads workspace-root `AGENTS.md`, `.github/AGENTS.md`, `.github/copilot-instructions.md`, `CLAUDE.md`, `.voidrules`, `.v3coderules`, and `.cursorrules`. Existing compatibility filenames can be retained. Do not assume nested instruction files have the same discovery rules as another agent. For an ACP agent, check that agent's instructions and configuration separately. ## Keep instructions small Large files consume context. The editor caps instruction injection; root AGENTS.md has a smaller cap and some history-oriented sections are treated separately. Keep active guidance short and link to longer reference documents. Use [Memory](/editor/memory) for durable project facts and [Skills](/editor/skills) for reusable task procedures. Avoid putting secrets or stale task lists in either. ## Check what the agent understood Ask it to summarize the applicable project rules and identify their files before a sensitive change. If the summary is wrong, correct the instructions or explicitly attach the relevant document. A model repeating a rule does not prove compliance. # Subagents and parallel work ## Give each worker a bounded task The native agent can delegate independent work to child agents. A good task names the objective, files in scope, constraints, and the evidence expected back. > Ask a research worker to locate the authentication flow while you review the tests. > Do not let either task edit files yet. Child agents do not automatically receive the entire parent conversation. Their instructions need enough context to stand on their own. ## Work and research profiles **Work** children inherit enabled tools, with the applicable approvals. **Research** children are read-only. Plan mode forces delegated work into research; Debug also uses research delegation. [Multitask mode](/editor/modes) separates coordination from mutation by workers. The shipped background-delegation implementation allows three running children per parent, eight per window, and nesting depth two. Additional work can queue. These are concurrency bounds, not a promise that a provider will have capacity. ## Watch and verify Background launches return before the work is complete. Status is available in the Agents panel, and results return as notifications. Do not interpret a launch receipt as a finished task. Avoid overlapping file ownership. Parallel workers are not automatically isolated Git worktrees. Review the combined diff, reconcile conflicting findings, and run integration checks before accepting the result. External [ACP agents](/connect/agent-client-protocol) may have different delegation features and limits. These instructions describe the native V3Code agent. # Permissions and approvals ## Read the requested action Review file paths, commands, and service access before approving an action. A permission request is not proof that an operation is safe. Decline requests outside the task. The native tool registry separates file edits, terminal commands, MCP tools, computer control, and project changes. For example, opening a project changes the active editor context; terminal approval also covers Git writes and persistent command execution. ## Modes narrow the tool set [Read and Plan](/editor/modes) offer a narrower workflow than Agent. [Debug](/editor/debug-mode) has a bounded repair tool set. [Subagents](/editor/subagents) inherit the relevant execution profile and approval boundaries; delegation should not be treated as a way to bypass them. Memory updates are not source-code edits and do not use the same approval category. Read-only investigation can still produce memory notes. ## External tools have their own boundaries Review each MCP connector before enabling it. Browser access can include authenticated pages. An ACP agent's own permissions and runtime also matter; native-mode restrictions should not be assumed to govern every external agent. ## Approval is not a sandbox A tool confirmation does not mean every command runs in a fully isolated operating system. Do not assume a universal network block or filesystem sandbox. Work only in trusted projects, keep credentials out of prompts, and use separate environments for untrusted code. See [Privacy](/account/privacy), [MCP](/connect/mcp), and [Other agents](/connect/other-agents). # Worktrees and isolated changes ## A separate checkout, shared history A Git worktree gives a task its own working directory and branch. It is useful for parallel changes or experiments that should not touch your current checkout. Subagents alone do not provide this isolation. Workers can edit the same files unless their tasks and workspaces are explicitly separated. ## Ask for an isolated task > Inspect git status and existing worktrees. Create a separate worktree for this fix, > keep the current checkout untouched, and report the branch and commit after testing. > Do not merge, push, or remove anything without asking. Choose names and locations that make sense for the repository. A fresh worktree may not contain ignored dependencies or generated files; account for those before testing. ## Review and bring the change back Check the diff and test results in the worktree, then deliberately merge or cherry-pick the approved change. Keep unrelated user work intact. Report the exact branch and commit so the handoff can be verified. ## Cleanup is a separate action The native repository hygiene tool can plan cleanup and perform targeted push, remove, or prune actions behind terminal approval. Review its plan first. Do not remove a checkout with uncommitted or unpreserved work. Worktrees isolate files; they are not security sandboxes and do not isolate all external services or credentials. # Chats and session continuity ## A conversation is not a running process V3Code stores native chat threads locally and lets you switch between them. Background subagents are also persisted threads that can be opened from the Agents panel. A saved transcript does not mean a model request or terminal process is still running after the application closes. Use **New Chat** for a fresh conversation. When continuing an existing task, reopen its conversation and check the project, selected model, and last completed action before asking the agent to proceed. ## Keep a handoff outside the transcript For longer work, ask the agent to record the objective, decisions, changed files, and remaining verification in a project document. Review it for accuracy. [Project instructions](/editor/project-instructions), [Memory](/editor/memory), and chat history serve different purposes. A new conversation does not automatically receive every detail of a previous one, and compacted context is not an exact replay. ## Background work The native agent supports background delegation and persistent terminal commands. Check their reported status rather than assuming a completed chat response means all background work finished. Ask for the command output or worker result. Before switching projects, verify where active tasks are working. Before closing the editor, preserve changes and record what is unfinished. ## Troubleshooting If a conversation appears to have stalled, check for an approval request or provider error. An unexpected-error message may allow you to continue by sending another message; inspect the last action first to avoid duplicating a write. Report the editor version, operating system, mode, provider, and the visible error without including credentials. External ACP agents may have separate session storage and recovery behavior. # Debug mode **Debug** is a permanent built-in mode for evidence-first repair. It is not a renamed Agent mode: it gives the model a stricter workflow and a deliberately smaller tool set. ## Use it ![The composer mode menu with Debug as a built-in option](/images/mode-picker-0098.png) Choose Debug from the mode menu before describing a failure. Screenshot supplied September 17, 2026. 1. Open the mode picker in the chat composer. 2. Choose **Debug**. 3. Describe what you expected, what happened, and the shortest reproduction you know. 4. Let the agent reproduce and localise the failure before approving a fix. 5. Confirm whether the repair worked when V3Code asks. Debug mode keeps instrumentation until the result is verified. The workflow is: reproduce, localise, rank plausible causes, prove or refute them, make the minimal fix, add a guard, then report the evidence. Failed theories stay visible as **refuted** instead of disappearing from the transcript. ## What Debug can do Debug receives the read-only investigation tools plus approval-gated file edits, commands, and tests. It does **not** receive delete, git-write, browser-mutation, or MCP tools. Any delegated helper is restricted to research. That boundary is intentional: Debug is for repairing the reported failure without turning the session into an unrelated refactor. ## A transcript built for investigation Debug transcripts expose the lifecycle of each operation: preparing, waiting for your approval, running, succeeded, failed, cancelled, or skipped. Active operations, questions, approvals, and failures remain individually visible. Completed operations can be grouped to keep a long investigation readable. The `v3code.chat.transcriptDensity` setting controls completed-operation grouping: - `verbose` keeps every operation separate. - `standard` groups adjacent successful operations of the same kind. - `compact` groups adjacent successful operations across kinds. - `minimal` also starts single completed cards collapsed. This setting affects Debug transcripts only. ## Runtime evidence In a trusted single-folder workspace, Debug can start a loopback-only evidence sink and pin new runtime evidence to the active investigation. Each user turn creates a run boundary so old evidence is not mistaken for a new reproduction. If the workspace is untrusted, has multiple roots, or the sink is unavailable, Debug continues with the normal read and test tools. It should not claim that runtime evidence was collected when the sink did not start. > Note: > > Debug mode improves the discipline and visibility of an investigation. It does not > guarantee that every bug can be reproduced automatically; hardware, credentials, > external services, and user-only actions may still require your help. # Cyber Protection Cyber Protection is an extra review aid for the current agent. It helps the agent surface possible security concerns it might otherwise overlook while reading or changing a project. Open the model picker in the composer and turn on **Cyber Protection** before asking for a security-focused review. It is not a promise that the project is secure, a complete vulnerability audit, or a replacement for experienced human review, runtime testing, and dedicated security tools. ## Turn it on ![Model picker options with the Cyber Protection toggle below Design](/images/composer-options-0098.png) Cyber Protection is an option in the composer’s model picker, not a separate chat mode. Screenshot supplied September 17, 2026. 1. Open the model picker in the composer. 2. Enable **Cyber Protection**. 3. Describe the part of the project you want reviewed and any specific concerns. 4. Ask the agent to separate confirmed findings from leads that still need investigation. The expected result is a review with evidence and limitations—not a security certificate. ## What changes when it is on The agent can start with the built-in `security_scan` tool. On supported workspace source, the scanner builds a code-property graph and looks for suspicious paths from untrusted data toward dangerous operations. It can flag patterns associated with SQL and command injection, cross-site scripting, server-side request forgery, path traversal, prototype pollution, unsafe deserialization, regular-expression denial of service, hardcoded secrets, and weak cryptography. The agent is then prompted to consider concerns a pattern scanner cannot decide by itself, such as ownership checks, authorization, rate limits, payment or role logic, and other application-specific trust boundaries. These are review leads, not automatically verified vulnerabilities. ## Read the results critically Potential findings include a location, severity, explanation, and suggested repair. A scan journal under `.v3code/` lets later runs distinguish new, fixed, and still-open findings. The scanner currently models JavaScript and TypeScript most deeply, with partial Python coverage. Unsupported languages and framework-specific behavior still require manual review. False positives and missed issues are possible, and a zero-finding result is not proof that an application is secure. Secrets-shaped paths such as environment files, private keys, and common credential directories are excluded from scanning. The workflow is defensive: it should explain and repair vulnerabilities, not create exploits or weaken a check to make the report green. ## A useful first prompt ```text Review this project with Cyber Protection. Start with the scanner, then examine the authorization and ownership checks around the highest-risk data flows. Report verified issues worst-first and separate them from anything that still needs runtime proof. ``` > Tip: > > Run the scan again after the fixes. The journal comparison is more useful than treating > one report as a security verdict. # Quick Edit Quick Edit is V3Code's focused inline rewrite surface. Select the code you want to change, press `Ctrl + K` on Windows/Linux or `Cmd + K` on macOS, and describe the result in plain language without leaving the file. It is deliberately narrower than chat: the selected lines are the edit boundary. ## Make an inline edit ### Select the target Highlight the lines you want to rewrite. If the selection is empty, Quick Edit uses the current line. ### Open Quick Edit Press `Cmd + K` on macOS or `Ctrl + K` on Windows/Linux. An instruction box appears directly below the selected region. ### Describe the outcome Write a concrete instruction such as “validate empty email addresses and return the existing error type” or “convert this callback to async/await without changing the public signature.” Press `Enter` to submit; use `Shift + Enter` for a new line. ### Review the diff V3Code streams the replacement into an inline diff. Keep the result only after you have inspected the changed lines. Press `Escape` to close or cancel the Quick Edit zone. ## What context it receives Quick Edit sends the selected lines together with bounded code before and after the selection. The prompt instructs the model to replace only the selected region and to preserve balanced syntax around it. Because the boundary is explicit, Quick Edit is ideal for: - Rewriting one function or branch. - Adding validation inside an existing handler. - Converting a small callback or loop to a clearer form. - Tightening types or error handling in a known region. - Reworking selected prose or documentation. Use [V3Code Tab](/editor/tab-and-v-go) when you want promptless completion at the cursor. Use [Turbo Draft](/editor/turbo-draft) when the entire file contains enough intent for a larger draft. Use [Agent mode](/editor/modes) when the request must search other files, run commands, or verify the full application. ## Model selection Quick Edit has its own model selector in the inline instruction box. It does not have to use the same model as Chat, Autocomplete, V Go, Apply, or Turbo Draft. That separation lets you choose a fast, economical model for bounded rewrites while reserving a deeper model for agent work. The context and request go to the provider of the Quick Edit model you selected. ## Write better instructions Good Quick Edit instructions name the target behavior and the important constraint: | Vague | Better | | ------------ | -------------------------------------------------------------------------------------------- | | “fix this” | “Return the existing `ValidationError` when `email` is empty.” | | “make async” | “Convert this callback to async/await; keep the function signature and error mapping.” | | “clean up” | “Remove the duplicate branch without changing the order of side effects.” | | “add types” | “Replace `any` with the existing `Invoice` and `LineItem` types; do not add new interfaces.” | You do not need to paste the surrounding file into the instruction box; V3Code already includes bounded prefix, selection, and suffix context. ## Troubleshooting ### Quick Edit changed too much Cancel the zone, make a smaller line selection, and restate the constraint. For a rename across references, use the language-aware Rename Symbol action instead of a generative rewrite. ### The replacement breaks surrounding syntax Reject it and retry with the required signature, return shape, or bracket constraint stated explicitly. Quick Edit asks the model to balance the replacement, but the result still requires review and project validation. ### Nothing happens after submission Confirm a model is selected in the Quick Edit box and that its provider credentials or local service are available. Quick Edit has a separate model slot from Chat. ### Another review is already open Finish or close the existing Quick Edit or Turbo Draft review in that file before starting a second overlapping edit transaction. # V3Code Tab & V Go V3Code has two in-editor prediction layers. **V3Code Tab** completes what you are typing at the cursor. **V Go** watches the edit you just made and predicts the next change point — sometimes somewhere else in the file. They share the same goal: keep small, obvious work out of chat. They are separate from [Turbo Draft](/editor/turbo-draft), which drafts a complete, reviewable change. ## Pick the right layer | Layer | Best for | How it appears | How you accept | | --------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -------------- | | **V3Code Tab** | Finishing a line, block, pattern, or nearby implementation | Ghost text at the cursor | `Tab` | | **V Go** | The likely follow-up edit after you pause | A predicted change point in the editor and Agents rail | `Tab` | | **Turbo Draft** | A whole-file or related multi-file change | Reviewable diff hunks | `Tab` per hunk | ## V3Code Tab Tab is fill-in-the-middle autocomplete: it reads the code before and after the cursor, then proposes the missing code instead of only continuing from the end of a file. It can also receive a small packet of related repository context from V3Code's local index. That means suggestions can follow patterns from neighboring files rather than treating the open editor as an isolated snippet. ### Start typing Open a source file and begin a function, condition, test, or repeated pattern. ### Read the ghost text V3Code renders the proposed completion inline. Keep typing to steer it, or press `Escape` when the suggestion is not useful. ### Accept with Tab Press `Tab` to keep the suggestion. V3Code records accepted edits as recent context, which can help V Go and Turbo Draft understand the task already in motion. ### Local by default, cloud when you choose Fresh installs select V3Code's built-in local code model for Autocomplete and Next Edit. It is designed to give you a zero-key baseline without sending the completion request to a hosted model. If you want a stronger completion model, open **Settings → Features → Autocomplete** and choose a compatible cloud FIM model after adding that provider's key. Autocomplete has its own model slot, so changing it does not change your Chat model. > Note: > > A cloud autocomplete model sends the context required for that completion to the > provider you selected. The built-in local model runs on your machine. ## V Go: next-edit prediction Autocomplete answers, “What code belongs at the cursor?” V Go answers, “Given the edit you just made, where and what are you likely to change next?” After you edit and pause, V Go can use the current file, recent changes, related indexed code, and structural context to prepare one next change point. The **V Go** strip in the Agents rail shows its state: | State | Meaning | | -------------------------- | -------------------------------------------------------------- | | **Watching your edits** | V Go is enabled and waiting for a useful change signal. | | **Predicting next edit…** | It is evaluating the likely follow-up. | | **Ready · 1 change point** | A prediction is ready; press `Tab` or open V Go to inspect it. | | **Next edit off** | Autocomplete/V Go is disabled. | The status bar also exposes V Go. Click it to open the dock, or run **Focus V Go** from the Command Palette. Run **Toggle V Go / Next Edit** to turn the prediction layer on or off. ### Accept or reject - Press `Tab` when V Go says a next edit is ready to apply it. - Press `Escape` to reject the pending prediction. - Click the change point in the V Go dock to reveal its file and line before deciding. V Go deliberately prepares one change point at a time. For a larger intent that needs a whole-file pass, use [Turbo Draft](/editor/turbo-draft); for a multi-step task with tests and terminal work, use [Agent mode](/editor/modes). ## Settings Open **Settings → Features → Autocomplete** to: - Turn Autocomplete and V Go on or off. - Pick separate models for **Autocomplete** and **Next Edit / V Go**. - Add a provider key for compatible cloud completion models. Two advanced settings are available in the normal Settings editor: | Setting | Default | Does | | --------------------------------- | ------- | ---------------------------------------------------------------- | | `v3code.tab.disabledLanguages` | `[]` | Disables V3Code Tab for selected language IDs. | | `v3code.tab.enablePartialAccepts` | `false` | Allows accepting the next word instead of the entire suggestion. | ## Troubleshooting ### No ghost text appears Confirm Autocomplete is enabled under **Settings → Features**, then check that its selected model is available. A first-run local-model download may still be finishing. Also check `v3code.tab.disabledLanguages` for the current language. ### V Go stays on Watching your edits Make a real source edit and pause. V Go suppresses weak or unsafe predictions rather than forcing a suggestion after every keystroke. Confirm the local index is healthy if repository context is missing. ### Tab accepts the wrong UI action Suggestion widgets, snippets, autocomplete, V Go, and Turbo review can all use the Tab family. Press `Escape` to dismiss the UI you do not want, then retry the intended action. During Turbo Draft review, Tab is intentionally reserved for accepting the current hunk. ### Cloud completion fails but chat works Autocomplete and Next Edit use separate model slots and require completion-compatible models. Reopen **Settings → Features** and verify those two selections rather than the Chat selection. # Turbo Draft Turbo Draft is the step between autocomplete and a full agent task. Put the cursor in a file, press a shortcut, and V3Code infers the unfinished intent, gathers relevant code and compiler facts, then returns a diff you review hunk by hunk. It does **not** silently save, commit, or publish anything. You decide which hunks stay. > Note: > > The product name is **Turbo Draft**. “Turbo Boost” is sometimes used conversationally, > but it is not a separate V3Code feature or command. ## When to use it Turbo Draft is a good fit when the work is visible in the editor but would be tedious to spell out in chat: - Finish a partially implemented file. - Turn a short comment-only brief into a scaffold. - Implement a nearby `TODO` or `FIXME`. - Complete work described by an open `plan.md`, `spec.md`, or similar document. - Make a deeper pass that follows the callers of the code you are changing. - Finish prose or documentation from the intent already on the page. Use a normal refactor for a deterministic rename. Use [Agent mode](/editor/modes) when the task needs exploration, clarification, commands, tests, and several iterations. ## Run a draft | Action | Shortcut | Reach for it when | | ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ | | **Turbo Draft** | `Shift + Tab` | You want the quickest bounded draft in the current file. | | **Turbo Draft (Deep)** | `Alt + Shift + Tab` | The file needs a more complete context-aware pass. | | **Turbo Draft (Deep, multi-file)** | `Ctrl + Shift + Q` on Windows/Linux; `Control + Shift + Q` on macOS | The change should follow related callers, up to three files. | You can also run all three actions from the Command Palette or the editor title/context menus. ### Leave a useful signal Select the most important instruction, place the cursor near a `TODO`, write a short comment-only brief in a new file, or keep the relevant plan document open. ### Choose Fast or Deep Press the shortcut. The Turbo Draft dock reports real phases such as reading, recognizing intent, finding context, validating, and creating review tabs. ### Review every hunk Press `Tab` to accept the current hunk, `Delete` or `Shift + Tab` to reject it, and `Escape` to discard the remaining draft. ### Verify normally Turbo Draft checks for newly introduced diagnostics after review. You should still run the project's relevant formatter, type-check, tests, and build before shipping. ## How it understands intent Turbo Draft looks for intent in a deliberate order so an old project plan does not override what you are doing now: 1. Your current editor selection. 2. The nearest `TODO`, `FIXME`, `HACK`, or `XXX` around the cursor. 3. A nearly empty, comment-only file brief. 4. An open plan-like Markdown file. 5. A general whole-file pass when none of the above exists. The request can combine the current file, cursor position, recent accepted Tab/V Go edits, recent agent-chat context, related indexed code, and live language-service facts. ## Compiler truth With **Use compiler truth** enabled, Turbo Draft asks the language server for current evidence before it generates: - Errors and warnings in the file. - Nearby real symbol signatures. - Call sites related to the code near the cursor. That gives the model actual types and diagnostics instead of asking it to infer them from lookalike code. The packet is time-bounded, so a slow or unavailable language server can produce partial context. ## Fast, Deep, and multi-file ### Fast Fast mode favors a smaller context packet and a bounded answer. Use it for an obvious unfinished block, a small scaffold, or a short document section. ### Deep Deep mode asks for a more complete file-level result and uses related code and chat context more aggressively. Use it when “finish this” means understanding the shape of the whole file. ### Deep multi-file Multi-file mode starts with the active file, then follows computed related callers in a small queue. It is intentionally bounded; it is not an unconstrained repository rewrite. For migrations or architectural work, plan the change and let Agent mode execute and test it incrementally. ## Safety and review Turbo Draft does more than paste a model response into the editor: - It accepts only anchored search/replace blocks or an explicit no-change result. - It rejects missing, ambiguous, empty, or no-op edit anchors. - It can ask the model once to repair malformed edits. - It can salvage independently valid hunks when another hunk fails validation. - It discards the draft if the source changed while generation was running. - It applies valid work through V3Code's normal diff review surface. - It compares diagnostics before and after review and can draft a narrow fix for new errors. These checks protect the edit transaction; they do not prove that the change is correct for your application. Human review, tests, and builds still matter. ## Model and feature settings Open **Settings → Features → Turbo Draft**. | Control | Default | Does | | ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------- | | **Same as Chat model** | Off | When enabled, Turbo Draft follows the eligible cloud model selected for Chat. | | **Turbo Draft model** | Not selected until configured | Lets you dedicate a compatible cloud chat model to drafting. | | **Use compiler truth** | On | Adds live diagnostics, signatures, and call sites when available. | | **Verify draft** | On | Checks accepted work for newly introduced errors and can prepare a focused repair. | Small local FIM models are designed for Autocomplete and V Go, not whole-file drafting, so Turbo Draft requires a compatible cloud chat model. ## Review shortcuts | While reviewing | Shortcut | | ------------------------------- | ---------------------------------------------------- | | Accept current hunk and advance | `Tab` | | Reject current hunk and advance | `Delete` or `Shift + Tab` | | Discard all remaining hunks | `Escape` | | Cancel an active generation | Run **Turbo Draft: Cancel** from the Command Palette | ## Troubleshooting ### V3Code asks me to pick a model Open **Settings → Features → Turbo Draft** and choose a compatible cloud chat model, or turn on **Same as Chat model** when Chat already uses one. ### Turbo Draft returns no changes Give it a stronger local signal: select the instruction, add a nearby `TODO`, or put a concise comment-only brief at the top of a new file. Deep mode is a better fit when the intent depends on the whole document. ### The draft was discarded because the source changed The file changed while the model was working, so V3Code rejected the stale result. Keep the new typing, then run the draft again against the current source. ### Compiler truth is empty or incomplete Confirm the language extension for that file is active and that the Problems panel, hover, and references work normally. Turbo Draft can continue with partial context, but you should verify the result more carefully. ### The draft is structurally valid but wrong Reject the hunk. Quality gates verify safe anchoring and review flow, not your business requirements. Use Agent mode when the work needs tests, interactive clarification, or a longer feedback loop. # Design mode Ask most agents to "make it look good" and they invent a look — usually the same generic, AI-flavored one. V3Code's **Design** capability doesn't invent. When you ask for anything visual, it opens a **live gallery of 169 proven, production-grade design directions** and builds your UI from the one *you* pick. ## How it works 1. **Ask for design** — "build a landing page," "make it look good," "give me a dark-premium dashboard," or name an aesthetic. 2. **Pick from the gallery** — V3Code opens a browsable gallery in its built-in browser. You choose a design direction (a "plugin") and add a quick brief. Each direction is a real, coherent system — color, typography, spacing, components — not a mood board. 3. **The agent builds it, section by section** — against that direction's spec *and* the craft laws, so every section is on-system from the first draft. 4. **Refine with Love / No / Note** — react to each section: **Love** locks it, **No** regenerates it, **Note** lets you type exactly what to change. The build converges on what you actually want. ## Craft laws: quality you can check The gallery gives the agent a real system; the **craft laws** keep it honest. These are enforceable rules, not taste — they ban the tells of AI-generated UI (the default indigo accent, emoji icons, filler copy) and enforce real discipline: a limited number of accent uses per screen, a proper type scale, contrast gates. That combination — a proven direction *plus* checkable rules — is why the output looks designed, not generated. ## What it's for Any user-facing visual deliverable: **websites, landing pages, dashboards and app skins, marketing pages, portfolios, slide decks.** For a one-line CSS tweak it stays out of your way — you don't get a gallery for a color change. ## Where the gallery lives The 169 directions and craft laws live in a **separate design library** (forked from Open Design) so the editor stays lean — the agent pulls from it on demand. It's the same library behind [Discover](/studio/discover) and the [web builder](/studio/web-builder); Design is how the agent turns a pick into real, on-system code, which you can then preview and tweak live with [Visual Edit](/studio/live-previews). # Context Bridge Most AI editors hand the model a pile of text and hope the right lines are in it. V3Code ships **Context Bridge**: a set of native, language-server-backed tools the agent calls to navigate your codebase structurally — definitions, callers, callees, references, type hierarchies, dependency graphs, and persistent notes. It's compiled into the editor, always on, and nothing leaves your machine. ## Why it's built in, not bolted on Context Bridge is **native — not an MCP server, not an external process, no daemon to start and no path to configure**. The language-server bridge lives inside the V3Code binary. Open a project and the agent can already navigate it: it asks the same TypeScript/LSP services your editor uses, in process. That's the difference between "find the string `handleAuth`" and "show me every caller of `handleAuth`, its type hierarchy, and the two diagnostics on its signature." The agent traces real edges instead of guessing from text — so when you ask *what breaks if I change this*, it already has the map. Two design choices keep the output high-signal: - **Stdlib and dependency noise is filtered.** Callers/callees that resolve into `node_modules` or a `lib.*.d.ts` (Promise.all, Array.filter, and friends) are dropped — they're never actionable and they eat the token budget real edges need. - **Syntactic fallback when the language server is cold.** If the TS server hasn't analyzed a file yet, Context Bridge returns a top-level declaration scan so a real code file never looks symbol-less, and flags it so the agent knows to retry once the server is warm. ## The 11 tools Context Bridge exposes eleven tools in three groups. Write-side note tools require approval; reads are unrestricted. ### Structural & briefing ### get\_file\_context A file's structural map — its symbols, imports (text-parsed, always available), and diagnostics. Function-local variables are stripped so the outline is the top-level + member skeleton, not every loop counter. ### get\_file\_dependencies Direct imports (resolved to files), external packages ranked by frequency, and — the useful half — everything that imports *this* file back (`importedBy`). Scans up to 2000 workspace source files. ### get\_symbol\_context A symbol's full neighborhood: definition snippet, callers, callees, references, nearby diagnostics, supertypes/subtypes (for class/interface/enum/type), and any persistent notes attached to it. Resolves via LSP, falls back to text. ### get\_call\_graph A recursive caller/callee tree, `depth` 1–4 (clamped). Cycles are de-duplicated; stdlib/dependency nodes are skipped so the tree stays actionable. ### pack\_context A token-budgeted bundle for a symbol, shaped by `task` — `understand`, `refactor`, `debug`, or `extend` — each with different caps on callers/references/snippet size. Trims to fit `maxTokens` (references first, then caller snippets) and reports what it dropped. ### get\_project\_briefing A session-opening orientation: pulls `Recent Changes` / `Session Memory` sections from `AGENTS.md` (or `.github/AGENTS.md` / `copilot-instructions.md`), a depth-3 curated file tree, the last \~20 git commits, and optionally your saved notes. This is how the agent starts already knowing the project. ### Notes (persistent memory) ### remember Attach a durable note to a symbol. Survives across sessions. Stored in `.v3code/notes.json` in the workspace. Requires approval. ### forget Remove a note by id. Requires approval. ### list\_notes List notes for a file, or all workspace notes when `null`. ### Search ### find\_text Grep with context and paging — exact/regex text search across the workspace. ### semantic\_search Meaning-based search over the local [semantic index](/editor/semantic-index). Returns ranked hits with the index state; optional rerank pass. See that page for how ranking works. > Note: > > `remember` / `forget` / `list_notes` are the storage layer under [Memory](/editor/memory). `semantic_search` is the query layer over the [Semantic index](/editor/semantic-index). Context Bridge is the connective tissue that makes both structural. ## Bring Context Bridge to any agent Context Bridge isn't locked inside V3Code's own chat. The same tools can be exposed over a single MCP endpoint so Claude Code, Cursor, or any MCP client gets the same structural view of your codebase. See [Bring V3Code to any agent](/connect/other-agents). ## Your code stays local Every tool here runs on your machine against your own language server and files. The only network traffic V3Code makes is the model calls you choose, with your own keys. See [Privacy](/account/privacy). # Memory The worst part of working with an agent is that it forgets. Close the chat and the next session starts cold — you re-explain your stack, your conventions, the quirk in that one file. V3Code is built so that never happens, and it does it without stuffing everything into the model's context. ## The idea: never forgets ≠ never forgets *on the wire* "Never forgets" is a **pull guarantee, not a push burden**. Everything the agent ever saw — every prompt, reply, tool result, edit, and decision — is written to disk and instantly recallable. That does **not** mean it's all shoved into the model every turn. The opposite: the agent holds only the **live task** in context and pulls the rest the instant it needs it. A chat assistant's job is the conversation, so it clings to the transcript. An editor's job is your **code and your current intent** — the conversation is scaffolding. So V3Code keeps the live wire small *because* nothing is lost and recall is excellent. This also dodges "context rot": a stuffed context window makes a model perform worse, not better, so bounded-but-generous beats racing toward a million tokens. ## The tiers ### Native window The recent raw turns the model holds itself. Cheapest, highest-fidelity memory there is — V3Code doesn't interpose on it. ### Session digest A running fact-sheet of the middle turns that scrolled off. Once it exists it stays on the wire for the rest of the session — the agent's own memory of what it already did. ### Cross-session memory Workspace facts, symbol notes, past sessions, other projects. Salience-ranked, scoped to what you're touching, mostly pulled on demand. ### Shadow floor A raw, append-only record of every event. Never pruned. The break-glass guarantee behind "never forgets" — always recallable, never auto-injected. ## What persists across sessions - **Workspace memory** — decisions, conventions, and notes tied to a project, surfaced when you're in that project. Symbol notes live in `.v3code/notes.json` (see [Context Bridge](/editor/context-bridge)). - **Global profile** — style and preferences that travel with you across every project. - **The full record** — anything condensed or elided off the wire is still retrievable by the agent on demand; decay changes *ordering*, never what's on disk. ## How the agent keeps the wire lean As a session grows, V3Code intervenes cheapest-first: hold the raw thread while it fits, elide old bulky tool outputs, then fold the conversation middle into the running digest only if still over budget — and it compacts *rarely*, near a large effective-context ceiling, not on every turn. Human-authored and test-verified facts are treated as evergreen. > Tip: > > Tell the agent to **remember** something directly — a convention, a gotcha, a decision *and the reason behind it*. The reason is the valuable part; save the why, not just the what, and it carries forward. ## Memory that follows your code V3Code's memory isn't a flat list — notes are **pinned to your code's structure** and resurface by walking it. This is the "graph-anchored" part, and it's what makes memory feel like the agent just *knows* your project. - **The graph.** The native symbol sidecar parses every file (tree-sitter) into a code graph — files → the symbols they define → the files that reference them. That's the real dependency structure of your project. - **Anchoring (write).** When the agent saves a memory about code, it's pinned to the relevant file/symbol nodes in that graph. Save it again and it's re-confirmed — its confidence goes up. - **The ripple (read).** When a prompt is assembled, V3Code looks at the files you're actively working in and recalls notes *near* them — rippling outward through the graph (the file's symbols, the files that reference them, their neighbors). A note on the exact file arrives at full strength; one a couple of hops away still surfaces, just discounted. The payoff: **memory follows code structure, not keywords.** Open a file and the agent automatically remembers the decisions, gotchas, and history attached to that neighborhood of the codebase — including notes on files it hasn't even opened — without running a single search. And it gets richer on its own: as the agent explores code, what it learns is recorded automatically, so the map of your project deepens just from working in it. > Note: > > Honest limits: this pulls from your few most-active files (a handful of notes each) per prompt; it uses the symbol sidecar (without it, memory gracefully falls back to the editor's own store); and every workspace starts empty — nothing is pre-populated. > Note: > > Working in a blank/greenfield folder? V3Code deliberately suppresses cross-project memory there, so the agent grounds in the empty project in front of it instead of hallucinating off unrelated history. Everything stays recallable on demand. # Semantic index V3Code builds a searchable index of your codebase on your own hardware. It's what lets the agent find relevant code by *meaning*, not just exact text, and it's a big reason the agent seems to understand a project the moment you start typing. ## Reading comes first A quick philosophy note, because it shapes everything below: V3Code leans on the agent **reading real code** and uses the index for **fast recall when it's needed** — not as a replacement for reading. We've found models are more accurate when they read more and reach for the index to jump straight to the right place. They hit harder and miss less. The index makes that fast; it doesn't do the thinking. ## Local by default The index lives on your machine in a local **IndexedDB** store (database `v3code-index`), with embeddings kept as compact **int8-quantized vectors** (\~4× smaller than float32, scored directly with a per-vector scale). Your code is never uploaded to build or query it. See [Privacy](/account/privacy). ## Embeddings: a fast code model by default The embedding model is chosen by `v3code.semanticIndex.embedModel` (default `auto`): | Model | Dim | Engine | Notes | | -------------------------------- | ---- | -------------------------------------- | ------------------------------------------------------------------------------------ | | **`potion-code-16M`** (default) | 256 | Model2Vec **static** (no forward pass) | Tuned for code and used as the supported local default. | | `Qwen3-Embedding-0.6B` (quality) | 1024 | llama.cpp (GPU) | Optional higher-quality path when it is selected and local hardware has room for it. | Older local-embedding selections now resolve to the supported default instead of loading retired backends. If the current embedding model cannot load, V3Code keeps lexical search available rather than presenting vector search as ready. ## Why a small model is enough: structural enrichment A lightweight embedder would normally cost recall. V3Code buys it back with **structure**. Chunks are cut **structurally** with tree-sitter (parent/child code blocks, not blind line windows), and the code graph is upgraded with real **LSP-derived edges** (`v3code.semanticIndex.lspGraphEdges`, on by default, tightly budgeted). That structural signal — surrounding symbol, file, and relationships — sharpens recall and ranking, so the small, fast model punches above its size. ## How ranking works Retrieval is a **hybrid, RRF-fused** search, not a single vector lookup: - **Lexical channel** — IDF token overlap (weight 0.4). - **Dense vector channel** — int8 cosine over the embeddings (weight 0.6). - **Previous-model channel** — dual-space scoring during a model swap (0.5). - **Recency** — a multiplicative boost (up to \~1.25× for the most-recently-touched code). - **Graph neighbors** — one-hop expansion over the code graph after ranking. Channels are merged with Reciprocal Rank Fusion at **k = 30** (deliberately steeper than the classic 60), with adaptive widening when too few strong results come back. Child chunks collapse into their parent (top-3, decayed). An optional local **`Qwen3-Reranker-0.6B`** cross-encoder can reorder the top candidates. `semantic_search` returns up to `topK` results (default **30**). ## Staying current - **Builds on startup** (`autoRebuildOnStartup`, on by default) and follows edits. - **Incremental** via a content-hash (Merkle-style) manifest — only changed files are re-chunked and re-embedded — plus a content-addressed store so switching branches back to a known state is instant. - **Security denylist** — secrets-shaped files (`.env*`, `.ssh/`, `.aws/`, …) are never indexed, regardless of your include settings. ## 1.4.9-0098: background work with room to breathe This release corrects the cadence of background memory indexing. Once a bounded idle slice finishes, V3Code now waits before asking for another idle slot instead of treating an idle deadline as a waiting period. The change avoids needless repeated background work in an otherwise idle editor; it is a targeted scheduling fix, not a promise that every project will index at the same speed. ## More than one engine — one search V3Code doesn't lean on a single index. It runs a **layered retrieval system**, and all of it answers through one `semantic_search` call — you never think about which engine served a result. The fusion is adaptive: it leans on lexical signal when vectors are sparse and on vectors when they're strong. ### The local semantic index The engine described above — meaning-based recall, in your editor, on your hardware. It starts on the supported `potion-code-16M` default. The optional Qwen3 path is available when you select it and your local setup supports it. ### The native symbol sidecar Vectors are great at "what does this *mean*" and bad at "where is this *exactly*." So V3Code ships a second engine — a purpose-built **Rust sidecar** for precision: - **Trigram-indexed** (Tantivy) for instant substring and identifier search, with a recall → regex-confirm pass so matches are exact, not fuzzy. - **Symbol-aware** — tree-sitter parses every file into a symbol index of definitions and references across many languages. - **Cross-file resolved** — stack-graphs follow real **go-to-definition** and **find-references** edges, not text look-alikes, so "what uses this?" is answered by the actual call graph. - **Hot-swappable** — it runs as its own process (the ripgrep model): it can start, be killed, or restart mid-flight without ever breaking search. If it's not there, the system degrades gracefully. The payoff is symbol lookups and change-impact traces in **single-digit milliseconds**, riding alongside the semantic index's meaning-based recall. It's also what powers [graph-anchored memory](/editor/memory). ### The cloud index (opt-in, paid) An optional hosted index — **never required**. It exists so people on **low-end hardware**, or who want indexing to run against their own **BYOK** models, can offload the work. It's a per-workspace service with its own lexical, vector, and symbol-graph search. Local-hardware users never need it; and if your local index ever hits trouble, V3Code falls back to the cloud index **free** so search keeps working. **In short: local for your own hardware, cloud for low-end machines or BYOK-model indexing — your choice.** > Info: > > The indexing stack is actively evolving (deeper sidecar fusion and a cloud-model path are in progress). This page describes current default behavior. # Appearance & theming V3Code's look is yours to set, right from Settings. No hunting for a theme extension: the color picker is built in. ## Theme Builder Open **Settings → Theme Builder** and every part of the editor UI is a color you can pick. Changes apply **live** as you go. It's grouped so you're not staring at a wall of swatches: - **Accent** — Focus/accent (focus rings + primary accent), Links, Badge, Button, Progress/usage. - **Surfaces** — Editor, Sidebar, Bottom panel, Activity bar, Title bar, Status bar, Active tab, Inputs. - **Text & borders** — Text (primary UI text), Muted text (secondary), Borders (separators). Each swatch opens a full picker (hex or RGB). **Reset** puts it back to default. > Note: > > On the built-in grey V3Code themes, some surfaces and accents are managed by the app chrome, so your custom colors apply best on top of another base theme. ## Venom animations V3Code shows a subtle **venom-green motion** while the agent works — the composer beam, the sticky-capsule "snake," and accent glows. It's on by default. Prefer calm? Turn **Venom animations** off in Settings for grey-only chrome. It's recommended if flashing or motion bothers you, and your OS **Reduce motion** setting turns it off automatically. # V3Code Terminal **V3Code Terminal is the command-line member of the V3Code family.** It gives you the full coding-agent workflow — ask, plan, edit, run, verify — without opening the editor, while keeping the same workspace identity, durable memory, and structural code index. > Note: > > **Preview status.** The source build is usable today. Public standalone installers and the editor-bundled `v3code` command are not released yet, and voice dictation has its interaction contract finished but no connected recorder driver. Everything else on this page is live in the current build. ## What it actually does You can ask questions about a repository, plan a change, edit files, run commands, and check the result — the same loop you'd run in the editor's chat, in a terminal. The parts that make it V3Code rather than a generic terminal agent: - **Durable memory.** Sessions write facts and handoffs into the shared V3Code memory contract, so what the agent learned yesterday is still there today. - **A structural context bridge.** The agent looks up real symbols, references, and impact — not text guesses. - **A private local index.** You choose exactly which folders get indexed. Nothing is scanned behind your back. - **An optional editor link.** When V3Code Editor is running, the terminal finds it automatically and shares its stronger bridge services. ## Two ways to run it ### Standalone The agent, sessions, local memory, built-in index, providers, tools, MCP clients, and the full interface all run on their own. Standalone is a supported state, not a degraded one. ### Editor-linked The terminal discovers the editor's local endpoint by itself — there's no pairing code — and shares its bridge services and memory transport. ## Install and first run The preview builds from source and needs Git and **Bun 1.3.14**. ```bash git clone cd v3code-terminal bun install bun run dev ``` `bun run dev` opens the terminal in the current directory. To work on a different project, start it from that folder or pass the path: ```bash v3code /path/to/project ``` ## Choose a provider and model On first launch without a usable model, the terminal opens **Choose a provider**. Anthropic, OpenAI, GitHub Copilot, and Google appear first; optional third-party services keep their own names and terms. Your provider's normal OAuth or API-key flow runs, then the model selector opens. Press `esc` to skip setup and reach the commands — incomplete setup simply returns on the next launch. To change things later, run `/connect` for providers and `/models` for models. Outside the interface: ```bash v3code providers list v3code providers login v3code providers logout ``` > Note: > > Your local index and memory database stay on your machine. But any code or context included in a model request goes to the provider you selected — their privacy and retention policy applies to it. See [Privacy](/account/privacy). ## Connect it to the editor No setup required. A running V3Code Editor publishes a local endpoint and the terminal finds it. Run `/bridge` and look for: ```text editor bridged — a running V3Code editor was found ``` If the editor is closed, that row reads `standalone` and everything local keeps working. ## Where to go next - [Commands and shortcuts](/terminal/commands) — every verified slash command and key. - [Agents and subagents](/terminal/agents) — the built-in agents, and how to write your own. - [Sessions and context](/terminal/sessions) — resuming, forking, reverting, and compaction. - [Skills and instructions](/terminal/skills) — teach it your project's conventions. - [Tools and MCP servers](/terminal/mcp-and-tools) — what the agent can do, and how to add more. - [Memory and the context bridge](/terminal/memory-and-bridge) — how the agent remembers and navigates code. - [Configuration](/terminal/configuration) — where settings live and every option worth knowing. - [Permissions and privacy](/terminal/permissions-and-privacy) — what needs approval and what touches the network. Shared concepts live on the editor pages: [Context Bridge](/editor/context-bridge), [Memory](/editor/memory), [Models & BYOK](/models/byok), and [MCP](/connect/mcp). ## Honest limitations - **Distribution:** installers and a signed release pipeline are prepared, but there's no approved public standalone release yet. - **Voice:** the hold-to-talk gesture is implemented, but no recorder driver is connected. `/voice` honestly reports `driver not connected`; no microphone opens. - **Worktree ownership:** workspace and worktree surfaces sit behind an experimental flag. - **Team transport:** local queueing works; cloud sync attaches through the signed-in editor. Queued is not the same as synced. - **Beast index:** the deeper Rust sidecar is optional. Without it, symbol search still works through the built-in index; deep trace explains what's missing instead of pretending it ran. - **Terminal variation:** color, mouse, and key-release support differ by terminal. Aim for at least 80×24. # Terminal commands & shortcuts Type `/` in the prompt to search commands — the list only shows what's available in your current state. Press `Ctrl+P` for the full command palette. ## Prompt controls | Input | Result | | -------------------------------------------------------- | ------------------------------------------------------- | | `Return` | Submit the prompt. | | `Shift+Return`, `Ctrl+Return`, `Alt+Return`, or `Ctrl+J` | Insert a new line. | | `Tab` / `Shift+Tab` | Move to the next or previous agent. | | `@` | Find and attach a file as context. | | `!command` | Enter shell mode and run a command directly. | | `/` | Search slash commands. | | `Ctrl+P` | Open the full command palette. | | `Escape` | Close a dialog, cancel voice, or interrupt active work. | | `Ctrl+C` | Clear a non-empty prompt; with nothing to clear, exit. | ## Slash commands These are the commands registered in the current build, with the exact title each one shows in the interface. ### Session | Command | What it does | | ----------- | ------------------------------------------------ | | `/new` | New session. Alias: `/clear`. | | `/sessions` | Switch session. Aliases: `/resume`, `/continue`. | | `/exit` | Exit the app. | ### Models, agents, and providers | Command | Interface title | | ----------- | -------------------------------------------------- | | `/connect` | Connect provider | | `/models` | Switch model. Aliases: `/model`, `/mo`. | | `/agents` | Switch agent | | `/variants` | Switch model variant (when the model has variants) | | `/mcps` | Toggle MCPs | | `/org` | Switch org (when you have more than one) | | `/themes` | Switch theme | ### Context, status, and system | Command | Interface title | | ---------------- | --------------------------------------------------------- | | `/bridge` | Local index status (semantic · symbols · memory · editor) | | `/memory-status` | View memory bridge status | | `/privacy` | View local-first privacy shield | | `/panel` | Open browser panel | | `/status` | View status | | `/debug` | View debug info | | `/help` | Help | | `/diff` | Open the diff viewer | > Note: > > **Memory, Index, and Team are sidebar tabs, not slash commands.** Press `Ctrl+X` then `B` to toggle the sidebar, then choose the **Session**, **Files**, **Tasks**, **Index**, **Memory**, or **Team** tab. If you've read an older internal guide that lists `/memory`, `/index`, or `/team`, this page is the accurate one — it was checked against the command registry in the current build. Project commands, plugins, MCP servers, and installed skills can add more entries. `/workspaces` stays hidden unless experimental workspace support is enabled. ## Leader key shortcuts The default leader key is `Ctrl+X`. Press it, then the second key. | Shortcut | Action | | ------------------ | -------------------------------------------------------------------- | | `Ctrl+X`, then `B` | Toggle the sidebar (Session / Files / Tasks / Index / Memory / Team) | | `Ctrl+X`, then `E` | Open the prompt in an external editor | | `Ctrl+X`, then `T` | List available themes | | `Ctrl+X`, then `S` | View status | | `Ctrl+X`, then `Q` | Exit the application | Every keybinding can be changed in configuration, and the leader key itself is configurable. ## CLI reference | Command | Purpose | | ------------------------------ | --------------------------------------------------- | | `v3code [project]` | Start the full interface in a project. | | `v3code -c` | Continue the latest session. | | `v3code --session ` | Continue a specific session. | | `v3code --session --fork` | Fork while continuing a session. | | `v3code run ` | Run one request without the full interface. | | `v3code models [provider]` | List available models. | | `v3code providers list` | List providers and credential state. | | `v3code mcp list` | List MCP servers and status. | | `v3code stats` | Show token usage and cost. | | `v3code export [sessionID]` | Export a session as JSON. | | `v3code import ` | Import session data. | | `v3code serve` | Start a headless server. | | `v3code web` | Start the server and open the web interface. | | `v3code debug info` | Show runtime debug information. | | `v3code debug paths` | Show data, config, cache, state, and log locations. | | `v3code debug config` | Print the resolved configuration. | | `v3code --pure` | Run without external plugins, for diagnosis. | Run `v3code --help` or ` --help` for the complete current reference. > Note: > > `--auto` approves permission requests that aren't explicitly denied. The CLI itself labels this **dangerous** — don't make it your default or use it unattended. See [Permissions](/terminal/permissions-and-privacy). # Agents & subagents An **agent** is a named working style: its own instructions, its own model, and its own permission rules. V3Code Terminal ships with four you can use immediately, and you can add your own as a markdown file. ## The built-in agents Two are **primary** agents — the one you're talking to. Two are **subagents**, which the primary agent delegates to. ### build The default agent. It runs tools according to your configured permissions — reading, editing, running commands, and verifying work. ### plan Plan mode. **Every edit tool is denied**, so it can research and design without touching your files. The one exception is writing the plan itself into `.opencode/plans/*.md`. ### general General-purpose worker for researching complex questions and running multi-step tasks. Use it to run several units of work in parallel. ### explore A fast, **read-only** codebase explorer. Its permissions allow only `grep`, `glob`, `list`, `bash`, `read`, `webfetch`, and `websearch` — everything else is denied, so it can't change anything. Tell it how thorough to be: `quick`, `medium`, or `very thorough`. A few more agents exist but stay hidden because the app drives them for you: `compaction` (condensing a long session), `title` (naming sessions), and `summary`. ## Switching agents | Input | Result | | ------------------- | -------------------------------------------------------------- | | `/agents` | Open the agent switcher. | | `Tab` / `Shift+Tab` | Move to the next or previous agent without leaving the prompt. | | `@name` | Mention a subagent by name in your message. | To change the default for a project, set `default_agent` in your configuration. ```jsonc { "default_agent": "build", } ``` ## Plan before you build When a request looks like it needs design work first, the agent can offer to switch you into `plan`. It asks — it doesn't move you silently. If you explicitly say you want a plan, it offers the switch first, before doing anything else. Plan mode is worth reaching for when a task spans multiple files or involves an architectural decision. For a small, obvious fix it just adds a step. ## Delegating to subagents The primary agent delegates with its `task` tool, choosing which subagent type to use. This is how a big job gets split up. What's worth knowing as a user: - **Several subagents can run at once**, which is the point — independent questions get answered in parallel. - **Each one starts with a fresh context.** It cannot see your conversation, so the instructions it receives have to be self-contained. - **A returned `task_id` can be reused** to continue that same subagent session later, instead of starting over. - **Its output isn't shown to you directly.** The primary agent reads the result and reports back, so you get a summary rather than a transcript. > Note: > > Subagents run in your working tree, not in a sandbox of their own. When two of them would edit the same files, give them separate areas — or separate worktrees. ## Write your own agent Create a markdown file in an `agent/` (or `agents/`) folder inside your config directory — `.v3code/agent/reviewer.md` in a project, or under `~/.config/v3code/` for every project. The frontmatter configures it; the body becomes its prompt. ```markdown --- description: Reviews changes for correctness and security. Use before a PR. mode: subagent model: anthropic/claude-sonnet-4-5 temperature: 0.1 color: warning permission: edit: deny bash: "*": ask "git diff*": allow --- You review code changes. Focus on real defects, missing error handling, and anything that touches auth or user input. Be specific and cite files. ``` The fields you'll reach for most: | Field | What it does | | ---------------------- | ---------------------------------------------------------------------------- | | `description` | When this agent should be used. Required for subagents to be picked well. | | `mode` | `primary`, `subagent`, or `all`. | | `model` / `variant` | Pin this agent to a specific model. | | `temperature`, `top_p` | Sampling controls. | | `permission` | Per-agent permission rules — the safest way to constrain an agent. | | `steps` | Maximum agentic iterations before it must answer in text. | | `hidden` | Keep a subagent out of the `@` autocomplete menu. | | `disable` | Turn the agent off without deleting the file. | | `color` | A hex value like `#FF5733`, or a theme color such as `primary` or `warning`. | > Note: > > `tools` is deprecated in favour of `permission`. It still works — a `tools` list is accepted and converted — but new agents should use `permission`, which is more expressive. You can also override a built-in agent from configuration, without writing a file: ```jsonc { "agent": { "plan": { "model": "anthropic/claude-opus-4-1" }, }, } ``` ## Sharing agents with the editor Agent files written for the V3Code **editor** load in the terminal too. The editor declares tools as a list of names; the terminal converts that into its own permission map automatically, so a shared `.v3code/` folder works in both products. Editor-only tool names simply won't match anything here. A broken or foreign agent file is skipped with a warning — **one bad file never stops the app from starting.** ## Related [Commands & shortcuts](/terminal/commands) covers `/agents` and the palette, [Permissions & privacy](/terminal/permissions-and-privacy) covers the rule syntax used above, and [Subagents](/editor/subagents) covers the editor's delegation model. # Sessions & context A **session** is one conversation and everything it did — messages, tool calls, file changes. Sessions are saved locally as you work, so closing the terminal doesn't lose anything. ## Starting and resuming | Command | What it does | | ------------------------------ | ----------------------------------------------------------- | | `/new` | Start a fresh session. Alias: `/clear`. | | `/sessions` | Switch to another session. Aliases: `/resume`, `/continue`. | | `v3code -c` | Continue the most recent session for this project. | | `v3code --session ` | Continue a specific session. | | `v3code --session --fork` | Branch off a session, leaving the original untouched. | Forking is the useful one when you want to try a different approach from a known-good point without losing the path you already have. ### Managing them from the CLI ```bash v3code session list # every session, newest first v3code session list -n 10 # just the last ten v3code session delete # remove one ``` Sessions get a short title automatically, generated by the `small_model` you configured, so a list of past work is actually readable. ## Undoing work If the agent went the wrong way, you don't have to repair the files by hand. V3Code takes a **snapshot** as it works, so a session can be rolled back to an earlier message — the files return to how they were at that point. You can also undo the undo: reverting is itself reversible, restoring the state you had before you rolled back. > Note: > > Snapshots are what make this possible, and they're controlled by the `snapshot` setting. With snapshots off, revert has nothing to restore from. > Tip: > > Revert covers files V3Code changed. It isn't a replacement for committing — commit at a known-good point and you always have a floor to stand on. ## When a conversation gets long Every model has a context limit. Rather than failing at the edge, V3Code **compacts**: it summarizes the earlier part of the conversation and keeps going. What survives compaction is tunable: | Setting | Default | Effect | | ----------------------------------- | ------- | ----------------------------------------------------------- | | `compaction.auto` | `true` | Compact automatically when the window fills. | | `compaction.tail_turns` | `2` | How many recent user turns are kept word-for-word. | | `compaction.preserve_recent_tokens` | — | A token ceiling on what's preserved verbatim. | | `compaction.prune` | `false` | Drop old tool outputs, which are usually the bulkiest part. | | `compaction.reserved` | — | Buffer left free so compaction itself has room to run. | A dedicated internal `compaction` agent does this work, which is why it doesn't disturb your current agent or model choice. > Note: > > Compaction condenses the *conversation*. Durable facts saved to [memory](/terminal/memory-and-bridge) are a separate store and aren't affected — that's the difference between what was said and what was learned. You can also cap how much any single tool result contributes, with `tool_output.max_lines` and `tool_output.max_bytes`. ## Exporting and importing ```bash v3code export # write the session as JSON v3code export --redact # redact sensitive transcript and file data v3code import # bring a session in ``` > Note: > > Use `--redact` before sharing an export. A raw export contains the full transcript and file contents, which can include secrets that were on screen. ## Sharing `/share` creates a link to a session. It's manual by default — nothing is published unless you ask. The `share` setting accepts `manual`, `auto`, or `disabled`, and `disabled` turns the feature off entirely for a project. ## Usage and cost ```bash v3code stats # all-time tokens and cost v3code stats --days 7 # the last week v3code stats --models # break it down by model ``` ## Where sessions live Session data is written under `~/.local/share/v3code/`, and `v3code debug paths` prints the exact locations. It stays on your machine — see [Permissions & privacy](/terminal/permissions-and-privacy) for what does and doesn't leave it. ## Related [Configuration](/terminal/configuration) covers the compaction and snapshot settings, [Memory & context bridge](/terminal/memory-and-bridge) covers durable memory, and [Sessions](/editor/sessions) covers the editor's model. # Skills & instructions There are two ways to give the agent knowledge it wouldn't otherwise have. **Instructions** are always loaded and describe your project. **Skills** sit on the shelf until a task needs them. ## Instructions — always on Put an `AGENTS.md` at the root of your repository. It's read at the start of every session, so it's the right home for conventions that always apply: how to run the tests, which patterns to follow, what never to touch. ```markdown # Project notes - Run tests with `npm test -w @app/api`. Never use `--force`. - Database migrations are generated, not hand-edited. - All API responses go through `packages/http/envelope.ts`. ``` ### What gets loaded, in order ### A global instruction file An `AGENTS.md` in your config directory, or `~/.claude/CLAUDE.md`. The first one found is used. ### One project instruction file `AGENTS.md`, then `CLAUDE.md`, then the deprecated `CONTEXT.md` — searched from your current directory up to the worktree root. ### Anything you listed in config Every entry under `instructions`. > Note: > > **Only the first project-level match is used.** V3Code doesn't stack an `AGENTS.md` from every folder up the tree, so instructions can't quietly accumulate as you move around a monorepo. The `instructions` array accepts relative paths, absolute paths, globs, `~/` paths, and `https://` URLs: ```jsonc { "instructions": [ "./docs/conventions.md", "./packages/*/AGENTS.md", "~/notes/my-style.md", ], } ``` > Tip: > > Keep instructions short and specific. A long document competes for the same context as your actual code — a page of real constraints beats ten pages of general advice. ## Skills — loaded when relevant A skill is a folder with a `SKILL.md` inside it. The agent sees every skill's *name and description* all the time, but only pulls the full contents in when a task actually matches — so you can keep a deep library without flooding the context. ```markdown --- name: release-checklist description: > Use when cutting a release: version bumps, changelog entries, tagging, and the publish order across packages. --- ## Steps 1. Confirm `main` is green. 2. Bump versions with `npm run version`. ... ``` The folder can hold more than the one file — scripts, templates, reference documents. The instructions can point at them by relative path, and the agent can open them. ### Where skills come from | Location | Scope | | ------------------------------------------- | ----------------------------------------------- | | `skill/` or `skills/` in a config directory | Global or project, depending on which directory | | `~/.claude/skills/**/SKILL.md` | Skills you already wrote for Claude Code | | `.agents/skills/**/SKILL.md` | A shared convention, global or per project | | `skills.paths` in config | Any extra folders you name | | `skills.urls` in config | Downloaded from a URL and cached | ```jsonc { "skills": { "paths": ["./tooling/skills", "~/skills"], "urls": ["https://example.com/.well-known/skills/"], }, } ``` A skill URL must serve an `index.json` listing each skill and its files. Entries without a `SKILL.md` are skipped with a warning, and a `version` field lets V3Code re-download only what changed. Downloads are cached under `~/.cache/v3code/skills/`. > Note: > > Skills you wrote for Claude Code load as they are — there's nothing to convert. Set `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1` if you'd rather V3Code ignored them, or `OPENCODE_DISABLE_EXTERNAL_SKILLS=1` to skip both external folders. These two runtime flags read the `OPENCODE_` name specifically — the `V3CODE_` alias doesn't apply to them. ### Using them Mostly you don't have to do anything: the agent picks a skill when the task matches its description, which is why the description matters more than the title. You can also just ask — "use the release-checklist skill." That makes description-writing the real craft here. Write it as *when to use this*, not *what this is*: "Use when cutting a release" gets matched; "Release documentation" doesn't. ## Which one should you use? ### Use instructions Facts that are true for every task in this repository — commands, conventions, hard rules. ### Use a skill A procedure for a specific kind of job that only comes up sometimes — releases, migrations, incident response. If it would be noise on an unrelated task, it belongs in a skill. ## Related [Configuration](/terminal/configuration) covers the `instructions` and `skills` blocks, [Agents & subagents](/terminal/agents) covers per-agent prompts, and [Skills](/editor/skills) and [Project instructions](/editor/project-instructions) cover the editor's equivalents. # Tools & MCP servers Tools are the things the agent can actually *do* — read a file, run a command, search the web. This page lists what ships built in, and how to add more through MCP servers or your own code. ## Built-in tools These are registered in every session. Each one is subject to your permission rules, so "available" doesn't mean "unattended." ### Files | Tool | What it does | | ------- | ---------------------------------------------------------- | | `read` | Read a file, with image support and large-file truncation. | | `write` | Create a file or replace its contents. | | `edit` | Make a targeted change inside an existing file. | | `patch` | Apply a structured patch across files. | | `glob` | Find files by name pattern. | | `grep` | Search file contents, powered by ripgrep. | ### Running and delegating | Tool | What it does | | ---------- | ------------------------------------------------------------------- | | `shell` | Run a command in your shell. | | `task` | Delegate to a subagent. See [Agents & subagents](/terminal/agents). | | `todo` | Keep a visible task list for multi-step work. | | `question` | Ask you a structured question mid-task. | ### Knowledge and context | Tool | What it does | | ----------- | --------------------------------------------------------------------------- | | `bridge` | Structural code intelligence — semantic search, symbols, references, trace. | | `memory` | Recall, save, and forget durable facts across sessions. | | `skill` | Load a skill's instructions into the conversation. | | `webfetch` | Fetch and read a URL. | | `websearch` | Search the web. | > Note: > > `bridge` and `memory` are covered in depth in [Memory & context bridge](/terminal/memory-and-bridge). `websearch` availability depends on your provider or a configured search key. Two more are behind experimental flags and off by default: an `lsp` tool for language-server queries, and a `plan` tool used by plan-mode switching in the CLI. ## MCP servers **MCP** — the Model Context Protocol — is an open standard for giving an agent extra tools. A GitHub MCP server adds GitHub tools; a database MCP server adds query tools. V3Code Terminal connects to them as a client. Run `/mcps` to toggle servers on and off for the current session, and `v3code mcp list` to see every configured server with its status. ### Local servers A local server is a process V3Code starts and talks to over stdio. ```jsonc { "mcp": { "my-tools": { "type": "local", "command": ["bun", "x", "some-mcp-server"], "environment": { "API_TOKEN": "..." }, "enabled": true, "timeout": 5000, }, }, } ``` | Field | Meaning | | ------------- | ------------------------------------------------------------- | | `command` | The command and arguments to launch, as an array. | | `cwd` | Working directory. Relative paths resolve from the workspace. | | `environment` | Environment variables for the server process. | | `enabled` | Whether it starts with the session. | | `timeout` | Request timeout in milliseconds. Defaults to 5000. | ### Remote servers A remote server is reached over HTTP. ```jsonc { "mcp": { "company-api": { "type": "remote", "url": "https://mcp.example.com/sse", "headers": { "Authorization": "Bearer ..." }, "enabled": true, }, }, } ``` OAuth is detected automatically when the server advertises it. If the server needs specific client details, configure them under `oauth` — `clientId`, `clientSecret`, `scope`, and either `callbackPort` or a full `redirectUri`. The default callback is `http://127.0.0.1:19876/mcp/oauth/callback`. Set `"oauth": false` to switch auto-detection off. > Note: > > **Keep credentials out of committed config.** A token in a project's `v3code.json` gets committed with it. Prefer environment variables, or put the server in your global `~/.config/v3code/v3code.json`. ### MCP tools ask permission too Tools from an MCP server are not automatically trusted. They appear under their own tool names and can be governed by the same permission rules as anything else, so an unknown tool can be set to `ask` or denied outright. ## Your own tools For something small and project-specific, you don't need a full MCP server. Drop a JavaScript or TypeScript file into a `tool/` folder in your config directory — `.v3code/tool/changelog.ts` — and its exported tools are registered automatically. The file name becomes the namespace: a default export from `changelog.ts` registers as `changelog`, and a named export `recent` registers as `changelog_recent`. Plugins can contribute tools the same way. List them under `plugin` in your configuration. ## Controlling what's available Three levers, from blunt to precise: ### tools A simple enable map in configuration. Good for turning something off globally. ### permission The real control. Works per tool and per pattern, and is what agents use to constrain themselves. ### agent permission Rules set inside an agent file apply only to that agent — how `explore` stays read-only. ## Related [Permissions & privacy](/terminal/permissions-and-privacy) covers approval rules, [Configuration](/terminal/configuration) covers where these blocks live, and [MCP](/connect/mcp) covers the editor's MCP support. # Memory & context bridge This is the part that makes V3Code Terminal different from a generic terminal agent. Two systems run underneath every session: **memory**, which keeps what was learned, and the **context bridge**, which understands how your code fits together. ## The sidebar is where you see it Press `Ctrl+X` then `B` to toggle the sidebar. It has six tabs: **Session**, **Files**, **Tasks**, **Index**, **Memory**, and **Team**. > Note: > > These are tabs in the sidebar, not slash commands. For a live status summary without opening the sidebar, run `/bridge` or `/memory-status`. ## Memory The terminal writes completed session activity into the shared V3Code memory contract — the same contract the editor uses. It can keep tool activity, the files involved, failures, a checkpoint summary, and durable facts. The agent can search both the facts and the indexed handoff documents. The **Memory** tab shows: - local fact and searchable-handoff counts; - the current session's events, tools, files, and failures; - decisions, quirks, patterns, and symbols; - recent handoffs, each with a detail popup; - team relay counts for queued, sent, received, or retrying handoffs. The agent has a `memory` tool with four actions: ### recall Searches relevant facts and indexed handoffs. ### save Stores a durable decision, pattern, quirk, dependency, file state, symbol, or roadmap fact. ### forget Removes a selected fact. ### status Reports the local library and editor connection state. > Note: > > The local copy is authoritative. When no signed-in editor transport is attached, team handoffs stay **queued locally** — queued is not the same as synced to the cloud. ## The project index — you choose what gets read Open the **Index** tab to add source locations. You can paste a path, use your system's folder picker, or pick a single file. V3Code scans supported source and documentation text for a preview, shows the file count and size, and **waits for your confirmation before building anything.** Each location can be paused, resumed, rebuilt, or removed. The semantic index is stored at `~/.v3code/semanticdb/` and never needs a running editor. Hard safety limits, enforced in code: | Limit | Value | | -------------------------- | ---------- | | Files per location | 20,000 | | Size per file | 512 KB | | Filesystem entries visited | 200,000 | | Discovery time | 45 seconds | System roots, drive roots, and your entire home folder are blocked outright. Dependency, build, credential, secret, and ignored paths are excluded. If the agent is asked to search semantically before you've approved any location, it asks you to open the Index tab. **It does not silently scan your project.** ## The bridge tool The agent's `bridge` tool has six actions: | Action | What it does | | ----------------- | ------------------------------------------------------------------------- | | `semantic_search` | Searches only your approved Index locations, by behavior or intent. | | `symbol_search` | Finds declarations with identifier-aware matching. | | `references` | Finds call sites and usages, grouped by file. | | `trace` | Estimates the blast radius of a file or symbol through the Beast sidecar. | | `status` | Reports built-in index, Beast, memory, and editor state. | | `reindex` | Rebuilds the structural index after large changes. | The built-in structural index is created on first symbol or reference use. The optional **Beast** index adds deeper shared indexing with the editor. If Beast isn't installed, symbol search and references fall back to the built-in index, and deep trace tells you what's missing instead of pretending it ran. ## Team Flight Deck The **Team** tab shows the lead session with its real child sessions: agent and model identity, busy state, retry or approval state, worktree branch, changed-file count, and last update. Clicking an agent opens that session. The handoff rail never infers success: - `WORKTREE` says `shared checkout` until a connected worktree is attached. - `VERIFY` says `not recorded` until a captured verification command finishes. - `HANDOFF` says `checkpoint ready` only once the local memory library actually contains that checkpoint. Those are evidence states, not errors. ## Related The editor side of these systems is documented in [Context Bridge](/editor/context-bridge), [Memory](/editor/memory), and [Semantic index](/editor/semantic-index). # Configuration Everything is configurable from a JSON file, and nothing has to be. V3Code Terminal runs with sensible defaults — configuration is for when you want a specific model, tighter permissions, or your own agents and commands. ## Where configuration lives Two levels, and they merge. Global settings apply everywhere; project settings apply to one repository and win where they overlap. ### \~/.config/v3code/ Your personal defaults for every project. Holds `v3code.json`, plus `agent/`, `command/`, and `skill/` folders. ### .v3code/ in your project Settings for this repository, usually committed so your team shares them. Same layout as the global folder. A `v3code.json` or `v3code.jsonc` file at the root of your project works too. Files are searched from your current directory upward, stopping at the worktree root, so a config in a subfolder can refine the one above it. > Note: > > `opencode.json`, `opencode.jsonc`, and `.opencode/` are still read as compatibility aliases, and `OPENCODE_*` environment variables are accepted alongside `V3CODE_*`. New setups should use the `v3code` names. To see exactly what V3Code resolved — after every file and override merged: ```bash v3code debug config v3code debug paths ``` ## A practical starting file ```jsonc { "$schema": "https://v3code.dev/config.json", "model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5", "default_agent": "build", "instructions": ["./docs/conventions.md"], "permission": { "edit": "ask", "bash": { "*": "ask", "git status*": "allow", "rm *": "deny", }, }, } ``` `.jsonc` files — and `.json` files here — accept comments and trailing commas. ## Options worth knowing ### Models and agents | Option | What it does | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `model` | The default model, as `provider/model`. | | `small_model` | A cheaper model for small internal jobs like session titles. | | `default_agent` | Which agent a new session starts in. | | `agent` | Override any built-in agent — `plan`, `build`, `general`, `explore`, and the internal `title`, `summary`, `compaction`. | | `provider` | Per-provider settings and custom endpoints. | | `disabled_providers` / `enabled_providers` | Narrow which providers appear at all. | ### Behavior | Option | What it does | | -------------- | ------------------------------------------------------------------------------------------ | | `permission` | Approval rules per tool and pattern. See [Permissions](/terminal/permissions-and-privacy). | | `instructions` | Extra instruction files to load, by path or glob. | | `command` | Custom slash commands defined inline. | | `skills` | Extra skill folders (`paths`) and skill URLs (`urls`). | | `mcp` | MCP servers, local or remote. See [MCP servers](/terminal/mcp-and-tools). | | `plugin` | Plugins to load. | | `snapshot` | Whether file snapshots are taken, enabling revert. | | `share` | `manual`, `auto`, or `disabled` for session sharing. | | `autoupdate` | `true`, `false`, or `"notify"`. | ### Environment and tooling | Option | What it does | | ------------------------------------- | -------------------------------------------------- | | `shell` | The shell used for the terminal and the bash tool. | | `formatter` | Formatters to run on edited files. | | `lsp` | Language server configuration. | | `watcher.ignore` | Paths the file watcher should skip. | | `logLevel` | How much detail goes into the logs. | | `username` | The name the agent calls you. | | `tool_output.max_lines` / `max_bytes` | Cap how much tool output enters the context. | ### Compaction When a session approaches the model's context limit, V3Code condenses the earlier part instead of failing. | Option | Default | What it does | | ----------------------------------- | ------- | ---------------------------------------------- | | `compaction.auto` | `true` | Compact automatically when context fills. | | `compaction.prune` | `false` | Drop old tool outputs. | | `compaction.tail_turns` | `2` | Recent user turns kept word-for-word. | | `compaction.preserve_recent_tokens` | — | Token ceiling on what's kept verbatim. | | `compaction.reserved` | — | Buffer left free so compaction itself can run. | ## Instruction files Beyond `instructions`, V3Code picks up instruction files automatically — the same `AGENTS.md` convention the editor uses. It reads a global `AGENTS.md` from your config directory (or `~/.claude/CLAUDE.md`), then looks for a project file: `AGENTS.md`, then `CLAUDE.md`, then the deprecated `CONTEXT.md`. > Note: > > **The first project-level match wins.** V3Code does not stack an `AGENTS.md` from every folder up the tree — one project file is used, so instructions can't silently pile up. Entries in `instructions` may be relative paths, absolute paths, globs, `~/` paths, or `https://` URLs. ## Custom slash commands Drop a markdown file into a `command/` folder and it becomes a slash command. `.v3code/command/review.md` becomes `/review`; a file in a subfolder becomes a namespaced name. ```markdown --- description: Review staged changes before committing --- Run `git diff --staged`, then review the changes for defects, missing error handling, and anything touching auth or user input. ``` Commands can also be declared inline under `command` in `v3code.json`. ## Where your data sits V3Code follows the XDG layout, so nothing lands in surprising places: | Location | Contents | | ------------------------ | --------------------------------------- | | `~/.config/v3code/` | Configuration, agents, commands, skills | | `~/.local/share/v3code/` | Sessions, logs, plans, repositories | | `~/.cache/v3code/` | Downloaded skills, binaries | | `~/.v3code/semanticdb/` | The local semantic index | Run `v3code debug paths` to print the resolved locations on your machine. ## Related [Permissions & privacy](/terminal/permissions-and-privacy) covers the permission block in depth, [Agents & subagents](/terminal/agents) covers agent files, and [Skills & instructions](/terminal/skills) covers skill discovery. # Permissions & privacy V3Code Terminal does not silently approve every tool. Risky actions stop and ask you first, and the product is local-first by default. ## The approval prompt When a guarded action needs approval, you see **Permission required**, the exact target or command, and three choices: ### Allow once Approves just this one request. ### Allow always Approves the displayed permission or pattern until V3Code restarts. ### Reject Stops the action. A child agent can also be given written feedback explaining the rejection. Prompts can protect edits, reads, file listing, glob and grep searches, shell commands, subagent tasks, web fetches, web searches, access to directories outside the project, language servers and skills, and continuation after repeated failures. Unknown plugin tools can request permission by their own tool name. > Note: > > The `--auto` flag and the palette action **Enable auto-approve permissions** approve anything not explicitly denied. The CLI's own help text calls this **dangerous** — keep it out of defaults and unattended runs. ## Configure permission rules Permission actions are `ask`, `allow`, and `deny`. A rule can cover a whole tool or just matching patterns. Project configuration lives in `v3code.json`, `v3code.jsonc`, or under `.v3code/`. User configuration lives under `~/.config/v3code/` on macOS and Linux. ```jsonc { "permission": { "edit": "ask", "external_directory": "ask", "webfetch": "ask", "bash": { "*": "ask", "git status*": "allow", "git diff*": "allow", "rm *": "deny", }, }, } ``` **When several patterns match, the last one wins.** So keep the broad fallback first and your specific exceptions after it, exactly as above. ## What touches the network Run `/privacy` to inspect the policy actually in effect. Without an opt-in, V3Code Terminal does **not**: - send product analytics or OTLP telemetry; - check for updates in the background; - refresh the model catalog hourly; - download remote syntax parsers or language servers; - install plugin dependencies in the background; - clone or refresh configured remote repository references; - automatically share sessions. The built-in model catalog still works from the packaged snapshot or local cache, and anything previously cached stays usable. Local-first startup also skips the inherited OpenCode account-config refresh, even if an old OpenCode credential is still stored. The upstream account-console and GitHub-bot commands aren't exposed by the V3Code CLI. ### What still uses the network Traffic that directly serves something you asked for: - your chosen model provider receives the request context; - configured MCP servers receive their protocol calls; - web tools reach the sites you requested; - an explicit provider login, plugin install, catalog refresh, or confirmed `/share` reaches its named service. ### Opt-in environment variables | Variable | Effect | | ----------------------------------- | ---------------------------------------------- | | `V3CODE_ALLOW_BACKGROUND_NETWORK=1` | Allows background dependency traffic. | | `V3CODE_ALLOW_TELEMETRY=1` | Enables telemetry (separately off by default). | | `V3CODE_ALLOW_AUTO_SHARE=1` | Enables automatic session sharing. | | `V3CODE_ALLOW_REMOTE_PARSERS=1` | Allows remote syntax parsers only. | Each lane is separate on purpose — enabling background network traffic does not turn on telemetry or sharing. ## Troubleshooting ### Provider setup returns on every launch Setup completes only when a currently available model is selected. Finish **Choose a provider** and **Choose a model**. Run `/connect` to retry authentication, `/models` to pick a usable model, or `v3code providers list` outside the interface. A removed model or missing credential deliberately makes setup return. ### The editor row says `standalone` Open V3Code Editor as the same local user and run `/bridge` again. The discovery file is `~/.v3code/endpoint.json` — don't hand-edit it. Local memory and index features keep working regardless. ### `/bridge` says the index isn't built The structural index is lazy and builds on first use. Ask the agent to run `bridge reindex` after a large refactor. Semantic search is separate and only covers locations you approved in the Index tab. If Beast says `not installed`, symbol search still works; only deep trace needs the sidecar. ### A language server or highlighter didn't download Local-first mode blocks those downloads. Install what you need locally, or set `V3CODE_ALLOW_BACKGROUND_NETWORK=1` deliberately. Run `/privacy` after restarting to confirm. ### Configuration isn't taking effect ```bash v3code debug config v3code debug paths ``` V3Code reads the `V3CODE_*` environment prefix first and accepts legacy `OPENCODE_*` aliases for compatibility. ### Startup or runtime failure ```bash v3code --pure --print-logs --log-level DEBUG ``` `v3code debug startup` prints startup timing and `v3code debug paths` shows the log directory. Remove secrets before sharing logs. ## Related [Privacy](/account/privacy) covers the editor's policy, and [Permissions](/editor/permissions) covers its approval model. # Teams **Teams is where V3Code stops being a single-player tool.** It's in active development, and this page will grow as it lands. > Note: > > **Status: in active development.** Parts of the foundation already ship in the terminal today and are documented below. Anything not described here as working is not working yet. ## The idea One developer with a good agent is faster. A team where every agent shares what the others have learned is a different thing entirely. Today, memory is per-machine: your editor and terminal share a memory contract, but that knowledge stops at your laptop. Teams extends that boundary so a team's agents can hand work to each other with real evidence attached — what changed, what was verified, and what's still open. ## What ships today The terminal already has the local half of this, and you can use it now. ### Team Flight Deck Open the sidebar with `Ctrl+X` then `B` and choose the **Team** tab. It shows the lead session alongside its real child sessions: - agent and model identity; - busy, retry, or approval state; - worktree branch; - changed-file count; - last update time. Clicking an agent opens that session. ### The Worktree Handoff Rail The rail reports evidence, and it refuses to infer success: | Label | Meaning | | ------------------------------ | ------------------------------------------------------------------- | | `WORKTREE` — `shared checkout` | No connected isolated worktree is attached to this session. | | `VERIFY` — `not recorded` | No captured verification command has finished yet. | | `HANDOFF` — `checkpoint ready` | The local memory library actually contains that session checkpoint. | Those are honest states, not errors. A handoff only claims to be ready when the checkpoint really exists. ### Local relay queue The Memory tab shows team relay counts for queued, sent, received, and retrying handoffs. > Note: > > **Queued is not synced.** When no signed-in editor transport is attached, handoffs stay queued on your machine. The product says so plainly rather than implying your work is shared when it isn't. ## What's still being built - **Cloud transport.** Team handoffs currently attach through the signed-in editor. Full hosted sync arrives with [Cloud](/cloud/overview). - **Worktree ownership.** Workspace and worktree surfaces exist behind an experimental flag. End-to-end isolated agent ownership, safe apply, restore, and handoff aren't a public promise yet. ## Related - [Terminal memory & context bridge](/terminal/memory-and-bridge) — the memory system Teams builds on. - [Worktrees](/editor/worktrees) — how isolated checkouts work in the editor. - [Subagents](/editor/subagents) — parallel agents inside a single session. - [Cloud](/cloud/overview) # V3Code Cloud **V3Code Cloud is the hosted side of V3Code — and it's coming.** > Note: > > **Status: in development.** Cloud is not generally available yet. This page exists so you know what's planned and can tell the difference between what ships today and what's still ahead. When it's ready, full documentation lands here. ## The idea The editor and the terminal are local-first by design: your index, your memory database, and your files stay on your machine. That's deliberate, and it isn't changing. Cloud is about the things a single machine genuinely can't do on its own — carrying work across devices, and letting a team share what their agents have learned instead of each person starting from zero. ## What runs locally today Everything you need to work already runs without Cloud: - the agent, sessions, and models in both the [editor](/get-started/introduction) and the [terminal](/terminal/overview); - durable [memory](/editor/memory) and the [semantic index](/editor/semantic-index), stored on your machine; - the [context bridge](/editor/context-bridge) and all structural code intelligence. Cloud adds to this. It won't become a requirement for local work. ## Honest status Team memory transport is the clearest example of where the line sits right now. The terminal queues team handoffs locally, and cloud sync attaches through the signed-in editor. **Queued locally is not the same as synced** — the product deliberately says so rather than implying work is backed up when it isn't. That's the standard we're holding Cloud to before it ships: no feature described here as available until it actually is. ## Related - [Teams](/teams/overview) — shared agent work, in active development. - [Account & billing](/account/billing) - [Privacy](/account/privacy) # Models overview V3Code runs one agent across several models. You pick the model, or let the router pick — the mode and everything else stays the same. The whole system is built around one idea: **get the best models while keeping caching intact so it stays cheap.** ## The V3 models (DeepSeek, optimized) - **v3fast** — an optimized version of **DeepSeek V4 Flash**: quick and cheap for everyday edits. - **v3pro** — an optimized version of **DeepSeek V4 Pro**: the stronger workhorse the editor was built around. "Optimized" means the system around them is tuned to cache well and do the most with the fewest tokens — that's where a lot of the cost savings come from. ## The Anthropic hybrids These ship as **hybrids that consult Anthropic** — a cheaper model does the work and calls in a stronger one only when the task gets hard, so you get top-tier results without paying top-tier prices on every step. | Hybrid | How it works | | ---------------------- | ------------------------------------------------------------------- | | **Opus Easy** | **Haiku** does the work and **calls Opus** for the difficult parts. | | **Opus Hard** | **Sonnet 5** does the work and **calls Opus** when needed. | | **Hybrid (switching)** | Switches between **Sonnet, Opus, and Fable 5** as the task demands. | To you it behaves like a single model — the switching and escalation happen underneath. ## Auto: let it route **Auto** picks and escalates for you. A cheaper model handles the easy steps and a stronger one takes over when needed. Auto is tuned to **preserve prompt caching** rather than break it — reshuffling the context every turn would throw away the cache and run up the bill, so V3Code steers the agents to keep the cache working. ## Free, BYOK, and paid - **Connected plans** let you sign in to supported provider subscriptions and bring the models they expose into the V3Code picker without pasting an API key. Usage counts against that provider's plan. See [Use your existing provider plans](/models/connected-plans). - **Free agent models** are available through a best-effort rotating lane. The roster and capacity change, so it may be less reliable than a connected plan, BYOK, hosted, or local model. - We work hard on the caching to make Anthropic as good as possible for **BYOK** users (your own Anthropic key) and as cheap as possible for **paid** users. - **Paid users get customized versions of the Auto and hybrid routers** — tuned to save money and use the fewest tokens. These are unlocked for paid BYOK users and paid plan users. See [Connected plans](/models/connected-plans) for subscriptions, [BYOK](/models/byok) for keys, and [V3Code plans](/models/plans-and-trials) for what's unlocked where. # Use your existing provider plans V3Code can use supported subscriptions you already pay for. Open **Settings → Account → Connected accounts**, sign in through the provider's supported local client, and recheck the connection. Models made available by that account then appear in V3Code's model picker alongside your other choices. These are plan-backed connections, not API-key billing. Requests count against the provider subscription's own limits and are shared with your normal use of that provider. V3Code does not turn one subscription into unlimited usage or bypass its availability, rate limits, terms, or account requirements. ## Connect, recheck, then choose ### Sign in with the provider Open **Settings → Account → Connected accounts**. Use the provider's supported local client and sign-in route below. This is different from signing in to your V3Code account. ### Recheck the connection Return to Connected accounts and choose **Recheck**. If the connection remains unavailable, verify the provider client is installed, current, and signed in. ### Choose a model Open the composer model picker and select a model exposed by that connection. Send a small request first. Being signed in does not guarantee available model capacity. ## Supported connected accounts | Connection | Sign-in path | How usage is counted | | ------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Grok (Plan)** | Run `grok login`, then recheck the account in V3Code. | Your Grok subscription limits. | | **Claude (Plan)** | Run `claude`, then `/login`. On macOS, the first Keychain read may require permission. | Your Claude plan limits, shared with Claude Code. | | **Gemini (Plan)** | Install the Gemini CLI, run `gemini`, and choose **Sign in with Google**. | Your Gemini or Code Assist allowance; shared service capacity can still be exhausted. | | **GitHub Copilot** | Run `copilot login`, or use an existing supported Copilot sign-in. | Your Copilot premium-request allowance. | | **OpenAI (Plan)** | Run `codex login` to use the signed-in ChatGPT plan lane. | Your ChatGPT plan limits; it does not silently fall back to API-key billing. | | **Cursor (Local)** | Connect through the supported local companion service and keep it running. | Your Cursor plan limits. | The picker shows the models the connection currently exposes. That list can change when a provider changes its plan, model catalog, authentication, or capacity. If a model is missing, recheck the account first; then confirm the provider's client is still signed in and current. ## Free agent models V3Code also includes a beta **free-auto** lane that needs no account or API key. It rotates across the free, tool-capable models currently available to V3Code and can try another member before a response starts when one is rate-limited or unavailable. Free availability is best-effort. Models may be rate-limited, replaced, degraded, or withdrawn without notice, so this lane can be hit-and-miss. Choosing a specific free model turns off rotation and fails honestly if that model is unavailable. For steadier work, use a connected provider plan, BYOK provider, hosted V3Code model, or a [local model](/models/byok#run-models-locally--no-key-at-all). > Note: > > Free cloud models are not local. Prompts and any file context you include leave your > machine and are processed by the third-party gateway and its upstream model provider. > Hide the free models or choose another provider if you do not want to use that lane. ## Pick the right lane - **Existing subscription:** connect the plan and use the models it exposes. - **Provider API account:** add your key through [BYOK](/models/byok); billing goes to that provider. - **No account or key:** try free-auto, understanding that availability changes. - **Keep requests on your computer:** run a supported local model. # Token wallet The token wallet is V3Code's usage meter. It shows what you've used and what it cost, broken down by model, so there are no surprises — whether you're on BYOK or a hosted plan. ## What it tracks - **Spend over time** — this session, today, last 7 days, last 30 days, with a tokens-per-day chart. - **Requests and models used** — how many calls, across how many models. - **Per-model breakdown** — your top models by tokens and cost (e.g. Sonnet, Haiku, Opus), expandable to the full list. - **Cache reads saved** — how many input tokens caching saved you. This is a headline number, because caching is where the savings come from (see [Models overview](/models/overview)). BYOK token usage is **tracked locally and persists across restarts**, and cost is shown as a **cache-aware estimate** — it accounts for cached input rather than charging you full price for tokens the cache served. ## Soft budget You can set a **soft budget** — a spend cap across all models over a period. It's a guardrail and a signal, shown as a fill bar in the meter — not a hard cutoff. ## How paid quota is metered On a paid plan your included usage is split into buckets, each with its own meter for the cycle: | Bucket | Covers | | --------------------- | ------------------------------------------------- | | **V3 Pro / V3 Fast** | Fast-tier DeepSeek requests included in your plan | | **Auto / Hybrid** | Auto-routed and hybrid-model usage | | **Opus** | Premium Opus-class usage | | **On-demand overage** | Usage beyond included limits, billed in arrears | # Bring your own keys (BYOK) V3Code is BYOK-first: point it at your own model provider keys and it runs against them directly. Your keys are stored locally and only the calls you make go out — see [Privacy](/account/privacy). BYOK works **with no account, free forever**. ## Providers out of the box Add a key in **Settings → Providers** and the provider's models appear in the picker: | Provider | Examples of what you can run | | ----------------- | ----------------------------------------- | | **Anthropic** | Fable 5, Opus, Sonnet, Haiku | | **OpenAI** | GPT-5.5 family, o-series reasoning models | | **xAI** | Grok 4.x family | | **Google Gemini** | Gemini 3.5 / 2.5 families | | **DeepSeek** | DeepSeek v4 Pro / Flash | | **Mistral** | Codestral, Devstral, Mistral Large | | **Groq** | Fast open-weight serving (Llama, Qwen) | | **OpenRouter** | One key, most models on the market | Beyond these, an **OpenAI-compatible** provider slot accepts any endpoint that speaks the standard API — plus first-class slots for Azure, Vertex, and Bedrock setups. ## Run models locally — no key at all V3Code runs local models right in the editor — fully offline, free, and private. - **Built-in local inference** — V3Code bundles a code model it can run itself (Qwen-Coder class, GPU-accelerated with a CPU fallback). No server to set up. - **Ollama** — point V3Code at your running Ollama and your installed models appear in the picker automatically. (If a call fails, it's usually because Ollama is off.) - **LM Studio and vLLM** — autodetected the same way. Local models pair naturally with the [semantic index](/editor/semantic-index), which already runs its embeddings on-device — a fully local setup end to end. ## When you need a key - **The beta `free-auto` connection** does not need an account or API key. It uses currently available free cloud models and can be unavailable or rate-limited. See [free models](/models/connected-plans#free-agent-models). This is separate from Auto orchestration tiers that require a configured provider key. - **Any provider you want to run yourself** — set the key and use that model directly instead of hosted credits. ## Hosted vs. BYOK - **Hosted (paid plans)** — V3Code runs inference for you on its own models and meters; nothing to set up. Hosted tiers live in their own namespace, so a hosted **V3Fast** and your own BYOK DeepSeek key never collide — you can use both side by side. See [Plans](/models/plans-and-trials) and [Token wallet](/models/token-wallet). - **BYOK** — you supply the key and pay your provider directly. Good if you already have provider credit or want full control of the model. # Plans & trials V3Code has one editor and four plans: **Free, Pro, Power, and Max**. Plans are managed on [v3code.dev](https://v3code.dev) — see the site for current pricing; this page covers what each plan includes. Usage on paid plans is metered per cycle — see [Token wallet](/models/token-wallet). Your existing model-provider subscriptions are separate from V3Code plans. You can [connect supported provider plans](/models/connected-plans), and their models will appear in the picker with usage charged against the provider's own limits. ## Plans | Plan | What you get | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Free** *(forever)* | The full editor on **BYOK** or fully local models: local semantic indexing, structural search, all Context Bridge tools, persistent memory, Visual Edit, the auto router's base tier. No card, no account. | | **Pro** | Everything in Free · hosted model meters (**V3 Fast + V3 Pro**) · Opus escalation rounds · optional cloud indexing (dual local + cloud index) · live usage meter in the editor. | | **Power** *(Popular)* | Everything in Pro · the upper auto-router tiers (Auto / Hybrid with Opus escalation) · **Build 4.5** meters · agent-driven browser · **MCP connect** · effort control · on-demand overage headroom. | | **Max** | Everything in Power · Opus-class hybrids at full tilt · the highest meters and maximum overage headroom · new hosted models first · priority support. | ## Trials New accounts get a short hosted trial — enough to feel the hosted tiers and the router before deciding. Everything in Free keeps working when a trial ends; BYOK and local never expire. ## How usage is metered Paid plans include usage across three buckets — **V3 Pro / V3 Fast** (fast tier), **Auto / Hybrid** (the auto router and hybrid tiers), and **Opus** (premium) — plus **on-demand overage** for anything past your included limits, billed in arrears. The [Token wallet](/models/token-wallet) shows each meter for the current cycle. ## Free vs. paid, in one line **The editor is free.** The full local experience — [Context Bridge](/editor/context-bridge), the [local index](/editor/semantic-index), [memory](/editor/memory), BYOK, and the [browser](/studio/browser) — costs nothing. Paid plans add the hosted pieces: the [auto router](/models/overview)'s upper tiers, hosted models with nothing to configure, and **cloud indexing**. > Note: > > If your **local index** ever runs into trouble, V3Code falls you back to the **cloud > index for free** — so you're never stuck without search, even though cloud indexing is > otherwise a paid feature. # Web builder V3Code's web builder is an **open-source, local, agent-driven design platform**. Instead of starting every site or UI from a blank file, you start from a library of hundreds of high-end designs, make them yours by setting your colors and tokens, and hand the build to an agent. ## Where the designs come from The builder is a **fork of Open Design**, packaged into a design repo the agent pulls from and served in webviews inside V3Code's own browser. It ships hundreds of designs — full websites, decks, prototypes — spanning first-party/official templates and community submissions. You browse and curate them in [Discover](/studio/discover), then build the ones you like. ## Make it yours: tokens first Pick a design, then set the palette. A theme editor exposes your design tokens as editable swatches — app background, surfaces, borders, foreground/muted/dim text, and the accent — with a live side-by-side so you can compare, say, "Current" against a "Proposed Darker" variant before committing. Representative tokens: | Token | Role | | ----------------------------------------- | -------------------------------------------- | | `--bg` | App background | | `--surface`, `--surface-2`, `--surface-3` | Panels/sidebar, inputs/cards, hover/overlays | | `--border`, `--border-2` | Dividers, focus ring | | `--fg`, `--fg-muted`, `--fg-dim` | Primary / secondary / placeholder text | | `--accent` | Accent | It's the "choose your colors" step you'd expect from a modern tool — you set the system, the design conforms to it. ## Any agent builds it Once you've picked a design and set your tokens, an agent builds it out — the same agent stack that powers the rest of V3Code, served through the editor and the built-in browser. This ties into [Design mode](/editor/design-mode), which loads the design skill so output stays on-system. # Live previews V3Code has its own built-in browser, so what the agent builds renders live, right beside your work — no second window, no context switch. And you're not limited to watching: you can reach in and edit the page directly. ## Visual Edit Turn on **Visual Edit** and every element on the live page becomes selectable. Click a heading, a button, a section, and a style panel opens for it: - **Text** and **Background** color - **Size** and **Weight** - **Padding** and **Radius** Your changes **stage** as a list of edits rather than applying blindly. When you're happy, hit **Send edits to agent** — the agent takes your visual changes as precise instructions and applies them in code, with an optional note ("make the hero pop"). It's design-by-pointing: you show the agent what you want instead of describing it. > Note: > > Visual Edit shares the selected element and your staged changes with the agent ("Sharing with Agent"), so the handoff from "I tweaked this in the browser" to "the agent changed the code" is one click. ## Why it's in V3Code's browser Because the preview, the visual editor, and the agent all live in the same place, an edit loop that normally spans a design tool, a browser, and an editor collapses into one surface. Pair this with [Discover](/studio/discover) and the [Web builder](/studio/web-builder) and the whole path — pick a design, set tokens, build, preview, tweak, ship — stays inside V3Code. # Discover Discover is the front door to V3Code's [design platform](/studio/web-builder): a browsable feed of hundreds of designs you can pick from instead of starting from scratch. Full websites, slide decks, and prototypes, spanning polished first-party templates and community work. ## Browse and curate Each design is a card with a live preview and a short description. You react to it to shape what you build from: - **Love it** — keep it, use it as a starting point. - **No** — pass; tune what surfaces next. - **Note** — leave a note for yourself or the agent. Examples of what's in the feed: a developer-native "Terminal Mono" deck, a neo-brutalist "Raw Grid" pitch deck, a "Retro Windows" Windows-95 throwback, a 3D-creator portfolio prototype, a precision-agriculture landing page. Cards are tagged by kind and origin — `deck`, `slides`, `prototype`, and `community` / `first-party` / `official` / `example`. ## From Discover to built Pick a design you love, set your [tokens](/studio/web-builder), and an agent builds it — then [preview and hand-edit it](/studio/live-previews) in V3Code's browser. Discovery is also how free users meet the platform: it's meant to be in front of everyone, not gated. # The browser V3Code ships its own browser, and the agent can **drive anything in it** — not a screenshot-and-click toy, but a **Playwright-backed automation surface** with dev-grade tools. The agent can navigate, read the DOM headless, take images, click through a page, work an authenticated flow, reverse-engineer a layout — it can even drive interactive pages and games. Real work on the web, not a demo. It's **DOM-driven first** (the agent targets real elements by reference and selector) with **screenshots available** when it needs to see the page — so it's precise where a purely visual agent guesses. The headline trick: it can **reconstruct a website pixel-perfect** — pull a live site's build back into source you can study, clone, or rebuild from. ## What the agent can do ### Drive the page ### open\_browser / open\_browser\_page Open a URL — with mobile emulation when you need it — in the built-in browser. ### navigate\_page · click\_element · type\_in\_page · hover\_element · drag\_element Full interaction: navigate/back/forward, click (including double-click and specific mouse buttons), type text and keys, hover, and drag between elements. ### handle\_dialog Handle JavaScript dialogs and native file pickers — including selecting files for upload. ### fill\_form Fill a whole form in one call. ### See and extract ### read\_page · extract\_page\_data · screenshot\_page Read page content, pull structured data with a focus hint, or screenshot the page or a single element. ### get\_computed\_styles · watch\_page Inspect an element's computed CSS, or wait for the page to reach a condition before continuing. ### Inspect like a developer ### get\_browser\_console\_logs · intercept\_network · get\_browser\_network\_log Read the console, intercept requests by URL pattern (optionally with bodies), and pull the network log — the tools you'd use to understand or reverse-engineer how a site actually works. ### reconstruct\_page\_sources Reconstruct a live page's sources into files — the basis for cloning a site pixel-perfect, bundling it out of the browser, or studying how it's built. ### Go beyond the built-ins ### run\_playwright\_code Run arbitrary Playwright code against the page for anything the named tools don't cover. ### save\_browser\_session · restore\_browser\_session Save and restore a browser session, so the agent can stay logged in across runs instead of re-authenticating every time. ## Why it's more capable than a basic browser agent Most agent browsers can click, type, and screenshot. V3Code's adds the developer layer: **network interception, console access, computed styles, session persistence, page-source reconstruction, and raw Playwright** — which is what lets it reverse-engineer a page, clone a layout, drive an auth'd flow, or debug why a site behaves the way it does. # MCP V3Code speaks the **Model Context Protocol (MCP)**, so you can extend the agent with external tools — issue trackers, databases, browsers, your own servers — without leaving the editor. ## Install from the editor The **MCP Marketplace** tab lets you browse available MCP servers and install them in a couple of clicks. Once a server is connected, its tools show up alongside V3Code's built-in tools and the agent can call them. ## Bring your own servers V3Code reads the standard MCP config format — the same `mcpServers` schema used across the ecosystem — from `~/.v3code/mcp.json`: ```json { "mcpServers": { "my-server": { "command": "npx", "args": ["-y", "@yourorg/your-mcp-server"] } } } ``` Anything you've built or configured for other MCP clients works here too. The editor can open the config file for you, and servers added through the marketplace are written to the same file — one config, no magic. > Note: > > V3Code deliberately owns its MCP experience: it doesn't silently import configs from > other editors, so the servers you see are exactly the servers you chose. ## The other direction Connecting servers **to** V3Code is half the story — V3Code also **serves its own code-intelligence tools over MCP** to any agent you already use. See [Bring V3Code to any agent](/connect/other-agents). # Extensions and the connector marketplace ## Choose the right kind of extension | You need | Use | | --------------------------------------------- | ------------------------------------------------------- | | Reusable instructions for an agent task | [Skills](/editor/skills) | | Editor language support or editor UI features | The editor's Extensions view | | Tools from another service | [MCP](/connect/mcp) and the connector catalog | | A separate coding agent in native chat | [Agent Client Protocol](/connect/agent-client-protocol) | These are separate systems. Installing a skill does not install a service, and installing an editor extension does not automatically expose tools to the native agent. ## MCP connector catalog V3Code's connector marketplace is a catalog of MCP servers, not the editor extension marketplace. Open **Settings → MCP Servers** to review available connections and their setup requirements. Some connectors need a sign-in flow, others need credentials or a local executable. Follow the card's setup action, inspect its reported status, and verify that tools are available before asking the agent to use them. Availability in the catalog does not mean the service is authenticated or working. ## Editor extensions Use the editor's Extensions view for editor add-ons. Check publisher, compatibility, permissions, and installation errors. An extension may depend on APIs or services that are not available in this build. ## Plugin compatibility is not automatic V3Code does not promise that another agent's plugin manifest, marketplace source, hook format, or slash commands can be copied into the native editor unchanged. Use the documented skill format, MCP configuration, or the external agent's own setup. Only install code and connectors you trust. Tool access can expose project files and, for browser-enabled agents, signed-in pages. See [Other agents](/connect/other-agents) and [Privacy](/account/privacy). # Other agents V3Code's [Context Bridge](/editor/context-bridge) isn't locked inside its own chat. You can expose the same structural tools — symbol context, call graphs, dependencies, notes, semantic search — to **any agent that speaks MCP**, over a single endpoint. ## Why do this It turns V3Code into an **intelligence layer** for whatever agent you already use. Point Claude Code or Cursor at the endpoint and they get the same LSP-backed view of your codebase that V3Code's own agent has — structure and relationships, not just text. Their answers get sharper because their inputs get sharper. ## Connect from Settings Open **Settings → Expose V3Code**. The status at the top tells you whether the local server is running and which workspace it serves. V3Code offers three guided connection paths: - **Codex + ChatGPT desktop** — choose **Connect**. If V3Code finds an older fixed-port entry, the button becomes **Repair** and replaces it with the stable definition. - **Claude Desktop** — choose **Create extension**, then double-click the generated `V3Code.mcpb` file to install the local connector. - **Claude Code + other local agents** — choose **Copy config** and paste the stable stdio definition into that client's MCP configuration. The stable definition follows the correct running editor even if its loopback port changes after an update or more than one build is open. It stays on the current computer and does not require a V3Code account. The page also shows a **Current direct endpoint (advanced)** for clients that specifically need streamable HTTP. Treat the shown URL as runtime state, not a permanent port to copy into long-lived configuration. V3Code writes the live endpoint and open workspaces to `~/.v3code/endpoint.json` for local discovery. > Tip: > > Tell your agent to call **`orient`** first — it returns a project briefing and index > health in one call, so the agent starts every session already knowing the codebase. ## What's exposed V3Code serves a **curated set of tools** over the endpoint. Any MCP client you configure can call them in-process against your local project: - **Structural reads** — `get_symbol_context`, `get_call_graph`, `get_file_context`, `get_file_dependencies`, `pack_context`, `get_project_briefing`, `semantic_search`, `find_text`, `get_build_errors` (live language-server errors, no recompile). - **Memory & recall** — `list_notes`, `search_notes`, `deep_recall`, `workspace_delta`, `recent_edits`, `session_diff`, `index_health`, plus write-side `remember` / `forget`. - **Precision search** (when the native symbol sidecar is running) — `symbol_lookup` (definitions/references) and `impact_trace` (change blast-radius). - **Handy composites** — `orient` (briefing + index health in one call), `run_subagent` (a read-only investigation subagent on your own key), and `send_chat` / `get_chat` to drive and read your live V3Code chat. - **Review and navigation** — bounded `read_file`, `ls_dir`, `git_log`, and `git_diff` calls for clients that need review context without shell access. - **Durable local coordination** — private notebooks and collaboration records tied to the serving editor and workspace. Long research jobs return a job ID that can be checked, retrieved, or cancelled instead of holding one request open indefinitely. Editing, terminal, and git-write tools are **deliberately not exposed** over the endpoint — external agents get V3Code's intelligence, not the keys to your filesystem. ## Make your agent actually use it Here's the honest part most integration docs skip: **connecting the endpoint isn't enough.** Agents default to their built-in habits — grep, read, guess — and won't spontaneously reach for tools they don't know they should prefer. The fix is a small standing instruction (a "skill") that tells your agent when these tools beat its defaults. The **Teach Claude when to use V3Code** control can copy an instruction file for that client. For any other model, adapt the same behavior to its project-instruction format: ```markdown --- name: v3code description: Use the v3code MCP tools for code intelligence and memory whenever working in this repo — the running V3Code editor indexes it live, so results are current and authoritative. Trigger on any "where/how/what implements X", symbol lookup, impact analysis, build-error check, or memory recall. --- # Using V3Code's live code intelligence This workspace is indexed live by the V3Code editor's MCP server (`v3code`). Prefer its tools over grep/read for exploration. - Call **`orient`** first on every non-trivial task — project briefing + index health in one call. - **`semantic_search`** for "where/how is X done" (meaning); **`find_text`** for exact strings only. - **`pack_context`** instead of opening five files; **`get_symbol_context`** / **`get_call_graph`** for callers, callees, and blast radius. - **`get_build_errors`** before claiming a change compiles — live language-server errors, no build needed. - **`remember` / `forget`** for durable notes; **`deep_recall`** when you need history the context dropped. ``` That instruction changes the default behavior: the agent starts sessions with `orient`, searches by meaning instead of guessing filenames, and checks real compiler state before declaring victory. > Note: > > Exposing V3Code is the opposite direction from installing an MCP server in V3Code. > **MCP Servers** gives V3Code new tools; **Expose V3Code** gives another local agent > V3Code's tools. # Agent Client Protocol V3Code can host compatible external agents in native chat through the **Agent Client Protocol (ACP)**. You choose the agent; it keeps its own identity and conversation while V3Code keeps the editor, workspace context, and approval boundaries visible. Compatible agents appear beside V3Code in the compact agent picker. Choosing one opens a new native chat with that agent's identity, approvals, diffs, and advertised slash commands instead of squeezing it into the current V3Code conversation. ## Before you begin - Install the agent using its own documentation. - Open the project folder you want that agent to work in. - Keep V3Code up to date. ACP setup guidance described here is available in **1.4.9-0098** and later. ## Add an agent ![Agents settings showing an external agent with setup, chat, and per-agent access controls](/images/agent-settings-0098.png) Choose Memory / Index and Browser access before opening a new agent chat. Launcher available does not prove sign-in is complete. Screenshot supplied September 17, 2026. 1. Start a new chat and open the agent menu. 2. Choose **Add agents** to open the relevant Settings screen. 3. Enable a listed agent, or choose **Add custom agent** and enter the command that starts its ACP stdio process. 4. Choose which editor capabilities new chats receive: - **Memory / Index** shares the workspace-scoped V3Code context bridge. - **Browser** shares the native browser through the authenticated bridge. Turn this on before opening the chat; existing chats do not gain it later. 5. Return to the agent menu and select the agent to begin a new conversation. Selecting an agent creates a separate agent chat. It does not send the current chat transcript to that agent, and it does not close your editor tabs. If V3Code Terminal is already installed, **Add V3Code Terminal** registers its `v3code acp` command. The button does not install the terminal or sign you in. ## Complete setup or sign-in deliberately An agent marked **Launcher available** can be started from your machine, but it may still need its own installation, account setup, or sign-in. Use **Setup / sign in** when it is available. V3Code opens an integrated terminal and can stage a single reviewed command for you. Read it before continuing, then press Enter yourself if it is correct. V3Code does not run setup commands automatically, copy account credentials, or complete a sign-in flow on your behalf. If the setup screen is empty or the command is not familiar, use the agent's own documentation instead of guessing a package command. When an agent supports managed authentication, it may ask for consent inside chat before starting its authentication method. Terminal-only sign-in still happens in that agent's own tooling. V3Code does not automatically download agent binaries. ## Keep project context accurate ACP chats are tied to the workspace they started in. Reading a file outside that folder does not retarget V3Code's index, memory, or workspace-scoped context. To work in another project: 1. Open that folder in V3Code, optionally in another window. 2. Start a **new** agent chat in that folder. 3. Wait for the index to report ready before expecting indexed search or workspace context to be available. You can still use an agent while an index is building. It simply should not claim that indexed project context is ready until V3Code says it is. ## When something is not working - **The agent is listed but will not run:** complete its documented install or sign-in first. Launcher detection alone does not verify authentication. - **The wrong project is in context:** open the correct folder and begin a new agent chat. - **Indexed search is unavailable:** check index readiness, then let the local index finish before retrying the question. - **An advertised slash command is missing:** start a new agent chat after setup. Commands are negotiated when the ACP session starts. - **You need code intelligence in another client instead:** use the [MCP connection](/connect/other-agents), which is a separate local integration. > Note: > > External agents are separate local programs and keep the operating-system permissions > of the user who launched them. V3Code displays protocol-routed approvals and diffs; it > is not an operating-system sandbox for the external process. # Billing Your plan and billing live on [v3code.dev](https://v3code.dev). The editor shows your usage; the hub handles payment. ## Managing your plan Sign in at [v3code.dev](https://v3code.dev) to see your current plan, upgrade or downgrade, and manage payment. The editor is free; paid plans add the [auto router](/models/overview) and cloud indexing — see [Plans](/models/plans-and-trials). ## Seeing what you've used The [Token wallet](/models/token-wallet) in the editor shows your usage and a cache-aware cost estimate — per session, day, and cycle, broken down by model. On paid plans, included usage is metered in buckets (fast tier, auto/hybrid, Opus) with on-demand overage beyond your limits. # API keys (hub) V3Code is [BYOK](/models/byok)-friendly. Add your model provider keys in Settings and V3Code uses them directly. ## Where keys live Your keys are stored **locally** on your machine, not on a server. Only the model calls you make use them, going straight to the provider you're calling. ## Which keys you might add - **Anthropic** — required for the free [auto router](/models/overview). - **Any other provider** you want to run yourself instead of using hosted credits. - **Local models** need no key at all — see [Run models locally](/models/byok). # Privacy V3Code is built local-first. The intelligence that makes it good — the index, the structural tools, your memory — runs on your machine, not in someone's cloud. ## What stays local - **Your code.** The [semantic index](/editor/semantic-index) is built and stored on-device, and [Context Bridge](/editor/context-bridge) reads your files in-process. Nothing is uploaded to be indexed. - **Your memory and notes.** Workspace notes live in `.v3code/notes.json` in your project; usage is tracked locally. - **Your keys.** [BYOK](/models/byok) keys are stored locally, and with local models you can run fully offline. ## What leaves your machine, and when The only traffic V3Code makes is the **model calls you choose**. On BYOK, that goes straight to your provider with your key. On a hosted plan, it goes to V3Code's inference. Cloud indexing (a paid feature, or a free fallback if your local index breaks) is the one case where indexed content is processed in the cloud — and it's opt-in by plan. # Tools reference The V3Code agent has a large set of built-in tools. Reads run automatically; anything that changes files, runs commands, or drives the browser asks for approval first (see [Modes → Approvals](/editor/modes)). This page is the reference for what actually ships. ## Files & search (read-only) | Tool | Does | | --------------------------------------------------------------- | ----------------------------------------------------------------------- | | `read_file` | Read a file or line range, paginated, with a COMPLETE/TRUNCATED footer. | | `ls_dir` · `get_dir_tree` | List a directory / a shallow tree. | | `search_for_files` · `search_pathnames_only` · `search_in_file` | Full-text, filename, and in-file search. | | `find_text` | Workspace text search with optional surrounding context lines. | | `read_lint_errors` · `get_build_errors` | Live language-server diagnostics for a file / the whole workspace. | | `read_skill` | Read an agent skill's full `SKILL.md` by name. | ## Edits (approval: edits) | Tool | Does | | ------------------------------------------------- | ---------------------------------------------------- | | `create_file_or_folder` · `delete_file_or_folder` | Create / delete files and folders. | | `rewrite_file` · `append_file` · `edit_file` | Replace, append to, or search-replace within a file. | | `rename_symbol` | LSP rename across the workspace. | All edits pass through a shadow-workspace lint verify with rollback before hitting disk. ## Terminal, tests & sandbox (approval: terminal) | Tool | Does | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `run_command` | One-shot command in a temp terminal (timeout 1–600s). | | `open_persistent_terminal` · `run_persistent_command` · `kill_persistent_terminal` | Named background terminals. `read_terminal_output` reads them (no approval). | | `run_tests` | Run the workspace test runner. | | `run_sandbox` | Run a JS/TS snippet in an isolated `node:vm`. | ## Git Reads (`git_status`, `git_diff`, `git_log`, `git_branch`, `git_remote`, `git_show`, `git_blame`) are automatic. Writes (`git_stage`, `git_commit`, `git_push`, `git_pull`, `git_checkout`, `git_stash`, `git_merge`, `git_rebase`, `git_cherry_pick`, `git_restore`, `git_reset`) ask for approval. Hard reset is blocked. ## Context Bridge (structural intelligence) `get_file_context`, `get_file_dependencies`, `get_symbol_context`, `get_call_graph`, `pack_context`, `get_project_briefing` — all read-only. See [Context Bridge](/editor/context-bridge) for details. Notes: `remember` / `forget` (approval) and `list_notes` / `search_notes` (read). ## Search & recall | Tool | Does | | ------------------------------------------------------------- | --------------------------------------------------------------------------- | | `semantic_search` | Meaning-based code search over the [local index](/editor/semantic-index). | | `symbol_lookup` · `impact_trace` | Native symbol tags and change-impact tracing (when the sidecar is present). | | `search_chat_memory` · `get_chat_session` · `get_chat_thread` | Search and read recorded chat memory. | | `deep_recall` · `get_shadow_record` | Break-glass search of the raw shadow archive. | | `recent_edits` · `workspace_delta` · `session_diff` | What you or the agent changed recently. | | `index_health` | Semantic-index status, with optional re-scan. | ## Security review | Tool | Does | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `security_scan` | Reviews supported workspace source for suspicious data flows and compares possible findings with the previous scan journal. It helps the agent notice issues; it is not a complete security audit. See [Cyber Protection](/editor/cyber-protection). | ## Web & browser `web_search` and `web_fetch` are read-only. `open_browser` opens an in-editor browser pane. The full Playwright automation suite (`open_browser_page`, `click_element`, `fill_form`, `run_playwright_code`, `reconstruct_page_sources`, `intercept_network`, session save/restore, …) drives real pages — the navigating/mutating ones ask for approval; reads like `read_page`, `screenshot_page`, and `get_browser_console_logs` are automatic. See [The browser](/studio/browser). ## Subagents, planning & image | Tool | Does | | ----------------- | ------------------------------------------------------------------------------------ | | `launch_subagent` | Background, fire-and-forget subagent; result is injected back into the thread later. | | `run_subagent` | Synchronous delegation that blocks and returns a result. | | `update_plan` | The agent's per-thread todo list (persists in `.v3code/active-plan.json`). | | `ask_user` | Ask you a multiple-choice question. | | `generate_image` | Generate an image (Grok / xAI) into the workspace (approval: edits). | # Keyboard shortcuts Because V3Code is a VS Code fork, your keybindings carry over — including the keymap you're used to. See [Coming from VS Code](/get-started/coming-from-vscode) to bring your setup across. ## The ones you'll use most | Action | macOS | Windows / Linux | | ------------------- | ----------------- | ------------------ | | Open chat | `Cmd + I` | `Ctrl + I` | | Show all commands | `Cmd + Shift + P` | `Ctrl + Shift + P` | | Open recent | `Ctrl + R` | `Ctrl + R` | | Open file or folder | `Cmd + O` | `Ctrl + O` | | Toggle terminal | `` Ctrl + ` `` | `` Ctrl + ` `` | ## Prediction and drafting | Action | Shortcut | | ------------------------------- | ------------------------------------------------------------------- | | Open Quick Edit | `Cmd + K` on macOS; `Ctrl + K` on Windows/Linux | | Accept V3Code Tab completion | `Tab` | | Reject a Tab or V Go prediction | `Escape` | | Accept a ready V Go next edit | `Tab` | | Turbo Draft (Fast) | `Shift + Tab` | | Turbo Draft (Deep) | `Alt + Shift + Tab` | | Turbo Draft (Deep, multi-file) | `Control + Shift + Q` on macOS; `Ctrl + Shift + Q` on Windows/Linux | | Accept current Turbo Draft hunk | `Tab` | | Reject current Turbo Draft hunk | `Delete` or `Shift + Tab` | | Discard remaining Turbo Draft | `Escape` | Tab-family shortcuts are context-aware. During Turbo Draft review, `Tab` accepts the current hunk instead of an autocomplete suggestion. See [Quick Edit](/editor/quick-edit), [V3Code Tab & V Go](/editor/tab-and-v-go), and [Turbo Draft](/editor/turbo-draft) for the full workflows. # Slash commands In the chat input, two shortcuts do most of the work. ## Slash commands Type **`/`** to run a command — plan, build, and the other agent actions surface right in the composer, so you don't have to describe what you want in prose. ## Context with @ Type **`@`** to pull something into context — a file, a symbol, or other project context — so the agent works against exactly what you mean instead of guessing. # Troubleshooting ## Search or indexing seems off The [semantic index](/editor/semantic-index) rebuilds incrementally on startup and as files change. If results seem stale, let the index reach a ready state before asking an agent to rely on indexed search. If the local embedding model is unavailable, V3Code can still use lexical search; do not treat that fallback as a completed semantic index. ### The index keeps firing and the editor feels slow **Symptoms.** The editor becomes laggy or stuttery while the logs repeat file-read errors. Typical messages say that a path is actually a directory, or that a file such as `AGENTS.md.git` does not exist. An occasional bad-path error is usually harmless. A repeating retry loop is not: it can keep walking the wrong tree, generate log noise, and spend work on files that are not part of your active project. Search results may also point to an old copy of the code, while `find_text` appears to miss files that you know exist. The most common cause is a wrong or stale workspace root. For example, the folder that contains the current work may never have been attached, while an older copy or a large neighboring repository remains attached. File-watcher churn can then surface directory paths or malformed paths as though they were source files. Fix it in this order: 1. Run `index_health` with rebuild enabled to clear stale indexed chunks. 2. Check the reported paths on disk. Confirm that directory paths are directories and that malformed paths such as `AGENTS.md.git` do not exist. 3. Attach the folder that actually contains the current project. Use `open_project` with mode `add` if you intentionally need a multi-root workspace. 4. Run a search for a symbol or phrase that only exists in the current project. The top results should come from the live root, not an older copy. 5. If an attached root is obsolete, detach it with `close_project` so duplicate-looking results cannot come from both the stale and current trees. Do not use a green `index_health` result as the only proof. A healthy index can still be indexing the wrong folder. A correct search hit from the expected root is the stronger verification. **Rule of thumb:** when indexing is noisy and the editor slows down, first verify which workspace roots are attached. The index may be repeatedly walking a stale tree rather than finding a problem in your code. ## An external agent is not ready V3Code can find an agent launcher on your `PATH` before that agent has completed its own setup or sign-in. **Launcher available** only means V3Code found a way to start it. 1. Open the agent's setup details and use its documented setup or sign-in flow. 2. Review the command V3Code stages in the integrated terminal before you press Enter. V3Code does not run the command, copy credentials, or complete sign-in for you. 3. Open a new agent chat after setup. If you changed projects, open the target folder in V3Code first, then start the new chat there so its workspace context and index match. Read the full [Agent Client Protocol guide](/connect/agent-client-protocol) for the supported setup flow and workspace boundaries. ## An MCP connection broke after an update Open **Settings → Expose V3Code**. If the Codex connection shows an older fixed-port definition, choose **Repair**. For other clients, copy the current stable definition again instead of saving the direct loopback URL as a permanent port. The current endpoint is available under **Current direct endpoint (advanced)** and in `~/.v3code/endpoint.json`. It can change when V3Code updates or when multiple builds run. ## Debug cannot collect runtime evidence The Debug evidence sink requires one trusted workspace folder. Multi-root or untrusted workspaces continue with ordinary read, command, and test tools but do not collect the loopback runtime stream. Open a single folder and trust it before retrying if that stream is necessary for the reproduction. ## A local model call fails If you're using [Ollama](/models/byok) and a call errors out, it usually means Ollama is powered off — start it and retry. For built-in local inference, make sure the model finished downloading. ## A free model will not run The beta `free-auto` connection needs no API key. Its upstream free models can be busy, rate-limited, or withdrawn. Retry later or choose a different configured connection; adding an unrelated API key will not restore free-model capacity. See [free agent models](/models/connected-plans#free-agent-models). Do not confuse that connection with Auto orchestration tiers that use configured providers. If a selected tier explicitly requests a provider key, check the connection and tier you selected before entering credentials. ## Cloud sync shows an error Cloud sync state is shown in the status bar. A paused or errored state doesn't affect local work — your local index and memory keep running. ## I do not see a new release Check the current version on the [download page](https://app.v3code.dev/download). If it is newer than your installed build, quit V3Code and use the platform's latest installer or archive. Apple Silicon Macs and Windows x64 normally receive update prompts; Intel Macs and Linux x64 are manual downloads today. If a newer build still will not install, email [support@v3code.dev](mailto:support@v3code.dev) with your operating system, CPU, installed version, and a screenshot of the message. Leave API keys, account tokens, and project files out of the report. # Changelog ## 1.4.9-0098 — September 16, 2026 **Agents, Debug, Cyber Protection, and a calmer editor.** - Compatible ACP agents now run inside native V3Code chats with their own identity, approvals, diffs, slash commands, and separate conversation history. The compact agent picker makes the active agent clear without replacing open editor tabs. - **Settings → Agents** adds registry and custom-command setup, honest launcher and sign-in states, per-agent Memory / Index and Browser access, and an explicit V3Code Terminal ACP entry. Setup commands are staged for review, never run automatically. - **Connected accounts** brings models from supported provider subscriptions into the V3Code picker without API-key billing. A separate free-auto lane rotates across the currently working free agent models, with clear warnings that capacity and the roster can change. - **Debug mode** adds an evidence-first reproduce → localise → prove → fix → guard workflow, bounded repair tools, visible operation lifecycle, transcript density, and a loopback runtime-evidence dock for trusted single-folder workspaces. - **Cyber Protection** adds a composer toggle that helps the agent notice possible security concerns it might otherwise overlook. A built-in scan supplies review leads, followed by authorization and business-logic checks that still require judgment. It is an aid, not a complete audit or a guarantee that a project is secure. - **Expose V3Code** now offers guided desktop connection, repair, local extension, and stable config paths. Review tools, pollable research jobs, and workspace-scoped local coordination expand what connected agents can use without granting shell access. - External-agent briefings make the project boundary explicit: open the target folder, start a new agent chat there, and wait for index readiness before relying on indexed context. - Background memory indexing now pauses deliberately between bounded idle slices, which avoids repeatedly scheduling work in an otherwise idle editor. This is a targeted reliability improvement, not a universal speed claim. - Retired local-embedding selections resolve to the supported path, while lexical search remains available if local embeddings cannot load. - V3Code 1.4.9-0098 is available for Apple Silicon Macs and Windows x64 through their stable update channels. Signed Intel Mac downloads and Linux x64 early-access archives are available manually from the [download page](https://app.v3code.dev/download). ## 1.4.9-0048 — July 10, 2026 **Auto-update is live.** V3Code now keeps itself current. - The editor updates itself — new builds arrive in the background on macOS, signed and notarized end to end. - Removed the bundled GitHub Copilot runtime, making the download noticeably smaller. - Fixed a settings error notification that could appear on startup. ## 1.4.9-0047 — July 10, 2026 **Plans, meters, and V3Code Build 4.5.** - Account tiers arrive, with a live token meter in the profile menu so you always know where you stand. - New model: V3Code Build 4.5. - Opus Hybrid upgraded — harder problems now route to a stronger executor automatically. - Smoother sign-in handshake, plus rendering fixes in packaged builds. ## 1.4.9-0044 — July 9, 2026 **Signed macOS builds.** - macOS builds are now Developer ID signed and notarized — no more Gatekeeper warnings. - Update feed infrastructure in place, paving the way for auto-update. - V3Code now lives at v3code.dev. ## Earlier — June–July 2026 **Foundations.** - Semantic index quality jump — a new embedding model on the auto setting makes codebase search markedly sharper. - Persistent memory with knowledge-graph recall: the agent remembers your project between sessions. - Beast search joins the built-in toolset. - Prompt assembly presets for tuning how much context each request carries. *** The full timeline, back to day one, lives at [v3code.dev/changelog](https://v3code.dev/changelog). # Documentation for agents ## Use a single page Choose **Copy for LLM** below any page title to copy that page's authored content as Markdown. **View as Markdown** opens the same content without navigation or interface elements. If clipboard access is blocked, use that link and copy the text manually. Page exports live at `/markdown/.md` and regenerate on every build. For example, [Skills as Markdown](/markdown/editor/skills.md). Use the same documentation you read here as plain-text context for an agent. The files are generated from the authored pages used by this Astro/Starlight site on **every build**. They do not include the site's navigation, HTML interface, or footers. ### [Start with the index](/llms.txt) Every docs page, organized by topic, with a link and a one-line description. ### [Read all documentation](/llms-full.txt) All page content in one Markdown file, with page titles as headers. ## What is llms.txt? `llms.txt` is a plain-text, Markdown-formatted guide to documentation for language models. It helps an agent find the right page without reading menus or guessing routes. It is a documentation convention, **not an executable instruction, an MCP connection, or an automatic installation**. A client will not necessarily discover or load it by itself. Prefer the index first. Ask the agent to read the relevant linked pages; use the full file when it needs broad context and has room for it. Reading the entire file can consume more of your model's context window. ## Use it in V3Code Paste this into your agent chat: ```text Read https://docs.v3code.dev/llms.txt and follow the documentation links relevant to my question. Explain how to connect my existing provider plan in V3Code. Distinguish provider models from external ACP agents and MCP tools. Cite the pages you used and say if you could not access them. ``` The selected agent must have a way to fetch the URLs. If it cannot, download the text and attach it using the client's normal file-context controls. Do not assume it has read a page merely because you pasted its address. ## Use it in Claude Code or Cursor Give Claude Code or Cursor the same prompt and documentation URL in its agent chat. When it asks to fetch the documentation, review that request normally. If web access is unavailable, attach a downloaded copy instead. For a recurring project instruction, add a short note to the instruction file that your client actually uses: ```text For V3Code-specific behavior, consult https://docs.v3code.dev/llms.txt first. Read the relevant linked guides. Do not invent settings, commands, or capabilities. If the documentation is unavailable, say so instead of assuming its contents. ``` This does not change the agent's tools or permissions. Client capabilities and context limits still apply; the documentation does not override your project's instructions. ## Download a local copy ```bash curl -fL https://docs.v3code.dev/llms.txt -o v3code-docs-index.md curl -fL https://docs.v3code.dev/llms-full.txt -o v3code-docs-full.md ``` Review files before adding them to a shared repository. A downloaded copy does not update itself: download it again when you need current documentation. ## What is included? The index follows the docs sidebar: Get Started, The Editor, Models & Tokens, Studio & Discover, Connect, Account, and Reference. This guide is included too. The full file preserves prose, links, lists, tables, and code examples as Markdown. Visual components become readable headings, links, image descriptions, and captions—not HTML widgets. Screenshots are still images: an agent without vision can read their descriptions, but cannot infer details that are only visible in the image. No account credentials or private editor sessions are included in these public documentation exports.