# AI Cockpit — User Guide

            . | .
             \|/
         .--- O ---.
        /    /|\    \
       '    / | \    '
            . | .

      AI Cockpit · One IDE. Every AI.

> A multi-agent orchestration interface for Claude, Gemini, Ollama, LocalAI (or both at once via Dual mode), online LLM providers (Workers), and local CLI tools (Tools).

> Built by Dario Ruggi · maestro.ruggi.site

## Table of contents

1. The 30-second tour
2. The supplier strip — your 5 agents
3. Sending a prompt
4. Multi-agent modes
5. Styles
6. Projects and chats
7. Left sidebar
8. Right-sidebar tabs
9. Capabilities — MCP, Skills, tool shims
10. The Orchestrator + Planner
11. Workers — online LLM providers
12. Tools — local CLI binaries
13. Library, Snippets, Sources
14. Search the web
15. Keyboard shortcuts
16. Troubleshooting
17. Configuration files
18. Context menus
19. Themed confirm & prompt dialogs
20. Plan Re-Run
21. Spend-cap warnings
22. Ollama runtime knobs
23. Model Manager enhancements
24. Media generation
25. Translation
26. Time tracking
27. Terminal, Files, Browser
28. Accumulator
29. Skills system
30. Summarize
31. Caveman mode
32. Themes & theming
33. Typography controls
34. Comprehensive help system
35. Power Combos (Tier 0)
36. Your own combos
37. Delegate — task auto-routing
38. Multiple local users
39. Cockpit Account & Marketplace
40. Supplier Slots — CLI aliasing
41. Background Tasks & Scheduler
42. Transcriber

## The 30-second tour

The cockpit window has four regions:

    ┌──────────────────────────────────────────────────────────────────┐
    │ TOPBAR — 5 supplier cards · Start/Stop/Restart · Theme · Rules   │
    │          Project / Chat / Path · Jobs · Accumulator · Help       │
    ├──────────┬──────────────────────────────────────┬────────────────┤
    │ LEFT     │  CONSOLE (chat scroll)               │  RIGHT         │
    │ SIDEBAR  │                                      │  SIDEBAR       │
    │          │  user: ...                           │                │
    │ Chats    │  CLAUDE: ...                         │  Preview       │
    │ Projects │  GEMINI: ...                         │  Code          │
    │ Files    │  OLLAMA: ...                         │  Library       │
    │          │                                      │  Snippets      │
    │          │  ┌──────────────────────────────┐    │  Sources       │
    │          │  │  PROMPT  ·  Execute/Clear    │    │  Config        │
    │          │  │  Attach  ·  Save  ·  Voice   │    │  Search        │
    │          │  └──────────────────────────────┘    │  Capabilities  │
    │          │  Mode: Single·Pipeline·Broadcast·Plan│  Plans         │
    │          │  Style: Chat·Build·Debug·Research·…  │  Attachments   │
    │          │  Toolbar: Translate·Summarize·Skills… │  Usage         │
    ├──────────┴──────────────────────────────────────┴────────────────┤
    │ FOOTER — Font size · Typography · Caveman · Model selector       │
    └──────────────────────────────────────────────────────────────────┘

To do anything:

1. Pick an agent by clicking its card in the topbar
2. Type a prompt in the textarea
3. Press Execute (or Ctrl-Enter)

For multi-agent flows, switch the mode strip below the prompt to Pipeline, Broadcast, or Plan before pressing Execute.

## The supplier strip

Five cards run across the top of the cockpit. Each represents one provider class. Only the active card is expanded; the others show just an icon, the selected model name, and a thin progress bar.

Card | Color | What it is
--- | --- | ---
CLAUDE | amber | Anthropic Claude — best at reasoning, refactoring, architecture
GEMINI | blue | Google Gemini — fast iteration, broad knowledge, summaries
OLLAMA / LOCALAI / DUAL | orange | Local models running on your GPU — fully offline. Card 3's label follows whichever backend is assigned (Ollama, LocalAI, or Dual for both at once)
WORKERS | purple | Online LLM APIs — Groq, HuggingFace, OpenRouter, etc.
TOOLS | teal | Local CLI binaries — ffmpeg, whisper, pandoc, etc.

### Switching agents

Click any inactive card to make it active. The previous active card collapses to its icon-only state. The console border-color and Execute-button color follow the active agent so you always know what’s loaded.

### Reading a card at a glance

Inactive — icon + selected model name + 3px progress bar.

Active — icon + agent name + AGENT button label, model dropdown, settings or open-tmux button, and a full usage line below.

The progress bar reflects different things per agent:

- Claude: tokens used vs the ~44K context budget
- Gemini: total prompt+response tokens estimated
- Ollama: 0% (no quota — local model)
- Workers: aggregate tokens across all providers (informational)
- Tools: enabled tool count vs total registered

## Sending a prompt

1. Click the prompt textarea at the bottom
2. Type your message
3. Click Execute or press Ctrl-Enter

While the agent is responding, you’ll see a small ⏳ placeholder for that message which gets replaced as tokens stream in.

### Cancelling a stream

Click the Stop button next to Execute. The stream is aborted on both the frontend and the backend (the agent’s tmux process is signaled). The partial response stays in the chat for context.

### Re-running a prompt

The Up arrow key in the empty textarea brings up your previous prompt for quick edit-and-resend.

### Attaching context

Click the Attach button (next to the prompt) or drag files onto the chat to attach. Text/code files are inlined as agent context; images go to vision-capable models. Manage attached files in the Attachments tab (right sidebar).

You can also attach reference material from the Library, Snippets, and Sources tabs — click any item’s attach icon to insert it into your next prompt as quoted context.

### Prompt-area buttons

Button | Action
--- | ---
EXECUTE | Send prompt (same as Ctrl+Enter)
CLEAR | Empty the prompt text area
SAVE | Save prompt text to Snippets or Library
Attach | Open file picker to attach files
🎤 Voice | Record and transcribe locally (whisper.cpp)

## Multi-agent modes

Below the prompt textarea is the mode strip:

    ┌─────────────────────────────────────────────────────────┐
    │  ◉ Single   ○ Pipeline   ○ Broadcast   ○ Plan           │
    └─────────────────────────────────────────────────────────┘

### Single mode (default)

Prompt goes to the active agent only. Standard chat behavior.

### Pipeline mode

Prompt goes to agent A; A’s response becomes the prompt for agent B; B’s response becomes the prompt for agent C; etc. Useful for refinement chains:

> Claude analyzes the spec → Gemini drafts code → Ollama runs the test suite

To configure pipeline order, the Multi-agent panel above the mode strip lets you select which agents to include and in what order.

### Broadcast mode

Same prompt sent to every selected agent in parallel. Responses appear side-by-side. Useful for getting different perspectives on a question or comparing model output quality.

### Plan mode

Treats the prompt as a goal and triggers the Orchestrator. All 3 main agents draft a plan in parallel; a synthesizer merges the votes; the result is saved to the Plans right-sidebar tab where you can review, edit, and execute it step-by-step. See The Orchestrator + Planner.

## Styles

The style strip (below modes) prepends an instruction to every prompt, steering how the agent responds:

Style | Behavior
--- | ---
Chat | Conversational — answers in prose, no code unless asked
Outline | Plan first, then implement
Research | Explore and explain with sources and reasoning
Build | Default builder mode — writes working code directly
Debug | Focus on finding and fixing bugs
Analyze | Deep analysis of code, data, or architecture
Report | Structured output — formal report with sections and conclusions

In Plan mode, the style prefix is NOT prepended to the orchestrator goal — it only applies to direct agent prompts.

## Projects and chats

The cockpit organizes work into projects (folders on disk) containing chats (separate conversation threads).

### Default location

Projects live under:

    /home/dario/Software/Programing/LocalAIProjs/

Each project is a directory; each chat is a `chat_<name>.json` file inside that directory.

### Creating a project

1. Open the Files tab in the left sidebar
2. Click the + New Project button
3. Type a name (alphanumeric, dashes, underscores)

The new project becomes the active one. The path appears in the topbar’s info bar.

### Creating a chat

1. Open the Chats tab in the left sidebar
2. Click + New Chat
3. Type a name

The chat is created inside the active project. The textbox in the topbar shows the active chat name.

### Chat operations

- Double-click a chat name to rename it.
- Export — save chat as JSON for backup or sharing.
- Import — load a previously exported chat JSON.
- Detach — move a chat to the Free (standalone) pool.
- Delete — permanently remove (with confirmation).

Each chat has independent history, attachments, and proposals.

### Switching context

Click any project name → that project becomes active. Click any chat name → that chat becomes active.

The info bar (`Project: foo · Chat: bar · /path/...`) always reflects the current context.

### Standalone mode

If no project is selected, the cockpit operates in `_standalone` mode — chats live in `~/scripts/cockpit_data/_standalone/`. Useful for quick one-off questions.

## Left sidebar

The left sidebar has three tabs:

Tab | Purpose
--- | ---
Chats | List of chats in the current project. Create, rename, import/export, detach, delete.
Projects | All projects. Create, switch, edit COCKPIT.md rules, delete.
Files | Project directory file tree. Click to preview/edit. Map button generates a Pascal/PHP unit map.

## Right-sidebar tabs

The right sidebar has 11 vertical icon tabs:

Tab | Purpose
--- | ---
Preview | Live preview of HTML/Markdown files. Updates when you select a file from the file tree.
Code | Inline code editor with syntax highlighting, find/replace, line numbers, word wrap.
Library | Saved references — URLs, file paths, notes. Scopeable to project or global.
Snippets | Reusable code fragments with language tags. Save from chat (F2) or add manually.
Sources | Source code files used as context or reference material for agents.
Config | Configuration — storage paths, attachment routes, import/export settings.
Search | Web search (Brave/DDG). Results can be fetched and injected into prompt context.
Capabilities | MCP servers and tool-shims. Toggle ON/OFF per capability.
Plans | Orchestrator plans — view steps, run/sequence/schedule, inspect votes.
Attachments | Files attached to the current chat. Upload, manage, and reference in prompts.
Usage | Token usage, quota tracking, and paid API spend for all suppliers and workers.

Click any tab to open its panel. Only one panel is visible at a time. Tab state persists across page loads.

Below the tabs, the Pending Proposals section shows agent suggestions (file edits, commands) awaiting your approval. Approve or reject individually or in batch. Always visible regardless of which tab is open.

## Capabilities

The Capabilities tab unifies three layers underneath:

- MCP servers for Claude and Gemini (Anthropic’s standard)
- Skills for Claude (Anthropic-specific `SKILL.md` folders)
- Tool shims for Ollama (which doesn’t speak MCP natively)

You declare a capability once with up to three implementations; the cockpit routes correctly per agent.

### Built-in capabilities

ID | What | Claude | Gemini | Ollama
--- | --- | --- | --- | ---
`filesystem` | Read/write project files | MCP | MCP | shim
`git` | Inspect/modify git repo | MCP | MCP | shim
`web-search` | Brave/DDG search | MCP | — | shim
`web-fetch` | Fetch URL → text | MCP | MCP | shim
`ssh` | Run commands on remote hosts | — | — | shim

### Enabling a capability

1. Open the Capabilities tab
2. Find the capability in the list
3. Click the toggle (left side of the row) — it turns blue
4. Restart the agent (Stop/Restart buttons in the topbar) — capabilities take effect on the next agent session start

### Creating your own capability

Click + New in the Capabilities toolbar. Provide:

- ID — lowercase, alphanumeric + dash/underscore
- Name — display name
- Description — one sentence

This scaffolds an empty `CAP.json` at:

    ~/scripts/cockpit_data/capabilities/<id>/CAP.json

Edit the file to wire up implementations. See `CAPABILITIES_README.md` for the full schema.

### Adding a community MCP server

Browse the registry suggestions via the cloud_download button in the Capabilities toolbar. Suggested options include GitHub, Slack, GDrive, SQLite, and Memory. Currently you copy the package name into a custom capability manifest (auto-install is a future feature).

## The Orchestrator + Planner

The Plan mode treats your prompt as a goal and breaks it into executable steps using all three agents collaboratively.

### How it works

    USER GOAL
        │
        ├──→ Claude  ─┐
        ├──→ Gemini  ─┼──→ 3 draft plans
        └──→ Ollama  ─┘
                           │
                           ▼
                      SYNTHESIZER (default: Claude)
                           │
                           ▼
                      MERGED PLAN — saved to Plans tab

If only one voter produces valid JSON, the synthesizer is skipped — that voter’s plan IS the plan. If the synthesizer fails, the longest valid voter plan is used as fallback.

### Running a plan

1. Switch the prompt mode strip to Plan
2. Type your goal
3. Press Execute
4. Watch system messages: voting → synthesis → “Plan ready”
5. Open the Plans tab (right sidebar)
6. Click your new plan → expanded step view with Run/Skip/Edit per step
7. Click ▶ Run in the plan toolbar to execute end-to-end

### Plan controls

Button | What it does
--- | ---
▶ Run | Execute all remaining steps honoring auto-run mode
⏸ Pause | Stop auto-progression after current step
🗳 Votes | Show all 3 original voter plans side-by-side
🗑 Delete | Remove the plan from disk
▶ (per step) | Run just that step now
⏭ (per step) | Mark step skipped
✏ (per step) | Edit the step’s description

### Auto-run modes

Click the tune icon in the Plans toolbar to cycle through:

Mode | Behavior
--- | ---
`auto` | Run all steps to completion, no prompts
`approve_destructive` | Pause before any step marked destructive (default)
`approve_each` | Pause before every step (browser confirm dialog)
`manual_only` | Don’t auto-progress; click Run on each step manually

A step is marked destructive when it writes files, modifies git, runs network commands beyond GET, or uses ssh.

### Editing plans mid-flight

Click the ✏ pencil next to any pending step to rewrite its description. Already-running and done steps can’t be edited (re-run them with the per-step ▶ button if needed). Edits persist on disk.

## Workers

Workers are online LLM providers used for tasks the main agents can’t do (image generation, audio, niche translations) or as fallback when the main providers are exhausted.

### Built-in providers

Provider | Free? | Specialty
--- | --- | ---
Groq | Yes (generous) | Ultra-fast text inference
HuggingFace | Yes (hourly) | Text + image-gen + audio + translate
OpenRouter | Has free tier | Universal LLM gateway
Together AI | $1 free | Open-weight models, image gen
DeepInfra | Pay-per-use | Cheap inference

### Setup

1. Click the gear icon next to the WORKERS button → settings modal opens
2. For each provider you want to use:
   - Click the Get key link → sign up on the provider’s site
   - Paste the API key into the input field → click Save
   - Click Disabled to toggle to Enabled
3. Close the modal — the model dropdown above WORKERS now lists all enabled `<provider>:<model>` pairs

### API key storage

Keys are encrypted with AES-256-GCM at rest. The encryption key is derived from your machine’s `/etc/machine-id` plus a fixed cockpit salt, which means:

- Casual disk-grep won’t find them
- Accidental git-commit doesn’t leak them
- Copying the encrypted file to another machine fails to decrypt

This is not military-grade — anyone with shell access on your machine can decrypt. Same security level as your `~/.ssh/` keys.

### Manual invocation

1. Pick the WORKERS agent (click the card)
2. Select a model from the dropdown
3. Type a prompt → press Execute

The cockpit dispatches via HTTP, captures the response, and renders it inline:

- Text → plain text in the chat
- Image → embedded `<img>`
- Audio → embedded `<audio controls>`

### Auto-route (per-project opt-in)

When enabled for a project, all main agents (Claude/Gemini/Ollama) get a system-prompt addition advising them about the marker:

    %%WORKER:provider:task:prompt%%

`crud_executor.sh` dispatches the markers and surfaces results inline. To enable, POST to `workers.php?action=set_auto_route` with `{"project":"myproject","enabled":true}`.

### Usage tracking

The WORKERS card’s bar shows aggregate tokens used; the settings modal shows per-provider call counts, error counts, tokens in/out, and last-call timestamp. Right-click the card’s usage area to reset all counters.

## Tools

Tools are local CLI binaries for file → file transformations. No internet, no API keys, no usage tracking.

### Built-in tools

Tool | Presets | What it does
--- | --- | ---
ffmpeg | 9 | Audio/video conversion, extraction, resize, frames
whisper | 7 | Speech-to-text (auto/EN/ES/HE), SRT, translate-to-EN
pandoc | 8 | Document conversion (md ↔︎ pdf/docx/html/epub)

### Setup

1. Click the gear icon next to the TOOLS button → settings modal
2. Click Detect at the top to scan `$PATH` for binaries
3. For each tool that shows “✗ not found”:
   - Either install it (`sudo nala install ffmpeg whisper pandoc`)
   - Or paste the absolute path in the Override binary path field
4. Close the modal — the preset dropdown shows enabled `<tool>:<preset>` pairs

### Running a tool

1. Pick a preset from the dropdown
2. Click the TOOLS card to make it the active agent
3. Press Execute — the input modal opens
4. Paste an absolute path (or click Browse to fill the filename)
5. Optionally paste extra arguments
6. Click Run

The output appears inline as a clickable file path with size, runtime, and embedded preview if it’s an image/audio/video.

### Browser file picker limitation

Browsers refuse to expose absolute file paths to JavaScript. The Browse button only fills in the filename. You’ll need to paste the full absolute path manually. This is a fundamental browser security restriction with no workaround in pure web code.

### Output paths

Default resolution order:

1. Per-preset override (rare, set in tool JSON)
2. Per-tool override (set in Tools settings → Override output dir)
3. Current project directory (auto when working in a project)
4. Default: `~/scripts/cockpit_data/tools_outputs/<tool>/<timestamp>/`

### Auto-route

Same pattern as Workers. When enabled per-project, agents emit:

    %%TOOL:tool:preset:input_path%%

    # or with extra args:
    %%TOOL:tool:preset:input_path|extra_args%%

## Library, Snippets, Sources

Three right-sidebar tabs hold reference material:

### Library

Long-form reference texts — design docs, specs, project briefs, AI persona descriptions. Stored as markdown files at:

    ~/scripts/cockpit_data/library/

To add: paste content into the chat with a `%%LIB:title%%` marker, or use the agent’s “Save as Library entry” suggestion that follows substantive responses.

To use: click the 📎 attach icon to insert the entry as quoted context in your next prompt.

### Snippets

Short, reusable code snippets — boilerplate, regex patterns, useful one-liners. Same workflow as Library entries.

### Sources

URLs, file paths, or other external references the agent should be aware of. Linked rather than copied — the agent fetches the content fresh each time the source is referenced.

## Search the web

The Search right-sidebar tab provides web search via Brave Search (primary) → DuckDuckGo lite → DuckDuckGo HTML (fallback chain).

1. Open the Search tab
2. Type a query → press Enter
3. Top 5–10 results appear with title, snippet, and link

Two extra buttons:

- B — opens Brave’s AI summary for the query
- D — opens DuckDuckGo Chat for the query

Search results have a fetch button that retrieves the page’s text content and adds it to the chat as quoted context.

## Keyboard shortcuts

Shortcut | Action
--- | ---
Ctrl+Enter | Send prompt to active agent
Esc | Cancel current request / close any modal
Ctrl+F | Search in chat console (or find/replace in editor)
↑ / ↓ | Cycle prompt history (in empty prompt box)
F1 | Context help for element under cursor
? | Open full help guide
F2 | Save selected text to Snippets
F3 | Save selected text to Library
F8 | Open Ollama Model Manager
Double-click chat | Rename chat
Tab (in editor) | Insert 2 spaces
Right-click (chat) | Copy, Select All, Save to Snippets/Library
Right-click (prompt) | Cut, Copy, Paste, Select All, Save

## Troubleshooting

### “Agent not responding”

1. Click the open-tmux button (`open_in_new`) on the agent’s card
2. The tmux session opens — check for error messages
3. If the session is dead, click Restart in the topbar
4. If `cockpit_start.sh` reports an error, check `~/scripts/cockpit.log`

### Stream stalls partway

Caused by:

- Network blip during streaming
- Model running out of context budget mid-response
- tmux session crashed

Click Stop to abort, then re-send. The token cleanup runs every poll so stale state is cleared.

### “Capability not found” after enabling

Capabilities take effect on the next agent session start. Click Restart in the topbar to reload all sessions with the new capability configuration.

### “Worker call failed: HTTP 401”

API key is missing, expired, or invalid. Open Workers settings and re-paste the key.

### “Worker call failed: HTTP 429”

Rate limited — you’ve hit the provider’s per-minute or per-hour cap. Wait or switch to a different provider/model.

### Tool says “Binary not found”

Either:

- Install the binary: `sudo nala install <name>`
- Or paste an absolute path in the Tools settings → Override binary path

After installing, click Detect in Tools settings to refresh.

### Plan execution stops unexpectedly

Check the auto-run mode in Plans toolbar’s tune button. If it’s `approve_destructive` and a step is marked destructive, the orchestrator pauses for confirmation. Click ▶ on the next pending step to continue.

## Configuration files

The cockpit’s runtime configuration is split across these files:

    /var/www/html/cockpit/                     ← Web root (PHP backend + frontend)
    ├─ index.html                              ← UI
    ├─ bridge.php                              ← Stream/poll/cleanup
    ├─ files.php, status.php, ...              ← Other backends
    ├─ capabilities.php, orchestrator.php, ...
    ├─ paths.json                              ← Where cockpit_data lives
    ├─ workers_providers.json                  ← Worker provider catalog (seed)
    └─ tools_builtins/*.json                   ← Tool definitions (seed)

    /home/dario/scripts/                       ← Scripts run by Apache user
    ├─ cockpit_start.sh, cockpit_stop.sh
    ├─ agent_loop.sh                           ← Per-agent dispatch
    ├─ crud_executor.sh                        ← %%CRUD%% / %%TOOL:%% / %%WORKER:%%
    └─ cockpit_data/                           ← Per-user state
       ├─ library/, snippets/, sources/
       ├─ capabilities/_builtin/
       ├─ workers_state.json
       ├─ workers_keys.enc                     ← Encrypted API keys
       ├─ workers_usage.json
       ├─ tools/, tools_outputs/
       └─ tools_state.json

    /home/dario/Software/Programing/LocalAIProjs/   ← Projects root
    ├─ <project>/
    │  ├─ chat_<name>.json
    │  ├─ capabilities.json                    ← Per-project enabled caps
    │  ├─ orchestrator.json                    ← Per-project plan settings
    │  └─ plans/plan_<id>.json

Most files are JSON; edit them directly with `xed` if needed. The cockpit re-reads configuration on each request, so changes take effect immediately (except agent capabilities, which require a session restart).

# Update — June 2026: New features

This section covers features added after the original guide. Everything here is local-first and offline unless noted.

## Directives (the “Rules” button)

Global standing rules that are prepended to every supplier’s context at dispatch — Claude, Gemini, Ollama, and text Workers alike. Write once; they apply everywhere.

- Open with the Rules button (top bar).
- Full directives go to Claude/Gemini; a Compact variant is used for tiny Ollama models so a long preamble doesn’t crowd out the task.
- Tick which suppliers use the compact variant.
- Per-project rules still live in each project’s `COCKPIT.md` and layer on top.
- Stored in `cockpit_data/directives_global.md` (+ `_compact.md`, `_config.json`).

## Voice input (offline)

The 🎤 Voice button records your microphone and transcribes it locally with whisper.cpp — audio never leaves the machine.

- Language dropdown: pick `HE` to force Hebrew (otherwise it can be mistaken for Arabic); `Auto`/`EN`/`ES` for the rest.
- Model dropdown: lists your installed whisper models (bigger = more accurate; `Auto` uses the largest). The button tooltip shows the active model.
- The transcript drops into the prompt box, editable before sending.
- Requires whisper.cpp + a ggml model (see the Setup Guide).

## Effort and JSON-driven supplier controls

Each supplier card’s dropdowns are driven by a JSON file, so options can be changed without touching code.

- Model dropdown — the value is the real CLI model string.
- Effort dropdown (Claude) — passes the real `claude --effort <level>` flag: `low, medium, high, xhigh (Extra), max`.
- The tune ⚙ button on a card opens its control file (`cockpit_data/claude_controls.json` / `gemini_controls.json`) in the editor. Add an option to the `options` array, Save, and it appears in the dropdown.

## The floating code editor

Snippet/source/file editing now uses a draggable, resizable floating editor with:

- Syntax highlighting (Prism, offline) for Pascal/PHP/Bash/JS/JSON/YAML/CSS/HTML, themed to your current cockpit theme.
- Find & replace (Ctrl+F), line numbers, word wrap, a language picker (with custom suffix), Tab = 2 spaces, and Save / Save as….
- Used by the Files tree, Library/Snippets/Sources, and the Capabilities editor.

## Capabilities — now GLOBAL

Capability enablement is a single global on/off per capability — it applies to all projects, free chats, and every supplier the capability declares (the CLAUDE/GEMINI/OLLAMA badges are informational, set by the capability’s `CAP.json`).

- Built-ins default ON; user capabilities default OFF.
- User capabilities have edit (opens `CAP.json` in the editor) and delete.
- Enabling an MCP capability stages the server config that Claude/Gemini load on their next session (restart the agent for it to take effect).
- Example included: a `time` capability (uvx `mcp-server-time`).

## Workers — Discover and pick-and-add

In Workers settings, Discover probes each provider’s `/models` endpoint and shows the full list. Click + next to a model to make it selectable (it’s added to that provider, text kind). A filter box narrows long lists.

## Help system

See Comprehensive help system below for the full, current description.

## Scheduler — orphan recovery

A scheduled job left “running” for more than 15 minutes (its worker died) is now auto-marked failed, so the Jobs badge no longer shows stale “running” counts.

## Paid API workers + spend-safety gate

The same provider can be reached two ways: as a supplier (CLI subscription, via tmux — Claude, Gemini, Ollama) and as a worker (HTTP API, BYOK). Alongside the free-tier workers (Groq, OpenRouter, …) you can now add three paid API workers: OpenAI (ChatGPT), Claude (Anthropic API), and Gemini (Google API). The CLI supplier roles are untouched — this is purely additive.

Because these cost real money per call, they sit behind a deliberate safety stack (all enforced server-side, so no UI state can bypass it):

1. Global consent (default OFF). In Workers settings → Paid API spend, “Turn ON…” opens a consent modal (real money, BYOK, best-effort caps, revocable). Until you accept, no paid provider can be enabled or called.
2. Per-provider enable. Even with consent ON, each paid provider is still OFF until you enable it individually (and paste its key). Paid providers show a 💲 PAID API badge; their toggle is locked until consent is given.
3. Spend caps (monthly). Set a global cap and optional per-model caps. A call is blocked if it would breach either. Caps are best-effort — the exact cost isn’t known until a call returns, so spend can overshoot by about one call. The panel shows “Spent $X of $Y” with a warning near 80%.
4. Dual usage. A provider reachable as both CLI and API shows as separate lines — e.g. “Claude (CLI)” vs “Claude (Anthropic API)” — so you always know which budget you’re burning.

Why bother: a free/alternate API key can pick up when your paid CLI subscription hits a limit, and a Broadcast can fan out across mixed-cost providers at once.

> Pricing is editable per model (via the provider’s controls); until provider cards carry pricing, edit the input/output rates in the worker config.

## Context menus

Cockpit replaces all native browser right-click menus with themed, app-native context menus that follow the active theme.

### Chat panel (right-click on selected text)

- Copy — copy selection to clipboard
- Select All — select all chat text
- Save to Snippets — save selection as a code snippet
- Save to Library — save selection as a library reference

### Prompt area (right-click)

- Cut — cut selected text (when text is selected)
- Copy — copy selected text
- Paste — paste from clipboard
- Select All — select all prompt text
- Save to Snippets / Library — when text is selected

### Special right-clicks

- Ollama usage bar → Reset Ollama session stats
- Workers usage bar → Reset Workers usage counters
- Time button → Open time report

Input fields (text inputs, textareas, dropdowns) retain the native browser menu for paste and spell-check.

## Themed confirm & prompt dialogs

All `confirm()` and `prompt()` browser dialogs have been replaced with Cockpit-native modals that follow the active theme.

- cockpitConfirm(title, message) — async, Promise-based. Returns `true`/`false`.
- cockpitPrompt(title, message, placeholder) — async input modal. Returns the typed string or `null`.
- cockpitChoice(title, message, options) — multi-option modal for scope selectors (e.g., Project vs Global).

All modals use CSS variables (`--bg-base`, `--border-mid`, `--text-base`, `--accent-*`) — they adapt to every theme automatically, including dark, light, and custom themes.

## Plan Re-Run

Completed, halted, or failed plans now show a Re-Run button in the plan toolbar. Clicking it resets all steps to "pending" and restarts execution from step 1. Previous step results are cleared. Confirmation is required before re-running.

## Spend-cap warnings

When paid API spend reaches 80% of any configured cap (global or per-model), a system message warns you in the chat. Warnings are checked after every paid API call and include the current percentage and cap value.

## Ollama runtime knobs

The Model Manager (F8) now includes a runtime knobs panel at the bottom:

Knob | Default | What it controls
--- | --- | ---
`keep_alive` | 5m | How long models stay loaded in memory after last use
`num_ctx` | 4096 | Context window size in tokens (higher = more VRAM)
`num_parallel` | 1 | Concurrent requests per loaded model
`max_loaded` | 1 | Maximum models loaded simultaneously

Click Save knobs to persist to `cockpit_data/ollama_config.json`. Values are read by `agent_loop.sh` on session start via environment variables (`OLLAMA_KEEP_ALIVE`, etc.). Restart agent sessions for changes to take effect.

## Model Manager enhancements

- Probe — test if a model supports tool calls via a 4-check pipeline (health → model present → Messages API → tool-call round-trip). Result: AGENTIC CAPABLE or NOT AGENTIC.
- Variant — create an agentic-tuned variant with custom Modelfile parameters (num_ctx, temperature, repeat_penalty). Variants are tagged with an AGENTIC badge in the model list.
- Browse — search a curated catalog of popular Ollama models. Click to pull directly.

## Media generation

Generate media locally using your GPU — no internet, no cost.

Type | Engine | Time | Output
--- | --- | --- | ---
Image | stable-diffusion.cpp (SD 1.5) | ~20 sec | PNG with presets: Logo, Icon, FavIcon, Background, Image
Sound | Piper TTS | ~5 sec | WAV spoken audio from text
Video | sd.cpp + ffmpeg | ~2-3 min | Animated GIF from varying-seed frames

Results appear inline in the chat with Save/Download/Delete buttons. All files go to `cockpit_data/generated/`.

## Translation

Translation uses local LibreTranslate — no data leaves your machine.

- Translate chat — translates all messages in the current chat. Code blocks are excluded (preserved as-is). Pick source and target languages.
- Translate text — opens a free-text translation box. Paste any text, pick languages, translate. Result can be copied or inserted into the prompt.

## Time tracking

The Track button starts/stops a timer for the current project.

- Click to start. Click again to stop.
- The button shows elapsed time while tracking.
- Right-click → Time report: view logged entries with delete.
- The counter in the top-right shows total tracked minutes for the session.

## Terminal, Files, Browser

Three toolbar buttons provide embedded panels without leaving Cockpit:

- Terminal — full interactive shell (bash/zsh). Resizable panel below the chat. Output is captured for reference.
- Files — file browser for the current project directory. Click files to preview in the right sidebar.
- Browser — embedded web browser. Useful for checking docs, testing local dev servers, or viewing generated HTML.

## Accumulator

Extracts reusable knowledge from PDFs and documents using a local pipeline:

1. Extract — PDF → text (pdftotext, tika, or Ollama OCR fallback)
2. Chunk — split into overlapping segments
3. Summarize — Ollama generates a summary per chunk
4. Store — results saved as JSON for retrieval

Panel tabs: Queue (pending files), Results (processed documents), Health (pipeline checks). Click Run to process. Progress is shown live.

## Skills system

Skills are reusable prompt templates with auto-trigger capability.

- Open Skills manager → + New. Each skill has: Name, Description (with coach scoring), Tier (priority), and Content (prompt template with variables).
- Auto-trigger — when enabled, skills auto-fire based on keyword overlap + trigram similarity against your prompt. The best match above threshold is injected.
- Folder skills — defined as `SKILL.md` files in `cockpit_data/skills/<name>/` directories with YAML frontmatter.
- Built-in: Plan-and-Sequence skill teaches the planner to emit atomic, verifiable steps for weak local model execution.

## Summarize

The Summarize button generates a summary of the current chat session using the active agent. The summary appears as a new message. Useful for creating a recap before switching tasks or sharing context.

## Caveman mode

The Caveman toggle (bottom-right of prompt area) controls token compression for online suppliers (Claude, Gemini, Workers). Ollama (local) is never affected.

Level | Effect | Savings
--- | --- | ---
Off | Normal prompts and responses | —
Strip | Removes filler words, articles, pleasantries from your prompt before sending | ~30%
Strip+AI | Strip mode + asks the agent to respond in terse caveman style | ~60-75%

## Themes & theming

- Several built-in themes (dark, light, mixed). Switch via the theme toggle button.
- Theme Editor — full color editor with grouped pickers: backgrounds, text, borders, agent colors, accents. Live preview in a sandbox strip.
- Apply (session), Save As (persist), Delete (user themes only).
- Import VS Code themes — paste a .json VS Code theme; colors map automatically.
- Export/Import — transfer all themes as JSON between machines.
- Protanopia-safe — no red/green-only indicators. Blue, cyan, amber, orange, violet palette.
- All UI elements follow the theme: modals, context menus, confirm dialogs, sidebar tabs, code blocks, data bars.

## Typography controls

- − / + buttons (bottom toolbar) — change font size by 1px.
- Tt Aa button — full typography panel (font family, line height, spacing).
- B / I / U toggles (right sidebar footer) — bold, italic, underline for console text.
- All settings persist in localStorage.

## Comprehensive help system

The help system has been expanded to cover every Cockpit feature:

- 75+ topics organized by area: suppliers, modes, styles, prompt, chat, plans, workers, tools, skills, models, account, marketplace, and more.
- F1 context help — hover over any element and press F1 for context-specific help. Uses `data-help` attributes across the UI (an ancestor's attribute covers all its children, so most panels are wired via one attribute on the panel itself).
- Search bar — filter topics by title and content with highlight matching.
- Walkthrough button — 40+ step guided tour of all features.
- Settings button — comprehensive reference for every settings surface.
- Resizable and movable — drag the title bar to reposition; resize from edges/corners. Position and size persist across sessions.
- Setup Guide button — opens this guide's install/setup companion in a new tab.

## Power Combos (Tier 0)

Multi-model recipes — several small local models run together on one task and merge into a single answer, instead of one model answering alone. Works with Ollama models, LocalAI models, or a mix of both (see "Dual-mode" below). 705 combos across 8 categories — 150 free (50 per backend: Ollama, LocalAI, Dual) plus 555 premium (185 per backend, Content-tier). Full per-combo descriptions live in `cockpit_data/ Cockpit_AllCombos_Reference.md` (quick lookup table) and `Cockpit_AllCombos_Explained.md` (detailed rationale per combo) — too long to usefully inline here.

### Patterns

Pattern | What happens
--- | ---
Parallel | Several models answer the same prompt independently; results shown side by side (or merged).
Sequential | Models run in a chain — each sees the previous step's output.
Judge | Parallel candidates, then a judge model picks/synthesizes the best answer.

### Using combos

The Ollama and LocalAI dropdowns each have their own combo catalog and identical layout — a master row (total count, filter box, "+ new", ⊟/⊞ collapse-all), a categorized Combos section (★ favorites + one group per category, same 8 categories either side), a Needs both backends section for combos whose steps mix both servers (merged — a dual combo shows up in both dropdowns regardless of which catalog it's actually saved in), then the model list. Ollama's catalog is `combos_ollama.json`; LocalAI's is `combos_localai.json`; Dual's is `combos_dual.json` (merged into both single-backend views too) — same schema, same editor, kept separate since a "combo" is really "a recipe of model names," and the backends don't share model names.

1. Select the Ollama, LocalAI, or Dual card as active (Card 3).
2. Pick a combo from whichever panel's own combo section — filter box + ★ favorites + category groups, same in both.
3. Type your prompt and send as normal — the combo runs instead of the single selected model.
4. Combos needing models you haven't pulled are greyed out and unselectable; hovering shows exactly which model is missing from which backend. A combo you authored yourself stays editable even while it's missing a model — that's what Edit is for.
5. Category groups collapse/expand — click a group header (or ⊟/⊞ all in the master row) to hide/show its combos. Collapse state persists across reloads. With 8 categories, browsing collapsed-by-default is usually easier than one long list.

### Dual-mode (Ollama + LocalAI together)

Both Ollama and LocalAI run at the same time — installing AI Cockpit sets up both, no separate choice needed. A combo can mix steps from both: each step in a combo carries a small O/L tag showing which server it runs on, and steps tagged for different servers genuinely run in parallel (not switched back and forth) when the combo's pattern allows it. Before a combo runs, a quick pre-flight check confirms every server it needs is actually reachable — if one isn't running, you get a clear "X not reachable" message instead of a partial, confusing failure partway through.

### Dual-model regular chat (not just Combos)

The same idea works outside Power Combos too. Card 3's model list shows every Ollama model and every LocalAI model together — pick one of each and both stay loaded at once, VRAM permitting. Picking a third model while both slots are full triggers a real fit-check: if the two wouldn't fit together in your detected VRAM, the other slot is freed automatically instead of silently over-committing.

With only one model picked (either backend), chat works exactly as before — nothing changes unless you actually fill both slots. With both filled, sending a prompt first asks each model to rate its own confidence (a quick 1–10, not a full answer) — you'll see both scores, then choose: use one model's answer, or run both together as parallel / sequential / judge, the same patterns Combos use.

Known limit: LocalAI has no confirmed reliable "unload model" API, so clearing its slot updates the app's own tracked state honestly but can't guarantee the model actually leaves memory yet — the UI says so right next to the LocalAI chip.

### Free vs. protected combos

The 150 free combos ship plaintext across `combos_ollama.json`, `combos_localai.json`, and `combos_dual.json` — no account needed, works on any machine. The other 555 (and any future curated packs) are encrypted at rest in `combos_store.enc`, the key derived from this machine's ID + your account's license key — a copied file is inert on someone else's install. This stops casual copying/redistribution; it doesn't and can't stop a determined person reverse-engineering a combo's idea by watching it run — that's an accepted, honest limit shared by every local-execution product, not a Cockpit-specific weakness.

If a protected pack exists on disk but fails to decrypt (wrong machine, expired/missing license), Tier-0 shows an amber warning instead of silently returning fewer combos.

### Your own combos

Click ＋ new in either panel's master row to build your own — id, name, pattern, category (pick one or type a brand-new one, which creates that group on the fly), description, and steps. Each step has its own model dropdown (populated from your actually-installed Ollama and LocalAI models — not free-text, so you can't accidentally reference a model you don't have) and its own backend picker (Default / Ollama / LocalAI) — set different steps to different backends and you've built a dual combo, which then shows up under Needs both backends in both panels. Add a judge model + instructions for judge-pattern combos, same dropdown-driven picker. Saved instantly as plain JSON, never encrypted — it's already yours, nothing to protect you from. Edit (✎) or delete (🗑) anything tagged · mine — the edit icon works even when the combo is currently missing a model, since that's exactly when you'd want to open it and fix the model pick.

Publish to the Marketplace (Account panel → Marketplace → ⊕ Publish → kind My Combo, pick one of yours) to let others download it — requires a Content-tier subscription, same as publishing a Skill or Tool, and earns the same give-back credit on both downloads and usage. Unlike the admin-curated 185, your published combos are not admin-gated — publishing your own combos has always been open to any Content-tier subscriber.

Downloading someone else's combo merges it into your own Tier-0 (tagged · by <name>). Before it downloads, Cockpit checks each of its models against your actually-installed Ollama and LocalAI models (each model checked against the specific backend it actually runs on, for a mixed-backend combo) and shows which you're missing, so you can back out instead of downloading something you can't run yet — the same missing-model check already applies after download too (a combo needing an unpulled model just shows greyed-out, hover for which model is missing from which backend — whether it's built-in, protected, or user-authored). Published something by mistake? The 🌐✕ icon on your own published combos pulls it from the Marketplace; your local copy stays.

## Delegate — task auto-routing

Standing rules that automatically hand off matching tasks to a different supplier/model/combo before the normally-selected agent continues — the delegated result gets folded into your prompt as context, then the original dispatch proceeds. Works identically no matter which mode (Single/Pipeline/Broadcast/Plan/Combos) is active, since every prompt funnels through one shared dispatch point.

Not the same as the Rules (Directives) button — Directives inject static context into every prompt for every supplier; Delegate routes specific tasks to a different supplier.

### How a task gets matched

1. Keyword/phrase — set when you create the rule. Fast, free, exact.
2. Small local model fallback — if no keyword hits (or several rules could apply), a tiny Ollama model classifies the task.
3. Ask you — if the model isn't confident either way, you're shown the candidate rules to pick from (or "none — continue normally").

### Delegation targets

Worker (REST API provider), Power Combo, or a specific Ollama model. Tool-kind targets are file-in/file-out (ffmpeg/whisper/etc.) and aren't supported for automatic prompt delegation — that needs a file attached first, a different flow.

### Setting up a rule

Toolbar → Delegate → + New Delegation Rule → name it, list keywords/phrases (comma-separated), pick what it delegates to. Toggle rules on/off or delete them from the same panel.

## Multiple local users

One Cockpit install can serve several people (family, work profiles) with fully separate data — not just a login screen, genuinely separate tools/skills/combos/chat history/Cockpit Account subscriptions per person.

### Managing users

Account card (top-right of the supplier strip) → Users button opens the User Manager: add a new local login (username + password + role), see who's registered, remove one. Each local user gets their own data folder automatically on first login — nothing to configure.

### Switching users

Sign out (account card) and the next person logs in with their own credentials. Switching users tears down any running agent sessions in the background — the incoming user starts clean and clicks Start themselves; live agent sessions (the tmux processes) are still machine-wide, not per-user, so this avoids landing mid-conversation in someone else's chat.

### Change password

Same account card → Pass button — changes the local login password (not your Cockpit Account/SaaS password, which is separate — see below).

## Cockpit Account & Marketplace

Your online AI Cockpit account — separate from the local login above. Click the license status text (top-left) or the account chip (top-right of the supplier strip) to sign in, register, or manage it. Local features never require this — it's purely for the online/shared-content layer (marketplace, subscriptions, credits).

### Tiers

Free / Content / Everywhere / Combined — shown as a chip next to your account name. Content unlocks marketplace downloads of paid items and premium Power Combo packs; Everywhere unlocks remote-control relay to this machine from another device.

### Marketplace

Browse and download community skills/tools/themes/prompts/worker cards/pipelines, and Power Combos. Downloads install straight into the matching local panel — no manual file placement. ＋ Publish lets you share something you made (combo publishing is admin-curated, not open upload).

### Account portal

Profile, registered machines (deregister old ones), credits balance (from the revenue-share program, if you've published earnable content), and subscription/renewal choice (pay from credits vs. card).

### Several SaaS accounts, one machine

Change user (account modal) switches between several registered Cockpit Accounts on this machine without re-entering credentials — a roster, separate from the local-login "Users" feature above (you can have several local logins AND several SaaS accounts; they're independent systems).

## Supplier Slots — CLI aliasing

Card 1 ("Claude") and Card 2 ("Gemini") aren't hardwired — each slot can be reassigned to a different paid CLI supplier (e.g. Codex, Qwen Code) or, for Card 2, a free REST fallback (Groq, etc.).

### Reassigning a slot

Gear/tune icon on the supplier card, or the Slots button on the account card. Pick a different supplier from the catalog (`cli_suppliers.json`, user-editable) — the card's displayed name, its model dropdown, the status pill, and the "Open CLI in terminal" button all follow the assigned supplier automatically.

A REST-only fallback (no local binary) hides the CLI-launch button automatically; a genuine CLI alias (has a binary) keeps it, retitled.

Card 3's slot works the same way, with its own option list: Ollama, LocalAI, or Dual — Ollama + LocalAI. Picking plain Ollama or plain LocalAI gives you that one backend only, same as before this option existed. Picking Dual is what turns on everything described above under "Dual-mode" and "Dual-model regular chat" — the merged model list, the O/L chips, and mixed-backend combos. Switching away from Dual hides all of that again and restores the single-backend picker.

## Background Tasks & Scheduler

### Background Tasks

Long-running autonomous goals that keep working while you do something else — set a goal, Cockpit keeps making progress on it in the background instead of blocking the console for one prompt at a time.

### Jobs (Scheduler)

Cron-driven recurring tasks (e.g. "summarize new files every night at 2am") — separate from the Orchestrator's own one-off "Schedule" option inside Plan mode, which is for scheduling a single plan, not a repeating job.

## Transcriber

Batch audio/video → text extraction (local whisper.cpp), beyond the quick mic-dictation button in the prompt bar. Analyze a file, compile the transcript, download it, or export as HTML.