Skip to content

Personal AI, On Personal Devices

Python

docs: clarify CLI agent defaults and direct mode (#987)

Johnny C Wattc54525d28c90
diff --git a/docs/architecture/query-flow.md b/docs/architecture/query-flow.md
index 0261de6e..87c127b9 100644
--- a/docs/architecture/query-flow.md
+++ b/docs/architecture/query-flow.md
@@ -41,7 +41,7 @@ sequenceDiagram
AGT->>CTX: inject_context(query, messages, backend)
CTX-->>AGT: messages with context prepended
- loop Tool-calling loop (max_turns)
+ loop Inference (single turn for SimpleAgent; tool loop for tool-using agents)
AGT->>ENG: generate(messages, model, tools)
ENG-->>AGT: {content, tool_calls, usage}
opt Tool calls present
@@ -72,27 +72,39 @@ sequenceDiagram
OpenJarvis supports two query processing paths, selected by the `--agent` CLI flag or the `agent` parameter in the SDK.
-### Direct Mode (Default)
+The CLI and SDK have different defaults:
+
+- **CLI:** When `--agent` is omitted for a text query, `agent.default_agent` from configuration is used. Its default is `simple`. An empty configured default selects direct mode. Image and screen queries use direct mode automatically when `--agent` is omitted.
+- **SDK:** Omitting `agent` (or passing `agent=None`) uses direct mode. The SDK does not fall back to `agent.default_agent`.
+
+### Direct Mode
In direct mode, the query goes straight to the inference engine with optional memory context. This is the simplest path -- one inference call, no tool loop.
```bash
# CLI
-jarvis ask "What is the capital of France?"
+jarvis ask --agent "" "What is the capital of France?"
+```
-# SDK
+```python
+# SDK (direct mode is the default)
j = Jarvis()
response = j.ask("What is the capital of France?")
```
+Direct mode bypasses the agent's system prompt and persona handling. In the CLI, set `default_agent = ""` in the `[agent]` section of `~/.openjarvis/config.toml` to make this the default for text queries.
+
### Agent Mode
-In agent mode, the query is handled by a named agent that can perform multiple inference rounds and invoke tools. The `OrchestratorAgent` is the most common choice, enabling a multi-turn tool-calling loop.
+In agent mode, the query is handled by a named agent. The CLI's default `SimpleAgent` makes a single inference call without a tool loop, while applying the configured system prompt and persona files (`SOUL.md`, `MEMORY.md`, and `USER.md`). Agents such as `OrchestratorAgent` can perform multiple inference rounds and invoke tools.
```bash
# CLI
+jarvis ask "Hello" # Uses SimpleAgent with the default configuration
jarvis ask --agent orchestrator --tools calculator,think "What is 2^10 + 3^5?"
+```
+```python
# SDK
response = j.ask("What is 2^10 + 3^5?", agent="orchestrator", tools=["calculator"])
```
diff --git a/docs/user-guide/cli.md b/docs/user-guide/cli.md
index 519c957c..eaad767e 100644
--- a/docs/user-guide/cli.md
+++ b/docs/user-guide/cli.md
@@ -64,20 +64,20 @@ jarvis ask "What is the capital of France?"
| `--json` | flag | off | Output raw JSON result instead of plain text |
| `--no-stream` | flag | off | Disable streaming (synchronous mode) |
| `--no-context` | flag | off | Disable memory context injection |
-| `-a`, `--agent AGENT` | string | none | Agent to use (`simple`, `orchestrator`) |
+| `-a`, `--agent AGENT` | string | config (`simple`) | Agent to use; `""` selects direct mode |
| `--tools TOOLS` | string | none | Comma-separated tool names to enable |
| `-i`, `--image PATH` | path | none | Image file for a vision model (e.g. `gemma3:4b`); repeatable |
| `-S`, `--screen` | flag | off | Capture the current screen and send it to the vision model |
### Direct Mode vs Agent Mode
-**Direct mode** (default) sends the query straight to the inference engine:
+**Agent mode** is the default for text queries. When `--agent` is omitted, the CLI uses `agent.default_agent` from configuration, which defaults to `simple`. `SimpleAgent` makes a single inference call without a tool loop, while applying the configured system prompt and persona files (`SOUL.md`, `MEMORY.md`, and `USER.md`).
```bash
jarvis ask "Explain quantum computing"
```
-**Agent mode** routes the query through an agent that can use tools and manage multi-turn interactions:
+Use `--agent` to select an agent explicitly. Agents such as `orchestrator` can use tools and manage multi-turn interactions:
```bash
jarvis ask --agent orchestrator "What is 2+2?"
@@ -85,6 +85,14 @@ jarvis ask --agent orchestrator --tools calculator,think "Calculate sqrt(144) +
jarvis ask --agent simple "Hello"
```
+**Direct mode** sends the query straight to the inference engine with optional memory context, bypassing the agent's system prompt and persona handling. Pass an empty agent name to select it:
+
+```bash
+jarvis ask --agent "" "Explain quantum computing"
+```
+
+To make direct mode the default, set `default_agent = ""` in the `[agent]` section of `~/.openjarvis/config.toml`.
+
### Usage Examples
```bash
@@ -124,7 +132,9 @@ jarvis ask -i chart-a.png -i chart-b.png "Compare these two charts"
jarvis ask --screen "Summarize what's on my screen"
```
-Vision runs in **direct mode** only. If you also pass `--agent`, the image is
+Vision runs in **direct mode** only. When `--agent` is omitted, image and screen
+queries automatically use direct mode, overriding the configured default agent.
+If you explicitly select an agent, the image is
ignored and a note is printed — re-run with `--agent ""` to force direct mode.
The Ollama context window can be tuned for large images or long prompts with