YodaMan Manual

Local-first workspace intelligence with chat, search, mandatory Graphify knowledge graphs, supervised agent automation, plugins, desktop controls, VS Code commands, and mobile pairing.

Version 0.2.2

1. Setup

Install Context Expert, install Graphify, install dependencies, and start the runtime from the project root.

npm install -g @contextexpert/cli
python3 -m pip install graphifyy
npm install
sh setup.sh
npm start

The backend runtime listens on http://localhost:3090. The development web UI listens on http://localhost:5190. Use npm run desktop for the Electron app.

2. Core ideas

Local runtime

One private Express runtime powers the web UI, desktop app, VS Code extension, mobile companion, plugins, and runtime API.

Workspace control

Paste paths, browse folders in desktop clients, select, refresh, validate, edit, delete, and reindex absolute local workspace paths.

Knowledge graph

Graphify builds required workspace graphs for graph-aware answers, impact analysis, freshness warnings, architecture maps, and CLI health checks with yodaman doctor --graph.

Human-approved writes

Agent tasks use graph context, stream events, and pause for approval before applying file writes.

Local persistence

Task history and audit logs persist in SQLite when available, with JSON fallback.

Restricted plugins

Plugins declare permissions. Plugin uploads, unrestricted plugins, and agent shell commands are disabled by default and should only be enabled for trusted local support sessions.

Crash recovery

The desktop recovery screen shows the logo, runtime logs, retry/status actions, and Copy Error.

3. Web UI

Settings: Open from the top-right Settings button, sidebar plus button, or Configuration modal. Paste an absolute path or use Browse in the desktop app, then add, edit, and delete workspace paths.
Workspaces: Select a project, refresh the workspace list, validate health, toggle inclusion, edit the file path, delete a workspace, and sync the selected repository.
Chat: Ask questions using selected workspace context.
Search: Run semantic search across indexed code and documentation, optionally scoped to the selected project.
Dashboard: View status, database/index metrics, environment info, diagnostics, task counts, approvals, plugin policy, and mobile pairing.
Logs: Open searchable runtime logs, reindex requests, index queue state, and ctx index output. Filter by text, level, severity, and user action before copying diagnostics.
Manual: Read the in-app guide.
Plugins: Upload JavaScript plugins, inspect permissions and parameters, refresh loaded plugins, and delete non-mandatory plugin files.
Graph doctor: Run yodaman doctor --graph to check active graphs, persisted freshness, orphaned nodes, and the most dependency-heavy file.

4. Desktop app

The Electron app starts a managed runtime sidecar when no runtime is already available on port 3090. It also runs from the system tray.

Restart Managed Runtime restarts the managed backend.
Copy Mobile Pairing Link creates and copies a yodaman://pair link.
Add Project Folder opens a native folder picker.
Show YodaMan restores the window from the tray.
Quit stops the desktop app and managed runtime.

5. VS Code extension

The extension checks runtime status, starts the runtime command, adds workspaces by browsing, pasting, or using the current VS Code workspace, asks/searches/reindexes the current workspace, opens runtime logs, runs and cancels agent tasks, streams events, opens proposed writes as diffs, approves or rejects changes, clears task/audit history, and exposes the YodaMan activity bar sidebar.

6. Mobile companion

The mobile companion pairs with yodaman://pair links. It can check status, list projects, choose a workspace, ask, search, inspect task timelines, open event details, cancel active tasks, refresh pending approvals, and approve or reject proposed writes.

7. Runtime API highlights

GET/POST/PUT/DELETE /api/projects: List, add, update, or remove workspace paths.
POST /api/reindex: Queue a workspace for reindexing.
/api/graphify/*: Read graph status, rebuild graphs, query relationships, explain nodes, find paths, run impact analysis, and load architecture maps.
GET /api/search and POST /api/ask: Search and ask against indexed context.
GET /api/status and GET /api/desktop/diagnostics: Read status and diagnostics.
GET/POST/DELETE /api/plugins: Manage JavaScript plugins.
/api/agent/*: Run, inspect, approve, reject, cancel, or clear agent tasks.
GET/DELETE /api/audit: Inspect or clear audit logs.
POST /api/pairing: Create mobile pairing links.

8. Troubleshooting

Context Expert not found: Install @contextexpert/cli and confirm ctx --version works.
Graphify not found: Install graphifyy, confirm graphify --help works, or set YODAMAN_GRAPHIFY_BIN.
Graph health warnings: Run yodaman doctor --graph, then sync the affected workspace if orphaned nodes or missing graphs are reported.
Runtime unreachable: Check port 3090, restart the managed runtime, or run yodaman from Terminal.
Moved repository: Open Settings, edit the workspace path, save, then sync.
Search results are stale: Reindex the selected workspace.
Mobile cannot connect: Use the desktop LAN IP, confirm firewall access to port 3090, and generate a fresh pairing link.
Plugin blocked: Add explicit permissions or intentionally allow unrestricted plugins.
Crash screen: Use Copy Error to capture the message and logs.

9. Verification

npm test
npm run build
npm run desktop:pack
cd extensions/vscode-yodaman
npm run lint
npm run package