What is OpAgent

What is OpAgent

OpAgent is a true AgentOS.

What is an AgentOS?

A traditional operating system answers questions such as: How do applications start? Where are files stored? How are processes isolated? How does networking work? How are errors handled?

An agent operating system answers a different set of questions:

• How does an agent start?
• Where does an agent run?
• What capabilities does an agent have?
• How do agents collaborate with each other?
• If one agent crashes, will it affect the main application?
• Does it run locally, or does it run remotely?
• How are token usage, processes, and port usage managed across different machines and different agents?

Put together, these questions are no longer about a simple chat box. They are about a runtime layer for agents.

In OpAgent, a task roughly happens like this:

1. You open a directory, such as docs/.
2. OpAgent treats this directory as a workspace.
3. You bind a writing agent to this directory.
4. The agent reads the files in the directory and discusses them with you in Markdown.
5. The conversation is saved as a file, and the agent’s output is written back to the directory.
6. If needed, it can call another proofreading agent, or call a tool.
7. If the directory is on a remote machine, OpAgent starts the remote runtime over SSH so the agent can work inside the remote directory.

If you only build one agent, many things can be hard-coded into the program. But when a user has multiple directories, multiple agents, multiple models, and multiple remote environments, you need a system layer to manage these relationships. That is what AgentOS does.

Why not LangChain, LangGraph, or the Claude SDK?

Starting in April 2025, I began studying the MCP protocol. At the time, I was building a plugin system in Golang, and a thought came to mind: if MCP can call tools, why can’t it call agents? That led to an idea: install agents into a runtime the same way plugins are installed.

LangChain and LangGraph are better suited for orchestrating a single agent workflow in code. Developers put the model, tools, and state graph into the same program, and that program exposes a capability to the outside world.

But OpAgent is not trying to be “a framework for writing agent applications.” It is trying to be “an environment for running agents.” In this environment:

• An agent can be developed independently by a different team.
• An agent can run as an independent process, and a crash should not bring down the main program.
• An agent can be implemented in Go, Python, Node, or another language.
• An agent can be installed, upgraded, and replaced.
• An agent can be local or remote.
• A directory can have its own agent, and a subdirectory can have its own agent too.

So OpAgent cares more about runtime, communication protocols, process boundaries, directory binding, and how files are stored, rather than putting all agent logic into one application process.

Agents, Tools, and Skills are all Nodes

In OpAgent, Agents, Tools, and Skills are all called Nodes.

This lets them use the same integration mechanism. An Agent understands tasks and plans; a Tool executes concrete actions; a Skill packages a certain kind of capability. They have different responsibilities, but from the runtime’s point of view, they are all capability units that can be discovered and called.

A complex agent can run as an independent process, or be deployed as a remote service. A simple prompt-based agent does not need to start an independent process; the runtime can read its definition and load it into memory directly.

type OpNode struct {
  ID      string   `json:"id"`                                     // persistent node id, e.g. agent-cm1...
  HostID  string   `json:"hostID,omitempty" mapstructure:"hostID"` // host id
  UID     string   `json:"uid"`                                    // owner/tenant identifier
  OpCodes []OpCode `json:"opCodes,omitempty"`
  Kind    string   `json:"kind"` // agent | skill | tools
  URI     string   `json:"uri"`  // resource locator (file://, cloudos://, ...)
  Cwd     string   `json:"cwd"`  // current working directory
  Tags    []string `json:"tags,omitempty"`
  Run     Run      `json:"run,omitempty"`
  Meta    any      `json:"meta,omitempty"` // AgentMeta | SkillMeta | ToolsMeta
}

Nodes use OpCode to declare what they can do. For example:

agent/call
agent/continue
agent/loop/create
prompt/get
agent/scan
node/list
notify/message
thread/submit
thread/compact
......

After the runtime sees these declarations, it knows where to send each request. When one agent needs to call another agent, it does not need to know whether the other agent is a local process, a remote service, or a lightweight in-memory definition. It only needs to send the corresponding operation according to the protocol.

This design is inspired by MCP. MCP separates upper-level messages from lower-level connections: the upper layer uses JSON-RPC to express requests, responses, and notifications, while the lower layer can use stdio, HTTP streams, and other transports. OpAgent uses a similar idea so agents written in different languages and deployed in different ways can connect to the same system.

Design principles

1 Let agents live in directories

Many tools use “projects” as the boundary: one project, one AI assistant, one context.

OpAgent prefers to use directories as the boundary. Directories are already how you organize work: docs/ contains documentation, src/ contains code, deploy/ contains deployment scripts, and research/ contains materials. Different directories often need different agents.

For example:

• Bind a writing agent to docs/.
• Bind a coding agent to src/.
• Bind an operations agent to deploy/.
• Bind a research agent to research/.

These agents do not need to squeeze into the same large context. Each reads the files in its own directory and modifies the content it is responsible for. When collaboration is needed, they pass results to the next agent through files and conversation records.

2 Conversations are files

In many AI products, conversations live in the application’s own database. You can review them in the UI, but it is hard to edit them directly, copy them, manage them with Git, or let another tool continue working on them.

OpAgent saves conversations as Markdown files.

This means that when you ask an agent to write a proposal, it will not remain only in the chat history. It is itself a .md file. You can open it directly, change the title, delete noisy parts, add references, commit it to Git, or move it to another directory and keep using it.

A requirements discussion, a code review, or a troubleshooting session can all be preserved as files. When you open them later, you do not need to first remember what was discussed. The file is already in the directory.

3 Everything is a file

OpAgent follows the UNIX idea here: if something can be represented as a file, do not hide it inside an application’s black-box database.

In UNIX, files are not just “documents.” Configuration is a file, logs are files, and input and output are files. The benefit is simple: users can open, search, copy, back up, diff, and commit them to Git with existing tools. They can also pass the output of one program to another program for further processing.

OpAgent brings this idea into agent workflows:

• Conversations are Markdown files.
• Threads are jsonl files.
• Agents, Skills, models, and workspace configuration are local files whenever possible.
• Drafts, plans, and review results generated by agents also return to files in the current directory.

The file system is not just a place to “save results.” It is the interface for agent collaboration. Humans can edit these files directly, and agents can read them again. Content written by one agent can be picked up and continued by another agent.

4 Separate windows from workspaces

Traditional IDEs often map one window to one project. To open another project, you open another window.

OpAgent separates windows from workspaces. A window is only a UI container; a workspace is the concrete directory.

So one window can contain multiple directories at the same time. You can open a writing directory, a code directory, a materials directory, and a remote server directory in the same window. Each directory has its own agent, conversations, and configuration. Removing one directory does not affect the others.

5 Reuse the editor area for conversations

Many AI tools put conversations in a sidebar. This makes AI feel like a temporary assistant: it says something, and then the user copies the useful parts into the document. Over time, conversations and documents become two separate worlds.

OpAgent does not work this way. It puts conversations and files in the same editor area: file tabs are on top, holding the documents, code, and configuration you are working on; conversation tabs are below, holding the process of discussing those contents with agents.

The vertical split separates “result” from “process.” Reusing the same editor area makes it possible to transform result and process into each other at any time.

For example, when writing a proposal, the file tab above is the formal document, while the conversation tab below is where you discuss ideas, add background, and revise paragraphs with the agent. Content generated by the agent does not need to be copied out of a chat box first. You can directly delete, edit, and organize it in the conversation, move mature parts into the formal document, or ask the agent to continue based on the content you edited.

The point of this design is not reusing UI components. It changes how AI participates in work: a conversation is no longer a chat log sitting off to the side; it becomes part of the document-generation process.

6 Local and remote workspaces

OpAgent does not turn “local” and “remote” into two separate products. Local directories and remote server directories are both workspaces in the UI. The only difference is where the agent actually reads files, writes files, and runs commands.

A local workspace is straightforward: the directory is on your computer, and the agent works on this machine. Writing materials, private notes, small project code, and temporary research documents can all live locally. The benefit is simplicity and control: your data does not need to leave your machine.

Remote workspaces solve another kind of problem: many real work environments are not on the local machine. Code may live on a development server, data may be on an internal server, and tasks may depend on Linux, GPUs, databases, or the company intranet. The traditional approach is either to sync files locally or open a terminal and log into the server. OpAgent’s approach is: the local client is only responsible for the interface; the agent actually runs on the remote machine.

When connecting remotely, OpAgent prepares the remote environment over SSH, starts opagent-runtime and opagent-server on the remote side, and connects back through local port forwarding. The user sees an ordinary workspace tab, but file reads and writes, command execution, and context persistence all happen inside the remote directory.

This way, local and remote workspaces can sit in the same window. One tab can be a local documentation directory, and another tab can be a code directory on a remote development machine. You do not need to switch back and forth between an editor, terminal, and remote desktop, and you do not need to move server-side content locally just so an agent can work on it.

The point of this design is not “SSH support” itself. It is to let the agent follow the actual work site: wherever the files and environment are, the agent runs there; the human still manages everything from the same OpAgent window.

Markdown

OpAgent treats Markdown as the shared interface for humans and agents.

The reason is simple: humans can read it directly, and agents can modify it easily. Headings, lists, code blocks, tables, quotes, and links are already enough to express most collaboration processes.

In OpAgent, conversations, plans, task breakdowns, review results, and agent outputs can all be saved in Markdown. Users can edit them directly, and agents can continue reading them in the next round.

Many editors today add an AI sidebar to an existing editor. OpAgent takes a different approach: from the beginning, it puts the AI work process into Markdown files.

Scenario	OpAgent	Cursor	Claude Code	Obsidian	Typora
Markdown editing	✅ WYSIWYG	⚠️ Source editing	❌ Terminal output	✅ WYSIWYG	✅ WYSIWYG
Markdown edit review	✅ Reviewable AI edits	⚠️ Source review	⚠️ Source review	❌ Not available	❌ Not available
Workspaces	✅ Multiple workspaces in one window	⚠️ One workspace per window	⚠️ Terminal tabs	⚠️ One workspace per window	⚠️ One workspace per window
Conversation files	✅ Local .md files	❌ Hidden in app data	⚠️ Hidden in project data	❌ Not built in	❌ Not built in
Multiple models	✅ Any model	✅ Any model	❌ Mainly tied to Anthropic	❌ Not built in	❌ Not built in
Multiple agents in one project	✅ Agents bound to directories	❌ Single project-level AI	❌ Session-level	❌ Not built in	❌ Not built in
Managing Agents and Skills	✅ Visual management	❌ Hidden in files	❌ Not available	❌ Not available	❌ Not available

Integrating external agents

OpAgent does not need to reimplement every agent capability.

Claude Code, Codex, or existing internal command-line agents and service-based agents should all be able to connect.

OpAgent provides the opagent-protocol SDK. Once an external agent implements the protocol, it can be called as a standard Node: it can be bound to a directory, receive context, stream results back, and execute operations such as agent/call, thread/submit, and notify/message.

This way, an external agent is no longer an isolated terminal tool. It can enter OpAgent’s system of directories, files, conversations, and workspaces. Users still use it in the same interface, and results still return to the current working directory.

Marketplace

Marketplace is used to distribute Agents, Skills, Tools, and Workspace templates.

“Installing” here does not mean stuffing a black-box feature into the application. After installation, you get a set of local files: agent definitions, prompts, configuration, example directories, or a complete Workspace template.

For example, a team can package a “product requirements review” workflow as a template. After others install it, they get a directory structure, agent configuration, model configuration, prompts, and example files. Users can use it directly, or modify it into their own version.

Marketplace solves the reuse problem: once a person or a team has figured out an agent workflow, it should not have to be configured from scratch every time.

Why OpAgent is needed now

LLMs no longer just answer questions. They can read files, modify code, research information, call tools, and execute commands.

But many products still work like chat boxes: conversations live inside the application, generated results need to be copied out, and agents can only follow one project or one session. Over time, it becomes hard for users to organize these processes, and hard to hand them off to another tool for further processing.

OpAgent’s approach is direct: put agents into directories, save conversations as files, connect external agents through one protocol, and put local and remote directories into the same window.

In this model, AI no longer floats outside the work. It enters the file system, enters the directory structure, and enters the user’s real workflow.