Getting started
Basic concepts
Four principles that explain how Markwork works. When a behavior feels surprising, the answer is usually here.
The work folder is the context
Markwork works in one folder that you open: notes, documents, research, plans, and task boards. The agent receives a map of all the Markdown files in that folder, the contents of the open documents (including unsaved ones), the selected text, and the cursor position. It browses the rest on its own with the read tools.
Without an open folder, the agent only sees the active document and cannot propose new files or changes to other files.
Everything stays plain Markdown
Documents, kanban boards, and conversation history are stored as Markdown files. There is no database, closed format, or account. Everything can be read by other editors, diffed, and committed to Git.
- A kanban board is a Markdown file with
layout: boardin the frontmatter. - Conversations with the agent are stored in
.markwork/chats/in the work folder. - The API key is your own and is stored in the system keyring.
The agent reads freely and writes through proposals
The read tools (browsing, reading files, reading Git history) run right away. The write tools do not write anything: every action becomes a proposal shown in the review window. Files are only touched after you press Apply.
A proposal may only touch Markdown files in the work folder. Names outside the folder, starting with a dot, or containing .. are rejected. A file that changed since it was proposed is not overwritten.
Transparent about context and cost
Every answer shows the context that was sent, the lookups that were made, and the token usage. The context switches decide which documents may be sent to the model provider. The Agent log window shows every model round and tool call live.
Two kinds of agent
| The Markwork agent | An external harness (pi) | |
|---|---|---|
| Works in | The Markwork work folder | Another project folder, e.g. a code repo |
| Triggered from | The Assistant panel | A kanban card marked @pi |
| Writes | Only through proposals you approve | Freely in the project folder; you review in that repo |
| Files | Markdown only | Anything, including running commands |
See The pi orchestrator for the details of the external harness.