OwnAI — User Manuals

Generated: 2026-07-12

Table of Contents

  1. Loading a Local AI Model
  2. Connecting Cloud AI
  3. Running Local and Cloud Models in Parallel
  4. Chat Modes Guide
  5. Creating and Managing RAG Collections
  6. Ingesting & Querying Files in RAG
  7. Managing Memories
  8. Using Agent Memory in Chat
  9. Agent Mode
  10. Web Search Mode
  11. Batch Processing
  12. File Attachments and @-Context Pins
  13. Composer Tab
  14. Image Analysis and Screenshots
  15. Hybrid Image Analysis Mode
  16. Image Generation
  17. Agent Skills (SKILL.md)
  18. Cloud Privacy Gate
  19. MCP Integration
  20. General Settings & UI Customization
  21. Product Backlog Manager
  22. Audio (TTS & STT)
  23. Recurring Jobs
  24. GitHub Tab
  25. Explorer Tab

Loading a Local AI Model

Opening the Model Manager

Access the Model Manager via the main sidebar icon (chip symbol) or View > Model Manager. This panel handles all local inference assets.

Supported Formats & Prerequisites

OwnAI supports GGUF (recommended for llama.cpp) and Safetensors (Hugging Face standard).

  • RAM: Minimum 8 GB for 7B models; 16+ GB recommended.
  • GPU: Optional but highly recommended for speed. Ensure drivers are up-to-date.

Step-by-Step Loading

  1. In the Model Manager, click Browse Folder and navigate to your model directory.
  2. Select the desired .gguf or .safetensors file.
  3. Click Load AI. Progress bar indicates memory allocation.
  4. Verify success: the top header bar will emit a subtle green glow.

Unloading and Switching Models

To free VRAM/RAM, click Unload next to the active model in the manager. To switch, simply select a new file from your history or browse again; OwnAI auto-unloads the previous model before loading the new one.

Practical Tip & Common Mistake

  • Tip: Use Q4KM quantized GGUF files for the best balance of speed and quality on consumer hardware.
  • Mistake: Loading multiple large models simultaneously. OwnAI only supports one active local inference backend at a time; always unload before loading another.

Connecting Cloud AI

Accessing the Cloud AI Manager

Open Settings → Cloud AI Manager to configure remote model backends. Here you select your preferred provider (e.g., OpenRouter, Anthropic), enter the specific Model ID, and paste your API key.

Connecting and Testing

Click Test Connection to validate credentials without starting a session. Once verified, click Connect Cloud AI to activate the backend. Use Disconnect to safely terminate the session when finished.

Local vs. Cloud

  • Load AI: Runs models (GGUF/Safetensors) entirely on your hardware. Zero latency, fully private, free after download.
  • Connect Cloud AI: Streams responses from remote servers. Accesses cutting-edge models but requires internet and API credits.

API Key Storage & Fallbacks

ownAI stores your keys encrypted in your local Windows user profile for security. As a fallback, the app automatically reads standard environment variables (OPENAIAPIKEY, ANTHROPICAPIKEY, OPENROUTERAPIKEY) if no key is set in the UI.

💡 Pro Tip & ⚠️ Common Pitfall

Tip: Use OpenRouter as your provider to access dozens of models (Claude, GPT, Llama) using a single API key. Pitfall: Never commit your API keys to version control. If you paste them into a script or config file, ensure that file is in your .gitignore.

Running Local and Cloud Models in Parallel

OwnAI supports dual-slot operation: one local model and one cloud model active at the same time.

Dual-Slot Concept

SlotStatus IndicatorPurpose
loadedlocalllmGreen header glowPrivacy-first, offline, zero cost
connectedcloudllmRed header glowHigh capability, cloud API

Active Backend for Chat

When both are loaded, ownAI uses the cloud backend by default. The local model remains available in the background for quick fallback.

Fast Switch to Local

To fall back instantly: click Disconnect Cloud AI. ownAI switches to the local model immediately — no reload or re-initialization needed. Reconnect cloud anytime via Settings → Cloud AI Manager.

When This Setup Shines

  • Local: sensitive documents, draft code, offline work (privacy + cost-free)
  • Cloud: complex reasoning, large context, agent-heavy tasks (raw power with anonymization of private data and secrets)

Auto-Start Settings

In program_settings.json:

  • autostartllm: loads your local model on app launch
  • autostartcloud_ai: connects your cloud backend on app launch

Enable both for a ready-to-go dual-slot session from startup.

OwnAI Chat Modes Guide

OwnAI offers four distinct modes tailored to different tasks. Switch between them using the Mode Selector dropdown in the main chat toolbar.

Mode Breakdown

  1. Chat: Localk semi automatic chat mode with full control. Use for general Q&A, private data or brainstorming. The chat mode is without tools (no agentic loop) and if you wish you can still use web search and image generation functionalities by toggling the coresponding buttons.
  2. RAG (Retrieval-Augmented Generation): Answers based on your uploaded documents. Use when querying project files, manuals, or notes. Toggle the RAG switch in the toolbar. Adds semantic search results from ingested local documents.
  3. Memory: Long-term knowledge retention. Use for storing persistent preferences, project goals, or recurring facts. Toggle the Memory switch. Adds recalled long-term memory blocks to context.
  4. Agent (Coding): Autonomous workspace interaction. Use for writing code, debugging, running tests, or managing git. Select Agent in the Mode Selector. Note: Switching to Agent mode automatically hides RAG, Attachments, and Web toggles, as the agent manages its own tool context.

Comparison Table

ModePrimary Use CaseContext AddedActivation
ChatGeneral Q&AConversation HistoryDefault selection
WebLive InfoFetched Web PagesToggle Web Search switch
RAGDocument QueriesIngested File SnippetsToggle RAG switch
MemoryPersistent FactsLong-term Recall BlocksToggle Memory switch
AgentCode & TasksWorkspace Tools & FilesSelect Agent dropdown

Pick Guide

Use Chat for quick thoughts, RAG/Memory/Web for specific information retrieval, and Agent when you need OwnAI to actively execute tasks or modify your workspace files.

Creating and Managing RAG Collections

A RAG collection is a ChromaDB-backed knowledge base that stores embeddings of your documents, enabling semantic search within OwnAI. For not IT guys: you can virtualize the content of a text, word, pdf etc. into a collection and ask questions against it. Talk with books, video transcripts, documents and much more.

Opening the Document Manager

  1. Navigate to Explorer → Document Manager.
  2. Click Add Collection to create a new knowledge base.

Naming and Organizing

  • Use clear, project-specific names (e.g., woodworking-plans, civics-notes).
  • Keep related documents in one collection to maintain high retrieval relevance.

Managing Collections

  1. Rename: Right-click a collection and select Rename.
  2. Delete: Right-click and select Delete (removes all associated embeddings).
  3. View Details: Click a collection to open the Collection Details panel, showing document count, total tokens, and last update time.

Linking to Explorer

Collections are automatically linked to the Explorer Chroma Table. You can inspect raw vectors or delete specific chunks directly from the table view for fine-grained control.

Pro Tip

Regularly prune outdated documents to prevent retrieval noise. Use the Collection Details view to monitor token usage before hitting embedding limits.

Ingesting & Querying Files in RAG

Supported Formats

OwnAI ingests PDF, DOCX, TXT, MD, CSV, JSON, and plain code files. Ensure documents are text-readable (scanned images require OCR first).

Adding Documents

  1. Open the Document Manager (sidebar icon).
  2. Select or create a target collection.
  3. Click Add Files, choose your documents, and confirm.
  4. Watch the progress bar as OwnAI chunks and embeds your files into ChromaDB. Wait for completion before querying.

Querying via RAG Chat

  1. Create a new chat in RAG mode.
  2. Select the collection you want to interact with from the collection/file table and click Use Selected or double click on it.
  3. In the new RAG chat yu can type your question and only context from the selected colelction will be used to answer the question.
  4. Answers will include inline citations (e.g., [Source: manual.pdf]) linking directly to the retrieved chunks.

Updating Content

If you edit source files, RAG won't auto-update. Right-click the file in the Document Manager and select Re-ingest to refresh embeddings.

Pro Tip

Use specific keywords or exact phrases from your documents in your prompt. Vague questions yield broader, less accurate retrievals; precise queries match chunks faster and output quality increases.

Managing Memories in OwnAI 1.5

Opening the Memory Manager

  1. Click the Memory icon in the main sidebar or navigate via Tools → Memory Manager.

Collections & Entries

Memories are organized into user-defined categories. This structure lets you cleanly separate personal notes, engineering specs, and project preferences.

Managing Memories

  1. Add: Click New Memory, type your note, assign a category, and save.
  2. Edit/Change Category: Double-click an existing entry to modify the text or reassign its category.
  3. Search: Use the top search bar to instantly filter entries by keyword.
  4. Delete: Select one or multiple memories and click the trash icon to remove them permanently.

Manual vs. Agent Auto-Memory

  • Memory Manager entries are manually created, persistent notes that you fully control.
  • Agent auto-memory is generated automatically by the Coding Agent during active tasks (e.g., environment quirks, learned workflows). These appear in a dedicated agent_auto category and are managed internally by the agent.

Using Agent Memory in Chat

Agent memory lets you store and retrieve personal facts, preferences, and project decisions across sessions.

Natural-Language Commands

Use plain English in any chat:

  • Store: "Remember that I use metric units for all woodworking plans."
  • Recall: "What do you remember about my preferred wood finishes?"
  • List: "Show me all saved memories."
  • Update: "Update my memory: I now prefer walnut over oak."
  • Forget: "Forget everything about the old router project."

What Gets Stored

Preferences, design decisions, tool choices, and recurring project facts — anything you want the agent to retain between conversations.

Auto-Recall

When codingmemoryauto_recall is enabled (default in balanced/aggressive profiles), relevant memories are injected automatically at turn start. In safe profile it stays off for full transparency.

Memory vs RAG

  • Memory = lightweight, user-curated facts and preferences. Use for personal context.
  • RAG = document-backed knowledge base (PDFs, manuals, specs). Use for reference material.

Privacy

All memories are stored locally in your user_data/ folder. Nothing is sent to cloud providers.

Agent Mode

Setup

  1. Launch a new chat with the Mode Agent. It includes access to 100+ native tools, MCP servers, SKILLS, and customizable system prompts per mode. See Settings > Prompt Manager for configuration options.
  2. Select a workspace folder to start an agent chat. The agent will operate within this directory and have full access to its contents. You can choose an existing folder or create a new, empty one from scratch.

Capabilities

The agent acts as an autonomous helper & developer inside your workspace:

  • File handling: Read, create, and patch files safely (Powerpoint, Word, Excel, HTML Dashboards, ODT and many more formats).
  • DevOps: Run tests, lint code, execute shell commands, and manage Git (commits, branches, PRs).
  • Context Tools: Query RAG collections, recall agent memory, and analyze attached @-pinned files or images.
  • Reoccuring Jobs Run jobs with defined prompts and automate your tasks.
  • Image creation If you connect OwnAI to a cloud image model via API key, you can generate high-quality images directly from the app. This feature is entirely optional — skip it if you prefer to stay fully local.

Configuration & Safety

  • Profiles (coding_profile): Choose safe (strict confirmations), balanced (default), or aggressive (fewer prompts for speed).
  • Confirm Dialogs: Depending on your profile, the agent will ask permission before writing files or running terminal commands. Review carefully.
  • Project Rules: Drop an AGENTS.md in your workspace root to give persistent instructions (e.g., coding standards, preferred libraries).

Tip: Click on pin button to pin specific files for immediate context without searching.

Web Search Mode in OwnAI 1.5

Enabling Web Mode

Toggle Web in the chat toolbar before sending a prompt.

How It Works

OwnAI sends your query to DuckDuckGo, fetches the top results, and extracts clean text from the linked pages. This live context is injected into the LLM alongside your prompt.

Source Citations

Answers include inline citations linking back to the exact web pages used, so you can verify facts instantly.

Token Budget Impact

Extracted web text consumes a portion of your context window. Heavy searches may truncate older chat history to fit the new context.

Web vs RAG vs Agent Tool

  • Web Mode: Best for quick, live questions (news, current tech specs).
  • RAG Mode: Use for querying your own private documents and local knowledge bases.
  • Agent web_search tool: Used automatically by the Coding Agent when it needs to look up documentation or errors mid-task.

⚠️ Privacy Note

Web search queries are sent to DuckDuckGo servers and leave your machine. Avoid searching for highly sensitive personal data or proprietary code snippets when the web search toggle is activated (glow).

Batch Processing: Load Prompt File & Message Queue

Overview

The Load Prompt File feature lets you queue multiple prompts from a single file and send them sequentially. Ideal for testing prompt chains, benchmarking responses, or automating repetitive queries.

Supported Formats & Parsing Rules

  • Formats: .md (Markdown) and .txt (Plain text).
  • Splitting: The parser splits content into separate queue entries at double newlines or Markdown headers (##, ###).
  • Fenced blocks: Code fences (```) are preserved intact within their entry and never split across messages.

Step-by-Step

  1. Click the Load Prompt File icon (batch/stack symbol) in the chat toolbar.
  2. Browse and select your .md or .txt file.
  3. Parsed prompts populate the Message Queue sidebar. Preview each entry to verify splitting.
  4. Press ▶ Play to send messages sequentially. Use ⏸ Pause, ⏭ Skip, or drag to reorder.

Queue Management

  • Clear queue: click the trash icon.
  • Edit entries inline before sending.
  • Progress indicator shows current/total prompts.

File Attachments and @-Context Pins

What Are @-Pins?

@-pins ground the AI in your actual workspace files. Instead of guessing, the model reads pinned content directly before answering or coding. You can quickly pin a file and ask questions about it directly, without creating a RAG collection or re-uploading the file every time.

Adding Files

  1. Drag & Drop: Drop files onto the chat input area.
  2. Selected files appear as removable chips above the input box. They persist until you unpin or send the message.

Supported Formats

  • Code & Text: .py, .js, .md, .txt, .json, .xml (read verbatim)
  • Documents: .pdf, .docx, .pptx, .xlsx, .rtf (parsed via built-in extractor)

Context Injection & Budgets

When sent, ownAI prepends an ### Attached context (@-pins) block to your prompt:

  • Excerpts: Files are read up to a per-pin character limit. Large documents are truncated or summarized to fit.
  • Smart Budgeting: Total pin context caps at ~480k characters. The budget divides evenly across pinned files; more pins = smaller excerpts per file.
  • Grounding Footer: The agent receives explicit instructions to cite pinned paths in tool calls and verify excerpts before editing.

Best Practices

  • Pin selectively: Only attach files directly relevant to the current task. Over-pinning dilutes context with noise.
  • Max 24 pins: Keep batches small for optimal token usage.
  • Live state: Pins capture the file state at send time. Re-send if you edit a pinned file locally afterward.

Composer Tab: Live Agent Inspector

The Composer tab is a read-only dashboard visible only in Agent mode. It lets you monitor active coding agent runs in real-time without interrupting execution.

Location & Visibility

Located in the left sidebar, the Composer tab appears automatically when you switch to Agent mode and starts tracking as soon as an agent run begins.

Timeline Pane

  • Displays every agent step chronologically, showing tool names and status indicators.
  • The header includes the task title, a running mm:ss timer, cumulative token usage, and a Stop button to halt the agent.
  • Click any timeline row to instantly jump to the corresponding message in the main chat view.

Files Pane

  • Lists all files the agent reads, writes, or modifies during the session.
  • Click the diff icon next to a file path to open a unified-diff viewer, highlighting exactly which lines were added, removed, or changed.

Multi-Session Support

  • The Composer tracks multiple concurrent agent runs across different chats. A ·N badge in the tab title indicates N active sessions.
  • Use the session combo box at the top to switch between live runs instantly without losing your place.

Tip

  • Tip: Keep the Files pane open to visually verify code patches before asking the agent to run tests or commit changes.

Image Analysis and Screenshots in OwnAI 1.5

Uploading Images

  • Drag-and-drop or click the attachment icon in the chat input to upload images (PNG, JPG, WEBP).
  • Requires a vision-capable model or cloud multimodal endpoints.
  • Images are injected directly into the conversation context for immediate analysis.

Taking Screenshots

  • Click the camera icon in the chat toolbar to capture your screen or active window.
  • Ideal for UI debugging, transcribing error messages, or documenting physical builds (like woodworking joints!).
  • Screenshots are queued locally as attachments without external uploads.

What It Can Do

  • OCR & Text Extraction: Read text from photos, schematics, or printed manuals.
  • Code & Terminal Analysis: Upload a screenshot of IDE warnings or CLI errors for instant debugging guidance.
  • Visual QA: Ask descriptive questions about uploaded media ("Identify this wood grain," "Why is this layout broken?").

Privacy & Performance

  • Local vision models process pixels entirely on-device — zero data leaves your machine.
  • Image tokens consume a heavy share of the context budget (~1000–4000 tokens per image). Resize large photos before attaching to preserve chat history space.

Tip

  • Tip: Crop dense diagrams or error logs to the relevant section before uploading. It reduces token usage and sharpens model focus.

Hybrid Image Analysis Mode

Hybrid Image Analysis lets you attach images to chats while using a text-only cloud LLM. OwnAI runs a local vision model first to describe the image, then appends that description to your prompt before sending it to the cloud.

Prerequisites

  • A local vision-capable model loaded (for image description).
  • A cloud text-only model connected (to process the final prompt).
  • If your cloud model already supports vision, hybrid mode is bypassed automatically.

Setup & Settings

  1. Open Settings → Hybrid Mode Manager.
  2. Enable Image analysis local.

How It Works

  1. Attach an image and type your question.
  2. The local model generates a text description of the visual content.
  3. If enabled, the focused summary filters this description for relevance.
  4. The enriched text prompt is sent to the cloud LLM, which answers without ever seeing the raw image.

Image Generation in OwnAI 1.5

OwnAI generates images using cloud AI backends (OpenRouter fully supported and more providers are in the pipline).

Triggering Generation

  1. Agent mode: Enter into the user input box: "Create an image..." and the agent will you the image creation tool to create a picture with the cloud AI model.
  2. Chat, Documents (RAG), Memory modes: In the chat toolbar, click the Image Generation icon (cloud/palette symbol), enter your description of your desired picture into the user input box and click send.

Backend & Models

OwnAI supports multiple image models depending on your provider:

  • Flux / SDXL (high detail, artistic)
  • DALL-E 3 (prompt adherence, text rendering)
  • Stable Diffusion 3 (balanced speed/quality)

Select your preferred model in the Cloud AI Manager before generating.

Prompting & Results

  • While generating, an animated placeholder appears in the chat bubble.
  • Once complete, the full-resolution image renders with a small caption showing the model and prompt.
  • Right-click the image to save locally or copy it to your clipboard.
  • In Agent mode, the coding agent can invoke image generation automatically when requested (e.g., "create a diagram of this architecture").

Tip & future support local image generation models

  • Tip: Use explicit aspect ratios and style keywords in prompts (e.g., --ar 16:9, photorealistic, isometric blueprint) for consistent results.
  • future support local image generation models: OwnAI initially supported local diffusion-based image generation (e.g., Z-Image-Turbo) but has since removed this feature.

The decision was made because no currently available local image model includes built-in content filtering to prevent the creation of explicit or pornographic material. Until a clean local model with integrated safety safeguards becomes available, OwnAI will not support local image generation.

Agent Skills (SKILL.md)

Agent skills are focused, step-by-step workflow instructions that teach the Coding Agent how to handle specific tasks (e.g., code reviews, release checklists, debugging). They use the Cursor-compatible SKILL.md format.

Placement & Priority

Create a folder for each skill containing a SKILL.md file:

  1. Project: <workspace>/.ownai/skills/<name>/SKILL.md (highest priority)
  2. Cursor compat: <workspace>/.cursor/skills/<name>/SKILL.md
  3. Global user: <user_data>/skills/<name>/SKILL.md (available across all workspaces)

SKILL.md Structure

Each SKILL.md requires YAML frontmatter to define when it activates:

  • name: Skill identifier
  • description: Short summary shown in the agent UI
  • triggers: List of keywords/phrases that auto-load the skill when mentioned in chat
  • paths: Glob patterns matching files that should trigger this skill

Auto-Loading

The agent continuously monitors your chat input and workspace context. If you type a trigger word or work on a file matching a path glob, ownAI automatically injects the skill's instructions into the agent's context—no manual activation needed.

Tip & Pitfall

  • Tip: Keep triggers specific (e.g., "run security audit") to prevent unwanted context injection and save tokens.
  • Pitfall: A skill folder without a valid SKILL.md file at its root is silently ignored. Always verify the markdown parses correctly.

Cloud Privacy Gate: Anonymizing Data Before Cloud Requests

The Cloud Privacy Gate scans your chat input locally and replaces sensitive data with placeholders before any request leaves your machine for a cloud LLM.

Setup & Settings

  1. Open Settings → Cloud AI Manager.
  2. Enable Anonymization.
  3. Choose a Gate Mode:
  • Strict: Blocks the request if scanning fails.
  • Warn: Shows a warning but allows sending.
  • Off: No blocking (anonymization still runs).
  1. Toggle specific Categories to detect: API keys, passwords, IBANs, credit cards, emails, phones, German addresses, ID numbers, and internal hostnames/IPs.

How It Works

  • Preview Dialog: Before sending, ownAI shows a summary of detected items. Review and confirm.
  • Session Vault: Detected secrets are stored temporarily in RAM as [[OWNAI:EMAIL:001]] placeholders. The cloud never sees your actual data.
  • Response Redaction: When the cloud replies, ownAI automatically rehydrates placeholders in the chat so you see your original values.

Visual Status

A shield icon 🛡️ appears next to the model name in the chat header:

  • Visible: Anonymization active and ready.
  • Hidden: No cloud backend connected.

Tip & Pitfall

  • Tip: Enable the Preview toggle to manually verify or edit what gets masked before it leaves your PC.
  • Pitfall: The vault is session-scoped (RAM only). If you restart ownAI, placeholder mappings are lost, and rehydrated values may revert to [[OWNAI:...]] tokens in old chats.

MCP Integration Manual: Extending Agent Capabilities

The Model Context Protocol (MCP) allows ownAI's Coding Agent to connect to external tools and data sources via standardized servers.

Enabling MCP

  1. Open Settings → AI Backends → MCP.
  2. Toggle Enable MCP to activate the integration.
  3. Configure global defaults like startup timeouts, call limits, and confirmation prompts for unverified server actions.

Adding an MCP Server

  1. Click + Add Server in the MCP settings panel.
  2. Provide a Name (e.g., playwright or sqlite).
  3. Select the Transport type:
  • stdio: Runs a local executable (most common). Point to the binary and pass required environment variables.
  • sse: Connects to a remote server via Server-Sent Events. Provide the base URL.
  1. Click Save. The server status will show as Connected once initialized.

Using MCP in Agent Mode

Once connected, MCP tools appear alongside native agent tools. The agent can autonomously invoke them during tasks (e.g., browsing web pages with Playwright or querying external databases). You can also trigger specific MCP tools manually via chat.

Tip & Pitfall

  • Tip: Use stdio transport for local utilities to keep data private and reduce latency.
  • Pitfall: Misconfigured environment variables or missing binaries will cause silent connection failures. Always verify the server logs in the Explorer tab if a tool returns an error.

General Settings & UI Customization

Access Settings via the gear icon to personalize ownAI's appearance and performance.

UI & Appearance

  • Themes: Switch between Light, Dark, or custom color schemes for chat bubbles and backgrounds.
  • Zoom Levels: Adjust text scaling (75%–150%) for better readability on high-DPI or smaller screens.
  • Sidebar Widths: Drag the edge of the left/right sidebars to resize panels like Explorer, Composer, or Chat history to your preference.

Performance & Token Budgets

  • Token Status Bar: Toggle visibility to monitor real-time context window usage during long sessions.
  • Streaming Delays: Adjust rendering pauses (ms) to reduce UI lag during high-speed token generation.
  • Local Backend Overrides: Set localhistorymaxtokens and codingagentstepmax_tokens to balance generation speed vs. context depth for on-device models.

Tips & Pitfalls

  • Tip: Save custom UI layouts by exporting your program_settings.json as a backup before major application updates.
  • Pitfall: Setting token budgets too low may cause the agent to truncate critical context, leading to incomplete code patches or lost conversation history.

Product Backlog Manager

The Product Backlog tab lets you plan, track, and manage project requirements using a built-in agile workflow.

Opening the Backlog

  1. Switch to Agent mode (required for full backlog features).
  2. Click the Backlog tab in the left sidebar.

Core Workflows

  1. Create Requirements: Click + New Requirement, add a title, description, priority (High/Medium/Low), and acceptance criteria.
  2. Plan Sprints: Select unassigned requirements and click Plan Sprint to group them into a time-boxed iteration (e.g., Sprint 1: Core UI).
  3. Track Progress: Mark requirements as Done when the agent completes the associated tasks. Link backlog items to agent jobs using the @requirement-ID syntax.
  4. Export/Import: Use the gear icon to export your backlog as CSV or import Jira-compatible .csv files for migration.

Integration with Agent

  • The coding agent can read backlog status via the backlog_list tool.
  • Use @req-01 in chat to attach a specific requirement's context to an agent task.

Tip & Pitfall

  • Tip: Define clear, testable acceptance criteria (e.g., "User can export PDF without errors") so the agent knows exactly when a requirement is fulfilled.
  • Pitfall: Forgetting to link requirements to sprints makes progress tracking fragmented; always assign items before starting work.

Audio (TTS & STT) Manual

Setup

  1. Open Settings → Audio.
  2. Enable Piper TTS for local Text-to-Speech and Whisper STT for Speech-to-Text.
  3. Select your preferred Voice and Language from the dropdowns. Both run entirely on your machine.

Usage

  • TTS: Toggle Auto-play to hear responses read aloud instantly. Adjust Streaming Buffer to balance latency vs. smooth playback.
  • STT: Click the microphone icon to start dictating. Enable VAD (Voice Activity Detection) to automatically stop recording when you pause speaking.

Privacy

All audio processing (synthesis and transcription) happens locally. No voice data leaves your computer.

Tip & Pitfall

  • Tip: Use a smaller Whisper model (base or small) for faster transcription on CPU-only machines.
  • Pitfall: High streaming buffers reduce robotic artifacts but increase delay; lower the buffer if replies feel laggy.

Recurring Jobs: Automated Agent Tasks

The Jobs tab (visible in Agent mode, left sidebar) lets you define, schedule, and monitor background tasks that run the coding agent headlessly—no active chat session required.

Creating a Job

  1. Click + New Job in the Jobs tab.
  2. Provide a Name and write the Prompt (the exact instruction the agent will execute).
  3. Select a Trigger:
  • once: Runs immediately, then stops.
  • interval / daily / weekly: Repeats at fixed cadences or specific weekdays.
  • cron: Advanced scheduling using standard 5-field cron syntax (e.g., 30 8 1-5).
  • on_startup: Executes automatically when ownAI launches.
  1. Click Save. The job appears in the list with its next scheduled run time.

Managing & Monitoring

  • Run / Stop / Pause: Use the action buttons to manually trigger a job, halt an active execution, or toggle scheduling on/off.
  • Run history: Double click the on an entry in the run histoy to review the headless output, tool calls, and token usage for past runs.
  • Agent Tools: You can also create jobs via chat using scheduletask (define) and jobenqueue (trigger manually).

Tip & Pitfall

  • Tip: Use on_startup triggers for routine maintenance like running linters, updating changelogs, or syncing repos every morning.
  • Pitfall: Recurring jobs run headlessly with zero chat history. Keep prompts self-contained; avoid instructions that require manual confirmation or prior context.

GitHub Tab: Version Control in Agent Mode

The GitHub tab appears in the left sidebar exclusively during Agent mode. It provides a visual interface for managing commits, branches, tags, and remote repositories without touching the terminal.

Layout

  • CHANGES (top): Lists unstaged and staged files. Right-click entries to open, stage/unstage,push, pull etc. or use the Stash menu to temporarily save work-in-progress.
  • GRAPH (bottom): Visualizes commit history, branch topology, and tag positions. Unpushed commits are highlighted for quick identification.

Core Workflows

  1. Commit: Type a message in the input box at the bottom of CHANGES and press Ctrl+Enter (or click Commit) to save changes.
  2. Branch & Tag Management: Use the dedicated controls to create, switch, rename, or delete local branches and tags. Filter lists instantly with the search bar.
  3. Remote Operations: Add a remote origin via the settings gear, then Push, Pull, or Fetch directly from the tab.

Explorer Tab: Workspace Navigator & Inspector

The Explorer tab (left sidebar) provides file navigation, database inspection, and integrated development tools for your active workspace.

File Tree & Navigation

  • Displays the directory structure of the workspace.
  • Expand/collapse nodes to browse folders. Double-click a file to open it in the built-in viewer or external editor.
  • Right-click any item for quick actions: Copy path, Delete, Rename, or Pin to chat context (@).
  • Drag-and-drop files directly into the message input to attach them.

Chroma Table Viewer

  • Switch to the Tables sub-tab to inspect RAG collections without leaving the workspace.
  • View ingested documents, metadata fields, and embedding vectors in a sortable grid.
  • Click any row to preview raw chunk content or verify retrieval distances for debugging.

Terminal & GitHub (Agent Mode Only)

  • Terminal: Integrated console capturing all agent shell commands, test results, and linting logs. You can type manual commands when the agent is idle.
  • GitHub: Shows repository sync status, recent commits, and offers quick Push/Pull/Clone actions tied to your workspace root.

Tip & Pitfall

  • Tip: Use the search/filter input at the top of the tree to instantly jump to files by name or extension (e.g., *.md or test_).
  • Pitfall: The Explorer only reflects the folder set in workspace. If your project files are missing, update the workspace path in Settings → Coding Agent.

OwnAI — User Manuals. Last updated: 2026-07-12.