Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Orchestrator

Orchestrator chat

On this page
  1. Architecture
  2. Tauri surface
  3. MCP tools (gitoodo mcp)
  4. Context layers (#339)
  5. Proposed changes (#340)
  6. App
  7. Open

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 via gemini --experimental-acp, Codex via the codex-acp adapter). ACP agents get the same gitoodo mcp server (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 claude in stream-json mode (--input-format stream-json --output-format stream-json --verbose) with --mcp-config pointing to gitoodo mcp.
  • The session runs under the user's subscription. ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are 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 env GITOODO_CLAUDE, else claude (tests use a fake).

Tauri surface#

NameKindMeaning
orchestrator_chat_startcommand, resume?, scope?start (replaces a running chat); returns ModelFallback or null, model per ai.models.chat as --model (#341)
orchestrator_chat_sendcommand, text: stringone user message
orchestrator_chat_stopcommandstop; no-op without a chat
orchestrator-chat-eventeventpayload 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.

ToolRequiredEffect
ledger_list_itemsnone (repo, readiness, label, limit)open issues, highest score first
ledger_release_statusnone (repo)items of the next release and their state
ledger_list_questionsnone (repo)open question cards
dispatcher_statusnoneusage, throttle, lock, counts
dispatcher_workersnonerunning workers
dispatcher_queuenone (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.

ToolOptional argumentsContent
context_overviewnoneper repo: rule state, open count, readiness, leases
context_itemsrepo, kind, readiness, limitopen issues (ledger) and/or PRs (checks, linked issues)
context_labelsrepolabel usage and readiness distribution
context_activityrepo, limitrecently updated issues and PRs of one repo
context_itemkey, kindone 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, preview with the item's title and before/after state 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) or failed (error); pending → discarded. Apply and discard work only from pending; a second OK is refused with proposal_settled, an unknown id with proposal_unknown. A failed write is not retried; the model may propose again.
  • An applied create_issue is 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 it ready when 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_with in proposal.rs). Error texts are passed through secret redaction and lose any user: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_retried and siblings in crates/core/src/orchestrator_chat/proposal/tests.rs (also answers_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_nothing in crates/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.ts is the pure reducer from ChatEvents plus local actions to entries (user, assistant, tool row, turn error) and phases idle, starting, ready, busy, ended, failed. Consecutive text blocks merge; a tool_result fills its tool_use row; 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/name or owner/name #7) with a clear button back to all repos, and the layers used so far (answered context_* 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_change row (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, model doctor.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_failed each 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> with chat-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.

Docs version: dev