fs.read, fs.write, fs.edit, fs.delete and the selected shell tool use bound workspaces. Shell inputs describe the command, timeout and optional terminal input; the Kernel chooses execution permissions. A confirmed Plan authorizes its declared operations and targets. Workspace Shell authorized by a Plan enforces its declared writable paths; command details within that scope do not require reconfirmation. A separate approval can authorize an additional workspace Shell call within the workspace boundary; it applies only to that call and does not expand the Plan. The Kernel asks before executing file changes outside the Plan. Host Shell has broader access: with an active Plan or Plan approval enabled, every Host call needs separate approval before execution. That approval authorizes the entire call with host-user permissions, leaves the Plan unchanged and does not authorize later calls. Neither Plan writable paths, external permission allow nor an existing run-level Host grant replaces it. Without a confirmed Plan, workspace permission allow remains an explicit advance authorization for workspace changes.
Settings > Tool permissions > Command denylist stores one command per line. Rules match command names and argument prefixes before Shell approval or execution, including when other permissions allow execution. The default rule blocks recursive forced root removal with rm; ordinary project cleanup is unaffected. An explicitly empty list disables these rules. Changes apply to the next run. This is syntactic matching, not script evaluation.
Delegated execution approval reviews additional access and execution requests through a separate model request. Select its model in Settings > Models and services; leave the selection empty to use the current run's model with an independent review context. The reviewer receives original task instructions, confirmed Plan scope when present, the exact prepared operation and the requested access. Necessary host environment checks can be approved without another user confirmation. Its decision applies only to that call. An uncertain or failed review asks the user; explicit command rules and human-only controls remain effective. This setting does not approve Plans, choose engineering routes or answer the Agent's questions for the user.
Tasks follow the execution environment specified by the user and project instructions. A task requiring a container uses that container for its commands. Interactive input belongs to its individual tool invocation. One invocation does not permanently change the shell or working directory of later calls.
Tool results retain success, failure and denial facts. Read a denial and the current Plan scope before correcting arguments or scope; do not repeat an unchanged rejected call. Reports distinguish executed, passed, not executed and unsupported-environment results. A progress label does not change these execution facts.
Tools report their actual start and available stdout/stderr while running. Live output is a bounded view; the Kernel keeps the full captured output archive, while the Session journal stores lifecycle facts. A silent command or output redirected to a file does not generate console output. Final results replace the live view and remain the authority for success or failure.
A Plan describes proposed changes, authorized scope and validation. When creating a module, it can propose the module's explicit directory scope, including new files, for user approval. Adding scope to an existing Plan preserves its phases, verification and progress and requires confirmation of the added scope. The review shows the additions and reason first, with the complete effective Plan available in a disclosure.
The task panel displays the Agent's current Todo list. Each entry has a phase description and one status: pending, inProgress, completed or blocked. todo.update replaces the complete ordered list in one call; an empty list clears it. The update does not require a Plan, ToolRecord IDs or user approval. When the run has no Todo list yet, confirming a Plan initializes it from that Plan's steps; later Plan changes preserve an existing list.
For multi-step work, keep phases few and meaningful and combine related work. The Agent chooses a suitable count; there is no fixed limit. Trivial work can omit the list. Updates are useful when progress changes, not after every tool call or before every answer. Todo is independent of permission and does not gate the final answer or run completion. Unfinished and blocked work retains its actual status; marking a phase complete does not replace tool results or validation evidence.
GUI, CLI and TUI share the same Host and Session. A Host automatically started by an application stops after its last client disconnects and no tasks are running. Running tasks continue in the background, then the Host stops when they finish. A task waiting for a user decision keeps its state in the Session journal and permits the idle Host to stop. Reading a Session projects its persisted history without starting a runtime. An explicit execution or decision command restores the task when needed.
Use deepcode-cli start-host to start a persistent service, or keep the currently shared Host running after clients exit. Use deepcode-cli stop-host to explicitly stop that service. Closing one client does not stop another client's work. The Host owns service shutdown and each tool invocation owns its child processes.
The model picker shows user-defined profile names and the reasoning levels supported by that profile. Reasoning status and elapsed time describe the current request. A long request alone does not establish that the Agent Loop is stuck; inspect Provider completion, tool duration and the last error.
The local Provider stream has no body idle timeout or total duration limit. Users can cancel an unresponsive request. The Kernel transport reuses its HTTP connection pool and gives connection establishment 10 seconds. Session retries only explicitly classified transient Provider network failures, with five total attempts per logical request and cancellable waits of 1, 2, 4 and 8 seconds. Each attempt preserves its identity, error chain, available OS code and archive location. HTTP rejections, malformed responses, tool errors and user cancellation do not trigger this retry policy. Failed-attempt partial output is discarded; local tools execute only after a complete validated Provider turn.
When attempts are exhausted, the run stops and the Session journal records a failure-state index into its existing messages, attempts, tool records and plan. This is not a second execution history or an automatic rollback. Users can continue the original Session, or start another Session that reads the source with session.read. Reading history requires neither Provider calls nor the historical runtime. Process termination or unavailable storage can prevent a final snapshot; errors from snapshot persistence or cleanup remain secondary to the original failure. Cancellation is shown as an unfinished generation and does not mark pending Todo entries complete.
Input cache hit rate is cached input tokens divided by total input tokens. The context indicator shows the last settled Agent request. Permission reviews and context compaction do not replace that reading. The session-wide cache indicator includes all requests. Settings provide token details. Different ratios across these scopes are not by themselves a calculation error.
The model, task identity and execution settings remain fixed during a run. Saved plugin registration, permission, search, document and environment settings activate on the next run. Content changes to a Skill or CLI plugin already selected for the run are read before the next model request; existing calls keep their prepared content. User plugin mentions and Agent-requested plugin activation are independent inputs. Use plugin.search to discover installed capabilities and plugin.activate to load enabled plugins for this run; user mentions are optional. Both paths prepare tools before the next model request. Loading does not install plugins, enable disabled plugins or grant permission for their effects. Each request records its tool definitions, instructions, aliases and Kernel catalog binding. Earlier requests, pending approvals and in-flight calls keep their original bindings. Registration alone does not expose an optional plugin. A preparation failure retains its reason and is not reported as an applied selection. Tool results, Skill text and new messages append to history. Do not rewrite historical facts, reduce reasoning effort, hide errors or fabricate usage to claim improved cache efficiency.
A message may contain only file attachments. During a running task, newly attached images and other immutable file snapshots join the same run after the current model request and its tools settle. They enter the next request without changing the model, project directories, earlier resource handles or write permissions. Images still require a model with image-input capability. Project-directory changes continue to apply to the next run.
Local links retain their line and column. Relative links are resolved against the conversation's bound directories by checking the exact target, not by searching the project. A unique target opens directly; multiple targets require an explicit choice. Missing paths and read failures retain their diagnostics. Absolute links keep their existing resource binding.
Command, attachment and file-opening notices above the composer have a dismiss button. Dismissing a notice leaves the draft, queued messages, pending decisions, task status and recorded failures unchanged. A subsequent failed operation can display a new notice.
Settings separate appearance, Agent behavior, execution environments, permissions, model profiles, services and plugins. Plugins are grouped by purpose: tools, display plugins and custom Skills. Tool sources include built-in capabilities, CLI plugins and MCP integrations. Built-in Skills are omitted from settings lists, counts and search. A text Skill supplies instructions; it is not an executable binary. Save a model or plugin with the controls for that item. New conversations use the last model selected for a submitted task; merely viewing history or editing a profile does not change that choice. Choose reasoning effort in the conversation selector: the last choice is saved per model and inherited by new conversations. Service default clears an explicit effort; model templates do not force an effort level. Existing conversations retain their own model settings.
The @ picker and plugin chooser share one catalog. Functional Skills and plugins are discoverable by default; product documentation remains searchable. A selected item is prepared on submission. A pure documentation reference uses structured guidance and skill.read or doc.read, without creating an execution plugin instance. MCP tools and UI extensions serve different purposes: an Echo MCP tool is selected for task execution; a UI extension renders content.
Desktop selection uses the operating system's dialog. Attachments keep one "Files and folders" entry: choose either type in the same window and add it to the existing reference list. Skill sources and workspaces also use a single selection window; creating a project requires a directory. Windows provides a "Select" action inside its native dialog to confirm the highlighted file or folder, while the standard Open action can navigate into folders. Cancelling leaves the selection unchanged. Browser sessions use the existing Host directory browser because a browser file upload does not provide a usable absolute Host path.
In Plugins, choose a Skill folder or an individual SKILL.md file, review the displayed path and save the changes. Sources can be enabled, changed or removed. Manual path entry is a secondary option. Native paths, including Windows drive paths and UNC shares, pass to the existing Skill loader without POSIX conversion. The available Skill list is read through the Host UI proxy.
For a requested polished report or document export, read skill.read with name=deepcode-documents, then only its relevant references or template. Use document.render with an output path, format (html, pdf or markdown) and content. HTML and PDF inputs are complete self-contained HTML; Markdown input is source text. Embed images and SVG; PDF export has no network or arbitrary local resource-read effect and does not execute JavaScript. Source is limited to 1 MiB and PDF output to 32 MiB.
Document generation is a workspace mutation. It shares confirmed file/directory write scope with fs.write and fs.edit, while deletion remains separate. PDF rendering uses the Python interpreter in agent.documents.pythonPath, then the configured document environment or system Python when the setting is omitted. WeasyPrint and its platform libraries must be available. A renderer error or cancellation retains the error and does not replace the existing output file. Do not claim an artifact until the successful ToolRecord returns it.
The GUI reads artifact bytes through the Session-bound resource API. The file reader displays Markdown, HTML and code as read-only source with line numbers, syntax highlighting and search. Soft wrapping is enabled by default and can be switched per file without changing its contents. It does not render Markdown or execute HTML. PDF uses continuous vertical scrolling, renders nearby pages on demand, and defaults to fit width. Page navigation, fit page, percentage zoom and selectable text remain available; reader position is retained across tab and panel-size changes. Explicitly opening local HTML or a URL in the browser uses the existing native WebView and browser tools. Selecting a local file for human reading does not attach it to a workspace or send it to the model. These viewers do not run another Agent Loop. CLI/TUI retain the same artifact facts and paths.
The TUI header shows the current run's model profile and state; a selected next-message profile appears beside the input. Pending decisions stay above the input: use /reply to answer and /decision for full details. Ordinary input retains the Session's existing queue behavior. Use /tool <activity-id> for complete tool output and /error for the original error chain and failure-state index. Mouse-wheel and page-key scrolling retain the reading position until reaching the latest output. The welcome mark is shown only for an empty transcript; the CLI keeps its plain, compact output.
Different changes become available at different boundaries:
| Change | When it takes effect |
|---|---|
| Enabled UI plugin's compiled entry module or manifest | The Host watches the selected files and replaces that plugin in the open GUI. TypeScript sources must first be compiled to the declared JavaScript entry. |
| Content of a Skill or CLI plugin already selected for a run | Prepared before the next model request. Earlier requests, pending approvals and running calls keep their original content and bindings. |
| Saved model, permission, plugin registration or execution environment settings | The next run; the active run retains its captured configuration. |
| Rebuilt GUI resources copied into an existing package | Reload the interface with Cmd+Shift+R on macOS or Ctrl+Shift+R elsewhere, or invoke browser.page with action: refreshInterface. |
| Session, Kernel, native application or bundled guidance changes | Build and install the corresponding service/package, then restart the affected processes. Editing source files alone does not update them. |
UI plugins use the supported display inputs and ports described in the UI plugin API and example. Disabling a plugin releases its views and styles; conversation drafts and history remain available. The same request and run boundaries apply to GUI, CLI and TUI; display plugins affect only the GUI.
Browser previews created in the current conversation appear in the Reader's tabs as they become available. Open Browser and Preview, select a page and use Refresh to reload that page while the Agent is running or after it stops. New pages leave your selected tab and panel visibility unchanged. A closed page is removed; selecting another page remains your choice. Switching conversations and returning restores the selected page if it is still open.
For source development, make dev-deepcode-gui starts the Docker development service. Open its URL in the internal browser and retain the same preview while editing source; Vite applies hot updates. openSelf opens packaged resources. Refreshing a page loads its current file or server content; it does not build edited source. The refresh interface returns scheduled when a reload is queued or needsUser when unsaved settings or an active save require attention. It preserves view state and does not approve discarding user changes.
Before replacing a complete application package, finish or cancel active tasks and close its clients. If a persistent Host was started with deepcode-cli start-host, stop it with deepcode-cli stop-host before replacing the program. Reopen DeepCode after installation. User configuration, conversation history and artifacts remain in their separate user directories.