Agent Threads documentation

Settings Reference

Every settings section, including the Projects and Secrets managers, with desktop navigation and mobile pairing controls.

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

SettingDescription
Conversation placementConversation 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 runOn 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 densityCompact, Comfortable (default), or Spacious — controls message spacing and padding in the conversation view
Tool call styleHow grouped tool calls look: Tree (default), Chips, or Cards. Applies immediately.
Context footer commandShell 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 awakePrevent the Mac from sleeping while Claude is responding; shows a ☕ indicator in the status bar
Debug loggingVerbose console logs for stream events, session lifecycle, and relay connections. Turn on only when diagnosing issues.
DiagnosticsEnable 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

SettingDescription
Agent harnessInitial 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 pathPath 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 pathPath to the codex executable. Leave empty to find it on $PATH; set this when Codex is installed somewhere else.
OpenCode binary pathPath 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 useOff 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 / providerClaude 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 modelModel 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 modeDisabled (default), Adaptive (Claude decides when to use extended thinking), or Enabled (fixed token budget)
Thinking token budgetMaximum tokens for thinking when mode is Enabled (default: 8,000)
Effort levelDefault (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 effortDefault, 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 summariesWhen 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 directoryStarting 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

SettingDescription
Sandbox VM imageImage 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 VMWhere 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 imageContainer 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 networkDefault 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 memoryMemory 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 CPUsCPU 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 setupOne-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 connectionGeode 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 emailEmail 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

SettingDescription
Extra environment variablesKEY=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

SettingDescription
Enable model escalationWhen the keyword appears in a message, route that single turn to the escalation model. The keyword is stripped before sending.
Escalation keywordWord or phrase that triggers escalation (default: /escalate). Only shown when escalation is enabled.
Escalation modelModel 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

SettingDescription
Permission modeHow the active Claude or Codex harness handles tool-use permission prompts — see the full permission mode table
Web Viewer toolLets 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 visualizationsRenders 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 toolsComma-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

SettingDescription
Save threads to vaultAuto-save conversations as Obsidian notes after each response
Save raw JSONL logsSave 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 folderWhere 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

SettingDescription
Enable summarizationShow a Summarize button in each thread and enable the “Summarize active thread” command
Auto-summarize after responseRegenerate the summary + tab name after each assistant turn. Only shown when summarization is enabled.
Summarization modelModel 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

SettingDescription
OpenAI API keyUsed 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 hotkeyHold 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

SettingDescription
Auto-collapse side panelNone (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 threadsOn 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 controlDescription
Schedule rowsEach non-system schedule appears once in its group. Rows are collapsed by default and summarize status, cadence, next occurrence, Project, and actual execution behavior.
OrderingEnabled schedules are sorted by next occurrence. Paused schedules appear last. Past-due work is marked as overdue and catching up.
Next run / Next checkOrdinary jobs show Next run. Gated jobs show Next check, since a gate may skip that occurrence.
Scheduled work groupsRecurring standalone jobs are separated from thread-specific loops and one-shot wakeups. The internal orchestrator heartbeat is omitted from the primary list.
Expanded detailsShows 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 / ResumeDisables or enables future occurrences without deleting the job.
Open last runOpens the most recent thread created by the job, when one is available.
DeletePermanently removes the scheduled item.
Create with ClaudeOpens a thread with a scheduling prompt so you can describe the work and cadence in natural language.
Watched documentsLists 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

SettingDescription
Enable remote accessTurn on/off mobile pairing via the WebSocket relay. Generates a room ID the first time it’s enabled.
Room IDYour 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 statusWhether the mobile relay is currently connected
Relay URLWebSocket relay server URL. Change only if self-hosting.

See Remote access (mobile) for the full pairing flow.

Skills

SettingDescription
Local skills folderVault-relative folder for authored skills. Changing it does not move files.
Auto-update GitHub skill sourcesOn 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 sourcesShows 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:

SettingDescription
Pairing codePaste the code shown on desktop to connect manually, as an alternative to scanning the QR code
Paired roomShows the masked room ID once paired, with a Disconnect button
Reload pluginReload Agent Threads; if threads are currently running you’re warned before the plugin restarts — see Safe plugin reload
Relay URLWebSocket relay server. Change only if self-hosting.