StoryCode User Guide

Applies to: StoryCode Desktop v1.0 (Windows / macOS) · Last updated: 2026-09-23

1. Introduction

StoryCode is a local-first AI coding agent for the desktop. Its interface is built with Tauri 2 + React/Vite, while the agent core, session management and local services are written in Rust. Through MCP (Model Context Protocol) extensions, the agent can connect to a wide range of external tools.

1.1 Capabilities at a Glance

1.2 Architecture Overview

• Desktop UI: a Tauri desktop app (React 18 + Vite + TailwindCSS + Radix UI) with multiple windows, a system tray and native menus.
• Agent core: a Rust agent runtime that handles sessions, LLM calls, tool scheduling and approvals.
• Local API service: a built-in HTTP/WebSocket service. On startup the desktop app binds it to a random free port on 127.0.0.1; it serves only the local UI and is protected by a secret key.
• Sandboxed execution: platform-specific sandboxes (macOS Seatbelt / Windows sandbox / Linux / external isolated runtime) protect the file system and command execution.
• Extension system: MCP-based extensions, plus composable building blocks such as Skills, Subagents and plugins.

2. Installation & First Launch

2.1 System Requirements

The installer is available in English and Simplified Chinese (the Windows NSIS installer lets you pick the language).

2.2 First-Launch Setup

The first time you launch StoryCode, you go through the following steps:

1. Language: choose the interface language (中文 / English). Your choice is saved and can be changed later in Settings → Appearance.
2. User agreement: read and accept 7 terms (covering AI output risks, your duty to review output, local data access, third-party services, sensitive data, disclaimer of warranty and prohibited illegal use). Declining the agreement exits the app.
3. Model source: choose between a cloud model (configure a provider API key) and a local model (download a GGUF model and run it on this machine).
   • Cloud → opens provider configuration, where you pick a provider and enter an API key (see Chapter 6).
   • Local → opens the local model onboarding, which recommends a model based on your hardware (RAM/VRAM) and installs it in one click.

2.3 App Updates

StoryCode has a built-in auto-updater that checks storycode.cc for new versions. On Windows, updates install in passive mode automatically after downloading. In Settings → About you can check for updates and see the current app version and Agent Runtime version.

3. Interface Overview

3.1 Main Window Layout

The main window has four areas:

The window title updates with the current page/session, and the window size and position are remembered automatically.

3.2 Sidebar Navigation

• Core entries: Home, Agent, Workspace, Session History, Stories, Knowledge, MCP Extensions and more.
• Groups: Media (Audio Recording / Image Generation / Screenshot / Screen Recording) and DevTools (Terminal / SSH / Database / Remote Agents) are collapsible groups. The Media Editor is not in the sidebar; open it from a recording or from the media pages.
• Pinned favorites: eligible pages can be pinned to favorites; unpinned pages live in the collapsible More section. Reset menu restores the default layout.
• Fixed footer:
  • Vault: a status indicator (Not set up / Locked / Unlocked). Click to unlock or lock; the dropdown lets you change the master password or reset the Vault.
  • Local Model: a service status indicator (running / sleeping / loading / stopped / error). Hover to see the model name, port, backend and inference speed; the action menu can start/stop/restart the service and toggle auto-start.
  • Settings: opens the Settings center.

3.3 Tabs

StoryCode works with multiple tabs:

• Each Agent session gets its own tab, and several sessions can run in parallel.
• Tool pages such as Terminal, SSH, Database and Git also open as tabs.
• Tabs for pages such as Workspace and Screen Recording keep their state (editor content, scroll position, etc.) when you switch away.
• Closing a Screen Recording tab while recording is blocked, so you don't lose a recording by accident.

3.4 Standalone Windows

Besides the main window, StoryCode uses several dedicated windows:

3.5 Menus & System Tray

Application menu

macOS also has the standard app menu (About StoryCode, Preferences… ⌘+,, Hide, Quit, etc.); on Windows, About StoryCode is in the Help menu. Menu labels follow the interface language.

System tray

The tray menu has three items: Show Window / New Agent Window / Quit. On Windows, left-clicking the tray icon shows the main window; on macOS a template icon adapts to light and dark menu bars. The tray (menu bar) icon and the macOS Dock icon can be shown or hidden in Settings → System.

3.6 Theme & Language

• Theme: four modes — Light, Dark, OLED black (power-saving) and System — switched in Settings → Appearance.
• Language: a bilingual Chinese / English interface; the application menu is rebuilt when you switch.
• Animation: turn on Reduce motion for fewer interface animations (accessibility-friendly).

4. Quick Start

After first-launch setup, follow these steps to run your first Agent task:

1. Choose a workspace: use the workspace switcher at the top of Home to pick or open a project folder (or File → Open Directory, Ctrl/⌘+O). The Agent's file operations use the workspace as their root by default.
2. Describe the task: type the task in plain language in the Home input box, for example “Add a dark mode toggle to this React project”.
3. (Optional) Configure tools: click Tool Center on Home to pick a capability preset and enable/disable tools in bulk; missing extensions can be enabled in one click.
4. Send and approve: once you send the message, the Agent starts working. Whether you are asked to confirm depends on the current tool access mode (see 5.3): in the default Autonomous mode, routine operations run directly and only high-risk ones show an approval bar; in Manual mode, every tool call that doesn't match a permission rule needs your confirmation.
5. Review the results: every tool call, the file changes made in each turn, plan updates and Todo lists appear as cards in the conversation.

5. Agent Workspace

The Agent page (/agent) is StoryCode's core workspace. Each session has its own tab, and multiple sessions can run in parallel.

5.1 Composer & Messages

The composer at the bottom of the page offers:

In the conversation, Agent replies stream in and can show the model's thinking. Both your messages and AI messages can be copied or read aloud, and selecting text brings up quick actions. The bottom of each reply offers actions such as knowledge trace (the sources and Stories it used) and copy link.

5.2 Tool Calls & Approvals

• Tool call cards: each tool call is shown as an expandable card with its arguments, result, logs and details, forming a complete call timeline.
• Pending approval bar: tool calls that need confirmation appear in a bar above the composer, together with the reason (permission rule, exec policy, protected path, security check, etc.). You can approve or deny; some approvals offer Always allow to save the decision. System notifications take you to the session waiting for approval when clicked.
• Form requests: when a tool or extension needs more information (such as a key or parameter), a form dialog asks for it.
• Turn changes card: file changes made in each turn are shown as a diff card with file previews; you can roll back or redo a turn from Session History (see Chapter 7).
• MCP UI: MCP UI extensions can render interactive interfaces inside the conversation (rendered in a sandbox).

5.3 Tool Access Modes

The tool access mode controls how the Agent's tool calls are approved. Switch it any time from the mode menu at the bottom of the composer, or set it in Settings → Agent → Modes:

Subagents also accept inherit (use the parent session's mode), always_ask (ask every time) and never_allow (deny everything). You can set these per task in a subagent definition or when dispatching.

Tool-level permission rules (allow/deny lists) are managed in Settings → Agent → Modes by clicking the configure button next to Manual. See Chapter 18 for details.

5.4 Voice Input & Read-Aloud

• Dictation: click the microphone button in the composer to start dictating, with a live waveform. Both cloud ASR and local ASR (Whisper / Qwen3) are supported; switch engines, pick the language and download models in Settings → Speech.
• Read-aloud (TTS): AI replies can be read aloud with the local Kokoro / Qwen3 TTS engines, controlled from the playback bar. Record a reference clip to use voice cloning.

5.5 In-Session Search

On a session page, press Ctrl/⌘+F to search within the session, Ctrl/⌘+G for the next match, Ctrl/⌘+Shift+G for the previous match, and Ctrl/⌘+E to search for the selected text.

5.6 Dispatching Subagents

Type @ in the composer and choose a subagent from the list to hand a task to a predefined subagent:

• An editor dialog opens so you can adjust the instructions and parameters before confirming; progress and results appear as cards in the conversation.
• For each dispatch you can set max turns, a timeout, allowed/denied tool lists, a model override, background execution and isolated workspace mode.
• See 12.4 for creating and managing subagents.

5.7 Work Modes & Capability Presets

• Work Modes: saved combinations of model + extensions + prompt + tool policy. Switch them on Home or in a session, and customize them in Settings → Agent → Work Modes.
• Capability presets: the Tool Center groups tools by capability so you can enable or disable a whole set for the session at once.
• Tool Center: available on Home. Browse all available tools (including those provided by extensions), view each tool's details and see a summary of the session's runtime tool policy.

6. Model Configuration

6.1 Cloud Model Providers

StoryCode supports 30+ cloud LLM providers through a unified interface. Add and configure them in Settings → Models → Configure providers. Most providers need an API key (stored in the system keyring by default), and some allow a custom base URL and model list.

Once configured, switch models per task with Settings → Models → Switch models or from the model menu at the bottom of the composer. Settings → Models → Reasoning Settings sets the thinking mode (Default / Enabled / Disabled) and reasoning effort (Default / Minimal / Low / Medium / High / Extra high; available levels depend on the model) for supported models.

6.2 Local Model Service

StoryCode includes a local inference service based on llama.cpp (the /local-model page), so you can run open-source models without an internet connection:

• Model management: browse, download and delete GGUF models (including multimodal mmproj files), with resumable downloads; before downloading, the app estimates how well a model fits your VRAM/RAM.
• Runtime management: detects your hardware and picks a backend (CUDA / Metal / Vulkan / CPU), updates the runtime and cleans up old versions.
• Service control: start/stop the local inference server and view concurrency slots and inference speed; the sidebar footer has a persistent status indicator and quick actions.
• One-click recommended models: recommends suitable models based on your hardware profile and guides you through download and installation.
• External access: expose the local service to your LAN with an OpenAI-compatible endpoint and access key, so other devices and apps can use it.

Options such as the inference backend policy for local language models are in Settings → Models → Local inference. Local inference also supports image and video generation models (see 14.2); their model cards and runtime are managed in Settings → Image & Video.

6.3 Lead / Worker Models

Enable Lead / Worker models from the model menu at the bottom of the composer. A more capable Lead model handles the first few turns of a session (3 by default), after which a faster or cheaper Worker model (the currently selected model) takes over. If the Worker fails a set number of times in a row (2 by default), the session falls back to the Lead model for a few turns (2 by default) before handing back to the Worker.

You can configure the Lead provider and model, the number of Lead turns, the failure threshold and the number of fallback turns. For example, you could use a cloud Claude model as Lead and a local model as Worker to balance cost and quality.

7. Session History

The Session History page (/sessions) manages all past Agent sessions:

• Session list: browse and search all sessions, with title, time, workspace and other details.
• Resume: reopen a session on the Agent page and keep going with its full context.
• Read-only view: view a session's full message history and the runtime policy card that applied at the time (tool permissions, mode, etc.).
• Turn snapshots: view the file-change snapshot for each turn, roll back a turn's changes, or redo a turn you rolled back.
• Export and delete: session entries can be exported or deleted.
• Insights: session usage statistics and insights.
• Channel session bindings: manage bindings between IM channels (such as Weixin or Feishu) and sessions. Conversations started from IM are bound to a specific session so context carries across devices (see Chapter 16).

8. Stories (Project Memory)

Stories are StoryCode's project memory: important information from your sessions (decisions, checkpoints, summaries, notes) is saved as structured documents that later sessions can recall automatically, so the Agent “remembers” the project's history.

8.1 Interface (/stories)

• List page: filter by scope (My Stories / Automatic / Starred / Trash) or by workspace, full-text search, tag filters and a timeline view.
• Editor page: reading and structured views, a template picker, version history with diffs, and relationship management (linked files, Git commits, etc.).

8.2 Typical Usage

• Save from a conversation: use Save result on a message in an Agent session to save it as a Story, or save a session's results in bulk from the archive dialog.
• Automatic recall: with the Story memory toggle in the composer turned on, the Agent automatically searches relevant Stories as context for new tasks (matched by topic keywords and file paths).
• Stars and versions: star important Stories to keep them handy; every edit creates a version snapshot you can diff and restore.

9. Knowledge Bases

Knowledge (/knowledge) is your private document search center. It combines full-text search and vector semantic search, so you can look things up yourself and the Agent can cite them through its knowledge tools.

9.1 Managing Knowledge Bases

• Create: pick files/folders to index. Indexing runs as a background task you can review later; indexes can be rebuilt (and the rebuild can be cancelled).
• Add content: import files, fetch web pages by URL, import from the clipboard, write Markdown entries directly, or save an AI answer into a knowledge base in one click.
• Folder watching: when enabled, folder changes are detected and the index updates incrementally.
• Management: rename, delete, or open a knowledge base's folder in the system file manager; each knowledge base shows its index status badge and watch status.

9.2 Semantic Search

The search panel on the right supports natural-language semantic search (using a local embedding model) and shows the embedding model's status. The embedding model ships with the app and works without extra setup; embedding options are in Settings → Advanced → Vector retrieval.

10. Workspace & File Browser

The Workspace page (/workspace) is the hub for your project files. It keeps its editor state when you switch tabs, so you don't need to reopen files when you come back.

10.1 Browsing Files

• File tree + list/grid views: navigate with the file tree on the left and view files as a list or grid on the right, with a toolbar and status bar.
• Search: file name search (cancellable); Ctrl/⌘+P for Quick Open.
• Inspector panel: shows detailed properties of the selected file; symbolic links are marked.

10.2 Preview & Editing

10.3 File Operations

Create, rename, copy, move and delete (to the trash), open in the system file manager, folder picker dialogs and more. File tree shortcuts: arrow keys to navigate, Enter to open, Delete to delete, Ctrl/⌘+A to select all, Ctrl/⌘+C to copy, Esc to cancel.

11. Git

The Git panel (/git) provides graphical Git operations and supports multiple repositories:

Git shortcuts: Ctrl/⌘+Enter to commit, Ctrl/⌘+Shift+S to stage the selection, Ctrl/⌘+Shift+U to unstage, Ctrl/⌘+Shift+D to discard changes.

12. Automation

StoryCode offers five layers of automation that can be combined: Workflows → Schedules → Skills → Subagents → Plugins.

12.1 Workflows

Workflows are reusable task templates defined in YAML/JSON and managed on the /workflows page.

Workflow file format

version: "1.0"
title: "Code review"
description: "Review all changes on the current branch"
instructions: "You are a senior code reviewer..."   # system prompt
prompt: "Please review all changes on {{branch}}"   # initial user message; supports {{parameter}} substitution
parameters:                            # configurable input parameters
  - key: branch
    input_type: string                 # string / number / boolean / date / file / select
    requirement: required              # required / optional / user_prompt
    description: "Branch to review"
    default: "main"                    # optional; not allowed for the file type
extensions: []                         # MCP extensions to enable
settings:                              # model/provider overrides (all optional)
  agent_provider: "anthropic"
  agent_model: "<model name>"
  temperature: 0.2
response:                              # optional: require structured output constrained by a JSON Schema
  json_schema: {}
sub_workflows: []                      # nested sub-workflows
activities: []                         # activity pills shown while loading
retry: {}                              # retry configuration
tags: ["review"]
category: "Quality"

Using the interface

• Create / edit: a visual editor for the core fields, instructions, parameter JSON Schema, sub-workflows and extensions.
• Create from a session: turn a successful Agent session into a workflow to capture what worked.
• Run: fill in the parameters and start a new session.
• Version history: view previous versions of a workflow.
• Import: import workflows from YAML/JSON files.

12.2 Schedules

Schedules run workflows automatically on a cron schedule (managed from the scheduling panel on the /workflows page):

• Cron expressions: 6 fields (seconds, minutes, hours, day of month, month, day of week). For example, 0 30 9 * * * runs every day at 09:30. The UI provides a visual time picker and shows the expression in plain language.
• Execution rules: schedules fire in the machine's local time zone; the seconds field must be a single value from 0–59 (so the minimum interval is 1 minute); if the previous run is still going, that trigger is skipped.
• Management: create, edit, pause, resume and delete; run now; stop a running task.
• Run history: view the session record and details of each run.
• Notifications: deliver results to an IM channel when a task finishes (using the channels configured in Chapter 16); the details page lets you edit the notification targets and view delivery records.

12.3 Skills

Skills are reusable instruction packs written in Markdown (with YAML frontmatter metadata) that teach the Agent a specific skill, such as “write the weekly report” or “operate an internal system”.

• Management (/skills): skill list, details and an editor (template area and validation panel), skill import and dependency warnings.
• Creating skills: write from scratch, start from a template, or import an existing skill file.
• Scope: global and workspace-level skills; the Agent loads a skill's instructions automatically when the situation matches.

12.4 Subagents

Subagents are independent Agents with predefined roles. Each has its own instructions, tool set and runtime configuration, and the main session can dispatch tasks to them.

• Management (/subagents): a list on the left (global/workspace scope badges, search) and details on the right (usage snippet, runtime configuration, instructions, extensions/skills/tags, allowed and denied tool lists, YAML preview).
• Creating subagents: new, clone, a three-step template wizard, or YAML import.
• History snapshots: every change creates a snapshot you can roll back to.
• Export / import: share subagent definitions as YAML.

12.5 Plugins

Plugins are capability bundles that package skills, workflows, slash commands, subagents, work modes, policies and knowledge bases for one-click installation. Plugins are managed on the /plugins page (Plugins in the sidebar).

• Install: install from a local folder, with validation and a dry-run preview beforehand.
• Diagnose and repair: diagnose plugin problems, preview a repair plan and apply it (including knowledge base rebuilds).
• Status: readiness badges, guidance for required extensions, a panel for missing secrets and a guided setup workflow.
• Scope: enable or disable plugins per workspace.
• Update and uninstall: preview update plans; preview and confirm uninstalls.

13. MCP Extensions

Extensions are based on MCP (Model Context Protocol) and connect the Agent to external tools and data sources. The extensions page (/extensions) provides:

• Extension list: all installed extensions and whether they are enabled; extensions can be enabled/disabled for the current session only, without changing the global configuration.
• Add extensions: several types are supported — local commands (stdio), remote services (SSE / Streamable HTTP) and built-in extensions (such as Developer, Memory, Computer Use and Knowledge).
• Configure extensions: edit environment variables, headers, timeouts, descriptions and other fields.
• Grouped loading: shows loading progress by group when enabling several extensions at once.

Workflows and plugins can also declare the extensions they depend on, which are then enabled automatically when needed.

14. Media Center

The Media Center (/media) brings together five media tools. Generated files are saved under .storycode/media/ in the workspace.

14.1 Audio Recording & Transcription (/media/audio)

• Recording: record from a microphone or system audio, with pause/resume, input device selection, a live level meter and waveform.
• Transcription: transcribe recordings or existing audio files using local ASR (Whisper / Qwen3) or cloud recognition; results are shown as cards.
• Playback: a built-in preview player that also shows audio specs and waveform data.

14.2 Image & Video Generation (/media/image)

• Generator: enter a prompt, set size, seed and count, and submit a generation job.
• Model profiles: local image/video models and cloud media providers are both configured in Settings → Image & Video.
• Job tracking: job status cards plus system notifications; a results gallery with image preview and video playback; a history panel for past jobs.
• Video generation: requires a first-frame image (you can generate an image first and use it).
• Drag and drop or paste images as input.

14.3 Screenshots & Camera (/media/screenshots)

• Full-screen, window (via a window picker) and region (via a separate selection window) screenshots.
• Take and save camera photos.
• Screenshots can be copied to the clipboard directly; a file list with previews.
• In-app region capture: in the StoryCode window, press Ctrl/⌘+Shift+X to select a region and capture it (doesn't work while an input field has focus). When done, you're taken to the Screenshot page.
• System-wide global shortcuts: Capture Screen and Capture Windows are registered with the operating system, so they work even when the app isn't in front. They are unset by default; define them in Settings → System → Screenshot Settings, where you can also set the image format, quality, delay, preview and clipboard behavior.

14.4 Screen Recording (/media/screen-recording)

• Sources: an entire display, a specific window or a selected region, with optional camera picture-in-picture.
• Controls: start / pause / resume / stop; closing the tab while recording triggers a warning.
• Advanced settings: audio source (microphone / system audio / none), audio–video offset calibration and quality settings.
• Open a finished recording straight in the Media Editor; manage your list of recordings.

14.5 Media Editor (/media/editor)

A timeline video editor for post-processing screen recordings and video clips:

• Timeline editing: trimming, zoom suggestions, cursor following and hotspot zoom regions.
• Inspector: adjust properties of the selected clip; a crop overlay for visual framing.
• Projects: auto-save and crash recovery (restore drafts).
• Export: FFmpeg-based export jobs (transcoding / compression).

15. Developer Tools

15.1 Terminal (/devtools/terminal)

• A full xterm-based PTY terminal with split panes (drag onto a split area).
• Detects available shells automatically (PowerShell, CMD, bash, etc.).
• Recording and playback: record terminal sessions (asciicast .cast format), then play them back or export them.
• Shortcuts: Ctrl+F to search in the terminal, Ctrl+L to clear, Ctrl+Shift+C/V to copy/paste.

15.2 SSH & SFTP (/devtools/ssh)

• Connection profiles: manage SSH profiles (basic/advanced forms), import from ~/.ssh/config (preview before applying), and confirm and manage host keys (known_hosts).
• Key management: generate, view and delete SSH keys; SSH agent integration (list, add and remove keys). Passwords and keys are encrypted in the Vault and available once you unlock it with the master password.
• SSH terminal: an interactive remote terminal with automatic reconnection.
• SFTP: browse remote folders, upload/download (files, folders, batches) and sync folders; transfers can be cancelled, paused and resumed.
• Port tunnels: create, edit and delete port forwarding rules, start/stop them and start them automatically.

15.3 Database Tools (/devtools/database)

Manage SQLite / PostgreSQL / MySQL databases in one place:

• Connections: create and test connection profiles; create new SQLite database files; connect to remote databases through an SSH tunnel (with a test preview); passwords are held for the session only.
• Browsing: a table sidebar, table structure, row browsing and a cell content viewer.
• Editing data: insert/update/delete rows, create tables, add/modify/drop columns.
• SQL console: write and run custom SQL, automatically classified as read / write / DDL; running queries can be cancelled.
• AI assistance: AI-generated SQL (with a schema summary as context) and an AI “explain SQL” dialog.
• Import / export: export tables (CSV/JSON/SQL), dump a whole database and restore from a dump.

15.4 Remote Agents (/devtools/remote-agents)

Deploy the StoryCode Agent to a remote server, operate it over SSH, and use remote compute from the local UI:

All remote operations are recorded in a searchable audit log, and the remote API access policy can be finely controlled.

16. IM Channels

StoryCode can connect the Agent to popular messaging apps so you can use the Agent remotely from a chat window: sending a message starts or continues a session, and results are pushed back to the chat. Configure channels in Settings → Remote Channel:

• Session bindings: bindings between IM conversations and Agent sessions are managed on the Session History page (see Chapter 7).
• Schedule notifications: channels also serve as delivery targets for scheduled task results (see 12.2).

17. Settings Reference

The Settings center (/settings; supports ?section=&subsection= deep links and has a settings search at the top) is organized into the following sections, in this order:

Other settings

• CLI tool: install or uninstall the storycode-cli command-line tool and add it to PATH in one click from Settings → System, so you can use the StoryCode Agent from your system terminal.
• Language servers (LSP): in Settings → Advanced → Developer tools. They provide hover information and completion in the code editor; you can detect, install and uninstall language servers and set custom server paths.
• Single instance: launching the app again focuses the existing window and passes along any command-line arguments.

18. Security, Sandbox & Permissions

18.0 Tool Inspection Pipeline (why Autonomous mode can still ask for approval)

In every mode except Chat, each tool call passes through six inspection layers. If any layer denies, the call is denied; if any layer asks for confirmation, an approval prompt appears:

18.1 Sandboxed Execution

Shell commands and file writes run by the Agent can execute inside a sandbox (macOS Seatbelt, the enhanced Windows sandbox, a Linux sandbox or an external isolated runtime) that limits file system and network access and protects data outside the workspace. Enabling the enhanced Windows sandbox walks you through workspace protection setup. Sandbox settings are in Settings → Security → Shell sandbox.

18.2 Exec Policy

The exec policy is a rule engine for shell commands. Each rule makes one of three decisions: allow, prompt (ask for confirmation) or forbidden (deny). Settings → Security → Exec policy rules provides an editor with built-in default rules and validation.

• Rule files: global rules in ~/.storycode/config/execpolicy/*.rules (a default.rules is generated on first launch); workspace rules in <workspace>/.storycode/execpolicy/*.rules.
• Syntax: prefix_rule(pattern = ["git", ["pull", "fetch"]], decision = "allow"). A nested list means “any of these”. If decision is omitted, it is treated as prompt. Note that the keyword is forbidden; writing deny causes a parse error.
• Precedence: for commands inside the workspace, workspace rules take priority; for commands outside the workspace, global and workspace rules both apply and the strictest match wins (forbidden > prompt > allow).
• In Autonomous mode, prompt rules are escalated to deny, keeping unattended tasks safe.

18.3 Tool Permission Rules

In Settings → Agent → Modes, click the configure button next to Manual to manage tool-level allow/deny lists. In Manual mode, your rules are checked first and only unmatched calls need manual confirmation. Choosing Always allow (save rule) during an approval also writes a rule.

18.4 Protected Paths

• Reading the workspace's .git metadata is allowed. Writing, deleting or executing in .git (including git reset --hard, git clean, git config writes, etc.) and reading or writing the global ~/.storycode always require confirmation and cannot be set to Always allow.
• The Agent may read and write runtime folders under the workspace's .storycode (cache, temp, media, etc.). The security policy files themselves (exec policy rules, permission rules, etc.) can never be granted write access, which prevents the Agent from escalating its own privileges.
• For grantable items, choosing Always allow this command and path is recorded in <workspace>/.storycode/permissions/protected-paths.yaml.

18.5 Approval Audit Log

The start and final outcome of every approval are appended, one line per event, to ~/.storycode/state/audit/tool-approvals.jsonl, so you can review afterwards which operations the Agent needed confirmation for. The log is redacted: it records only the tool name, the category of the approval reason and your decision — never the tool arguments or the reason text.

18.6 Keys & Credentials

• System keyring: sensitive settings such as provider API keys are stored in the system keyring (Keychain / Credential Manager) by default. You can turn this off with Settings → System → Use system keyring; secrets are then stored in the local file ~/.storycode/config/secrets.yaml (fewer system prompts, but less secure).
• Vault: SSH passwords, remote Agent tokens and similar secrets are encrypted with a master password. The sidebar footer shows the lock state; you can change or reset the master password and set auto-lock.
• Database passwords: held for the session only, and can be “forgotten” at any time.

18.7 Interface Security

• The WebView uses a strict CSP (Content Security Policy) and a navigation allowlist that blocks unauthorized page navigation.
• MCP UI content is rendered in a sandboxed iframe and talks to the host through a secure bridge.
• Remote Agents have an operation audit log and an API access policy.

19. Keyboard Shortcuts

Press Ctrl/⌘+/ or just ? at any time to open the in-app keyboard shortcuts dialog (it highlights shortcuts relevant to the current page; ? doesn't work inside input fields).

19.1 Global

19.2 In-Session Search

19.3 Agent Composer

19.4 Terminal

19.5 Git Panel

19.6 Workspace File Tree & Other

20. Appendix

20.1 Local ASR / TTS Configuration

Local speech recognition and synthesis can also be configured manually through configuration keys (advanced use: put them in ~/.storycode/config/config.yaml or provide environment variables with the same names; most users can simply use Settings → Speech):

20.2 Data Locations

20.3 FAQ

Q1: The app keeps asking me to configure a model provider.

This is expected — a configured model is required before you can reach the main interface. Follow the wizard to pick a cloud provider (enter an API key) or a local model (download a recommended model). You can change it later in Settings → Models.

Q2: Local model downloads are slow or fail.

Downloads are resumable from the download manager. You can also configure a proxy in Settings → Advanced → Network proxy. If you're low on disk space, remove old models or runtime versions first (the model page has cleanup options).

Q3: The Agent's commands are blocked, or it keeps asking for confirmation.

Check the reason shown on the approval bar, then:

• Permission rule: in Manual mode, calls that don't match a rule need confirmation. Add rules via the configure button next to Manual in Settings → Agent → Modes, or choose Always allow when approving.
• Exec policy: matching a prompt rule asks for confirmation; in Autonomous mode, prompt rules deny outright. Adjust them in Settings → Security → Exec policy rules.
• Protected path / security check: operations such as writing to .git or accessing the global ~/.storycode require confirmation in every mode (see 18.0 and 18.4). This is by design.

Q4: On macOS, screen recording shows nothing or the microphone has no sound.

Grant StoryCode access in System Settings → Privacy & Security → Screen Recording / Microphone. The app's media permission panel can check the status and open System Settings for you.

Q5: Video export fails with an FFmpeg error.

Media processing requires FFmpeg. Install it using the setup guide in the Media Center, or set a custom FFmpeg path and refresh the status.

Q6: How do I make the Agent remember my project's background?

Three ways: ① save conclusions from a session as a Story (Save result), which later sessions recall automatically; ② add project documents to a knowledge base so the Agent can find and cite them with semantic search; ③ put project-level instructions in Settings → Agent → Agent hints.

Q7: How do I report a problem?

Help → Report Issue opens storycode.cc/issues. The built-in User Guide (the /help page) provides full-text searchable documentation.