The PlanOpticon Companion is an interactive Read-Eval-Print Loop (REPL) that provides a conversational interface to PlanOpticon's full feature set. It combines workspace awareness, knowledge graph querying, LLM-powered chat, and planning agent skills into a single session.
4
5
Use the Companion when you want to explore a knowledge graph interactively, ask natural-language questions about extracted content, generate planning artifacts on the fly, or switch between providers and models without restarting.
6
7
---
8
9
## Launching the Companion
10
11
There are three equivalent ways to start the Companion.
12
13
### As a subcommand
14
15
```bash
16
planopticon companion
17
```
18
19
### With the `--chat` / `-C` flag
20
21
```bash
22
planopticon --chat
23
planopticon -C
24
```
25
26
These flags launch the Companion directly from the top-level CLI, without invoking a subcommand.
27
28
### With options
29
30
The `companion` subcommand accepts options for specifying knowledge base paths, LLM provider, and model:
| `--chat-model NAME` | Override the default chat model for the selected provider |
51
52
---
53
54
## Auto-discovery
55
56
On startup, the Companion automatically scans the workspace for relevant files:
57
58
**Knowledge graphs.** The Companion uses `find_nearest_graph()` to locate the closest `knowledge_graph.db` or `knowledge_graph.json` file. It searches the current directory, common output subdirectories (`results/`, `output/`, `knowledge-base/`), recursively downward (up to 4 levels), and upward through parent directories. SQLite `.db` files are preferred over `.json` files.
59
60
**Videos.** The current directory is scanned for files with `.mp4`, `.mkv`, and `.webm` extensions.
61
62
**Documents.** The current directory is scanned for files with `.md`, `.pdf`, and `.docx` extensions.
63
64
**LLM provider.** If `--provider` is set to `auto` (the default), the Companion attempts to initialise a provider using any available API key in the environment (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc.).
65
66
All discovered context is displayed in the welcome banner:
If no knowledge graph is found, the banner shows "No knowledge graph loaded." Commands that require a KG will return an appropriate message rather than failing silently.
81
82
---
83
84
## Slash Commands
85
86
The Companion supports 18 slash commands. Type `/help` at the prompt to see the full list.
87
88
### /help
89
90
Display all available commands with brief descriptions.
91
92
```
93
planopticon> /help
94
Available commands:
95
/help Show this help
96
/status Workspace status
97
/skills List available skills
98
/entities [--type T] List KG entities
99
/search TERM Search entities by name
100
/neighbors ENTITY Show entity relationships
101
/export FORMAT Export KG (markdown, obsidian, notion, csv)
102
/analyze PATH Analyze a video/doc
103
/ingest PATH Ingest a file into the KG
104
/auth SERVICE Authenticate with a cloud service
105
/provider [NAME] List or switch LLM provider
106
/model [NAME] Show or switch chat model
107
/run SKILL Run a skill by name
108
/plan Run project_plan skill
109
/prd Run PRD skill
110
/tasks Run task_breakdown skill
111
/quit, /exit Exit companion
112
113
Any other input is sent to the chat agent (requires LLM).
114
```
115
116
### /status
117
118
Show a summary of the current workspace state: loaded knowledge graph (with entity and relationship counts, broken down by entity type), number of discovered videos and documents, and whether an LLM provider is active.
This command requires a loaded knowledge graph. If none is loaded, it returns "No knowledge graph loaded."
174
175
### /search TERM
176
177
Search entities by name substring (case-insensitive).
178
179
```
180
planopticon> /search python
181
Found 3 entities
182
[technology] Python -- General-purpose programming language
183
[technology] Python Flask -- Web framework for Python
184
[concept] Python packaging -- Discussion of pip and packaging tools
185
```
186
187
### /neighbors ENTITY
188
189
Show all entities and relationships connected to a given entity. This performs a breadth-first traversal (depth 1) from the named entity.
190
191
```
192
planopticon> /neighbors Alice
193
Found 4 entities and 5 relationships
194
[person] Alice -- Lead engineer on the project
195
[technology] Python -- General-purpose programming language
196
[organization] Acme Corp -- Employer
197
[concept] Authentication -- Auth system design
198
Alice --[works_with]--> Python
199
Alice --[employed_by]--> Acme Corp
200
Alice --[proposed]--> Authentication
201
Bob --[collaborates_with]--> Alice
202
Authentication --[discussed_by]--> Alice
203
```
204
205
### /export FORMAT
206
207
Request an export of the knowledge graph. Supported formats: `markdown`, `obsidian`, `notion`, `csv`. This command prints the equivalent CLI command to run.
Request ingestion of a file into the knowledge graph. Validates the file exists and prints the equivalent CLI command.
228
229
```
230
planopticon> /ingest notes.md
231
Ingest requested for notes.md. Use the CLI:
232
planopticon ingest /home/user/project/notes.md
233
```
234
235
### /auth [SERVICE]
236
237
Authenticate with a cloud service. When called without arguments, lists all available services. When called with a service name, triggers the authentication flow.
List available LLM providers and their status, or switch to a different provider.
251
252
When called without arguments (or with `list`), shows all known providers with their availability status:
253
254
- **ready** -- API key found in environment
255
- **local** -- runs locally (Ollama)
256
- **no key** -- no API key configured
257
258
The currently active provider is marked.
259
260
```
261
planopticon> /provider
262
Available providers:
263
openai: ready (active)
264
anthropic: ready
265
gemini: no key
266
ollama: local
267
azure: no key
268
together: no key
269
fireworks: no key
270
cerebras: no key
271
xai: no key
272
273
Current: openai
274
```
275
276
To switch providers at runtime:
277
278
```
279
planopticon> /provider anthropic
280
Switched to provider: anthropic
281
```
282
283
Switching the provider reinitialises the provider manager and the planning agent. The chat model is reset to the provider's default. If initialisation fails, an error message is shown.
284
285
### /model [NAME]
286
287
Show the current chat model, or switch to a different one.
288
289
```
290
planopticon> /model
291
Current model: default
292
Usage: /model MODEL_NAME
293
294
planopticon> /model claude-sonnet-4-20250514
295
Switched to model: claude-sonnet-4-20250514
296
```
297
298
Switching the model reinitialises both the provider manager and the planning agent.
299
300
### /run SKILL
301
302
Run any registered skill by name. The skill receives the current agent context (knowledge graph, query engine, provider, and any previously generated artifacts) and returns an artifact.
303
304
```
305
planopticon> /run roadmap
306
--- Roadmap (roadmap) ---
307
# Roadmap
308
309
## Vision & Strategy
310
...
311
```
312
313
If the skill cannot execute (missing KG or provider), an error message is returned. Use `/skills` to see all available skill names.
314
315
### /plan
316
317
Shortcut for `/run project_plan`. Generates a structured project plan from the loaded knowledge graph.
318
319
```
320
planopticon> /plan
321
--- Project Plan (project_plan) ---
322
# Project Plan
323
324
## Executive Summary
325
...
326
```
327
328
### /prd
329
330
Shortcut for `/run prd`. Generates a product requirements document.
331
332
```
333
planopticon> /prd
334
--- Product Requirements Document (prd) ---
335
# Product Requirements Document
336
337
## Problem Statement
338
...
339
```
340
341
### /tasks
342
343
Shortcut for `/run task_breakdown`. Breaks goals and features into tasks with dependencies, priorities, and effort estimates. The output is JSON.
344
345
```
346
planopticon> /tasks
347
--- Task Breakdown (task_list) ---
348
[
349
{
350
"id": "T1",
351
"title": "Set up authentication service",
352
"description": "Implement OAuth2 flow with JWT tokens",
353
"depends_on": [],
354
"priority": "high",
355
"estimate": "1w",
356
"assignee_role": "backend engineer"
357
},
358
...
359
]
360
```
361
362
### /quit and /exit
363
364
Exit the Companion REPL.
365
366
```
367
planopticon> /quit
368
Bye.
369
```
370
371
---
372
373
## Exiting the Companion
374
375
In addition to `/quit` and `/exit`, you can exit by:
376
377
- Typing `quit`, `exit`, `bye`, or `q` as bare words (without the `/` prefix)
378
- Pressing `Ctrl+C` or `Ctrl+D`
379
380
All of these end the session with a "Bye." message.
381
382
---
383
384
## Chat Mode
385
386
Any input that does not start with `/` and is not a bare exit word is sent to the chat agent as a natural-language message. This requires a configured LLM provider.
387
388
```
389
planopticon> What technologies were discussed in the meeting?
390
Based on the knowledge graph, the following technologies were discussed:
391
392
1. **Python** -- mentioned in the context of backend development
393
2. **React** -- proposed for the frontend redesign
394
3. **PostgreSQL** -- discussed as the primary database
395
...
396
```
397
398
The chat agent maintains conversation history across the session. It has full awareness of:
399
400
- The loaded knowledge graph (entity and relationship counts, types)
401
- Any artifacts generated during the session (via `/plan`, `/prd`, `/tasks`, `/run`)
402
- All available slash commands (which it may suggest when relevant)
403
- The full PlanOpticon CLI command set
404
405
If no LLM provider is configured, chat mode returns an error with instructions:
406
407
```
408
planopticon> What was discussed?
409
Chat requires an LLM provider. Set one of:
410
OPENAI_API_KEY
411
ANTHROPIC_API_KEY
412
GEMINI_API_KEY
413
Or pass --provider / --chat-model.
414
```
415
416
---
417
418
## Runtime Provider and Model Switching
419
420
One of the Companion's key features is the ability to switch LLM providers and models without restarting the session. This is useful for:
421
422
- Comparing outputs across different models
423
- Falling back to a local model (Ollama) when API keys expire
424
- Using a cheaper model for exploratory queries and a more capable one for artifact generation
425
426
When you switch providers or models via `/provider` or `/model`, the Companion:
427
428
1. Updates the internal provider name and/or model name
429
2. Reinitialises the `ProviderManager`
430
3. Reinitialises the `PlanningAgent` with a fresh `AgentContext` that retains the loaded knowledge graph and query engine
431
432
Conversation history is preserved across provider switches.
433
434
---
435
436
## Example Session
437
438
The following walkthrough shows a typical Companion session, from launch through exploration to artifact generation.