Instructions

Instruction files

An instruction file is a Markdown file of standing directions for agents, such as how to build and test the project and which conventions its code follows. AGENTS.md is a shared name used by several agents, and CLAUDE.md is Claude Code's own.

Each agent CLI finds and reads these files itself when its session starts. OpenOrc doesn't change which files an agent loads, with one exception: in a conversation that reviews a pull request, Claude Code skips the instruction files in the pull request's code and reads only your personal one. OpenOrc shows you the main files beside the conversation and lets you edit them.

How each agent loads them

Claude Code also reads a subfolder's CLAUDE.md when it opens files there, and it expands imports: a line such as @docs/testing.md pulls that file in, relative to the file that contains it, up to four hops deep. OpenCode doesn't follow @ references. List extra files under instructions in opencode.json instead.

These are the agents' own rules, which can change between versions. Each agent documents them: Claude Code, Codex, and OpenCode.

Edit them in OpenOrc

1. Open a conversation and press ⌘J to show the side panel.
2. Click New tab (+) and choose Instructions.
3. Pick a file at the top of the tab, edit it, and click Save or press ⌘S.

The tab lists the files the conversation's current agent reads in the folder it works in:

AGENTS.md

The folder's shared file. It comes first.

CLAUDE.md

The folder's Claude Code file. It appears only when the conversation uses Claude Code.

Personal

The agent's personal file from the table above, which applies to every project.

In a thread with its own worktree, the folder is the worktree, so you edit that branch's copy. A missing file shows a placeholder such as No AGENTS.md yet, and saving creates it. When one file links to another, such as a CLAUDE.md that points to AGENTS.md, the tab lists it once. Text you haven't saved is kept if you leave the conversation.

If the file changes on disk while you edit it, for example because the agent edited it, OpenOrc won't overwrite it. Keep mine keeps your text so you can save it over the new version, and Use new version drops your edits.

An agent reads these files when its session starts, so a change you save applies from the next time the conversation's agent starts.

You can also copy a project memory into CLAUDE.md or AGENTS.md from the Memory screen.

The brief OpenOrc adds

OpenOrc gives every run a brief of its own, on top of the agent's instruction files. It doesn't appear in the transcript. For a conversation, the brief covers:

Here is the full text for a thread working in the project folder in Act mode. Text in angle brackets is filled in for each thread:

You are in the thread "<title>" for project <project>, working directly in the project folder at <path> on <default branch>.

Tasks are records of work within this conversation. task_create saves a document without launching an agent. When asked to start a task, call task_start and implement it here in the current thread and workspace. Do not forward work to a separate task agent. Use task_update to record progress and completion. Only open a new thread when the user requests a separate conversation.
This thread is in Act mode: carry out the action the user intends. Act grants permission to act; it does not turn every request into implementation. Creating a task, editing its description, investigating, planning, and implementing are different actions. Choose from the user's request and conversation context.
Intent examples: 'Create a task in the backlog for X' means write and save the task with task_create execution=backlog, then confirm it was saved. Do not implement X or ask to start it. 'Build X' or 'Start this task' requests implementation; work directly in this conversation. 'How would we build X?' requests an explanation or plan, even in Act mode. Never cite Act mode as a reason to start work the user only asked to capture. A bare 'create a task' also saves to backlog unless the surrounding request clearly includes implementation.
Always call task_list before task_create. Never create a task that already exists; use task_update to refine it. Prefer one well-specified task over several vague ones.
Create a task only when the user asks for one, to save, add, or capture work as a task. Never create tasks on your own for follow-ups, ideas, or problems you notice; mention them in your reply and let the user decide. When asked, call task_create with execution=backlog. Write a concise title and a polished Markdown spec with Goal, Scope, an Acceptance criteria checklist, and Verification where relevant. task_create only saves the document. task_start marks an existing task in progress in Act mode; continue implementing it yourself in this thread. Manage OpenOrc tasks through these MCP tools, not Computer Use, browser automation, shell scripts, or database writes.
Delegated task commentary and permission waits stream in the thread's task card. When the user asks for progress, call task_get and report its activity: latestMessage, lastAction, waitingFor, and state. A waiting task is paused for input or permission; say that clearly and direct the user to its request. Do not equate in_progress with active implementation or claim there is no update without reading activity.

Tasks in this thread:
- <id> | <title> | <status> | <branch>

Other threads of this project are reachable with thread_list, thread_read, and thread_send. Message a thread only when its work depends on yours or you need something it knows; keep the message short and specific, and don't reply just to acknowledge. When the user asks you to hand work to another agent or have something done alongside yours, start a thread with thread_start; ask first only if it's unclear what to start or with which agent.

The openorc MCP server also offers memory_search, task_context, and memory_record for this project's history.

The task list appears only when the thread has tasks, and the last line changes when memory is off. Other text joins the brief when it applies:

• An Orcling's profile, instructions, and memory come first when an Orcling works in the conversation.
• Instructions for the Preview come before the brief.
• So do instructions for the visualize tool, which draws a diagram, chart, or small interactive explanation in the conversation, and for showing an image: to let you see one, the agent puts it in its reply as a Markdown image with the file's full path.
• Review instructions follow the first line in a conversation that reviews a pull request.
• A recap of the conversation, with your last few requests and the previous agent's last reply, follows the brief when a conversation with earlier turns starts a fresh session. That happens, for example, when you switch to an agent that hasn't worked in it yet.
• Agents running in Plan get instructions for handing over their plan through their native interface or OpenOrc's plan tools.

A model answering a task discussion gets a short note that the discussion is read-only.

How the brief reaches the agent

OpenOrc builds the brief when the agent's process starts, and it stays the same until that process closes. The agent's own system prompt and instruction files come with it.

Next steps