2a97ec3e58
* docs: turn README into an index and move reference detail to docs/guide The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md. * docs: send user docs to topic guides and budget the root README The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003). * chore: remove unreferenced screenshots and finished plan notes pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them. * docs: route always-loaded AGENTS.md files to scoped guides * docs(agents): cut scoped guides to scope, verify, traps, decisions Each AGENTS.md keeps four kinds of content: the scope of the directory, the verification commands, traps a local test run does not show, and decisions the code cannot state. Values, field lists, function inventories, test names, issue numbers and history are deleted, because the code, the tests and git state them. Search and fetch providers share one community guide. Four guides with no remaining content are removed. The size check now allows 6 KiB per file (hard limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB). * style: format frontend guide table and guidance test imports --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
4.5 KiB
Terminal Workbench (TUI)
deerflow is a terminal-native workbench for people who live in the shell. It runs embedded over DeerFlowClient — no Gateway, frontend, nginx, or Docker required — while honoring the same config.yaml, checkpointer, skills, memory, MCP, and sandbox settings as the rest of DeerFlow.
Parallel synchronous stdio MCP calls use independent sessions on their own event
loops. They do not cancel each other's connections, but they do not share
server-side state; session reuse requires the same loop. See the
MCP session notes for details.
Manually managed event loops must drain pending session owners before closing;
the normal asyncio.run() path does this automatically.
uv pip install 'deerflow-harness[tui]' # optional 'textual' dependency
deerflow # launch the terminal UI (TTY required)
deerflow --tui-transparent # use the terminal's default background
deerflow --continue # resume the most recent thread
deerflow --resume THREAD # resume a thread by id
deerflow --print "summarize this repo" # headless one-shot answer to stdout
deerflow --json "hello" # headless newline-delimited StreamEvents; failure -> one {"type": "error"} record, exit 1
deerflow --recursion-limit 250 --print "task" # override the headless agent-loop limit
Headless --print and --json exit with status 1 when the run fails, including provider errors returned as fallback messages. --print still writes the fallback text to stdout; --json appends a terminal error record.
A keyboard-driven chat surface with a streaming transcript (Markdown-rendered answers), compact tool-activity cards, a / slash-command palette, display-only /clear, /goal goal management, /model and /threads pickers, input history, PageUp/PageDown transcript navigation, and Esc / Ctrl+C interrupt. The composer preserves line breaks and indentation in pasted code, stack traces, and multi-paragraph prompts; Enter sends the complete document. Transcript refreshes preserve your reading position after you scroll upward and resume following new output when you return to the bottom. /clear removes rows from the current terminal display without deleting the thread or its persisted conversation; /new and /clear ask you to wait during an active run instead of resetting in-flight display state. Sessions opened in the TUI also appear in the Web UI sidebar — it writes the shared thread store under the local default user, so terminal and web stay in sync without running the Gateway.
TUI slash commands accept Unicode whitespace before their arguments, including spaces, tabs, line breaks, and nonbreaking spaces. A separator closes the slash palette so Enter submits the composed text. Pasted skill tasks can start on the next line; their internal line breaks and indentation are preserved.
During an active run, /resume, /threads, and /switch ask you to wait before
switching conversations. An invalid /resume reference displays an error without
closing the TUI or changing the current conversation.
After an interrupt, late stream actions from the previous run cannot change the
next run's display or status, even when both prompts use the same conversation.
A tool call already in progress still finishes, so until it does a new prompt in
that conversation is held back with a notice instead of racing it; /new and
/resume stay available. Quitting waits for that step as well and closes the TUI
once it finishes; press Ctrl+C again to quit at once without saving it.
If a run cannot start, the TUI reports an error and returns to idle so you can retry.
A message that is held back or cannot start stays in the composer, so Enter resends it.
At the last composer row, Down leaves an unsent draft untouched unless you are
browsing input history; after recalling history, it moves forward to restore your
saved draft.
At the first composer row, Up also leaves the draft, cursor, and undo history
untouched when no input history is available.
Recalling identical history text or a saved draft also preserves the cursor and
undo history.
Thread visibility and title updates remain best-effort. If a database update times out, the TUI requests cancellation of the pending update; already committed writes are not rolled back.
See backend/docs/TUI.md for the full guide.