Open Settings → Agent Threads in Geode or Obsidian, then use the Settings section selector at the top. Its eleven desktop sections are grouped under Preferences, Workspace, Extensions, and Connectivity. The host keeps its own settings navigation; Agent Threads uses a compact header instead of adding another sidebar.
Projects and Secrets have searchable lists and a detail editor, arranged side by side when space allows and stacked in narrow settings panes. On mobile, a reduced settings screen shows only pairing, plugin reload, and relay URL — see Mobile settings.
General
| Setting | Description |
|---|---|
| Conversation placement | Conversation first (default on new installs), or Classic sidebar for the original layout. On desktop, Conversation first keeps one Chat view in the main area and reuses an adjacent native companion for contextual content without detaching unrelated leaves; the Agents List and Skills Manager open in the right sidebar to match. Existing installs keep whichever placement they were already using. Mobile is unchanged. |
| Offer Chief of Staff on first run | On by default. On a brand-new install, adds the Chief of Staff skills and starts a Chief of Staff thread. Off shows the static getting-started guide instead. Set up Chief of Staff is available from the command palette either way. |
| Layout density | Compact, Comfortable (default), or Spacious — controls message spacing and padding in the conversation view |
| Tool call style | How grouped tool calls look: Tree (default), Chips, or Cards. Applies immediately. |
| Context footer command | Shell command that produces the status-line pills (JSON tags or plaintext). Runs per-thread, in the background, against that thread’s working directory. Desktop only. |
| Keep computer awake | Prevent the Mac from sleeping while Claude is responding; shows a ☕ indicator in the status bar |
| Debug logging | Verbose console logs for stream events, session lifecycle, and relay connections. Turn on only when diagnosing issues. |
| Diagnostics | Enable the always-on, local-only telemetry layer (performance counters plus renderer CPU/memory samples) that powers the Generate diagnostics report command. Nothing ever leaves your machine — no network calls. On by default; turning it off stops the sampler and freezes the counters. A Copy diagnostics button next to the toggle runs the report command directly. Desktop only. |
With Conversation first, Geode hosts that support durable companions reuse the same companion split after reloads, workspace restoration, and placement changes. Closing only its destination tab preserves sibling tabs and allows the next contextual item to open in that split. Older Geode versions and Obsidian keep their existing reload behavior. See Conversation-first workspace for closure and one-time cleanup details.
Agent
| Setting | Description |
|---|---|
| Agent harness | Initial Claude, Codex, or OpenCode default for new Agents List and Agent Board kickoff selectors. A selection made in either mounted view stays local to that view and does not rewrite this setting. Existing threads retain their original harness. |
| Claude binary path | Path to the claude executable. Leave empty to find it on $PATH — the plugin auto-detects /opt/homebrew/bin/claude, /usr/local/bin/claude, or ~/.local/bin/claude. |
| Codex binary path | Path to the codex executable. Leave empty to find it on $PATH; set this when Codex is installed somewhere else. |
| OpenCode binary path | Path to the opencode executable (desktop only). Leave as opencode to find it on $PATH, Homebrew, /usr/local/bin, or ~/.opencode/bin. OpenCode threads use the providers, credentials, and models configured in OpenCode. Model IDs use provider/model form, for example openai/gpt-5. See OpenCode Harness. |
| Codex computer use | Off by default. Blocks Codex’s bundled computer-use tools, including its shared browser REPL tools, in newly started or restarted sessions. Turning it on uses your existing Codex permissions and installed tools. Existing sessions keep their current configuration until restarted; use Reload plugin (safe) when ready. Agent Threads’ own contained browser tools remain available. See Codex computer use. |
| Account / provider | Claude account (default, uses the CLI’s own login) or Amazon Bedrock (sets CLAUDE_CODE_USE_BEDROCK=1 — also add AWS_PROFILE and AWS_REGION under Extra environment variables) |
| Default model | Model for new turns unless a thread overrides it with /model. “CLI default” defers to the Claude Code CLI configuration. Family aliases always track the latest version; pinned IDs lock to a specific release. Start a thread to populate the full model list from the CLI. |
| Thinking mode | Disabled (default), Adaptive (Claude decides when to use extended thinking), or Enabled (fixed token budget) |
| Thinking token budget | Maximum tokens for thinking when mode is Enabled (default: 8,000) |
| Effort level | Default (CLI default), Low, Medium, High, Extra high (Opus 4.7+), or Max (Opus 4.6+, Sonnet 4.6) — how much reasoning effort Claude applies per turn |
| Codex reasoning effort | Default, Low, Medium, High, XHigh, or Ultra — how much reasoning effort Codex applies per turn. Ultra enables Codex’s supported proactive multi-agent mode for work that divides cleanly; it can increase latency and compute use, and does not guarantee that Codex will fan work out to child agents. |
| Agent progress summaries | When enabled, running sub-agents emit an AI-generated progress summary roughly every 30 seconds |
| Enable 1M context window (beta) | Passes the context-1m-2025-08-07 beta header for Sonnet 4/4.5. Requires a model that supports it. |
| Default working directory | Starting directory for new threads. Leave empty to use the vault root. On desktop, Browse… next to the field opens the native folder picker. |
Sandbox VMs
| Setting | Description |
|---|---|
| Sandbox VM image | Image used by enter_vm; defaults to claude-threads-coding:1. Set up sandbox fetches it for you; or build it from the plugin’s sandbox/Dockerfile. Requires Apple’s container runtime on macOS 26+ with Apple silicon. |
| Run harness inside sandbox VM | Where a thread’s Claude CLI process runs. Auto (default) routes into the sandbox container only when the runtime, a probe and the harness image are all ready, and otherwise runs on your Mac and offers setup. Always — error if unavailable forces the container and errors instead of falling back. Never — host-local spawn only always runs on the host. A thread’s own Run in choice can override this; see Sandbox VMs. |
| Harness VM image | Container image the harness routes into, separate from the sandbox VM image. Leave empty for claude-threads-harness:1. Set up sandbox builds it for you. |
| Sandbox VM network | Default for new VMs: full egress, internal (host-only, no internet), or none (no network). An explicit enter_vm network argument overrides this setting. Existing VMs keep their current networking. |
| Sandbox VM memory | Memory limit per sandbox container, for example 4G or 2048M (default 4G). Invalid values fall back to the default. Applies only to newly created containers. |
| Sandbox VM CPUs | CPU count per sandbox container, a whole number from 1 to 64 (default 4). Applies only to newly created containers; remove an existing one with container rm --force claude-threads-vm-<thread-id> to pick up a change. |
| Sandbox setup | One-click Set up sandbox (also Finish setup / Update sandbox) installs the managed container runtime, pulls the published base image, and builds the Claude layer. Shows an Image version line and Update available when the image is stale. Reset sandbox removes the local images and sets up again. |
| Use Geode GitHub connection | Geode only. Lets threads use the GitHub account connected in Geode (Settings → GitHub) for git over HTTPS, gh, and the GitHub API, on the host and in the sandbox VM, with no personal access token. The token reaches every repository the Geode GitHub App is installed on. Your own GH_TOKEN, gh login, and git credential helpers take priority. On by default. |
| GitHub commit email | Email for commits made with the Geode connection. Leave empty to use your GitHub noreply address (ID+login@users.noreply.github.com). Only applied where a repository has no user.email of its own. |
See Sandbox VMs for setup and the distinction between guest commands and host tools.
Environment
| Setting | Description |
|---|---|
| Extra environment variables | KEY=VALUE pairs, one per line, merged into the Claude and OpenCode process environments (e.g. AWS_PROFILE, AWS_REGION, OPENAI_API_KEY) |
Manage keychain-backed environment variables in the dedicated Secrets section.
macOS users: the first time Claude accesses a folder like
~/Documents, macOS shows a privacy dialog. Click Allow — it only appears once per folder.
Model escalation
| Setting | Description |
|---|---|
| Enable model escalation | When the keyword appears in a message, route that single turn to the escalation model. The keyword is stripped before sending. |
| Escalation keyword | Word or phrase that triggers escalation (default: /escalate). Only shown when escalation is enabled. |
| Escalation model | Model the escalation keyword routes that turn to (default: Opus). Only shown when escalation is enabled. |
See Model escalation for the in-conversation behavior these settings control.
Tools
| Setting | Description |
|---|---|
| Permission mode | How the active Claude or Codex harness handles tool-use permission prompts — see the full permission mode table |
| Web Viewer tool | Lets Claude open URLs directly in the host Web Viewer panel (host_open_url). In Obsidian, this requires the Web Viewer core plugin to be enabled under Settings → Core plugins. |
| Inline visualizations | Renders a wrapped visualize{…} content reference from Codex as a live sandboxed chart inside the message, with a pop-out to full size — see Inline visualizations. Desktop only. On by default. |
| Hidden built-in tools | Comma-separated Claude Code built-in tools to hide from sessions. Cron* tools are hidden by default — the plugin has its own scheduler. |
Always-allowed tools
A list of tools granted automatically without prompting. Tools land here when you choose “Always Allow” in a permission prompt, or you can add one by name directly (e.g. Bash, Read, mcp__claude_threads__…). Each entry can be removed individually. Existing mcp__obsidian__… entries continue to work as deprecated compatibility aliases until the next major release.
Vault
| Setting | Description |
|---|---|
| Save threads to vault | Auto-save conversations as Obsidian notes after each response |
| Save raw JSONL logs | Save tool calls, completed results, usage and diagnostic events to <vault folder>/logs/<thread id>.jsonl, linked from the note’s raw_log frontmatter. Codex logging compacts repeated diff snapshots and streamed output automatically; see Log retention. |
| Auto-archive idle threads after (days) | Automatically archive a waiting thread once it has been idle (no activity) for this many days. Archiving writes the thread to its markdown note, with any images embedded, and removes it from the live thread list, so finished threads stop accumulating and data.json does not grow without bound. Only waiting threads qualify; active threads, the orchestrator thread, and threads awaiting a plan or question are never touched. Default: 14. Set to 0 to disable auto-archiving entirely. |
| Vault folder | Where thread notes are saved, relative to the vault root (default: Agent Threads) |
Log retention
Codex logs retain completed command and plan records, messages, errors and usage events. Repeated diff snapshots are coalesced to the latest snapshot per turn; snapshots larger than 512 KiB retain a bounded tail. Streamed command and plan output keeps up to 64 KiB of diagnostic text per item when the completed record cannot account for the streamed output, or the item never completes. These codex/log/compacted records identify their source and omitted bytes so a partial record is not mistaken for a complete output transcript.
Pending payloads are limited to 4 MiB and 128 entries per session. Reaching either limit flushes older entries early. Normal turn completion, interruption and session shutdown also flush pending diagnostics.
This reduces redundant event traffic in new logs. It does not rewrite existing logs or impose a maximum file size: completed results and long conversation histories still consume space. Pending compacted events are held in memory until a flush, so an abrupt host crash can lose that pending detail.
Projects
Choose Projects in the section selector, then New project. Enter a name and vault folder and choose Create project. Its working directory defaults to <vault root>/<vault folder>; set a filesystem cwd override for work outside the vault. Each Project shows its resolved effective cwd, and clearing the override returns it to the vault-derived path.
On desktop, Browse… next to the filesystem working directory field opens the native folder picker. You can also reach a blank draft from the dispatch Project menu on the Agents List and Agent Board by choosing New Project….
Search or select an existing Project to edit its name, vault folder, cwd override, or context prompt. Save changes applies the draft; Cancel discards it. The detail pane also lets you create/open its orchestrator or delete the Project after confirming the impact. Intentionally archiving a Project Orchestrator disables its heartbeat, completion wakeups, and automatic recreation; the disabled state survives reloads from synced data.json. Deliberately choosing Create/Open re-enables it. Deletion detaches threads and preserves scheduled work at the former effective cwd.
Projects focus initial context; they do not restrict vault tools, MCP servers, skills, secrets, filesystem permissions, or thread-coordination tools.
Secrets
Choose Secrets in the section selector to search, add, replace, or remove keychain-backed environment variables. Values are stored in OS-backed secret storage and never appear in data.json. Stored secret values, and common token formats such as GitHub, Anthropic/OpenAI, AWS, Slack, and Google keys, JWTs, private keys, and Bearer headers, are also masked in plugin logs, the diagnostics export, and raw JSONL thread logs. Thread notes and saved message history are not scrubbed, and a secret you never stored in the keychain may not be recognized.
Choose Add secret, enter its variable name and value, and set its project access. Global makes it available to every Project and Project-less thread. Selected projects limits resolution to the checked Projects. Confirm with Add secret for a new entry or Save changes for an existing one to apply the value and access together. Cancel discards the draft.
For an existing secret, leaving the replacement value blank preserves the stored value. Removing a secret requires confirmation. Project access controls secret resolution; MCP server and skill registration remain global.
Features
Summarization
| Setting | Description |
|---|---|
| Enable summarization | Show a Summarize button in each thread and enable the “Summarize active thread” command |
| Auto-summarize after response | Regenerate the summary + tab name after each assistant turn. Only shown when summarization is enabled. |
| Summarization model | Model alias passed to claude --model for summarization (e.g. haiku is fast and cheap, sonnet is higher quality). Only shown when summarization is enabled. |
Speech to text
| Setting | Description |
|---|---|
| OpenAI API key | Used for Whisper speech-to-text. Stored in your OS keychain — set a new key, change an existing one, or link a key already stored by another plugin. |
| Push-to-talk hotkey | Hold this key while focused in any input to record. Default: Alt+Space (Option+Space on Mac). Click to capture a new key combination, or reset to the default. |
See Push-to-talk voice input for the recording behavior these settings control.
Agent Board
| Setting | Description |
|---|---|
| Auto-collapse side panel | None (default), Left sidebar, Right sidebar, or Both sidebars — collapses the chosen sidebar(s) when the Agent Board opens, restoring them when it closes |
| Stack scheduled job threads | On by default — collapses repeat runs of the same scheduled/cron job into an expandable rollup in the Agent Board’s quiet columns and within each Project’s New, Reviewed, or Ready groups in the Agents List |
Portfolio Orchestrator
Shows the status of the thread-orchestrator thread: setup guidance if none has been created yet, an Open button once it resolves to a live thread, or a warning if the stored thread was deleted or archived outside the plugin.
Scheduled
The Scheduled tab is a dashboard for managing and inspecting scheduled work:
| Section or control | Description |
|---|---|
| Schedule rows | Each non-system schedule appears once in its group. Rows are collapsed by default and summarize status, cadence, next occurrence, Project, and actual execution behavior. |
| Ordering | Enabled schedules are sorted by next occurrence. Paused schedules appear last. Past-due work is marked as overdue and catching up. |
| Next run / Next check | Ordinary jobs show Next run. Gated jobs show Next check, since a gate may skip that occurrence. |
| Scheduled work groups | Recurring standalone jobs are separated from thread-specific loops and one-shot wakeups. The internal orchestrator heartbeat is omitted from the primary list. |
| Expanded details | Shows the prompt, working directory, active hours and gate when applicable, execution details, and recent outcomes/history, including runs, skipped checks, and errors. The native disclosure is keyboard accessible. |
| Pause / Resume | Disables or enables future occurrences without deleting the job. |
| Open last run | Opens the most recent thread created by the job, when one is available. |
| Delete | Permanently removes the scheduled item. |
| Create with Claude | Opens a thread with a scheduling prompt so you can describe the work and cadence in natural language. |
| Watched documents | Lists every active document watch with its path, owning thread, and last-alerted time, plus an unwatch control — the same list whether the watch was created from a note’s context menu or the watch_document MCP tool. |
Manual create/edit forms and a Run now control are not available in this release. Ask Claude to create or update a schedule instead.
Remote
| Setting | Description |
|---|---|
| Enable remote access | Turn on/off mobile pairing via the WebSocket relay. Generates a room ID the first time it’s enabled. |
| Room ID | Your device pairing identifier (masked). Show pairing QR code opens the pairing modal; Rotate room ID generates a new ID and disconnects all currently paired devices. |
| Connection status | Whether the mobile relay is currently connected |
| Relay URL | WebSocket relay server URL. Change only if self-hosting. |
See Remote access (mobile) for the full pairing flow.
Skills
| Setting | Description |
|---|---|
| Local skills folder | Vault-relative folder for authored skills. Changing it does not move files. |
| Auto-update GitHub skill sources | On by default. Fast-forwards GitHub skill sources in the background on launch and every 6 hours; updated skills apply to new threads. Pinned and diverged sources are skipped. |
| Skill sources | Shows how many sources you have, with an Open Skills Manager button. Add, update, and remove GitHub repos and local skill folders in the Skills Manager; private GitHub repos use Geode’s GitHub connection. |
MCP
Add, edit, and remove the external MCP servers (stdio, HTTP, or SSE) that get merged into newly initialized sessions on both the Claude and Codex harnesses — no hand-editing JSON required for the common case. Servers are stored in this plugin’s own data.json, scoped to this vault — not in ~/.claude/settings.json and not shared with the claude CLI. An interactive desktop agent can also propose a create-only registration with mcp_register_server, subject to a separate host confirmation. See Managing MCP Servers for the full walkthrough, including agent registration, the add/edit form, ${VAR_NAME} placeholders, and what happens when a placeholder can’t be resolved (the server is skipped, with a warning, rather than starting with a blank credential).
The MCP tab also has a Google Workspace section with opt-in Google Docs, Google Drive, Google Sheets, Google Slides, Gmail, and Google Calendar toggles (all off by default). It uses the Google Docs Sync account connected in the same vault and exposes Google’s hosted tools to new threads on either harness. See Google Workspace setup for connection, OAuth scopes, and preview-enrollment prerequisites.
Mobile settings
Obsidian Mobile shows a reduced settings screen instead of the desktop sections above:
| Setting | Description |
|---|---|
| Pairing code | Paste the code shown on desktop to connect manually, as an alternative to scanning the QR code |
| Paired room | Shows the masked room ID once paired, with a Disconnect button |
| Reload plugin | Reload Agent Threads; if threads are currently running you’re warned before the plugin restarts — see Safe plugin reload |
| Relay URL | WebSocket relay server. Change only if self-hosting. |