Repository navigation
KeelBot
Open the Code page and press ⌘I (or the KeelBot button at the bottom of the left bar), or open KeelBot in the
menu. In the terminal, KeelBot is the main view of keel TUI. Ask about the project in plain
words. KeelBot reads the code, the knowledge pages, the map and the code graph, and every answer links to the lines
(file:line opens the editor there). Answers stream in as they are written (Claude CLI, API keys; Codex, OpenCode and
Copilot send the answer when it is done).
KeelBot also knows keel itself: the workflows this project can run and its flows, the step a flow is at and its newest jobs. It gives you buttons; nothing starts, stops or is saved until you press one.
-
Which workflow? Ask "how do I add a weekly report page?": KeelBot names the workflow that fits and why, and gives a Start the flow button with a title (you can change it) and the request every agent gets.
-
About a running flow: "why does Euro prices wait?", "how far is the fix?", "what did it cost?", "what did the doctor find?".
-
Act on flows (you press): stop flows, approve or send back a gate, change a flow's run mode, or answer a flow's question (KeelBot proposes the answer as a button).
-
A workflow, rule pack, agent, skill or stack of your own: "make a workflow that runs the linters and the tests, then stops for a look". KeelBot writes it with only the steps the task needs; keel checks it on the spot and shows what it runs. Save it, or Ask KeelBot to fix it when the check finds a problem.
-
It asks you to choose with a question card, never as a prose "A or B?".
-
More room: hide keel's menu with ‹ next to the bell (or ⌘; ☰ brings it back); drag KeelBot's left edge to make it wider; Focus (in the status bar at the bottom, or ⇧⌘) hides everything but the code; ⤢ in the panel (or KeelBot in the menu) opens KeelBot alone on its own page, where a
file:linelink opens the Code page at that line. The status bar also shows the code graph index and ↻ Rebuild. -
Point at things: select lines and press Ask (or ⌘I); type
@for a file, a symbol or a criterion of the running flow; the open file always goes along. -
Commands: type
/—/explain,/where,/review,/plan,/gate(what the waiting gate asks),/test. A project can add its own in.keel/plugins/<name>/plugin.yml(seeplugins/keelbot/content/plugins/core/plugin.yml).
Four modes. The mode decides what KeelBot may change. Changing the mode keeps the chat, and KeelBot is told what changed.
| Mode | What KeelBot may do |
|---|---|
| Ask (default) | read only: no edit, no new file, no command that changes files or git, whatever the model. Asked to change something, it says Ask is read only and offers Edit (recommended), Side, or the exact command to run yourself |
| Edit (0.18.7) | change files and run commands in the project folder itself, with no flow |
| Fix | only while a flow waits at a gate: change things inside the rules of the flow's phase |
| Side | work in KeelBot's own copy of the project (a git worktree on its own branch); nothing touches your folder or a running flow |
- In every mode keel's always-on rules hold (no secrets, no
.git, no applied migration), and KeelBot never commits or pushes. Keep runs the checks and makes keel's commit of only KeelBot's files; Undo puts a file back. The panel lists every changed file with its diff. - In Fix mode Done runs the tests and lets keel commit only those files; if the tests fail, one click hands the failure back to KeelBot. In Side mode, after Keep: Make a task, Start a flow on the branch (a change flow writes the tests for it), or Throw away.
-
Permission cards: a command that changes something (
git checkout, a build, an install) waits for your OK in the panel, keel TUI or the Inbox: Allow once, Allowgit checkout *in this chat (the command's family), Deny, or Deny, and say why (KeelBot goes on from your reason). Commands that throw work away (git reset --hard,git checkout -- .,git restore,git clean,git stash drop,git branch -D,rm -r) always ask, with a warning; "in this chat" never covers them. When a flow works in the folder, the card says that switching branches changes its files. Esc on a card says no. - The failure rule (0.18.18): KeelBot never tries a failed command again unchanged. It says in one line why it failed (it quotes the error) and offers the ways forward as a card, the safe one first. Example: "check out main" with uncommitted work → stash, check out main, pull, stash pop (recommended) · commit them first · discard them · leave it · your own words. keel refuses an identical retry while nothing in the folder changed, also in the next turn. Every KeelBot button that fails offers Ask KeelBot to fix it.
- Chats: a chat lives in keel's backend, so it goes on in keel TUI, the dashboard or on another computer. Chats name themselves after the first answer (3–6 words); a name you give is kept. When a chat's context is above 85% before a turn, keel compacts it by itself: a summary of the chat in a fresh session (every message stays stored).
- Costs: each answer shows its tokens and time; the budget bar counts them. Claude and Codex continue their own session, so a follow-up question is cheap (the context stays cached).
- The model is the
helperagent's (Agents page); change it, and its thinking effort, for one chat in the panel.
From docs/GUIDE.md · All pages
keel v2
- Home
- How a flow works
- Flows in detail
- Web research
- Rules
- KeelBot
- keel TUI (keel2 tui)
- Thinking effort
- Plugins and the Marketplace
- Stacks
- Plugins: Database, Git and CI/CD
- Quality
- Inbox and run modes
- Usage and caps
- Tasks and Jira
- Logins
- Signing in
- Use keel from Claude Code or Claude Desktop (MCP)
- keel2 commands
- Where keel keeps its files (layouts)
- Native mode (no Docker)
- Docker mode
- Several project folders
- Git worktree projects
- Problems
- Folders in the container
- Without the install script
- Develop keel v2