user-guide.md

Hlið user guide

Hlið is a local web UI for working with an Obsidian vault through Claude, Codex, or another installed Agent Client Protocol provider. This guide is for the packaged Windows app. If you are running from source, the README has the setup and validation commands.

Install and first launch

1. Download the current hlid-vX.Y.Z-windows-x64.exe from GitHub Releases.
2. Run it. Hlið is currently unsigned, so Windows SmartScreen may get in the way. Check the filename, choose More info, then Run anyway if you trust the release.
3. The downloaded executable installs the real copy at %LOCALAPPDATA%\Hlid\hlid.exe, refreshes the Hlið Start Menu shortcut, starts the service, and opens http://127.0.0.1:3000.

Use the Start Menu shortcut after that. Running Hlið again while it is already up just opens the existing interface. Autostart is optional and lives in Forge.

Create the app password

The first browser on the Hlið machine shows Create app password. Use 12–256 characters. There is no uppercase, number, or symbol checklist.

Initial setup only works from the host machine. Once that is done, other trusted devices can sign in over the HTTPS endpoint. A browser stays trusted for 30 days unless you lock it, change the password, or revoke every device in Forge.

Pick the local Obsidian vault, then make sure the detected structure actually matches it.

Connect a vault

The first-run wizard has five small steps:

1. Welcome explains the page names.
2. Vault picks an existing local Obsidian vault. Hidden folders stay out of the folder picker.
3. Structure detects a PARA or wiki-style layout and fills in the folders it recognizes. Check the vault name, folder mappings, available default provider, that provider's permission mode, and the theme. Empty optional mappings are fine.
4. Primer explains how Hlið, the vault, and its skills fit together.
5. Done opens the app.

The wizard writes hlid.config.toml beside the installed executable. The same settings live under FORGE → Workspace later. If the vault gets moved, renamed, or disconnected, fix the path there before wondering why the vault pages are empty.

Run the first session

Open RAVEN and pick a provider. That provider needs to exist and already be authenticated in its configured runtime, either native Windows or a WSL wrapper.

The packaged app checks Claude and Codex during startup so provider-native commands, models, subagents, and MCP status are ready before the first real chat. If a provider is slow, Hlið finishes the check in the background. It does not send a user turn or spend model tokens.

Pick an old session or start a new one. Typing / opens the shared command picker, where vault skills, Hlid-managed imports, global skills, and provider-native commands live together. Compatible commands can be stacked. Their badges stay above the composer until they are removed or run.

Need to point the agent at something without pasting half the vault? Type @ in the Watch or Raven composer. The picker searches exact vault files and recent Relics, then keeps each selection attached to that turn. Hlid resolves the real path on the server and translates it for the selected Windows, WSL, or ACP runtime. The same references survive when a prompt gets queued behind a running turn.

The book button beside the normal attachment control grabs whichever note is active in the Obsidian desktop and adds it as the same kind of exact vault reference. Handy when the prompt is basically "look at what I am looking at."

CLIProxyAPI integration

Hlið can expose separate Claude Code · CLIProxy, Codex · CLIProxy, and OpenCode · CLIProxy providers. The selected harness still owns its agent loop, tools, commands, permissions, and MCP behavior, while CLIProxyAPI translates model requests to a connected OAuth account. These are optional routes alongside the normal Claude, Codex, and ACP providers.

Open Forge → Integrations → CLIProxyAPI and choose Install managed. On Windows, Hlid downloads a reviewed, pinned release, verifies it against the SHA-256 digest shipped with Hlid, creates a loopback-only configuration, and owns the process lifecycle. CLIProxy updates advance only with an Hlid release after the new archive has had time to settle. The managed install includes matching Windows and Linux binaries. Hlid starts the Linux sidecar inside each configured WSL distro so WSL-backed Claude Code and Codex harnesses keep their native toolchain while using the same OAuth accounts. Connect any supported account shown in Forge: OpenAI Codex, Anthropic Claude, Google Antigravity, Moonshot Kimi, or xAI. OpenAI, Kimi, and xAI use device-code flows, so you can finish their sign-in from the Hlid desktop or a mobile browser without a localhost callback. Claude and Antigravity keep their browser-callback flows on the Windows host. Forge opens the authorization page, keeps a fallback link visible, and shows the verification code when one is required. Hlid starts the integration with the app, offers an explicit repair control, and can remove the binaries and all saved accounts.

If Windows Security quarantines the executable after extraction, check Protection history before retrying. Once the reviewed file is allowed, Check / repair puts the managed install back together.

The generated client key and OAuth tokens remain in Hlid's private integration directory and are never returned to Forge. Remote management and the CLIProxyAPI control panel are disabled because Hlid does not use either one.

After CLIProxy is enabled, choose one of its routed providers anywhere Hlid offers a provider picker. Claude Code and Codex routes appear when their CLIs are installed. The OpenCode route appears when OpenCode's ACP command is installed. Hlid injects runtime-only provider configuration for Codex and OpenCode, so it does not rewrite ~/.codex/config.toml, opencode.json, or either harness's saved credentials.

For an existing, externally managed CLIProxyAPI process, configure advanced mode in hlid.config.toml:

[cliproxy]
enabled = true
mode = "external"
base_url = "http://127.0.0.1:8317"
api_key = "replace-with-a-long-local-key"
model = "gpt-5.6-sol"
effort = "xhigh"
permission_mode = "default"
turn_recaps = true

Keep an external process on loopback. The api_key is a CLIProxyAPI client-facing api-keys value, not a management secret. Hlid stores it in the local config file but redacts it from browser config responses. The provider health check verifies the selected harness executable and the proxy model catalog. Forge and Raven use every model returned by the catalog and show its upstream owner in the model label.

Ledger stores the routed harness and actual response model. Hlid estimates known OpenAI and Anthropic models from its effective-dated pricing catalogs. Models without a matching catalog rule, including supported Google, Moonshot, or xAI models, remain explicitly unpriced. Estimates are API-equivalent comparisons, not the amount charged to an OAuth subscription. Existing priced rows stay frozen when rates change.

Hlid does not consume CLIProxyAPI's short-lived usage queue or import traffic from other clients. Ledger therefore covers requests made through Hlid only. CLIProxyAPI account-wide quotas and subscription limits are not available as Hlid usage windows, so automatic usage-window sleep does not apply to this route.

Tool calls stay in the conversation. No mystery spinner while the agent does who knows what.

While a run is active:

• Tool calls show up inline and can be expanded when the details matter.
• Permission cards can approve once, approve for the session, save a permanent approval, or deny with feedback.
• Another prompt gets queued instead of interrupting the current turn. It can be promoted or canceled before it runs.
• Agent questions show their choices inline, with a note field when the buttons do not quite cover the answer.
• Plan mode waits for approval, revisions, or cancellation before the implementation turn. The HTML toggle opens an agent-authored plan in the sandboxed viewer. A pending plan stays visible when another trusted device opens the same session.
• Supported providers show subagent status, current work, runtime, and usage.
• Long chats load the newest history first. LOAD OLDER HISTORY pulls in the earlier turns without jumping the scroll position around.
• Agent output can render tables, alerts, highlighted text, Mermaid, and LaTeX math using $...$, $$...$$, \(...\), or \[...\].
• The message copy button copies the rendered text.

Files can be dropped onto the composer or added with the attachment button. Uploads can stay temporary for one session or become managed vault attachments.

The pages

Watch

Watch is the landing page and the fastest way to throw work at an agent.

WATCH runs a prompt or a compatible mix of vault, global, and provider-native slash commands. It can target a registered agent, attach files, use voice input, continue the current session, or send the run into the background.

The rest of the page keeps live session state, provider usage, recent query cost, seven- and thirty-day activity, the active provider's MCP status, and recent sessions in view. When more than one provider reports usage, use the provider tabs above the usage strip to switch between their reported windows. Hlið keeps the last good readings in place while it loads new ones. Live provider updates and a regular refresh keep them current. The draft survives navigation and refreshes until it is run or cleared. Small thing, but boy does losing a half-written prompt get old fast.

Use Schedule to turn the current prompt into a Routine, or open it with an empty draft to build one from scratch. A routine can run once, at a fixed interval, daily, or on selected weekdays. It freezes the provider, model, effort, agent directory, prompt inputs, and timezone with the definition, so a later default change does not quietly alter the job.

Routine inputs can include prompts, skills, provider commands, exact vault references, and retained Relics. Results can stay as a Markdown Relic, append to the daily note or an exact note, or create a new note in the mapped Inbox or Raw folder. Run now is there for the sensible test before trusting a schedule. The manager also shows run history and can pause, resume, or archive the definition.

Unattended access is explicit. A routine can be read-only, use a reviewed set of exact grants, or run with full access when Umbod also allows it. Exact grants can cover a file operation, shell command, Obsidian action, MCP call, or Hlid tool. Agent questions, plan exits, and Windows Computer Use are never preapproved. If a run reaches anything outside its policy, it stops at Action required instead of guessing what you meant. Overlapping runs are skipped rather than piled on top of each other.

Raven

RAVEN is the full agent workspace. Conversation history, provider controls, slash commands, attachments, voice, tools, permissions, questions, plans, subagents, and queued follow-ups all live here.

The badge above the composer changes the provider, model, effort, and permission mode for that chat. Those choices stick to the session. So do the selected agent, queued prompts, and unsent draft. Navigating away or refreshing the page does not reset the whole thing back to whatever the vault default happens to be.

Codex skills can be composed with each other. Claude accepts up to six compatible selections. An ACP session accepts one provider-native prompt command at a time, but that command can still use vault skills. Switching the active CLI drops commands that belong to the old provider instead of quietly sending nonsense to the new one.

The picker keeps three execution types distinct: vault or Hlid-managed skills inject a skill file, provider-native commands go back to that provider, and Hlid capabilities such as /review and /computer-use use Hlid's own routing, approval, audit, and accounting path.

Structured provider actions stay out of the prompt text too. /compact asks a supported Claude or Codex runtime to compact its active conversation, /mcp refreshes the session's MCP inventory, and /goal manages a native Codex goal without making the model interpret a pretend slash command.

Native Codex chats show their current goal above the conversation. Use /goal to open the editor, set an objective, and optionally give it a token budget. /goal pause, /goal resume, and /goal clear manage it directly. The strip shows elapsed time and token use, plus whether the goal is active, paused, blocked, usage-limited, budget-limited, or complete. The goal stays with the Codex thread.

Turn on Plan when the agent should figure out the work before touching it. Turn on HTML beside it for the full styled plan. Approval, cancellation, and revision feedback all happen from the plan card or viewer.

Completed assistant replies have Obsidian actions beside copy and read aloud. One appends the reply to the active note, and another appends it to today's daily note. If the vault has an Inbox or Raw folder mapped, a third action makes a new timestamped note there. That capture can use the template selected under FORGE → Workspace → Vault. Each action only sends the finished reply text, and one save is limited to 20,000 characters.

The Terminal toggle opens a real login shell in the current vault or registered-agent directory. Desktop puts it below the chat. Mobile switches between Chat and Terminal tabs. Toggling the terminal off ends the shell, but normal site navigation only detaches the browser. Come back to that chat and the shell is still there.

An idle supported Claude or Codex chat gets a fork control beside the new-chat button. It asks the provider for an exact copy of the whole conversation, opens the copy, and leaves the source alone. The fork keeps a link back to its source. Claude also offers Branch from here beside a completed assistant reply when only the conversation through that point should come along. The same whole-session fork is available from the row menu in Ledger. Current ACP agents do not expose an exact fork.

If interactive Claude mode is enabled in Forge, Raven becomes a full Claude CLI terminal instead of the structured timeline.

Same session and controls, just fitted to the smaller screen without turning into button soup.

Vault

Vault follows the folders and status words picked during setup.

VAULT browses the configured note, project, memory, and skill directories. Projects come from YAML front matter and the status vocabulary in hlid.config.toml. Hlið does not impose its own project statuses on the vault.

Text search ignores case and accents, so Hlid still matches Hlið. The same normalization is used by Relics, Ledger, Forge, and the slash-command picker.

Expand a note or project and Open in Obsidian jumps the desktop app straight to that file. Selected vault references in Watch and Raven get the same shortcut, which is pretty useful when an agent points out the exact note that needs a human pass.

Relics

Relics is the Hlid-owned library for attachments, plans, reports, and imported skills.

RELICS is the browser for Hlid-owned files. Uploads, generated HTML plans, reports, and imported skill packages live under the installed app's library directory rather than inside a repository or agent folder. The Obsidian vault and WSL workspaces remain linked sources; Hlid does not copy or relocate them.

When you ask for a durable deliverable, agents can publish generated HTML, PDFs, images, and other reports directly into Relics from an ordinary chat. Hlid copies workspace files across the Windows or WSL boundary into managed storage, associates them with the chat, and returns a link that opens through the existing Relics viewer. General HTML reports do not require plan mode; HTML plan proposals continue to use the separate plan review workflow.

Use Skills to install a managed Agent Skill from a GitHub repository, repository URL, or skills.sh URL. Hlid discovers the available packages, stages the selected revision, and shows every readable file for review before anything is installed. Approve one package at a time when its instructions and supporting files make sense. The installed copy then appears in the Watch and Raven skill picker and can be removed from Hlid later without changing its source repository.

Use Import for skills that are already installed in a Claude or Codex registry or a configured ACP workspace. Discovery does not start an agent or CLI process, so it remains responsive while those providers are busy. Hlid groups the results by provider and shows scope, known enabled state, Windows or WSL runtime, description, file count, and size. Read SKILL.md loads the complete source document on demand without sending its filesystem path to the browser. Select the packages you want and import them together. The provider-neutral Hlid copies work even when a provider has a same-named skill. Removing an imported copy leaves the provider's original alone, ready to import again if that seemed like a better idea tomorrow.

The same managed files show up under Relics in the composer @ picker. Pick one there when an existing attachment, report, or generated plan needs to go back into a prompt. It stays a reference to Hlid's managed copy, so there is no second upload to clean up later.

Filename search updates while you type. The list can be filtered by artifact category, date, MIME group, or owning session, then sorted by size or creation time. If a new upload lands while the page is open, a NEW RELICS pill appears instead of yanking the list back to page one. Desktop gets the full table, while mobile uses compact cards.

Deleting a vault attachment normally removes its managed record. Deleting the source file too is a separate opt-in setting in Forge, because those are two very different levels of "clean up."

Ledger

LEDGER has two views: Sessions and Stats.

Sessions puts live processes above the recorded session list. Search labels as you type, filter by agent or model, and sort by recent activity, cost, or tokens. A drill-down from Stats carries its date, provider, model, or stop reason filters into the list.

On mobile, the live rows collapse into a LIVE SESSIONS summary. Open it to see sessions ordered with approvals and errors first, followed by running and idle work. A session can still be opened in Raven, stopped, or closed from that panel.

The overflow menu exports every session as CSV or JSON. It can also remove records older than 7, 30, or 90 days when the database actually has sessions that old. A row menu handles one rename or delete, pins a useful session to the top, or moves it into the archived view. Archiving is reversible, clears its pin, and protects the session from age-based cleanup. Supported idle Claude and Codex rows also get the exact fork action.

Import provider history discovers Claude CLI/SDK/Cowork and Codex CLI/Desktop/editor sessions from Windows and every configured WSL distro. Hlid makes a checked SQLite backup, imports the transcripts and usage, and marks the original surface on each row. Current imports can be opened and resumed in Raven. Sessions that already came through Hlid's Codex bridge are skipped so their usage is not counted twice. Running the import again upgrades what it can and leaves anything already current alone. Older usage-only imports remain read-only if their original transcript is no longer available.

Stats filters by date range, agent, provider, and model. It breaks down cost, priced coverage, input/output/cache tokens, activity, model share, tool use, tool errors, stop reasons, and time-of-day patterns. Pick a model or stop-reason segment to drill into the matching sessions.

Privacy mode masks the headline totals, sensitive chart labels, session names, and paths. Handy when a screenshot is the goal and leaking the whole workspace is not.

Einherjar

EINHERJAR adds other agent directories. A context entry loads AGENTS.md or CLAUDE.md as an instruction/personality overlay while keeping the vault as the working directory. If both files exist, AGENTS.md wins because it is the provider-neutral ACP contract. CLAUDE.md stays as the compatibility fallback.

A cwd entry runs the agent from the registered directory instead. Paths outside the vault need the external-agent switch in Forge.

Expand an Einherjar entry to preview or edit its root AGENTS.md and CLAUDE.md. Missing files can be created in place. Hlid keeps the two files separate because Codex and Claude load different native instruction names.

Forge

Forge groups settings by what you are trying to change, not by whichever config object owns it.

FORGE is split into these categories:

• Overview shows the current config and service state.
• Workspace holds the vault, folder mappings, vocabulary, and the optional Obsidian desktop CLI connection.
• Agents holds provider, model, effort, permissions, usage limits, recaps, vault and global instruction-file editors, automatic usage-window sleep/resume behavior, and Codex Computer Use defaults when the Windows capability exists. Global files are grouped by their Windows or WSL runtime, and edits take effect when the matching provider conversation starts or reloads.
• Access has network, TLS, password, and trusted-device settings.
• Experience has built-in or custom desktop/mobile themes, input behavior, the provider-entry visibility toggle for the / picker, HTML plan defaults, voice, and browser-local privacy mode. Hlid and vault entries always remain visible; the toggle controls every provider-badged skill, command, or plugin.
• Integrations manages CLIProxyAPI, MCP, Umbod, and the ACP catalog.
• Extensions manages installed Claude and Codex plugins and their marketplaces.
• Developer switches between the event log, local API reference, and pricing catalog.
• Advanced has database maintenance, provider-session reload, restart, and shutdown controls.

Most edits autosave. The header shows whether the form is saving, dirty, saved, or waiting on a restart. Server, ACP, and Umbod changes are the main things that set the restart marker. If a save or system inventory call fails, the same header has a retry action.

The search box filters whole setting categories. Vault MCP configuration stays vault-scoped. Each Einherjar entry keeps its own MCP configuration on that agent's page. Hlid merges those compatibility files with provider-native and live runtime discovery into one scoped inventory; it does not flatten servers from unrelated agents into a global list. MCP edits sync into the live vault session. Working-context changes still need a provider-session reload, which clears the live provider conversation but leaves its recorded Ledger history alone.

Extensions keeps the Claude and Codex inventories separate. Browse an installed package or marketplace, filter by environment or category, and review one package before installing it. The review includes its files and the capabilities it declares, such as hooks, MCP servers, scripts, or apps. You can also add or remove a marketplace source, then enable, disable, update, or remove its packages through the provider's native registry. An idle runtime refreshes immediately. If a turn is running, Hlid leaves it alone and reloads the extensions before the next turn.

Agents → Auto-sleep on usage limit pauses work near the provider's usage threshold or after the provider reports a hard limit. Hlið uses the five-hour window when it is available and weekly usage when it is not. The Raven banner shows which window filled up and when the session should wake. RESUME NOW wakes every sleeping session on that provider and lets them keep going until the current window resets. Maximum sleep keeps a session from waiting longer than the configured cap.

Developer → Pricing shows the built-in model and alias timelines, then edits pricing-overrides.toml for local rules. Rates and aliases can use UTC effective_from and effective_until dates, so a moving label like codex-auto-review can change without an app release. Saving validates the whole file before replacing it. Old priced rows stay frozen, and new fallback estimates use the rule that was active at the query time.

The custom theme editor can start from the active, dark, tan, or desktop palette. App, navigation, chat, Ledger, and chart colors are separate. Desktop and mobile can have different palettes, and the native-control setting keeps browser menus, inputs, and scrollbars readable against the result.

Obsidian CLI

Hlið still reads the configured vault directly, so the Obsidian CLI is an optional extra rather than a new requirement. It is there for the bits where Obsidian's own index and desktop state know more than a filesystem scan does.

Install Obsidian 1.12.7 or newer and turn on Settings → General → Command line interface inside Obsidian. Then open FORGE → Workspace → Obsidian desktop. Recheck detects the installation without launching anything. Test connection verifies the configured vault and may start the Obsidian desktop if it is closed.

Hlid can find the installed Windows redirector even when obsidian is not on PATH. A source build running inside WSL can use that same Windows install, so there is no second Obsidian setup hiding in the sauce.

When the bridge is available, Claude, Codex, and installed ACP agents get the same curated Obsidian tools. They can search indexed text, inspect the active or daily note, read exact notes, follow the link graph when asked, find unresolved or orphaned notes, query tasks and properties, run Bases views, and inspect or compare local file history. Broad queries come back with totals and truncation details instead of dumping the whole vault out the wazoo. The agent can narrow by path, status, view, or version, or ask for a count when that is all it needs.

The write side is curated too. Agents can create notes with a core Templates or Templater template, capture a quick note into the mapped Inbox or Raw folder, open today's daily note, append or prepend text, replace one exact block in an existing note, or apply several exact replacements as one atomic patch. They can also add an item through a Base, update one exact task or property, move or rename a file through Obsidian so its links can follow along, and send one exact file to trash through Obsidian's default delete behavior. Hlid does not expose the permanent flag. Exact replacement first requires the agent to read the note. It fails without a change when expected text is missing or occurs more than once. An atomic patch applies every replacement or none of them. Raven groups successful changes into a Vault activity card with the affected paths, added and removed text previews, and shortcuts back into Obsidian. File history stays read-only, so recovery still happens in Obsidian itself.

Every note change follows the active agent permission policy. Running an arbitrary Obsidian command is stricter: the agent discovers the exact command ID first, and a new command still asks for approval even when the chat would normally bypass permission prompts. Always trusts only that command in the configured vault. Remembered commands show under FORGE → Workspace → Obsidian desktop, where they can be forgotten again.

A command's vault activity shows the active note before and after when Obsidian can report it. That is useful context, not a complete file diff, because a plugin command can touch more than the active note. Open the note in Obsidian for the full history and recovery options.

Remote and mobile access

Hlið binds to 127.0.0.1 by default. Do not put port 3000 directly on an untrusted network. Come on now.

For another device:

1. Install and authenticate Tailscale on the Windows host and the other device.
2. Open FORGE → Access → Network and use Set up with agent, or follow the manual steps shown there.
3. Generate a Tailscale certificate for the host's MagicDNS name and keep the certificate and private key under %LOCALAPPDATA%\Hlid.
4. Set the TLS certificate/key paths, turn on network access, and restart Hlið.
5. Open the HTTPS MagicDNS address shown in Forge. The default TLS proxy port is 3443.
6. Sign in with the app password. The browser can install the PWA if an app-shaped window is useful on that device.

Remote password login and microphone capture both need HTTPS. Hlið accepts localhost and Tailscale CGNAT peers by default. Only turn on regular RFC1918 LAN access for a network you actually trust.

Voice and attachments

Read aloud

Every completed assistant reply in Raven has a speaker control beside the copy action. It starts only when tapped. While it is reading, the same control pauses or resumes and a separate stop control ends playback.

Open FORGE → Experience → Read aloud to choose the speech engine, voice, and reading speed. Device browser uses a local speech voice on the device viewing Raven. Hlið excludes voices that the browser reports as remote. Microsoft host uses a voice installed on the Windows computer running Hlið, then plays the result as regular audio on the viewing device. That option works from a phone connected through Tailscale and gives the browser exact media pause and resume behavior.

When Codex realtime Developer Preview is available for the signed-in Codex account, Codex realtime appears as another read-aloud engine with its own voice. This is a separately gated Codex capability. The local device and Microsoft choices remain available without it.

The speech engine, Microsoft voice, and reading speed are saved in the Hlið configuration and apply to every device. The selected device-browser voice stays on that device because each browser can expose a different voice list. Microsoft speech and device speech both run locally without a cloud speech service. Microsoft speech audio does travel from the Hlið host to the viewing device over the current Hlið connection.

Read aloud skips fenced code blocks, link addresses, and Markdown formatting. It reads the finished response text, not tool activity or a reply that is still streaming.

Voice input

Open FORGE → Experience → Voice and choose what the microphone should do. Dictate with Whisper creates editable text locally. Download a Whisper model, select it, and turn voice on. The model loads locally and stays warm for repeated transcription. Switching models hot-loads the new one without a server restart.

Whisper threads controls how much CPU a transcription can use. Higher is faster, but boy does it make the machine work for it. Changing the value reloads the voice model. Vocabulary hints gives Whisper up to 50 preferred spellings, one per line, which is handy for project names and technical terms the old noggin does not want to correct after every recording.

In Watch or Raven, tap the microphone once to record and again to stop. On desktop, the configured shortcut does the same thing. The default is Alt+Shift+V.

The browser converts the recording to mono 16 kHz WAV, then the Hlið host transcribes it locally. Audio does not become an attachment or a database row. The text can fill the draft or send immediately, depending on the Forge setting.

Talk to Codex records the full clip and sends it as a normal audio turn to the selected native Codex model. It appears only when that model and account support audio. Unlike dictation, it does not turn the recording into an editable draft first.

With the same separately gated Codex realtime capability, an idle native Codex chat also shows Raven Live. It opens a live microphone session with two-way audio and a running transcript. It is its own mode, not a replacement for local Whisper or the normal recorded audio turn.

Remote microphone capture needs the HTTPS endpoint. If it is not working, check browser permission, HTTPS, the selected model, and the voice toggle.

Attachments

The default upload limit is 25 MB. Images, PDF, plain text, Markdown, CSV, and JSON are allowed out of the box. Both the byte limit and MIME allowlist live in hlid.config.toml.

Use an ephemeral attachment for throwaway session context. Use a vault attachment when the file should still exist after the session is done.

Windows Computer Use

Windows Computer Use only appears when Hlið runs on Windows with a native Codex CLI and the computer-use:computer-use plugin installed and enabled. Its status lives under FORGE → Agents → Computer Use.

The one-shot worker can inherit the calling chat's model and effort or use fixed defaults. Select /computer-use in Watch or Raven, then describe the Windows desktop task. Hlið starts a fresh native Codex worker and shows its progress inline.

This works from a WSL-backed chat because /computer-use is an Hlid capability, not a command executed inside that WSL process. Hlid authorizes and audits the handoff, then delegates the desktop task to the Windows-native worker. Codex's native per-application approval store remains the final app-access boundary.

Every app approval still goes through the normal Hlið/Umbod policy. Session and permanent approvals need an explicit choice. The worker closes when the job is done, while its turns, duration, tokens, cache use, and estimated cost stay in Ledger.

Maintenance and troubleshooting

Import or repair provider usage

These tools are for a source checkout, not the packaged app. They dry-run first and write a JSON manifest before changing anything.

bun scripts/import-provider-history.ts --db /path/to/hlid.db \
  --codex-root /path/to/.codex/sessions \
  --claude-root /path/to/.claude/projects

# Discover the current user's Claude and Codex history automatically.
bun scripts/import-provider-history.ts --db /path/to/hlid.db \
  --discover-claude --discover-codex

bun scripts/repair-codex-usage.ts --db /path/to/hlid.db \
  --rollout-root /path/to/.codex/sessions

bun scripts/repair-claude-usage.ts --db /path/to/hlid.db \
  --transcript-root /path/to/.claude/projects

Add another root flag for archive directories. Read the manifest, then repeat the command with --apply if the plan is right. Apply mode verifies source hashes and a standalone SQLite backup before touching the database. Current imports include the transcript needed to resume from Raven; old accounting-only rows can be upgraded when their original source is still available. Stop Hlið before running maintenance against its live hlid.db.

Updates and SmartScreen

Hlið checks GitHub Releases at startup and can check again from Forge. An app update downloads a versioned executable and launches it through Windows so SmartScreen can do its thing. Accepting that launch replaces the canonical copy and restarts Hlið. Dismissing it leaves the current version alone.

Hlið also checks the installed Claude and Codex CLI versions. Enabled ACP agents report their own versions, which get compared with the ACP registry. Updates show in the global banner and under FORGE → Overview with the command that belongs to that installation.

From a loopback browser or an authenticated Tailscale connection, UPDATE can handle a user-writable installation. Hlið warns before stopping active provider sessions, releases shared app-server processes, runs the known update command, then checks the installed version again. Terminal sessions stay open.

An install that needs elevation, like a root-owned global npm package inside WSL, gets OPEN TERMINAL instead. Hlið releases the provider, copies the exact command, and opens a terminal in the matching distro and workspace. Paste the command there so sudo can ask for the password itself. Hlið never asks for, stores, or relays that password. Custom ACP executables keep using their original installer.

Other LAN clients can see versions and copy guidance, but they cannot stop sessions or launch an update.

Installed PWA clients pick up a new build through the service worker. It swaps the cached assets and refreshes on the next load. No manual cache-clearing dance needed.

Autostart and lifecycle

Forge can add or remove the current executable from the per-user Windows Run key. Restart and shutdown are in the same area. Autostart runs Hlið in the background without opening a browser.

Session reloads

Reload a provider session after changing its vault context or MCP setup. A browser refresh only reloads the interface. It does not replace a provider reload or a full Hlið restart.

Reset a lost password

Run this on the Windows host, then restart Hlið:

%LOCALAPPDATA%\Hlid\hlid.exe auth reset

That removes the password credential and every trusted-device session. Vault data and application config stay put. The next local visit goes back to Create app password.

Remote login does not work

Check that the URL uses HTTPS, both devices are on the same Tailscale network, Forge shows the expected MagicDNS name and certificate paths, network access is on, and Hlið was restarted after the change. A normal LAN IP also needs the local-network switch.

The vault does not open

Open FORGE → Workspace on the host and check that the vault path still exists and is a directory. Fix moved or renamed folder mappings, save, then reload the provider session that uses them.