Ocsidian Documentation

Ocsidian ships for macOS on Apple Silicon. Install from the download page, GitHub Releases, or Homebrew — all paths deliver the same stable desktop build.

• Download page: ocsidian.com/download — one-click macOS installer
• GitHub Releases: https://github.com/ETAProjects-Inc/Ocsidian/releases — full version history and assets
• Homebrew Cask: brew install --cask ocsidian

brew install --cask ocsidian

Already installed? Open Ocsidian and use Check for Updates… to stay on the latest stable without re-downloading from the site.

On first open you land on Home — a full-window entry surface for creating, opening, or resuming a project. Agent chrome (sidebars, Game rail, chat) appears only after a project is open.

1. Launch Ocsidian from Applications or Spotlight.
2. Sign in with your Ocsidian account when prompted so models, credits, and sync stay attached to you.
3. Choose New project, Open workspace, or pick a recent entry from Home.
4. Wait for the project loading splash — then the studio cockpit opens on that worktree.

A project is a local folder (or clone) that Ocsidian treats as the source of truth for worktrees, Notes, chat, and the BlackFrost Engine preview.

• New project — seeds a playable BlackFrost template (project config, main scene, BlackFrost invent entry) and opens it in the agent interface.
• Open workspace / Browse — point Ocsidian at an existing folder or git repo on disk.
• Add project from the sidebar projects list when you already have a session open.

Once registered, the project shows in Home recents and the projects rail so you can jump back without hunting paths.

The Ocsidian loop is author → direct → experience. Four steps get you from an empty idea to a running play slice.

1. Open project

From Home, create a new project or open an existing workspace. Wait for the studio to load on that worktree — chat, Notes, and the Game rail become available.

2. Write plan note

Open project Notes and capture a short plan: goal, player feel, first playable slice. Markdown lives with the worktree so agents and humans share one brief.

3. Run agent

Start managed native chat (Scout, Prime, or Apex). Describe the vibe or attach your plan note. The agent edits BlackFrost invent scripts and project files in the open worktree.

4. Play on Game rail

Use Game rail Play to run the BlackFrost preview docked in the shell. Watch logs and screenshots, then iterate in chat until the slice feels right.

After first launch, a short setup path helps multi-task workflows stick. Complete what matches how you work — nothing is a hard gate on inventing.

• Open at least one real project you care about.
• Create a second worktree when you want two features isolated in parallel.
• Turn on notifications so you know when an agent finishes or needs attention.
• Connect GitHub or GitLab integrations if you open issues and PRs from the app.
• Optional: automate workspace setup scripts so new worktrees install deps on create.

BlackFrost Engine is the real-time runtime behind Ocsidian playables. The shell (chat, files, Notes, rails) is plane A; the hosted engine dock is plane B — one continuous product, not a bolted-on preview.

• Scenes and assets live in the project worktree.
• Behavior is written in BlackFrost invent (.ocs).
• Play runs through the Game rail, docked in the agent interface.
• Agents can drive Play, logs, status, and screenshots without sending you to engine homework.

The Game rail is the engine surface inside the agent cockpit. It hosts the docked BlackFrost preview, Play/Stop controls, and status so invent and experience stay in one glance.

• Opens after a project is loaded — not on Home.
• Shows the live playable viewport when the engine session is running.
• Keeps play chrome next to chat so agents and humans share the same run.

Play starts the BlackFrost session for the open worktree. Stop ends the run cleanly so the next Play picks up current project files.

1. Save or let the agent finish file edits under the worktree.
2. Press Play on the Game rail (or let a managed agent call engine play).
3. Interact in the docked preview; watch logs if something misbehaves.
4. Press Stop when you are done iterating or before large structural edits.

The docked preview glues the engine viewport into the Game rail layout so focus, resize, and agent tools stay aligned with the shell.

• Viewport scales with the rail; you keep chat and Notes visible.
• Status and log tools report against the same session you see.
• Screenshot capture targets this Game-rail host surface for vision-aware agents.

BlackFrost invent is the product invent surface for playable behavior in BlackFrost projects. Prefer .ocs sources for gameplay logic agents and humans edit together.

• Lives in the project tree next to scenes and assets.
• Edited in Code / file surfaces; agents write BlackFrost invent scripts during invent.
• Hot path for movement, goals, HUD, and feel tweaks without leaving Ocsidian.

Managed agents can operate the engine without asking you to click panels. These tools are the evidence loop for invent → play → fix.

After a project opens, Ocsidian is a calm cockpit: projects and worktrees on the left, primary work in the center, context tools (chat, Game, source control) in rails and tabs.

• Left rail — projects, workspaces/worktrees, Notes entry, file/tree access.
• Center — tabs for terminals, files, diffs, and other work surfaces.
• Chat — managed native chat for Scout / Prime / Apex direction.
• Game rail — docked BlackFrost play and engine chrome.

Tabs hold terminals, editors, browsers, and related panes per worktree. Terminals are first-class for shell work that stays bound to the same isolation boundary as chat and Notes.

• Create terminal tabs for installs, tests, and long-running servers.
• Split panes when you need logs beside a command.
• Closing a worktree tears down its managed terminals with it.

Native chat is the in-process managed conversation surface. Reasoning is presented only as product flows — Scout, Prime, and Apex — not as external provider names.

• Understands the open project and worktree context.
• Can edit files, run engine tools, and use git helpers under your permission mode.
• Stays in the shell — no iframe host for chat chrome.

Quick Open is the jump palette for files, notes, and actions without digging through trees. It keeps navigation keyboard-first while you stay in flow.

• Open the palette from the command/search entry in the shell.
• Type a file name, note title, or action fragment.
• Confirm to open in the center surface or jump to a note.

Project Notes are markdown that live with the worktree. Plans, specs, maps, and runbooks stay next to the code agents edit — not trapped in a disposable chat scroll.

• Create and edit from the Notes surfaces in the sidebar and editor.
• Use headings, lists, tables, and checklists for agent-friendly structure.
• Run an agent from a note to bind the brief into the session.

The sidebar Notes rail lists project notes scoped to the active workspace. Filter, open, and organize without leaving the cockpit.

• Browse notes for the current project / worktree scope.
• Open a note to edit in the markdown surface.
• Use folders or sections when the list grows beyond a few plans.

Create a note from the Notes rail or related new-note actions, give it a clear title, and write markdown as you would any project brief.

1. Open project Notes from the sidebar.
2. Create a new note and name it for the task (e.g. “Coin grab feel”).
3. Outline goal, constraints, and acceptance in short sections.
4. Save — the file lands in the worktree Notes storage automatically.

Project Notes are markdown files stored under the worktree’s Notes folder. They travel with the workspace path — clone, worktree, or archive keeps the same briefs beside the code.

• Local-first: readable as ordinary markdown on disk.
• Scoped per worktree so parallel branches do not overwrite each other’s plans.
• Compatible with CLI note commands when you automate outside the UI.

Run as agent packages the open note as the task brief and launches managed work against the current worktree.

1. Open the note that holds the plan.
2. Choose Run as agent (or the equivalent action on the note).
3. Confirm the worktree and flow if prompted.
4. Watch native chat: the agent cites the note and writes follow-up notes back into project Notes when documenting.

Notes use an in-process markdown editor tuned for plans and specs. Code files open in the code editor; Notes stay a writing surface without iframe hosts.

• Headings, lists, code fences, and tables render cleanly for review.
• Keep checklists for acceptance criteria agents can tick through.
• Paste short logs or paths as fenced code when evidence matters.

Agents in Ocsidian are studio teammates inside the open project. They invent playables, edit BlackFrost invent scripts, drive the Game rail, and help ship git changes under your permission mode.

• Managed native chat — primary surface (Scout, Prime, Apex).
• Worktree isolation — each task can own its own branch and terminals.
• Engine tools — play, logs, status, screenshot without panel homework.
• Notes-bound runs — plans stay on disk and in scope.

Managed chat is gateway-backed native conversation. Pick a flow depth — Scout for fast iteration, Prime for balanced work, Apex for hard reasoning — and stay on product names only.

• No requirement to install third-party coding CLIs for core invent.
• Harness knows BlackFrost host skills and BlackFrost invent patterns.
• Tool loop can include files, shell (when allowed), engine_*, and git helpers.

Start from empty chat, a note, a worktree create prompt, or an issue integration. Always confirm which worktree is active before long runs.

1. Select the target worktree in the left rail.
2. Open native chat and choose Scout, Prime, or Apex.
3. Paste a short goal or run from a project Note.
4. Set permission mode if the task needs broader auto-apply.
5. Let the agent play and fix; answer only feel questions when asked.

Run multiple agents by giving each its own worktree. Isolation prevents file thrash when two features land at once.

• Create two worktrees from the same project base.
• Start a chat (or note run) in each.
• Use board statuses to track which slice is in progress vs review.
• Merge or open PRs independently when each is ready.

Notes are the best launch pad when the brief is longer than a chat bubble. Running from a note cites the path and keeps deliverable docs in project Notes.

• Write the plan with clear acceptance criteria.
• Run as agent from that note on the correct worktree.
• Ask the agent to update the same note or sibling notes for maps and audits.

Agent status shows whether a session is working, waiting on you, blocked, or done. Pair it with notifications so long runs do not need babysitting.

• Working — tools and edits in flight.
• Waiting — needs your answer or approval.
• Blocked — permissions, network, or environment issue.
• Done — turn complete; review diff and play.

Permission modes govern what managed agents may do without asking. Pick the mode that matches trust and blast radius for the task.

Worktrees are isolated checkouts Ocsidian manages for parallel work. Each card is a workspace with its own branch path, terminals, Notes, and agent sessions.

• Created from a registered project / repo base ref.
• Shown on the board with status, name, and optional issue links.
• Removed with cleanup that respects dirty git state.

Create a workspace (worktree) from the projects rail, board, or CLI when you need a clean branch for a task.

1. Choose the project and base branch.
2. Name the workspace for the task.
3. Optionally attach an issue, setup script run, or first agent prompt.
4. Activate the new worktree and start chat or Notes.

ocsidian worktree create --name coin-grab --json

Isolation means each worktree has its own files on disk and its own git branch. Agents editing in A cannot clobber uncommitted work in B.

• Separate cwd for terminals and engine play.
• Separate project Notes for that workspace path.
• Independent source control status and PRs.

The workspace board uses quiet default statuses so you can scan parallel work without loud chrome.

When a workspace is finished, merge via your normal git/PR flow, then remove the worktree from Ocsidian so the board stays lean.

1. Commit and push from source control or agent git tools.
2. Open a PR and merge when checks pass.
3. Delete or archive the worktree from the board (force only if you accept discarding local-only files).
4. Confirm terminals for that worktree are gone.

Source control shows the git status of the active worktree: changed files, staging, commit, push, and remote PR context when integrations are connected.

• Review diffs before you accept agent edits.
• Commit with a clear message tied to the note or issue.
• Push to open or update a pull request.

Annotate diffs to leave review intent on hunks — questions, must-fix notes, or follow-ups for the next agent turn — without leaving the shell.

• Open the file diff from source control or a review surface.
• Select a region and add an annotation.
• Send annotations back into chat when you want the agent to address them.

Create a PR when the worktree is ready for review. GitHub and GitLab are both supported behind provider checks — keep naming generic (pull request, merge request as the host calls it).

1. Push the branch from source control.
2. Use Create pull request (or the host equivalent) with a title that matches the workspace name.
3. Link the issue if you opened from one.
4. Move the board card to In review.

Settings group product concerns so you can find account, appearance, keybindings, and integrations without hunting.

• Account — Ocsidian identity and subscription context.
• Models / flows — Scout, Prime, Apex availability for managed chat.
• Integrations — GitHub, GitLab, Linear, and related task sources.
• Appearance — theme, density, and chrome preferences.
• Keybindings — remap chords per platform.
• Privacy / telemetry — local-first controls and diagnostics opt-in.

Keybindings are configurable. On macOS, chords use ⌘; on Windows and Linux they use Ctrl. Menu accelerators use CmdOrCtrl so one definition spans platforms.

Appearance settings keep the cockpit quiet: dark studio defaults, restrained status colors, and density that favors long sessions over neon chrome.

• Theme and contrast preferences for the shell.
• Optional compact cards on the workspace board.
• Font and UI scale where exposed by the build.

The ocsidian CLI talks to a running desktop runtime (or local note/git helpers) so agents and scripts can drive worktrees, terminals, and project Notes from the shell.

• ocsidian status — runtime readiness
• ocsidian worktree … — list, create, set, remove
• ocsidian notes … — list/create/write project notes on disk
• ocsidian terminal … — list, send, stop managed terminals

ocsidian status
ocsidian worktree list --json
ocsidian notes list --json

The product CLI ships with the desktop app as ocsidian. After install, ensure the binary is on your PATH (packaged app resources or shell integration from the app).

1. Install Ocsidian (DMG or brew install --cask ocsidian).
2. Open the app once so runtime services can register.
3. Run ocsidian status in a terminal to verify the command resolves.
4. Use ocsidian --help or ocsidian agent-context for machine-readable command schema.

Worktree commands mirror the board: create isolated checkouts, set metadata/status, and remove when done.

ocsidian worktree list --json
ocsidian worktree create --name feature-hud --activate --json
ocsidian worktree set --worktree active --workspace-status in-progress --json
ocsidian worktree rm --worktree active --json

• Selectors accept active, folder ids, or full worktree ids from list --json.
• Pass --force only when remove must discard dirty files.
• Use --json for agent-friendly output.

Small recipes that cover common studio automation without expanding into unsupported surfaces.

Spin a task workspace

ocsidian worktree create --name spike-jump --activate --json

Seed a plan note

ocsidian notes create --title "Jump feel" --body "Goal: snappy jump.\nDone: lands clean." --json

Inspect terminals on the active worktree

ocsidian terminal list --worktree active --json

Ocsidian keeps project truth on your machine: worktrees, Notes markdown, terminals, and engine project files live in local paths you control.

• Open and edit offline for files and Notes; managed model calls need network when you chat.
• SSH and remote hosts are supported — still your repos, not a mandatory cloud workspace.
• Exports and packages are opt-in handoffs, not silent uploads of the whole tree.

Diagnostics and product telemetry help ETAPX improve reliability. Official builds may include opt-in or settings-gated analytics; secrets and private source are not the payload you write in chat drafts.

• Review Privacy / telemetry controls in Settings.
• Prefer redacting tokens and .env contents before pasting into any chat.
• Crash/diagnostic bundles, when sent, follow the product safety and privacy posture on ocsidian.com.

Security is layered: OS permissions, git boundaries, agent permission modes, and product refusal to disclose internals or credentials.

• Grant macOS permissions only for features you use (notifications, accessibility if a surface requests it).
• Keep Bypass mode rare; prefer Manual/Accept edits/Auto ladders.
• Review agent diffs before push — human in command.
• Treat release downloads as authentic only from ocsidian.com/download, Homebrew cask ocsidian, or ETAProjects-Inc/Ocsidian releases.