v0.18.0 What's new

The same agent, everywhere you run it

One open-source runtime for your terminal, your editor, a server or your own Rust app. Bring any model.

Prefer a desktop app? Try Openheim Studio

Pick how you run it.

The same binary, config and tools, from your terminal to production.

A chat UI in your terminal

Run it with no arguments. Replies stream in, each tool call waits for your approval, and the footer shows the model and context size.

  • — Switch model, effort or mode mid-session
  • — Resume any saved conversation
  • — Nine accent colors
Read the docs on openheim
$ openheim

:models            switch model mid-session
:effort high       let the model think harder
:mode architect    read-only tools, plans only
:sessions          pick up a saved conversation
:theme green       change the accent color

Running several agents? Give each its own --config, with its own history, skills and memory. How it works

Everything the agent loop needs.

Call the model, run its tools, feed the results back, repeat.

Identity

Write who the agent is in system.md: its role, tone and rules. It goes into every turn, ahead of any skills.

Read the docs on Identity

Tools

Shell, files, search and web fetch are built in. Connect any MCP server, or write your own tool in Rust.

Read the docs on Tools

Skills

Markdown files in ~/.openheim/skills/ go into the system prompt, every session or picked per session.

Read the docs on Skills

Subagents

Hand a task to another agent with its own persona, model and tools. Only the final answer comes back.

Read the docs on Subagents

Long-term memory

Ask it to remember something and it saves a note. Search is offline by keyword, or semantic with embeddings.

Read the docs on Long-term memory

Modes

Code mode gets every tool. Architect mode only gets read-only ones, so the agent plans but never edits.

Read the docs on Modes

Effort levels

Low, medium or high, mapped onto each provider's reasoning settings. Set per session, kept across model switches.

Read the docs on Effort levels

Switch models

Change model mid-session, even to another provider. The conversation carries on, and the switch is saved.

Read the docs on Switch models

Bring your own model.

Native clients for Anthropic, OpenAI and Gemini. Switch providers with one line in config.toml, or switch models in the middle of a session.

Plus anything that speaks the OpenAI API: OpenRouter, LiteLLM, vLLM, LM Studio. Or write your own client for anything else.

Read the docs on providers

What the agent can do.

Twelve built-in tools, plus anything you connect.

Files

Read, write and edit files in place, list folders and regex-search them, all inside work_dir.

read_filewrite_fileedit_filelist_dirsearch

Shell

opt-in

Run scripts, builds and git. Off until you set allow_shell = true, and each command stops after 120 seconds.

execute_command

Web

Fetch a public page as plain text. Private, loopback and cloud metadata addresses are refused.

web_fetch

Delegation

Hand a self-contained task to a subagent with its own persona, model and tools.

delegate_task

Memory

Save notes for later sessions, then search, update or delete them.

remembersearch_memoryedit_memoryforget

Your own

Tools from any MCP server join at startup, or implement ToolHandler in Rust.

server__toolToolHandler

Safe by default.

An agent that runs tools needs limits. These are on before you change a single setting.

Read the docs on sandboxing

Shell is opt-in

execute_command stays hidden from the model until you set allow_shell = true in config.toml.

Files stay in work_dir

File tools can't read or write outside the work directory, and symlinks can't be used to escape it.

You approve tool calls

The TUI and ACP editors ask before each call: allow once, allow always, or reject. "Always" on a shell command covers only those exact arguments. Tools you trust can go in always_allowed_tools.

Read-only architect mode

Switch a session to architect mode (:mode architect in the TUI) and the agent only gets tools that can't change anything.

Guarded web fetch

web_fetch refuses private, loopback and cloud metadata addresses, and stops after 20 seconds or 256 KiB.

Bounded commands

Each shell command runs in its own process group, is killed after 120 seconds, and has its output capped at 64 KiB.

Shell commands can still use absolute paths outside work_dir. For full isolation, run openheim in a container.

Extend it in Rust.

Embed the agent in your own app, or plug in tools, model backends and approval flows. Each one is a single trait.

OpenheimClient

Embed the runtime

Sessions, streaming, history, skills, memory and MCP behind one client. Leave out the CLI, TUI and server with default-features = false.

let client = OpenheimClient::builder().build().await?;
let session = client
    .new_session()
    .cwd("/my/project")
    .start()
    .await?;

session.prompt("Summarise the README", |event| {
    if let StreamEvent::LlmResponse { content } = event {
        print!("{content}");
    }
}).await?;
Read the docs on library usage
ToolHandler

Add your own tools

Implement two methods and the agent can call your code. Tools get the same work_dir boundary and approval flow as the built-ins.

#[async_trait]
impl ToolHandler for TicketLookup {
    fn definition(&self) -> Tool {
        // name, description, JSON schema
    }

    async fn execute(
        &self,
        args: &str,
        turn: &TurnContext<'_>,
    ) -> Result<String> {
        // run your code; the string goes to the model
    }
}

OpenheimClient::builder()
    .tool(Box::new(TicketLookup))
    .build()
    .await?;
Read the docs on custom tools
LlmClient

Bring any model

Wire in a backend that isn't built in: a private API, a research endpoint, or a mock for tests. OpenAI-compatible servers need no code at all.

#[async_trait]
impl LlmClient for MyProvider {
    async fn send(
        &self,
        messages: &[Message],
        tools: &[Tool],
    ) -> Result<Choice> {
        // call your model and map its reply to a Choice:
        // text, or tool calls for the agent to run
    }
}
Read the docs on custom LLM providers
PermissionGate

Own the approval flow

Decide how tool calls get approved: a CLI prompt, a Slack message, a policy check. Subagent calls go through the same gate.

#[async_trait]
impl PermissionGate for SlackApproval {
    async fn check(
        &self,
        req: &PermissionRequest<'_>,
    ) -> PermissionDecision {
        // ask about req.tool_name and req.arguments
        PermissionDecision::AllowOnce
    }
}

let session = client.new_session().start().await?
    .permission_gate(Arc::new(SlackApproval));
Read the docs on permission gates

Openheim Studio

Prefer a desktop app?

Openheim Studio is built on openheim: the same agent, without a config file. Free to use.

  • — Agents for different jobs, each with its own instructions, tools and folders
  • — Shared memory between them
  • — macOS, Windows and Linux, with iOS and Android coming
Get Openheim Studio
Openheim Studio on macOS, with a chat where an agent wrote a brief and waits for approval to save it to shared memory

Common questions

Does openheim work inside my editor? +

Yes. Run openheim acp to start an ACP (Agent Client Protocol) stdio agent. Register it in your editor's ACP agent settings and you get a full tool-equipped agent inside Zed, JetBrains, and any other ACP-compatible client — no separate service needed.

Does openheim require a specific LLM provider? +

No. openheim works with OpenAI, Anthropic, Gemini, and any OpenAI-compatible endpoint — including local models via Ollama, vLLM, or LM Studio. Switch providers with one line in config.toml.

Is it safe to let openheim run shell commands? +

The shell tool is off until you set allow_shell = true, and file tools can't reach outside the configured work_dir. In the TUI and in ACP editors, openheim asks before each tool call. Shell commands can still use absolute paths, so for full isolation run openheim in a container.

Can I use openheim as a library instead of a CLI? +

Yes. Add openheim as a dependency with default-features = false to embed it directly in your own Rust application, without pulling in the CLI, TUI, or server extras.

Up and running in a minute.

Install it, run openheim init, add an API key. Open source and free.