Autonomous agents from a markdown file
In rysh, a coworker is a markdown file: YAML frontmatter on top, a system prompt below. ##agent spawn does the rest.
Ask a platform team what it takes to stand up a new automated worker and you'll get a list: a service repo, a Dockerfile, a deploy pipeline, a queue, a dashboard nobody checks after week two.
Ask rysh, and the answer is: a markdown file.
The whole deploy artifact
Here is a complete, working agent definition:
---
name: code-reviewer
description: Reviews diffs for correctness before they hit CI.
model: # optional — defaults to your configured Claude model
---
You are a meticulous reviewer for this repository.
Focus on correctness first, style second. When you flag an issue,
quote the exact lines and propose a concrete fix. If a diff touches
actor code, check for state accessed outside the mailbox. Never
approve a change you haven't actually read.
The frontmatter is metadata (name, description, optionally model). Everything
below it is the system prompt. That's it. No SDK, no build step.
Spawn it:
##agent spawn ./agents/code-reviewer.md
Don't even want frontmatter? Skip it. If the file has no YAML block, the entire file
is the system prompt and the agent's name is derived from the filename. A
release-notes.md full of instructions becomes an agent called release-notes. The
laziest possible path still works, on purpose.
What actually got created
This is the part I want to be precise about, because "AI agent" is a phrase that means everything and nothing in 2026.
When you run ##agent spawn, rysh creates a headless actor inside your session. No
PTY. No pane. No window. It doesn't occupy screen real estate and it isn't a terminal
tab cosplaying as a service. It gets three things:
- A name in the registry. Your session keeps a roster of agents; this one is now
on it (
##agent listshows you everyone). - Its own execution loop. Each agent runs its own LLM prompt-execution actor — the same engine that powers every rysh pane, with the same tool use and the same approval gates. Your custom system prompt is its standing orders.
- An inbox. The agent is addressable by name, from anywhere in your workspace.
That third one changes how it feels day to day. From any pane, mid-whatever-you-were-doing:
@code-reviewer review the diff on my current branch — focus on the pane actor changes
The @ prefix routes your prompt to the named agent. It works on its task while you
keep your shell. And there's a control plane with a doubled prefix:
@@code-reviewer stop # cancel what it's doing right now
@@code-reviewer deactivate # bench it — stays defined, ignores prompts
@@code-reviewer activate # back in the game
Where do its replies go?
A headless worker still needs a place to speak. You register it to a pane:
##agent register-output code-reviewer
Now its output lands in that pane's chat stream — which in rysh is a separate
stream from your shell output and your own AI prompts. Your go test scroll and the
reviewer's findings don't interleave into soup; each pane keeps per-mode output
streams, and agent chatter has its own lane. Unregister it (##agent unregister-output) and it goes quiet again, still working, still addressable.
When you're done with an agent entirely:
##agent delete code-reviewer
No orphaned container. No zombie process to hunt. It was an actor in your session; now it isn't.
Why markdown, though?
You could imagine fancier formats. A JSON schema. A web console with a textarea and a Save button. Half the industry ships the textarea.
Markdown-with-frontmatter wins for one reason: the agent becomes an artifact you can
read. Its entire behavioral surface — name, standing orders, everything — fits in
one file that opens in any editor, diffs in any PR, and travels with a git clone.
When the reviewer starts approving things it shouldn't, you don't spelunk a dashboard;
you open the file and read what you actually told it.
There's a deeper consequence — your agents become version-controlled team members whose "performance reviews" are commit history — but that's a whole post of its own (https://rysh.ai/blog/agents-live-in-git). And once one file is one agent, a folder of files is a team you can hire in a single command (https://rysh.ai/blog/agent-spawn-all).
The honest part
rysh runs on Claude — you bring your own Anthropic key, and it's self-hostable on your own infra. A markdown file doesn't make an agent magically smarter; the model does the reasoning, and your system prompt does the steering. What the file format buys you is legibility: an agent whose entire definition you can read, review, and revert.
In a world where most agents are configured in someone else's database, that's the feature I'd fight for.
rysh is in private beta. If you want agents that live in your repo instead of a vendor's dashboard, we're onboarding design partners — free access, direct line to the founder, your feedback steers the roadmap: https://rysh.ai/design-partner
Related: ##agent spawn-all: hire a whole team from a folder of
markdown · Your agents live in
git