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
$ 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 IdentityTools
Shell, files, search and web fetch are built in. Connect any MCP server, or write your own tool in Rust.
Read the docs on ToolsSkills
Markdown files in ~/.openheim/skills/ go into the system prompt, every session or picked per session.
Read the docs on SkillsSubagents
Hand a task to another agent with its own persona, model and tools. Only the final answer comes back.
Read the docs on SubagentsLong-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 memoryModes
Code mode gets every tool. Architect mode only gets read-only ones, so the agent plans but never edits.
Read the docs on ModesEffort levels
Low, medium or high, mapped onto each provider's reasoning settings. Set per session, kept across model switches.
Read the docs on Effort levelsSwitch models
Change model mid-session, even to another provider. The conversation carries on, and the switch is saved.
Read the docs on Switch modelsBring 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.
- Anthropic
- OpenAI
- Google Gemini
- xAI
- DeepSeek
- Kimi
- Z.ai
- Ollama
Plus anything that speaks the OpenAI API: OpenRouter, LiteLLM, vLLM, LM Studio. Or write your own client for anything else.
Read the docs on providersWhat 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_dirsearchShell
opt-inRun scripts, builds and git. Off until you set allow_shell = true, and each command stops after 120 seconds.
execute_commandWeb
Fetch a public page as plain text. Private, loopback and cloud metadata addresses are refused.
web_fetchDelegation
Hand a self-contained task to a subagent with its own persona, model and tools.
delegate_taskMemory
Save notes for later sessions, then search, update or delete them.
remembersearch_memoryedit_memoryforgetYour own
Tools from any MCP server join at startup, or implement ToolHandler in Rust.
server__toolToolHandlerSafe by default.
An agent that runs tools needs limits. These are on before you change a single setting.
Read the docs on sandboxingShell 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.
OpenheimClientEmbed 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 ToolHandlerAdd 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 LlmClientBring 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 PermissionGateOwn 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

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.