Orchestrator

The Orchestrator is an interactive AI agent that can autonomously manage nodes, agents, sessions, operations, and chains across the Praxis network. Unlike semantic operations (which run predefined tasks), the Orchestrator is a free-form conversational interface where you give high-level goals and the AI figures out the steps.

Prerequisites

Before using the Orchestrator, you need:

1. MCP Server enabled — Open Settings with Ctrl+S, select Service, and enable MCP Server. The Orchestrator connects to the MCP server as a client to access all Praxis tools.

2. Orchestrator LLM configured — Open Settings with Ctrl+S, select LLM, configure a model definition, then assign it to the Orchestrator feature.

If the MCP server is not enabled when you start a session, you'll see an error message directing you to the settings page.

Starting a Session

1. Open the Orchestrator window with Ctrl+O
2. Type your goal or question — the session is opened on demand
3. Press Enter; the Orchestrator connects to the MCP server and fetches available tools

Sessions and State

The service holds no persistent orchestrator state. The TUI keeps one in-flight session against the service; when the TUI disconnects or closes the session, the conversation is dropped server-side.

• TUI (praxis) — One session per TUI process. The TUI mirrors every turn to ~/.praxis/sessions/<session_id>.json so you can resume later:

  • praxis --continue resumes the most recent saved session.
  • praxis --resume lists saved sessions and prompts you to pick one.

  When resuming, the saved transcript is shown immediately and the prior turns are sent as conversation history with session/new so the model has recent context for the next prompt. History is trimmed to the most recent ~20 entries on every prompt (not just on resume), so very long conversations lose earlier turns rather than growing unbounded.

What It Can Do

The Orchestrator has access to all Praxis MCP tools:

• Node management — List nodes, select nodes, request info updates
• Agent control — List agents, select agents, run recon (static and semantic), query stored recon data (sessions, projects, tools)
• Sessions — Create sessions, send prompts, close sessions
• Operations — List, run, monitor, and cancel semantic operations
• Chains — List, run, monitor, and cancel chain workflows
• Traffic — Search intercepted traffic with regex patterns

Plus two local tools:

• wait — Sleep for a specified duration (useful when polling operation status)
• report_plan — Show a step-by-step execution plan with progress tracking

Example Prompts

Simple exploration:

List all connected nodes and their agents

Multi-step task:

Connect to the first available node, select the Claude Code agent, create a YOLO session, and ask it to list the files in the current directory

Operation execution:

Run the recon::system_info operation on all active nodes and report the results

Monitoring:

Check the status of all running operations and cancel any that have been running for more than 5 minutes

Thinking Mode

If a model emits literal <think>...</think> tags in its plain-text output, the Orchestrator splits them out and renders them inline as a distinct segment before the rest of the response. This is plain-text parsing, not an API-level extended-thinking integration — there is no model-capability detection and no collapse/expand toggle; a thinking segment is always shown inline when present. Whether a model emits <think> tags at all depends entirely on the model/provider, not on any Praxis setting.

Plan Tracking

The Orchestrator can break complex tasks into steps and show progress via the report_plan tool. When the AI calls this tool, you'll see a plan panel with step descriptions and their current status (not started, in progress, done).

Concurrent Tool Calls

When the model emits multiple independent tool-call JSON blocks in a single response, the Orchestrator runs them concurrently and returns all results together in one follow-up message before the next model turn. Dependent steps still run across turns (call prerequisites first, wait for results, then continue).

This is useful for fan-out work such as listing nodes and available operations at the same time, or queueing op_run against several nodes in one step.

Token Usage

Token usage is displayed after each LLM call, showing prompt tokens, completion tokens, and totals. This helps monitor costs when using commercial API providers.

Session Controls

Ctrl+C cancels an in-flight inference while keeping the conversation. Type /clear and press Enter to start a fresh conversation. See Terminal UI for the complete Orchestrator controls.

Model Recommendations

The Orchestrator requires a capable model that can follow tool-calling instructions reliably:

Recommended:

• Anthropic: Claude Sonnet 4 or Claude Opus 4
• OpenAI: GPT-4o
• Google: Gemini 1.5 Pro

Not recommended:

• Smaller/faster models (Haiku, GPT-4o-mini) — these often fail to follow the tool calling format or hallucinate results

How It Differs from Semantic Operations

The Orchestrator is best for exploration, debugging, and complex ad-hoc tasks. Semantic operations are better for repeatable workflows that you want to run consistently.

Troubleshooting

"MCP server is not enabled"

Open Settings with Ctrl+S, select Service, and enable MCP Server. The Orchestrator requires the MCP server to function.

"Could not connect to the MCP server"

The Orchestrator connects to the MCP server when the session is created, so a connection problem is reported up front with the reason (rather than surfacing later as an opaque error on your first prompt). If you see this:

• Verify the MCP server is running in Settings (Ctrl+S) → Service
• Check that the configured port is not in use by another process
• Look at service logs for MCP server startup errors
• If you just enabled the MCP server, give it a moment to bind, then start the session again

Tools not executing

• Ensure you're using a capable model (see recommendations above)
• Check the tool execution results for error messages
• Verify nodes are connected and agents are available

Session disconnects

If the service restarts, its in-memory Orchestrator sessions are lost. The next prompt you send is detected as targeting a lost session, and the TUI automatically starts a fresh session (re-seeding it with the prior transcript) and resends your prompt — no action needed. If recovery can't re-establish the session, use /clear to start a clean one.

/clear uses standard ACP: session/close then session/new. The service keeps a shared MCP connection for the orchestrator, so after the first session of the process, close+new is near-instant (conversation only; no MCP reconnect).

To bring back a prior conversation deliberately, start the TUI with praxis --continue (or --resume): the saved transcript is replayed locally and re-seeded as history for the next prompt.