For developers · Orchestrator
Orchestrator chat
On this page
The human talks to the orchestrator in a chat that can see and steer the ledger.
Architecture#
- The chat runs on the agent picked in the settings (#425,
crates/core/src/orchestrator_chat/launch.rs): Claude Code in stream-json mode, or an ACP agent (Gemini CLI viagemini --experimental-acp, Codex via thecodex-acpadapter). ACP agents get the samegitoodo mcpserver (narrowed to the scope), the orchestrator instructions and the picked model; they cannot resume a Claude session. - For Claude Code the app starts the user's
claudein stream-json mode (--input-format stream-json --output-format stream-json --verbose) with--mcp-configpointing togitoodo mcp. - The session runs under the user's subscription.
ANTHROPIC_API_KEYandANTHROPIC_AUTH_TOKENare removed from the child environment; no API key is ever used. - Network access and tokens stay in the Rust core and the keychain. Tool results carry no tokens.
- Program path:
ChatConfig.program, else envGITOODO_CLAUDE, elseclaude(tests use a fake).
Tauri surface#
| Name | Kind | Meaning |
|---|---|---|
orchestrator_chat_start | command, resume?, scope? | start (replaces a running chat); returns ModelFallback or null, model per ai.models.chat as --model (#341) |
orchestrator_chat_send | command, text: string | one user message |
orchestrator_chat_stop | command | stop; no-op without a chat |
orchestrator-chat-event | event | payload is a ChatEvent, tagged by type |
ChatEvent types: started (session_id, model, tools), text, tool_use (id, name, input),
tool_result (id, text, is_error), turn_done (session_id, is_error, result, usage, cost_usd),
other (kind), malformed (line), ended (code). Unknown stream events become other.
scope is a ChatScope tagged by kind: all, repo (account, repo = owner/name) or
item (plus number); missing means all. The child runs gitoodo mcp --scope acc/owner/name
or --scope acc/owner/name#7, and the system prompt names the scope.
MCP tools (gitoodo mcp)#
No tool of gitoodo mcp changes anything. All of them read, except forge_propose_change, which
only hands a change to the human (see "Proposed changes" below). The chat pre-approves exactly
these tools by name (CHAT_TOOLS in crates/core/src/orchestrator_chat/session.rs, passed as
--allowedTools mcp__gitoodo__<tool>,…), so reading needs no prompt and nothing is written,
paused or stopped without the OK on the proposal card. ACP agents get the same server; its
permission requests are granted only for this server's tools, and there is no writing tool to
grant. Contract tests: handshake_and_tool_surface (the surface equals CHAT_TOOLS) and
no_tool_writes_without_an_ok in crates/cli/src/mcp.rs,
command_line_uses_subscription_stream_json_and_only_the_mcp_tools in
crates/core/tests/orchestrator_chat.rs.
| Tool | Required | Effect |
|---|---|---|
ledger_list_items | none (repo, readiness, label, limit) | open issues, highest score first |
ledger_release_status | none (repo) | items of the next release and their state |
ledger_list_questions | none (repo) | open question cards |
dispatcher_status | none | usage, throttle, lock, counts |
dispatcher_workers | none | running workers |
dispatcher_queue | none (limit) | ready, unleased issues of dispatching repos |
Context layers (#339)#
Read-only tools the model calls on demand, broad to narrow. Each stays inside the chat scope (a
repo outside it is an error result); overview, labels and issue lists read only the synced
ledger; pull requests, activity and item details fetch through the core's forge client with the
keychain token.
| Tool | Optional arguments | Content |
|---|---|---|
context_overview | none | per repo: rule state, open count, readiness, leases |
context_items | repo, kind, readiness, limit | open issues (ledger) and/or PRs (checks, linked issues) |
context_labels | repo | label usage and readiness distribution |
context_activity | repo, limit | recently updated issues and PRs of one repo |
context_item | key, kind | one item in depth; defaults to the scoped item |
Contract test: context_layers_follow_the_scope in crates/cli/src/mcp.rs (fake backend).
Proposed changes (#340)#
The chat never changes anything on its own: not the forge, not the repository states, not the
workers. forge_propose_change (required change) only validates the call against the chat scope
and answers that the human decides; the backend is never touched. Forge changes: comment
(body), labels (add, remove), status (status), close (optional reason, posted as a
comment first), reopen, answer (block_id, answers as ledger_list_questions and the app's
answer form use them, optional free_text; posted as the answer comment of the question format)
(each on key = account/owner/name#number, default the scoped item) and create_issue
(title, body, labels, on account + repo, default the scoped repo). Gitoodo's own state:
pause_repo and resume_repo (on account + repo, default the scoped repo; only between
active and paused) and stop_worker (on key; parks the worker without a restart, the issue
keeps its lease). Earlier, these three and the answer were direct tools
(ledger_answer_question, ledger_set_repo_state, dispatcher_stop_worker) that ran without the
human's OK; they are gone.
- The app records every accepted call in a
ProposalBook(crates/core/src/orchestrator_chat/ proposal.rs), keyed by the tool call id; a call with an error result is dropped again. - Commands:
orchestrator_chat_proposal(id)→ProposalView(proposal,state,previewwith the item's title andbefore/afterstate and labels,preview_error; reads only),orchestrator_chat_proposal_apply(id)→ProposalState,orchestrator_chat_proposal_discard(id). state.phase:pending→applying→applied(link, the forge's page of the result) orfailed(error);pending→discarded. Apply and discard work only frompending; a second OK is refused withproposal_settled, an unknown id withproposal_unknown. A failed write is not retried; the model may propose again.- An applied
create_issueis written with the chat's account (the human's connected account and token), so it is an ordinary issue by that author: the classifier's intake (spec 5.3) makes itreadywhen the author is trusted and the body is complete, exactly like an issue the human wrote on the forge or with "New issue" on the board. The OK on the card is the only confirmation; there is no second approval. - Writes go through the same paths as the app's buttons: forge changes through the core's forge
write paths, an answer through the answer path on the open question card (the card must still
be open; the preview shows the exact comment), pausing and resuming through the repository state
(orchestrator mode only) and stopping through the dispatcher's park request (
confirm_withinproposal.rs). Error texts are passed through secret redaction and lose anyuser:pass@part of URLs. Local changes report no link. - Contract tests:
nothing_is_written_without_an_ok,an_ok_applies_once_and_reports_the_link,a_failure_is_shown_without_credentials_and_not_retriedand siblings incrates/core/src/orchestrator_chat/proposal/tests.rs(alsoanswers_repo_state_and_worker_stops_are_proposals_too,an_answer_is_posted_only_after_the_ok_and_only_once,local_changes_run_the_callers_write_once_and_report_safe_errors);proposing_a_change_writes_nothingincrates/cli/src/mcp.rs.
Unknown tools and bad arguments are JSON-RPC errors (-32602); failing valid calls are results with
isError: true.
App#
- Reachable only in orchestrator mode: the chat is the third top tab "Chat" (
shell-tab-chat, key 3) next to "Asked of me" and "Overview" (#379). Direct mode hides the tab; switching to direct mode while the chat shows moves to the overview (src/views/shell/tabs.ts). - The conversation and the unsent draft live in a module store
(
src/views/dashboard/chatStore.ts) that follows the events for the app's lifetime; switching tabs keeps the session running until it is stopped. src/views/dashboard/chat.tsis the pure reducer fromChatEvents plus local actions to entries (user, assistant, tool row, turn error) and phasesidle,starting,ready,busy,ended,failed. Consecutive text blocks merge; atool_resultfills itstool_userow;mcp__gitoodo__is dropped from tool names; arguments show as one line, cut at 80 characters.- After the process ends, "Resume" restarts with
resume= the last session id; "New conversation" clears the log and starts without one. - Context bar under the header: the active scope as a chip ("All repos",
owner/nameorowner/name #7) with a clear button back to all repos, and the layers used so far (answeredcontext_*calls, without errors, broad to narrow). - Changing the scope while the chat runs restarts it with
resume, so the conversation stays but a running turn is cut; when stopped, the next start uses the new scope. - "Discuss in chat" on each overview item row and each repo header sets the scope, starts the chat if needed and switches to the chat tab.
- Proposal card under each accepted
forge_propose_changerow (src/views/dashboard/ ChatProposal.tsx): what changes and where, the comment, answer or issue text, and for state and label changes a before/after list (removed labels struck, added ones marked, also for screen readers). "Apply" and "Discard" while pending, "Nothing written yet" beside them; afterwards the outcome: a link to the result (none for pausing, resuming or stopping a worker), the error, or "Discarded". A refused OK reloads the card. - Empty log: a short welcome and four starters (
/status,/doctor, "What is waiting for me?",/questions); the session starters wait for a ready chat, the system check runs any time. /doctor(system check) runs in the app, not in the agent session: one checklist card in the log (src/views/dashboard/ChatDoctor.tsx, modeldoctor.ts) over accounts and app sync, a live forge check per account (doctor_forges, silent token read, 12 s timeout, never the token), classifier and dispatcher, CLI versions, the services' token access, the worker agent's login and its questions skill. Each row: ok / attention / problem as mark plus text, the reason, and the one fix (sign in, keychain approval, restart, install, reinstall CLI, install skill, settings); "Check again" reruns into the same card. The store build lists only the forges.- Keys: Enter sends, Shift+Enter breaks the line (IME composition is respected); the log is a
focusable
role="log"region, tool results open as<details>. - Errors:
cli_missing,chat_start_failed,chat_not_running,chat_send_failedeach have their own text in the error bar, with a retry where a restart helps. - testIDs:
shell-tab-chat,chat-panel,chat-headline,chat-status,chat-start,chat-stop,chat-restart,chat-clear,chat-error,chat-idle,chat-log,chat-empty,chat-message-<n>,chat-message-text-<n>,chat-tool-<n>,chat-tool-toggle-<n>,chat-turn-error-<n>,chat-typing,chat-composer,chat-input,chat-send,chat-starter-<status|doctor|waiting|questions>,chat-idle-doctor,chat-doctor-<n>withchat-doctor-summary-<n>,chat-doctor-recheck-<n>,chat-doctor-item-<id>,chat-doctor-fix-<id>,chat-doctor-keychain-explain,chat-context,chat-scope,chat-scope-clear,chat-layers,chat-layer-<layer>,chat-proposal-<n>with suffixes-state,-target,-body,-new-title,-diff,-before,-after,-preview-error,-apply,-discard,-link,-error,-refused,-retry,dashboard-orchestrator-discuss-<repo>-<n>,dashboard-orchestrator-discuss-repo-<id>,dashboard-orchestrator-sheet-discuss(the main action of the board's item sheet, #518).
Open#
Worker restart, setting the human label, per-worker pause (the dispatcher has no such request; pause is per repository), and the 10 % context reset with handoff.