Markwork

Markwork is a Markdown workspace for humans and AI agents for Linux, macOS, and Windows: a personal workspace where you and an AI agent work on notes, documents, research, plans, and tasks with the same context. The agent does not stop at an answer: it browses your files, then proposes real actions (creating a file, changing text, moving a task card) as a diff that you review and approve first. Its foundation is a Markdown editor with a live formatted view, a kanban board, and Git history. Built with Electron, React, and CodeMirror 6; the application itself is plain TypeScript that runs on Node, and the window only draws what it is told. Everything is bundled with Vite.

There is no separate preview panel: the text is shown formatted right away. The visual editor (on at first) hides Markdown syntax such as #, **, ` and [](url) everywhere and edits through a toolbar, a selection menu, and a / menu, so someone who does not know Markdown can write; Markdown (the Visual / Markdown switch in the header, or Ctrl+/) shows the file exactly as it is written, all its syntax in a fixed-width font. The switch is on every kind of document: for a board, list, table, calendar, timeline, gallery, chart, or CSV file, Visual is that view and Markdown is its text. With the visual editor off in Preferences, the live view shows the syntax on the line where the cursor is. The file is plain Markdown in every case.

Its landing page is in docs/ and only shows the agent features; the complete feature documentation per topic is in docs/docs/ (static HTML; enable GitHub Pages from the /docs folder of the main branch to publish it). The screenshots are made by scripts/capture.mjs (npm run docs).

The website uses the app's Geist fonts, zinc colors, sidebar, and document tabs. Body text is 16px, navigation is 15px, and secondary text is 13–14px; small section labels stay at least 12px, including on narrow screens. It starts in the dark theme; the appearance button at the foot of the sidebar switches to light and remembers that choice across pages. Screenshots and animations follow the selected theme. Reduced-motion preferences replace animations with still images. Icons are embedded directly in the page, so they also render when an HTML file is opened locally. Run npm run site:build after changing the application's theme tokens, fonts, or website icons, and npm run test:site to check the theme and media contracts. npm run docs captures both appearances (docs/assets/ for light, docs/assets/dark/ for dark), with a still image for every GIF; MARKWORK_THEME=light or dark captures only that appearance. Preview locally with python3 -m http.server --directory docs.

Goal: Markdown workspace for humans and AI agents

The goal of Markwork is to be a personal workspace where the user and an AI agent work with the same context: notes, documents, research, decisions, plans, and tasks in one work folder. The agent helps to understand information, make plans, and finish work with results that the user can check. Writing remains one of the main workflows. The principles of its development:

• The context comes from the workspace. The open documents (including unsaved ones), the selection, the cursor position, and a map of the whole folder are assembled automatically; the model also browses files by itself with read-only tools
• Transparent. Every answer shows what context was sent, what lookups were made, and how many tokens were used
• The user stays in control. The agent reads freely, but never writes by itself: it can only propose new files or changes, and files are only touched after you press Apply on the diff. Later action capabilities must provide a clear access boundary and a result that can be reviewed; an action that needs approval waits for the user's approval. The documents sent to the model provider can be limited through switches, and the API key is your own
• The text stays yours. Everything is plain Markdown in plain files (they can be diffed and committed to Git); no closed format and no account

The current state: a Markdown editor, kanban, Git history, and a DeepSeek-based agent that browses documents, answers with quotes of the file and the line number, reads the Git history of the work folder (git_log, show_commit, file_at_commit), and proposes actions that are approved through the review window: new files (create_file), text replacement (edit_file, one occurrence or all of them), text insertion (insert_text), removing and moving files (delete_file, move_file), and changes to the notes and setup of kanban boards and other structured documents (edit_note, edit_schema). The agent does not write work files without your approval; a batch may be applied partially, a decision can come with a note for the agent, and a change that has been applied can be undone from the panel. The work plan (set_work), change batches (propose_batch), the check of the result (verify_work), and the action journal are stored together with the conversation. Pending work can be resumed after the app is opened again.

Markwork can also be an orchestrator of external harnesses: a kanban card assigned to [agent:: pi] is worked on by pi in another project folder (for example the repo ~/web-ecommerce), not in the Markwork work folder. Markwork builds the prompt from the card, runs the harness, moves the card to In Progress and then Review, records a summary of the result on the card, and shows the log of the tools that were called. When pi asks a question or asks for permission, the card gets the status waiting and you answer straight from Markwork. In a Git repository each card gets its own worktree and branch, several cards of a project work at once, and the result is reviewed in Markwork (the diff, line comments sent back to pi, merge, send as a pull request, or discard) before anything reaches the project folder; a folder without Git is worked on by one harness at a time, and other cards queue.

The next direction of development: expanding the context sources and adding other actions that stay reviewable and controllable. Not available yet: an automatic consistency check, actions by the Markwork agent itself outside Markdown (for example running commands; that is only done by an external harness that the user runs from a card), and model providers other than DeepSeek (see Limitations).

An example workflow

One day of work in a sample folder: a product launch project with plans/launch.md, notes/meeting-1-oct.md, a research/ folder, and a tasks.md board.

1. Home. Start the day on Home: the files to continue, today's journal, agents that are running, due dates from your boards, and the unprocessed inbox.
2. Inbox. Capture ideas, links, and quick notes in one line, then process them later and turn the ones worth doing into kanban cards.
3. Journal. Write short notes through the day with Ctrl+Shift+J. Markwork adds the activity for you: cards moved, agent changes applied, harness results, and Git commits.
4. Kanban. Plan the work on a board. Due dates show up on Home, and checking a task there writes [x] back to its board.
5. Agent. Ask "Is there a meeting decision that has not made it into the launch plan yet?" and the agent answers with quotes and line numbers: the 1 October meeting postponed the release to 22 November, while the plan still says 15 November. Then ask "Update the release date and move the release material card to In Progress." Two proposals open in a review window with a Git-style diff; press Apply or Reject. A card marked @pi goes to the external harness instead.

At the end of the day, Summarize Journal with Assistant proposes a summary that is only written after you apply it.

The meaning of the name

Markwork is Markdown plus work. The foundation is plain Markdown files, and the goal is to get work done: notes, plans, tasks, and results live as documents that are easy to read and edit, and the agent helps finish them with changes that you review first.

Getting Markwork

The installers are attached to each release: an AppImage and a deb for Linux, a dmg for macOS, and an exe installer for Windows. The AppImage, the dmg, and the Windows installer update themselves from the releases; the deb is updated by installing the next one.

Markwork reads and writes plain files, so it needs nothing else to edit notes. Some features use programs of their own:

• git, for the History tab, pull requests, the agent's history tools, and a worktree per card
• pi, for cards worked on by an external harness
• a DeepSeek API key, for the Assistant (set DEEPSEEK_API_KEY, or paste it in the Assistant settings)
• markworkd (markworkd/, Linux only), to keep agents running after the window closes or to run them on another machine

The Programs page (at the foot of the sidebar, or the ☰ menu → Programs) says which of them are installed and how to install the others, and Home lists the missing ones that a feature you use needs.

Building and running from the source

Node.js 22.12+ (tested with Node.js 24) and npm:

npm install
npm run hooks:install
npm start

npm start builds the app into dist-electron/ and opens its window. A path after -- opens that folder (or that file):

npm start -- ~/notes

Without a path, the folder and the tabs of the last session come back. On the first launch the editor shows a sample document; after that, an empty one or Home.

Read AGENTS.md before contributing. Branch names use type/short-kebab-case-description (for example feat/horizontal-rules), and commit subjects use type(module): description (for example feat(editor): add a block removal button). Types are feat, fix, refactor, docs, test, chore, and perf. npm run hooks:install enables the tracked commit-message hook in this checkout; PR CI checks branch names and all new non-merge commits. The installer refuses to replace an existing custom hooks directory. These checks validate format; contributors still review the English description and its accuracy.

Command	Function
npm start	Build, then open the app in dev mode: the Editor Inspector (Ctrl+Alt+I) and the UI Gallery (Ctrl+Alt+G)
npm run build	Check the types and the layer rules, then build the app into dist-electron/
npm run typecheck	Only check the types (the core without Node's types, the core's tests and the Node port, the Electron app) and the layer rules
npm test	The core's tests on Node, then the Electron app's tests (below)
npm run test:core:node	The core's tests on Node (tests/core/core-tests.ts through tests/core/run-core-node.ts)
npm run test:electron	Build, then drive the real app with Playwright under Xvfb (tests/electron/*.mjs)
npm run electron:dist	Build the installers for the system it runs on into release/ (electron-builder, electron-builder.yml)
npm run electron:pack	The same, unpacked, to try the packaged app without installing it
npm run docs	Take the screenshots and animations of docs/assets/ from the real app (scripts/capture.mjs)
npm run test:live	The Assistant against the real DeepSeek API on the sample manuscript (needs DEEPSEEK_API_KEY in .env, see .env.example)
npm run test:live:forge	The forge layer against a real Forgejo or Gitea (needs FORGEJO_TOKEN in .env; add FORGEJO_CONTRIBUTOR_TOKEN and -- --write to also send, merge, and resolve)
scripts/forgejo.sh test [read|write|all]	The live Forgejo suite against a throwaway Forgejo in a Podman (or Docker) container that the script starts, seeds, and tears down with down; the tokens go to .env.forgejo
npm run bench	Measure the Markdown module on Node; bench:save and bench:compare keep and compare results ()

The live tests and the benchmarks are not part of npm test.

Releases

npm run electron:dist makes the installers of the system it runs on; the release workflow runs it on Linux, macOS, and Windows when a v* tag is pushed and attaches the files to the release. Signing and notarizing take their secrets from the environment (CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, WIN_CSC_LINK, WIN_CSC_KEY_PASSWORD) and are skipped without them. The app icon is resources/icon.png, drawn from resources/icon.svg by npm run icon.

Translations

The source language of the interface is English. Text in src/ is wrapped in _() (or fmt(_('… {name} …'), { name }) for text that contains values, pgettext() when a context is needed) from src/base/i18n.ts. To add a language: npm run pot, copy po/markwork.pot to po/<code>.po, translate it, and add its code to po/LINGUAS. The build compiles each listed language with msgfmt (from gettext) into dist-electron/locale/, where the core reads it for the user's language. The window's own labels in electron/renderer/ are not wrapped yet.

Features

Live formatted writing

• The visual editor (on at first; the Visual / Markdown switch in the header bar, Ctrl+Shift+M, or Preferences → General): the syntax stays hidden on the cursor line too, a list item has a bullet and a task a checkbox you click, and the cursor never lands inside a hidden # or - (Home goes to where the text starts, Backspace there makes the line a paragraph, and Backspace/Delete beside a hidden ** remove the letter, not the marker). A toolbar over the text has undo/redo, the text style, the inline formats, the three lists, and table/image/divider (row and column buttons in a table, which stays a grid whose cells are typed in: Tab, Enter, and the arrows move between cells); every block (paragraph, heading, list, quote, table, code block) has a handle on hover, a + that adds a block after it and opens the / menu, a − beside it that removes the block (Ctrl+Z restores it), and a grip that drags it to another place (Ctrl+Shift+↑ / ↓ move it from the keyboard); selected text gets a menu with the formats and Ask (the Assistant); / at the start of a line or after a space opens a menu of blocks that narrows as you type. Typed Markdown still works. The file is the same Markdown as in Markdown (source mode), which shows every marker
• Headings, bold, italic, strikethrough, ==highlight==, inline code, links, and images are formatted right away
• Code blocks, quotes, and horizontal rules are styled (nested quotes >> are indented further, up to three levels); the ``` fence lines are hidden outside the block
• Programs. A tab of its own (the box at the foot of the sidebar, marked with a dot while something needed is missing) that checks git, pi, and markworkd: installed or not, the version and the path, what each is for, and how to install a missing one (a command per system with a copy button, Open Terminal, the instructions page). What is needed follows Preferences → Agents: agents in this window need pi here; through markworkd they need markworkd too; on an SSH machine markworkd, pi, and git are checked on that machine through its daemon. Check again looks once more, and so does coming back to the window while something needed is missing.
• Home. A special tab (a house icon) that summarizes what you can continue: a greeting according to the time, Continue cards (the latest files from different folders), (the number of notes and activities, with a quick capture button), that is working, queued, or waiting for your answer (click to answer, see the log, or open its board), from all the kanban boards in the work folder (unfinished cards that are overdue or due today, tomorrow, or the day after, with the project name from ; the checkbox writes straight to its board), an that still has unprocessed items, and . Above them, while a program a feature needs is missing, a section names it with (it can be hidden until that list changes). Home opens when the app starts without saved tabs and when the last tab is closed (it can be turned off in Preferences), and through or the ☰ menu → . Its data is recalculated from the Markdown files every time Home is shown or the window becomes active again, without a database.

View

• Many documents in one window (tabs). The tab bar appears above the editor as soon as there are two or more documents. Clicking a file in the Files tree or choosing it in the Open File dialog opens a new tab (or switches to its tab if that file is already open; an empty unsaved document is reused), and New (Ctrl+N) makes an empty tab. Every tab has its own undo history, cursor, and scroll position; the Focus/Typewriter/Source modes and the theme apply to all tabs. The • mark on a tab title means it is not saved, Ctrl+W closes a tab (asking if there are changes; closing the last tab empties its document), and Ctrl+Tab / Ctrl+Shift+Tab (or Ctrl+PgDn / Ctrl+PgUp) switch tabs. With autosave on, leaving a tab saves it right away. The outline, the word count, the search, and the History tab follow the active tab, and the assistant reads the contents of other unsaved tabs, not the version on disk. Tabs are restored: when the app is opened again without arguments, the tabs with files of the last session are opened again with their order, the active tab, and their cursor positions; files that no longer exist are skipped (with a message in the status bar). When a work folder is restored, saved tabs outside that folder are skipped, so files from another workspace do not reopen. Without a work folder, standalone file tabs can still be restored. Opening a file or folder from the command line does not restore tabs
• Short notices. Messages such as Saved appear at the bottom of the window and can be dismissed from their upper-right close button.
• A sidebar like VS Code's: an activity bar that is always there (the views Files, Search, History, and Pull requests, with Programs and Preferences at the foot; a view's button opens the sidebar on it and the button of the view shown closes it), and beside it the panel of the view shown, whose edge is dragged to change its width (200 to 480 px, kept). Home and Journal are in the ☰ menu (Alt+Home, Ctrl+Alt+J):
  • Files: a view of sections that fold, share the height, are resized by the lines between them, and are shown or hidden from the view's ⋯ menu (their state is kept in sidebar-sections): Open Editors (the open documents with ✕, grouped by pane once the editor is split), the folder, Outline (the headings of the document; click to jump), and Timeline (the Git commits of the open file, folded at first and read only while open: the timeline-open setting tells the core). The folder section is the tree of the opened folder (through in the menu beside , , or by choosing a folder in the Open File dialog), with subfolders and all non-hidden files. Markdown files (, , , ) open in the document editor; other text files open in the read-only code viewer. Click a file to open it; the file that is open is also highlighted. Hidden files/folders and are not shown. a folder, a file, or an empty area opens a menu with , , , and (for a folder/file, and are added; delete asks for a confirmation and moves to the Trash, not a permanent delete; if the open document is deleted, its contents stay in the editor and are marked as unsaved; Markdown/CSV/HTML document names keep a supported document extension or gain , other file names are kept as entered, and an open document follows its new name): the item is created in the folder that was clicked (for a file: in its parent folder; for an empty area: in the root folder). A file name without a Markdown extension is given , a name that is empty, contains , starts with a dot, or already exists is rejected with an error message; a new file is opened in the editor right away. makes a file with an empty board (, the lists , , ) that is saved right away and opened as a board. moves a file or a folder: drop it on a folder to put it there (a closed folder that is hovered over for a moment opens by itself), drop it on a file to move it to that file's folder, or drop it on the tree title/an empty area to move it out to the root folder. A folder cannot be moved into itself, and a conflicting name in the target folder is rejected without overwriting. If the open document (or its parent folder) is moved, the document stays open with its new path. The tree updates automatically when a file is added or deleted on disk, and the last folder is opened again when the app starts

Collaboration (Forgejo and Gitea)

• Pull requests in the sidebar. The last sidebar tab lists the open pull requests of the repository that the folder's origin remote points to (the server and owner/repo are read from the remote; an SSH remote is reached over https on the default port). Each row shows the title, #number · author · time · comments, and a dot: green can be merged, yellow conflicts, gray not worked out yet. Markwork asks the server on a timer (60 seconds by default, 30 seconds to an hour in Preferences → General → Collaboration) and when the refresh button is pressed, and tells you when a pull request is opened or updated: a toast if the window is in front, a desktop notification if not (also switchable in Preferences). The pull requests that were open when the folder was opened are not announced. It needs an access token for the server (an account setting there, allowed to read and write repositories): click the server line at the bottom of the tab, paste it, and Test connection. It is kept in the system keyring per server (the Secret Service on Linux; on macOS and Windows the OS keychain through Electron's safeStorage; a 0600 file in the config folder without one), never in the settings; MARKWORK_FORGE_TOKEN is used first when set. More: Collaboration
• Reviewing. A click opens the pull request in the area of the editor, with the changed files on the left and three tabs on the right: Note (a Markdown file as a note: the frontmatter fields that changed, then the text with the changed lines marked, a new note all added), Diff (the unified diff of the file), and Discussion (the description and the comments, with a box to write one). The text of both versions is asked from the server when a file is chosen.
• Merging. Merge (with a menu: merge commit, squash and merge, rebase and merge) asks first, merges on the server, and, when the folder is on the base branch, brings it up to date with git pull --ff-only; a folder on another branch is left alone and the toast says why.
• A conflict, resolved here. A pull request that conflicts offers Resolve locally…: the folder has to be on the base branch with nothing uncommitted; the base branch is brought up to date from the server (fast-forward only), the pull request is fetched (refs/pull/N/head) and merged into it, and the files that conflict open in tabs in source mode with git's markers. Every conflict is colored by side (current in green with a “Current Change” label, incoming in blue with an “Incoming Change” label) with Accept Current Change, , and above it (one undo step; the same works in any file that has markers); opens a three-pane merge view of the selected conflict, including unsaved edits: Incoming on the left, Current on the right, and an editable Result below, with line numbers and highlighted words. Choose either side or both in either order, or edit the result, then press to replace only that conflict as one undo step. Closing the comparison discards the preview; a changed document must be compared again before applying. In a narrow window the source panes stack; to mix the sides, edit the text and delete the marker lines. (on the banner of the pull request) refuses while a marker is left, commits the merge, pushes the base branch, and records the pull request as merged on the server (which needs the repository to allow manually merged pull requests, and says so when it does not); undoes it.

The AI agent (chat and actions with approval)

• A panel on the right side (Ctrl+Shift+A or the Assistant button (the sparkles) in the header) to work with an agent based on a DeepSeek model (ask, request a plan, or request changes) (deepseek-flash or deepseek-v4-pro, chosen in the panel settings; the Deep thinking checkbox turns on a thinking mode that is more thorough but slower and more expensive). Answers stream as they are made and are shown with Markdown formatting. While the agent works, a status card shows its current step with a clock (the send button becomes a red Stop); afterwards the card shrinks to the number of lookups and the duration, and opens into the context sent, every lookup, and the thinking process of the model. Under a finished answer are Copy, Insert into note, Retry, and Log; a stopped or failed turn can be retried from the card. The assistant browses documents and proposes changes through a diff window; the user chooses Apply or Reject
• The context is assembled automatically from the workspace: the open documents (the editor contents, including unsaved ones; if too long, the part around the cursor), the selected text, the cursor position, a map of all the Markdown files in the opened folder (name, word count, headings), and the most relevant excerpts of other files (searched from the question, the selection, and the two previous questions). @filename in a message (optional) attaches a whole file right in the first message, so the model does not need a browsing round to read it; even without it the model searches and reads other files by itself through tools. The Context button below the panel details what will be sent together with its estimated tokens and has three switches (the active document, the selection, other files)
• The agent browses the workspace by itself (function calling). The initial context only holds the parts that are chosen automatically, so the model is also given read-only tools: list_files (which also shows the layout of a structured document), search_documents (a topic), search_text (exact text, e.g. a name, a date, or a number), read_file (the contents of a file by line range), describe_schema (the layout, fields, select options, defaults, and groups of a document with layout:), and query_notes (filter, sort, or count the notes of those documents by their fields, e.g. everything due before a date, or the number of notes per status). For a question like "is there a meeting decision that has not made it into the launch plan?", the model searches for every occurrence of the topic by itself, reads the surrounding parts, and then answers with quotes of the file and the line number. Every lookup is shown as a small line above the answer (e.g. ). The tools use the editor contents for open documents, only read Markdown files in the opened folder, and follow the switch: turned off, there are no tools at all

Other

• Find text, undo/redo, the word and character count, the cursor position
• Export to HTML with the CSS included. Images and links keep their original URL/path; Mermaid/DBML diagrams need the internet to load Mermaid from a CDN
• Autosave (the ☰ menu → Autosave, on by default): a document that already has a file is saved automatically 1 second after you stop typing (the write to disk runs in the background, so it does not hold up typing), and is saved without asking when closing, making a new document, or opening another file. A document that has never been saved still needs Ctrl+S
• A warning before closing, making a new document, or opening another file if there are unsaved changes (when autosave is off or the document does not have a file yet)

Shortcuts

On macOS, Ctrl in the table is ⌘.

Shortcut	Function
Ctrl+N / Ctrl+O	New document / open a file (both in a new tab)
Ctrl+W	Close the tab
Alt+Home	Home
Ctrl+Alt+J	Today's journal
Ctrl+Shift+J	Add to the journal (quick capture)
Ctrl+Tab / Ctrl+Shift+Tab or Ctrl+PgDn / Ctrl+PgUp	Next / previous tab
Ctrl+Shift+O	Open a folder
Ctrl+S / Ctrl+Shift+S	Save / save as
Ctrl+Shift+E	Export HTML
Ctrl+F / Ctrl+H	Find / find and replace (in a CSV table: in its cells)
Ctrl+Shift+F / Ctrl+Shift+H	Search / replace in all notes (the Search tab)
Ctrl+R / F5	Reload, in an HTML page tab
Ctrl+Z / Ctrl+Shift+Z or Ctrl+Y	Undo / redo (also for changes on a kanban board)
Ctrl+Shift+B	Kanban board or inbox: switch between the board/inbox view and the text
Ctrl+Q	Quit
Ctrl+B	Bold
Ctrl+I	Italic
Ctrl+Shift+X or Alt+Shift+5	Strikethrough
Ctrl+Alt+H	Highlight
Ctrl+`	Inline code
Ctrl+K	Link
Ctrl+Shift+I	Insert an image
Ctrl+Shift+K	Insert a code block
Ctrl+T	Insert a table
Tab / Shift+Tab	Move between cells (inside a table)
Enter	Move to the next row (inside a table)
Ctrl+Shift+T	Tidy up the table
Ctrl+1 … Ctrl+6	Heading 1–6
Ctrl+0	Back to a paragraph
Ctrl+Shift+Q	Quote
Ctrl+Shift+] / Ctrl+Shift+[	Bulleted list / numbered list
Ctrl+Shift+L	To-do list
Ctrl+Shift+↑ / ↓	Move the block at the cursor up / down

Tests

npm test

runs both suites below. The Electron tests need a display; on Linux npm run test:electron starts Xvfb (sudo apt install xvfb xauth), and npm run test:electron:run runs them on the display you have. CI runs both suites on Linux, macOS, and Windows for every pull request (.github/workflows/ci.yml); a pull request is merged only when all of them pass.

The core's tests (npm run test:core:node, about 830) are TypeScript without a framework (tests/core/framework.ts), bundled by Vite (vite.node.config.ts) and run on Node. They test the Markdown module, the agent, the forge, git, the orchestrator and the daemon client, and the application layer (AppSession with recording views), and they drive ProtocolServer with a scripted frontend over an in-memory line (tests/unit/protocol.ts), so what the window is told and what it may ask is tested without a window. They reach the runtime only through the platform port and a test host (tests/core/host.ts), wait for what they expect (until(), within()) rather than a fixed time, and use a temporary folder for settings, data, and the Trash.

The Electron tests (npm run test:electron) launch the real app (main process, core, and renderer) with Playwright and use it as a person would: the editor (smoke.mjs, editor.mjs, the visual editor in visual.mjs, the split editor in panes.mjs, and the sidebar in sidebar.mjs), the sample document and a hunt for crashes that compares what the editor draws after random edits with a fresh tab (robust.mjs), the structured views (structured.mjs), the adaptive layout (layout.mjs), the Assistant and the journal (assistant.mjs), the History tab and pull requests (git.mjs), agents and their worktrees (harness.mjs), the keyring through safeStorage (secrets.mjs), and the Editor Inspector and its checks (inspector.mjs). The model, the forge, and the agent are scripted fakes the core loads in place of the real ones (MARKWORK_TEST_MODEL, MARKWORK_TEST_FORGE, MARKWORK_TEST_HARNESS), so no test reaches the network. Each test file gets its own settings and data folder (tests/electron/support.mjs).

The sample files

tests/samples/all-formats.md holds all the supported formats together with the tricky cases: nested emphasis, escapes, URLs with underscores, emoji and non-Latin text, a table without pipes at the edges, a four-backtick code block, and unclosed emphasis. tests/electron/robust.mjs checks how it is styled and exported; open it to look at it yourself:

npm start -- tests/samples/all-formats.md

The other samples show the board and list layouts with typed fields, and a test keeps them valid (the layout is recognized, the schema reads without problems, every value fits its field, and saving changes nothing): kanban-board.md, inbox.md, reading-list.md, sprint-table.md, calendar.md, timeline.md, gallery.md, chart.md, and board-by-field.md. If you add a new format, add its example to all-formats.md too.

Architecture

Markwork is two programs talking over a wire: the core, which is the whole application (documents, views, the Assistant, git, agents) in plain TypeScript, and the window, which draws what the core tells it and reports what the user did.

┌ Electron main process (electron/main.ts) ─────────────────────────────────────────────┐
│  the window, file dialogs, the app:// and mwhtml:// schemes, the keychain (safeStorage) │
└───────┬─────────────────────────────────────────────────────────────┬─────────────────┘
        │ MessageChannel: the app protocol (docs/design/protocol.md)  │
┌───────▼───────────────────────────────┐            ┌────────────────▼────────────────────┐
│ core: a utility process               │  notices ► │ renderer: the page                  │
│ (electron/core.ts)                    │ ◄ actions, │ (electron/renderer/)                │
│ ProtocolServer → AppSession (src/app) │   asks     │ React, CodeMirror 6, the editor's   │
│ on the Node platform (src/platform)   │            │ own copy of the text                │
└───────────────────────────────────────┘            └─────────────────────────────────────┘

• The text lives in the editor. The renderer's CodeMirror holds the document; the core keeps a replica of it (app/protocol/replica.ts) from the changes the window sends, and writes back through the same changes. A write of the core that meets typing on its way is made again from the newer text, so neither is lost (protocol.md, section 5).
• The window decides nothing. It gets plain data (view.* notices), reports what happened (act.*), and answers questions (ask.*). What a file, a card, or a change is, and whether an action is allowed, is the core's: a path, a token, or a choice the window sends back is checked against what the core offered (stale otherwise).
• The core runs on Node and reaches the runtime only through the platform port (src/platform/index.ts: files, paths, processes, HTTP, the keyring, settings, translations, idle work). src/platform/node/ implements it; the tests swap in a fake with setPlatform().

Folder structure

electron/
  main.ts                 the main process: the window, the core's utility process, dialogs, the URL schemes, safeStorage
  core.ts                 the core's entry: the Node platform, ProtocolServer, and the test fakes
  preload.ts              what the page may call in the main process
  updater.ts              updates of the packaged app (electron-updater)
  renderer/               the page: client.ts (the protocol client and the store), App.tsx and its components,
                          editor.ts (CodeMirror and the decorations), and the views of every feature
src/
  app/                    the application layer: AppSession and its controllers (documents, views, notes, the
                          journal, Home, Programs, search, the Assistant, history, collaboration, harness, review,
                          preferences)
    protocol/             the app protocol: messages, the wire, the server and its handlers per controller, the replica
  markdown/               string → data: the parser, inline formats, tables, boards and their layouts, fields, HTML
                          export, diagrams, CSV, search, paths
  agent/                  the Assistant (context, the DeepSeek client, tools, proposals, plans, the log) and the
                          external harness (prompts, the pi stream reader, the run queue, worktrees, review)
    daemon/               the markworkd client (protocol, connection, socket and SSH links)
  forge/                  Forgejo and Gitea: pull requests, sending changes, resolving conflicts
  platform/               the port to the runtime (index.ts) and its Node implementation (node/)
  orchestrator/           index.ts runs harness processes for app/harness.ts; daemon.ts through markworkd; hub.ts connects per machine
  base/                   settings, files, fileops, workspace, git, gitlog, credentials, i18n, …   base modules
tests/
  unit/                   the core's tests, one file per module
  core/                   core-tests.ts lists them, run-core-node.ts runs them; the framework, fixtures, and test host
  electron/               the app's tests with Playwright; support.mjs is what they share
  live/                   live tests against real services
  bench/                  benchmarks and their baseline
  samples/                sample documents
scripts/
  electron-build.mjs      the build: main, core, preload, and renderer with Vite; the translations
  layers.mjs              the layer rules and the complexity limit (run by build and typecheck)
  ui.mjs                  the rules of docs/design/ui.md (run by typecheck and test:core:node)
  capture.mjs, capture/   the screenshots of docs/assets/ and their scripted fakes
  forgejo.sh, pot.sh, make-icon.cjs
resources/                the app icon and the packaging files electron-builder reads
markworkd/                the agent daemon (Go)
docs/                     the site (index.html, docs/) and the design notes (design/)

Build

scripts/electron-build.mjs bundles four things with Vite: the main process and the core as ES modules for Node, the preload as CommonJS (a sandboxed preload cannot be an ES module), and the renderer as one script next to its HTML and CSS. mermaid.min.js is copied next to the renderer and loaded with the first diagram, and the translations are compiled into dist-electron/locale/. The types are checked first (npm run typecheck): Vite turns TypeScript into JavaScript without checking it. Relative imports between TypeScript modules omit the file extension ('./tags'); Vite resolves and bundles them for both the application and the Node tests. Actual JavaScript assets and runtime build output keep their extensions.

Layers and the direction of dependencies

electron/renderer  ──(types, pure modules)──►  src/markdown, src/app/protocol messages, src/app/commands
electron/core.ts   ──►  src/app/protocol (ProtocolServer)  ──►  src/app (AppSession, controllers)
                                                                     │
                       src/agent, src/forge, src/orchestrator, src/base (the core)
                                                                     │
                                         src/markdown (pure)   src/platform/index.ts (the port)

• markdown/ holds only string → data functions and imports nothing outside it, so it is the easiest to study and test.
• The core (markdown/, agent/, forge/, orchestrator/, base/) imports only the core and reaches the runtime through platform(). It typechecks against the few web-standard globals it uses (src/globals.d.ts: timers, TextEncoder, TextDecoder), not Node's types, and only platform/node/ may import node: modules.
• app/ is the application layer: controllers that reach the screen through interfaces they declare (a view that gets plain data and reports with on* callbacks, dialogs that answer with a value or a Promise). AppSession builds and owns them and connects them to each other; the frontend hands it one AppFrontend, which app/protocol/frontend.ts implements by sending messages. Commands are data (app/commands.ts): an id, a label, default keys in a neutral notation (Ctrl+Shift+P, Ctrl is ⌘ on macOS), where they apply, and where they run.
• The renderer is a view. From src/ it takes the pure Markdown modules, the protocol's messages, wire, mirror, and change math, the command list, and a few pure agent modules for the log; other modules only for their types, and nothing that reaches the runtime.
• src/ imports nothing outside src/: electron/ uses it, never the other way round.
• The rules are checked. scripts/layers.mjs runs in npm run build and npm run typecheck and fails on a forbidden import. It also parses src/ and scripts/ and fails on a function whose cyclomatic complexity (counted like ESLint's complexity rule) is above 15. scripts/ui.mjs runs in npm run typecheck and npm run test:core:node and holds the window's code to : no color values, raw controls, text sizes in px, constant inline styles, icon buttons that are not , radii in px, spacing of 10px or 14px, on buttons with text, or classes of the old set. Every file is held to them; a line that breaks one on purpose says why with .

The editor

The renderer's editor (electron/renderer/lib/editor.ts) is CodeMirror 6 with Markwork's own parser. The parse (markdown/highlight.ts, HighlightCache) is kept per document and reuses every line that did not change; from it one decoration field builds, in the same transaction as the edit (a selection change keeps the drawing when nothing the drawing takes from the selection changed: selectionKey, which covers the diagrams and the markers spanning lines it touches in the visual editor, the selection's lines in the live view, and focus mode's paragraph):

• the style of each part (cm-md-bold, cm-md-h2-line, …) and the markers to hide, outside the lines of the cursor or the selection (source mode hides none); in the visual editor a one-line marker is hidden on those lines too, and a list item's - and [ ] are drawn as a bullet and a checkbox;
• tables as a grid widget while the cursor is elsewhere (tables.ts; a click on a cell opens the raw text there);
• code blocks as a box with colors from CodeMirror's language data, loaded the first time a language is used (codecolor.ts), and Mermaid and DBML blocks as diagrams (diagrams.ts; markdown/dbml.ts turns DBML into a Mermaid ER diagram);
• pictures under their line (images.ts), loaded from the document's folder through the main process's app:// scheme;
• git conflict markers with Accept Current Change / Accept Incoming Change / Accept Both Changes and a three-pane Compare Changes merge dialog (conflicts.ts, app/documents.ts, renderer/components/ConflictCompare.tsx), and the dimming of focus mode.

The visual editor's own behaviour is visual.ts: the drawing tells it what it hides and where each line's prefix ends, and from that it keeps the cursor out of a prefix (a transaction filter), makes the hidden ranges atomic, and turns Backspace and Delete into edits of the visible text; it also holds the selection menu (a tooltip) and the / menu (an autocompletion source), which run the window's commands by name. In the visual editor a table's grid (tables.ts) stays and its cells are edited in place: the cell being edited holds its Markdown in a box, and each keystroke changes that one cell of the text (setCellText in markdown/table.ts), so the grid is patched rather than drawn again and keeps its focus. The block handle (blockhandle.ts) draws a "+" and a grip beside the block under the pointer; what a block is and how one moves is markdown/blocks.ts. The toolbar (components/FormatBar.tsx) runs the same commands and shows what formatAt in editor.ts reads from the parse at the cursor.

The Editor Inspector (renderer/lib/inspect/, components/Inspector.tsx; the design is docs/design/debugger.md) finds bugs of the visual editor. recorder.ts keeps each tab's last 500 transactions with the key, click, or paste that made each, in every build, as changes and not copies of the text. From it Help → Report a Problem with the Editor… (components/ReportProblem.tsx, inspect/report.ts; also offered for a few seconds after an Undo of something just typed) saves a repro of what the editor just did in the app's data folder (reports/, written by the main process; nothing is sent), its text blurred unless the person says otherwise (markdown/blur.ts: Latin letters x, digits 0, the syntax, emoji, and other scripts kept, every offset the same) and with a picture of the editor taken while it shows the blurred text. In dev mode (--inspect-editor or MARKWORK_DEV=1) checks.ts runs the rules of the visual editor on each of them when the editor is idle (Backspace removes what is seen, the cursor stays out of a prefix, typing changes the text at the cursor, only the parser's markers are hidden and each hidden mark keeps its other half, undo gives back the text before an edit, a drawing kept over a cursor move equals a new one, no two replaced ranges cross, a table keeps its columns, drawing stays under 8 ms), and Ctrl+Alt+I opens a dock under the editor: the text as the file holds it with what is hidden, drawn as a widget, or a prefix marked and offsets in the gutter (a piece under the pointer is boxed in the editor, and the place under the pointer in the editor is lit there); the transactions with their diff and what the checks found; and the decorations around the cursor. Paused shows all of it as any recorded transaction left it, stepped back and forward. In dev mode a transaction also says which command of the visual editor took its key (traced() around the keys of visual.ts and blockselect.ts, handling() in the table grid of tables.ts) and what that command decided (trace()), in the dock and in npm run editor -- press --explain. The dock's Replay & test tab opens a repro (a person's report too) or takes the recording shown, plays it step by step as real input sent by the main process, and saves it or keeps it as a test in tests/electron/repros/.

The editing commands (bold, links, headings, lists, tables, Enter and Tab) are markdown/editcommands.ts: text and a selection in, the changes and the new selection out, shared by every frontend. Positions on the wire are code points (an emoji is one), converted to CodeMirror's UTF-16 units at the editor's edge (markdown/offsets.ts).

Read-only code (app/documents.ts, renderer/components/CodePage.tsx)

The file tree lists names without reading file contents. AppSession.openFile() preserves the Markdown, CSV, HTML, and image routes; other files go to DocumentController.openCode(), which checks regular-file kind, size, and UTF-8 text before opening a Page snapshot. The protocol sends page.open with kind code and the text, then view.page preserves that kind. CodePage uses a separate read-only CodeMirror with lazy language support, not the Markdown editor and its write callbacks. Code pages never join the document set used by autosave and assistant manuscript context. Tests: tests/unit/filescontroller.ts, tests/unit/protocol.ts, and tests/electron/code.mjs.

HTML pages (markdown/htmlview.ts, electron/main.ts)

A page from the Files tab runs its JavaScript, so what it may reach is limited from the outside: it is served under a private scheme (mwhtml://v<id>/<path>, only from the folder it was opened from; a path or a link that leaves it is refused), every response carries a Content-Security-Policy that allows nothing but that scheme, data:, and blob:, the frame may not navigate anywhere else, and a link to the web opens in the browser.

How the kanban board works (markdown/kanban.ts, app/views.ts, renderer/components/Board.tsx)

Format. A board is an ordinary Markdown file:

---
layout: board
---

## Plan

- [ ] Write the report #important [due:: 2026-10-20]
  card note (an indented line)
- [ ] Send the invitations

## Done

- [x] Book the venue

The frontmatter layout: board (case-insensitive, may be quoted) marks a document as a board, and layout: list as a list of notes (an inbox, a reading list); the marker is looked for in the first 40 lines before the closing frontmatter delimiter (markdown/layout.ts). A document without a layout: line, or with any other value, is opened as ordinary text. Existing frontmatter is kept as it is when saving. A ## heading is a list, a list item is a card ([x] = done, no box = an ordinary item), and lines indented under a card are its note. Anything not recognized (a board title at the top, ordinary lines inside a list such as **Complete** or ***, and the %% kanban:settings block at the end) is kept as it is, so files from Obsidian are not broken.

Data flow. The document text is the single source of truth:

document text ──parseBoard()──► board (ViewController in the core) ──view.notes──► Board.tsx draws it
      ▲                                                                              │ a NoteEdit (move, add, edit, …)
      └──── one write to the text (one undo step) ◄── serializeBoard() ◄── applied ◄──┘

1. When a document with layout: is shown, the core's ViewController (app/views.ts) reads its text with parseBoard() and sends the board to the window (view.notes).
2. The window never sends a board back. It reports what the user did as a NoteEdit (markdown/noteedit.ts): move this card there, check it, edit it. The core applies it to the board it holds, writes the result with serializeBoard(), and changes the text through the editor in one undo step, so a write from an agent that arrived in between is not lost.
3. Undo and redo change the text. A change that does not come from the board is noticed when the text no longer matches what the board last wrote, and the board is read again.
4. All operations on the model (addCard, moveCard, moveColumn, …) are pure and do not change the original board, so they are easy to test. moveCard uses the card's final position in the target list, so moving down within the same list needs no adjustment.

The markworkd daemon (markworkd/, agent/daemon/, orchestrator/daemon.ts)

markworkd/ is a separate Go program (standard library only) that owns agent processes so they keep running when Markwork is closed, or on another machine. The design and wire protocol are in docs/design/markworkd.md. On the Markwork side, agent/daemon/ is the client (pure protocol and client, a connection that reconnects and resumes without repeating or losing a record, and links over a Unix socket or the stdio of ssh host markworkd bridge), and orchestrator/daemon.ts turns a daemon run into the HarnessProcess the orchestrator already drives, so the pi reader, the queue, and the board logic are unchanged. Orchestrator.dispose() lets go of such a process instead of stopping it, when the user chooses to keep it running. It is chosen in Preferences → Agents (this computer, or an SSH machine); orchestrator/hub.ts holds the connections, window/harness.ts finds the runs of the board's cards again at startup, and Home shows whether the machine answers. A spawn may say how many runs of its lane go at once (lane_slots), which is how cards with their own worktrees run side by side; daemonGit() runs git as short runs in no lane, so the worktrees of a machine are made and read on that machine.

How the Programs check works (app/programs.ts, renderer/components/Programs.tsx)

ProgramsController decides which programs are needed from harness-machine and looks for each where it will run. On this computer it uses processes.findProgram() (the same lookup that starts pi: PATH, then the per-user bin folders) and runs --version (markworkd version) for the version line; markworkd counts as installed also when it is off the PATH but its socket answers. On an SSH machine it asks the daemon's info for markworkd's version, and runs pi --version and git --version as short runs through the daemon (daemonRun() in orchestrator/daemon.ts, which daemonGit() also uses) in one of the project folders chosen for that machine, since the daemon runs nothing outside its roots; the daemon's refusal ("is not in the configured programs") becomes Not allowed by markworkd, and no folder or no answer within 10 seconds becomes Unknown, which is never a warning. The check runs when the window opens, on Check again, when Preferences → Agents changes, and when the window comes back while something needed is missing. Home gets setup() (only the needed programs that are missing), the Programs tab gets data() (view.programs), and the sidebar gets the count (programs.missing). Hide stores the list it hid (setup-hidden), so the section comes back when the list changes. The install commands and the pages they come from are data in programs.ts; the page draws them and copies a command itself.

How the harness orchestrator works (agent/harness.ts, orchestrator/index.ts)

---
layout: board
project: web-ecommerce          ← the board's default project
---

## Plan
- [ ] Checkout with QRIS #feature [agent:: pi]  ← the harness assigned
- [ ] Test the cart #project/shop-admin [agent:: pi]  ← the project tag wins over the frontmatter

card + [[note]] ──buildPrompt()──► pi --mode rpc --name <title> [--session <id>]   (cwd = project folder)
  ▲                         stdin ▲            │ stdout: JSONL per line
  │   get_state, prompt, steer,  │            ▼
  │   extension_ui_response ─────┘   PiReader ──► AgentTrace (pi log) + ask / settled signals
  │                                             │
  │                         ask → ⏸ waiting ──► Answer pi… (dialog) ──► the answer goes through stdin
  │                         settled + "?" → ⏸ waiting; other settled → close stdin → pi exits
  └── updateBoard(): move to In Progress / Review, a ↳ result note

1. A project, not a path. The Markdown contents only mention the name of a project; the name is mapped to a folder in settings.projects, which is only filled in through the folder chooser dialog. So a card or an agent cannot point the harness to an arbitrary folder. checkProjectFolder() rejects Markwork's work folder, its contents, its parents, the root, and relative paths, because the harness writes freely without a review window.
2. Related notes. cardWikiLinks() collects the [[links]] in the card's title and note (at most 10, without duplicates, inline code skipped). OrchestratorHost.linkedNotes() in the window looks them up with resolveWikiLink() in the work folder (the same rules as Ctrl+click), reads their contents from the editor if open or from disk, and takes only the #heading section with noteSection(). buildPrompt() copies them into the Related notes from Markwork section inside a fenced code block longer than any backtick run in the contents, at most 8,000 characters per note and 24,000 in total; links that are not found are mentioned as they are. The harness is not given the path of the work folder, only the contents of the notes, because the work folder is deliberately out of its reach.
3. Running. Orchestrator.start() adds [agent:: pi] if it is not there yet, puts the run into the RunQueue, and then launch() looks for the program (PATH, then ~/.local/bin and similar, because apps launched from the desktop menu often do not inherit the shell's PATH) and starts it through spawnHarness() in pi's RPC mode. The process is spoken to through platform().processes.spawn() in pi's JSONL framing: one command or event per line, separated by LF. Once the process is running, Markwork sends get_state (the session id) and then prompt.
4. The queue. Runs take turns per lane, the project folder: at most slots of them are working or waiting at a time (a run waiting for an answer still holds its process), and the others are queued in order and start when a slot frees. A run in the folder itself has one slot, so it works alone; cards with their own worktrees have the project's "cards at the same time" (2 by default). Cancelling a queued run does not give anyone a turn.
5. Waiting for an answer. PiReader.line() returns signals. An extension_ui_request with select/confirm// becomes a and the run gets the status ; the answer is sent as an with the same id (, , or ). If a request has a , pi answers by itself with a default value after it, and Markwork returns the status to at the same moment. is only recorded in the log; / are ignored (TUI only). On , an answer that ends in () makes the run wait; a reply is sent as the next to the same process ( discards the old turn state), while closes stdin. Other answers close stdin immediately, and pi exits in an orderly way. sends ; after finishing runs pi again with and the same log.

How the assistant works (agent/*, app/assistant.ts, renderer/components/Chat.tsx)

The model only knows what is sent to it, so the quality of the answers is determined by agent/context.ts. Every question builds a fresh context (the manuscript may change between questions) within a token budget (DEFAULT_BUDGET = 48,000 tokens; 1 token ≈ 3 characters, deliberately wasteful). The context is split in two so that DeepSeek's prefix cache is used:

system message  (stable)   instructions + <project_map> + <active_document>     ← the same across questions, so the prefix is cached
history         (trimmed)  earlier questions and answers, without their old context
user message    (changes)  <extra_context> + the question                ← selection, cursor, @attachments, relevant excerpts

Every manuscript line that is sent is numbered at the front (12│ text, the real number in its file, also in the window around the cursor and in excerpts), the same as the output of read_file. Without numbers, the model guesses locations and often misses; the instructions forbid quoting those numbers as part of the manuscript. The live test (npm run test:live) checks that every file.md:N citation in an answer points to the right line.

The priority order and budget limits: the text selection (8%), the active document (40%; if it is longer, a window of lines around the cursor is taken and the rest is searched through excerpts), @mention files (20% per file), the project map (6%; more compact when there are many files), and then relevant excerpts (40%, at most 10). Excerpts come from splitting each file per heading (long sections are split at blank lines) and are ranked with BM25 over the keywords of the question (weight 1), the selection (0.5), and the two previous questions (0.4); common words are dropped and suffixes such as Indonesian -nya/-kan are stripped roughly. There are no embeddings, so there is no model download and no manuscript is sent just for searching. The history is limited to 25% of the budget, dropped in pairs from the oldest.

ChatSession.ask() runs the model ↔ tools loop, at most 10 rounds; the last round has no tools. The four read tools have a limit of 6,000 tokens per result and the total of read results equals the context budget. Single-change tools use onProposal; propose_batch uses onBatchProposal for one review of all the diffs. The Git tools use git in the handler (from ChatHost.git), counted in the same read budget. A batch produces one Change per file and rejects a batch that touches a file that is deleted/moved together with other actions, so each file can be applied or rejected on its own. A batch merges chained changes to the same file, checks all snapshots before writing, and tries to restore the files if a write fails. This is an in-process transaction, not a filesystem transaction that survives a power cut. Rollback failures are reported; changed contents and paths that go through a symlink are rejected.

For multi-step work, the model uses set_work and then verify_work. Verification re-reads the contents of the disk/buffer through the host (bypassing the cache) and checks required/forbidden text (per file, or across the whole folder with the file "*" to make sure old values do not remain in files that were not changed), cards in a given list and status, or the Markdown structure (markdown/lint.ts: the number of table cells, empty headings or ones that skip a level, unclosed code blocks, links to Markdown files that do not exist). The structure is compared with the contents before the work, so only problems that appear because of the change cause a failure; old problems are mentioned but left alone. For every changed file, verification automatically adds a structure check, makes sure files that were deleted/moved are really not at their old place, and requires at least one criterion from the model. The done status requires all steps to be done and the checks to pass. These checks prove concrete criteria, not the whole semantic consistency of a document; the quality of the criteria still depends on the model.

The journal stores a proposal before review and the decision after applying, including before/after snapshots. onState saves a checkpoint while the process is running if the save switch is on. Opening a conversation restores the plan, the journal, the Continue work button, and the button to view the history diff without re-applying. A proposal whose process was interrupted is checked against the actual contents: a result that matches the proposal is recognized as applied, an old result as an interruption, and a mixed result as a failure that needs to be inspected. A checkpoint restores the work; unsaved buffer changes still follow the editor's save rules.

The full history stays on disk. The model's context contains the latest turns and limited extractive excerpts from older turns; excerpts do not create new facts and can be cut off. The DeepSeek client retries connection failures, HTTP 429, and 5xx at most twice (300/900 ms pauses) only if no text or reasoning has been shown yet. Authentication failures are not retried. A stream that is cut off before [DONE] is treated as failed and does not run partial tool calls. Cancellation uses Cancellable (cancel.ts), including during the retry pause.

The deterministic evaluation in tests/unit/agentic.ts tests work through to a verified result, rejection, conflicts, incomplete verification, and recovery after failure; tests/unit/agentactions.ts tests the new edit tools, delete/move, extra kanban actions, change inversion, partial approval and notes, structure checks, and the Git tools (including a real git repository in a temporary folder). The GUI tests check batches, per-file checkboxes, notes, Undo (successful and rejected because the contents changed), moving open files, deleting to the Trash, and restoring the plan. The client tests use a local SSE server; all of them are part of npm test without a paid API. npm run test:live -- --agentic adds evaluation of a real model for approval, rejection, and conflicts, only on fixtures in a temporary folder (it uses API quota). npm run bench:agentic measures a 20-file batch, verification, a checkpoint along with its journal, and the history summary (median/p95/maximum; no network).

How tabs that are not documents work (app/documents.ts)

A tab is a Doc (a text, with an editor, a file, and changes to save) or a Page (app/document.ts: Home, or an HTML file). Home used to be a Doc with a home flag and an editor that nothing used, so the flag had to be checked wherever a document's text was touched (35 places). It is a page now, and Doc only describes documents.

1. One numbering, two lists. DocumentController keeps docs and pages, with ids from one counter, so the tab row can name either. shown is the page that is shown, or null when a document is. select(id), closeById(id), and switchTab() work on ids.
2. A document is always there. The rest of the application reads documents.active, so there is always one. While a page is shown it is the last active document (what the page leaves behind: search and the Assistant keep pointing at it). When only pages are open, the one empty document is parked: it has no tab (listTab(id, false)), and it comes back when a file is opened or a new document made.
3. Pages come and go. Opening a page retires the empty document's tab (parks it if it is the only one). Closing the last document shows the page that is open, or Home if it is switched on. Closing a page shows its neighbor in the tab row; the last tab stays if it is Home; an HTML page that was the last tab gives way to Home. A folder switch closes the HTML pages that lie outside the new folder.
4. What follows a page. AppSession.pageActivated() does for a page what activated() does for a document: the frontend's tab row and content follow, the outline is cleared, the view is chosen ('home' or 'html' in ViewController, pageMode = a tab that is not a document, which turns the text and document actions off), the title is a page title (DocumentTitle.page), and the tree and history follow shownFile() (an HTML page's file, nothing for Home).
5. Restoring. rememberTabs() records file tabs and Home in the tab row's order; an HTML page is not recorded. tests/unit/pagetabs.ts runs all of this against a fake tab row (tabRow() in tests/unit/appsession.ts).

Reading order

1. src/markdown/syntax.ts → inline.ts → highlight.ts → html.ts: the Markdown rules
2. src/markdown/kanban.ts, fields.ts, layout.ts: boards and the other layouts as data
3. src/app/session.ts and the controllers it builds (documents.ts, views.ts, …): what the application does
4. docs/design/protocol.md, then src/app/protocol/: how the window is told and asked
5. electron/renderer/lib/client.ts, App.tsx, and editor.ts: the window
6. tests/unit/protocol.ts and tests/electron/*.mjs: examples of every part in use

Adding a feature

An example of adding a new format, such as ^superscript^:

1. Add a pattern to EMPHASIS (src/markdown/syntax.ts), for example ['sup', /(\^)(?=\S)([\s\S]*?\S)\^/g, 1], and add 'sup' to the EmphasisTag type in the same file
2. Give cm-md-sup a style in electron/renderer/styles/theme.css
3. Add its conversion in emphHtml() (src/markdown/html.ts)
4. If a command is needed, add it to COMMANDS in src/app/commands.ts (wrap('sup', _('Superscript'), ['Ctrl+Shift+p'], '^')); the window takes its keys and its place in the palette from there
5. Add an example to tests/samples/all-formats.md, a parsing and export test in tests/unit/, and a step in tests/electron/editor.mjs

Settings

The settings are a JSON file, markwork-electron/settings.json in the config folder (~/.config on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows; XDG_CONFIG_HOME wins on every system when it is set). Its keys, types, and defaults are those of src/base/settingskeys.ts, and a value that does not fit its key is read as the default: the color theme (color-scheme: follow the system, light, dark), the side panel and its page, the work folder, the tabs of the last session, Home, the Assistant (model, thinking mode, saving conversations), the visual editor, focus, typewriter, autosave, the projects and machines of the agents, and the window size. Keys and tokens are never written there.

Limitations

• The assistant: DeepSeek only, chat with approved change proposals (there is no automatic contradiction check yet; contradictions can be asked about in the chat and the model traces them itself). Change proposals: only Markdown files (not folders) in the work folder, with a single action or a batch of at most 20 actions; moving a file does not update links in other files (the agent has to propose that separately), and Undo restores a deleted file from the journal snapshot, not from the Trash; the Git tools only read what has been committed; board serialization can tidy blank space elsewhere, and that shows up as it is in the diff; the plan, decision journal, diff, and verification are saved if the save switch is on. The details of the full context, the full read results, the thinking process, and token usage are not saved. Journal snapshots can make a conversation file large; checkpoints are still written synchronously. The history cannot be searched from the panel (search through its file), and a conversation moved to another folder midway is continued as a new file in the destination folder. Search (search_documents and the automatic excerpts) is keyword-based (BM25), not meaning-based, so the quality of browsing depends on the keywords the model picks; search_text looks for exact text and does not recognize synonyms or different spellings. Browsing costs model rounds, so broad questions are slower and use more tokens. The model name follows the current DeepSeek documentation; if the API rejects a model name, the error is shown in the panel. The token estimate is rough (3 characters per token). Answers are shown as formatted text, not full Markdown (no tables and images)
• Tabs: only file tabs are restored (documents that were never saved are not), and the list is recorded when the window is closed, so if the app stops suddenly the previous session is what is restored. With several windows, the last window closed decides. The undo history, the exact scroll position, and the text/board view are not restored (scrolling follows the cursor), and all tabs are fully opened when the app starts. The pane layout of the split editor is not restored, and all tabs share a single kanban board view (the board scroll position is lost when switching tabs). The command line only opens a single file or folder
• The journal: the journal/ folder and the template are fixed. Activity is only recorded while Markwork is open for the work folder that is open, and merged when the journal is opened through Ctrl+Alt+J or Home (not from the file tree). Cards moved through the board text or outside Markwork are not recorded; an amended commit can appear twice; Undoing an agent change is recorded as an agent change too
• Home: deadlines and the inbox are only read from the work folder that is currently open (at most 300 Markdown files, like the assistant context), not from code folders in projects. Clicking a task opens its board without highlighting the card. The agent status only exists while the app is open. Recent files are recorded by Markwork itself in its settings, so they do not appear in other apps' recent lists