# OpenVibely Docs

Source: /index.html

OpenVibely is a self-hosted web app for managing AI coding work from a project-aware UI. Users open the app, choose a project, chat about work, create tasks, watch execution, review diffs, schedule follow-up work, and connect team channels.

## Start Fast

```bash
git clone https://github.com/openvibely/openvibely.git
cd openvibely
./start.sh
```

Open `http://localhost:3001`. The first useful path is UI-first: add a model, create or select a project, then use Chat or Tasks to start work.

| Goal | Start Here |
|---|---|
| Understand the app | [Features Overview](features-overview.html) |
| Run it locally | [Installation](installation.html) |
| Use the UI for the first task | [Quickstart](quickstart.html) |
| Set up a durable instance | [First-Time Setup](first-time-setup.html) |

## The App Mental Model

OpenVibely is organized around a selected project. The sidebar project selector changes the context for the main product surfaces.

| App Area | What Users Do There |
|---|---|
| Project selector | Choose the repository/workspace that tasks, chat, memory, workers, schedules, and integrations apply to. |
| Chat | Ask questions, plan changes, attach context, and orchestrate work conversationally. |
| Tasks | Use a board to create AI coding tasks, run them, inspect output, review changed files, and follow up. |
| Schedule | Put project work on a calendar so tasks run once or repeat. |
| Insights | Use Grades, Pulse, Reflection, and Analytics to understand activity, health, history, and trends. |
| System | Configure alerts, models, agents, workers, channels, and personality. |

## What OpenVibely Provides

| Capability | Product Outcome |
|---|---|
| Project workspaces | Keep repository context, model defaults, worker limits, schedules, memory, and integrations tied to a real codebase. |
| Chat-first planning | Start from a conversation when the work is unclear, then turn the plan into executable tasks. |
| Task board execution | Queue coding work, stream progress, inspect logs and threads, review changed files, and decide what ships. |
| Reusable agents | Capture system prompts, tools, skills, plugins, permissions, routing hints, and lifecycle behavior as reusable worker profiles. |
| Reviewable changes | Use Git worktrees and GitHub integration so AI output becomes visible diffs and pull requests rather than hidden edits. |
| Automation | Schedule recurring work, chain dependent tasks, and run structured multi-agent workflows. |
| External channels | Create and monitor work through Slack, Telegram, GitHub, and inbound webhooks. |
| Memory | Store optional project memory under `.openvibely/memory` so future work can reuse learned context. |

## How The Docs Are Organized

| Section | Use It For |
|---|---|
| Start Here | Product overview, install, UI quickstart, first setup, and learning paths. |
| Web App Tour | The screens users click every day: Dashboard, Projects, Chat, Tasks, Schedule, Agents, Models, Workers, Alerts, and Insights. |
| Core Workflows | How UI actions become task state, worktrees, attachments, memory, and review. |
| Automation In The UI | Scheduling, task chains, and structured multi-agent workflows. |
| Channels | Slack, Telegram, GitHub, and webhooks as alternate front doors into project work. |
| Operate OpenVibely | Model providers, configuration, deployment, authentication, and troubleshooting. |
| Developer Reference | Optional lookup material for people extending or integrating with OpenVibely. |

## Source Verification

The docs were checked against OpenVibely source code, including domain models, configuration loading, UI rendering, source-wired product surfaces, and existing guides. The product navigation follows the actual app sidebar: Workspace, Insights, and System.


---

# Features Overview

Source: /features-overview.html

OpenVibely is a web workbench for AI-assisted software work. The UI is the primary surface: it gives teams a place to configure models and agents, select a project, create work, monitor execution, review changes, and automate recurring or multi-step tasks.

## Product At A Glance

| Area | What Users Experience | Where To Learn More |
|---|---|---|
| Projects | A selected workspace that controls repository context, task lists, chat, schedules, workers, memory, and channels. | [Projects](projects.html) |
| Chat | A project-aware conversation for exploration, planning, attachments, and task orchestration. | [Chat](chat.html) |
| Tasks | A board for backlog, active, and completed work with run/cancel controls, streaming progress, threads, attachments, diffs, and review. | [Tasks](tasks.html) |
| Schedule | A calendar-like surface for one-time and recurring runs. | [Schedule](schedule.html) |
| Insights | Grades, Pulse, Reflection, and Analytics surfaces for understanding project activity and outcomes. | [Insights](insights.html) |
| Models | UI-managed access to Anthropic, OpenAI, and Ollama with defaults, auth options, and capacity controls. | [Models](models.html) |
| Agents | Reusable AI worker profiles with prompts, skills, plugins, MCP servers, permissions, and lifecycle hooks. | [Agents](agents.html) |
| Review | Worktree-backed changes that users can inspect before merge or pull request creation. | [Git Worktrees](git-worktrees.html), [GitHub](github.html) |
| Automation | Scheduled tasks, task chains, and structured multi-agent workflows. | [Automation In The UI](scheduled-tasks.html) |
| Channels | Slack, Telegram, GitHub, and webhook entry points for creating and tracking work outside the web UI. | [Channels Overview](channels.html) |

## The Primary Workflow

| Step | What Happens In The UI |
|---|---|
| Configure | Add at least one model, optionally create agents, and set worker limits if needed. |
| Select a project | Use the sidebar project selector so every page knows which repository/workspace you are working in. |
| Start work | Use Chat when the work needs discussion, or Tasks when you already know the unit of work. |
| Monitor | Watch task status, streaming output, alerts, and board movement as workers execute. |
| Review | Inspect task threads, attachments, changed files, review comments, and worktree state before shipping. |
| Automate | Use schedules, task chains, or structured workflows for repeatable work. |

## What Makes It Different

- It is UI-first: the app is built around project selection, sidebar navigation, modals, task boards, calendars, chat, alerts, and review screens.
- It is project-first: tasks, chat, memory, schedules, workers, models, agents, and channels are scoped around the selected project.
- It is review-first: AI work becomes visible task state, event streams, logs, diffs, comments, and GitHub-ready changes.
- It is automation-ready: schedules, task chains, and workflows are managed from the app instead of hidden in scripts.
- It is self-hosted: operators control configuration, authentication, model access, database, worker capacity, and channels.

## Recommended Reading

| If You Want To... | Read This |
|---|---|
| Try it quickly | [Installation](installation.html), then [Quickstart](quickstart.html) |
| Understand the main UI | [Projects](projects.html), [Chat](chat.html), [Tasks](tasks.html), and [Schedule](schedule.html) |
| Configure AI behavior | [Models](models.html), [Agents](agents.html), and [Personalities](personalities.html) |
| Review generated code | [Task Lifecycle](task-lifecycle.html), [Git Worktrees](git-worktrees.html), and [GitHub](github.html) |
| Run for a team | [Deployment Modes](deployment.html), [Authentication](authentication.html), [Workers](workers.html), and [Channels Overview](channels.html) |


---

# Installation

Source: /installation.html

The fastest local setup is to clone the repository and run the startup script. The script is the recommended first path because it installs missing UI tooling, generates required assets, builds the server binary, starts OpenVibely, and tails the log.

## Requirements

- Go `1.26.3+`.
- Git for cloning and project worktree operations.
- Optional provider CLIs or credentials depending on which model authentication method you use.

## Fresh Clone

```bash
git clone https://github.com/openvibely/openvibely.git
cd openvibely
./start.sh
```

If the script is not executable:

```bash
chmod +x start.sh
./start.sh
```

## What `./start.sh` Does

- Loads `.env` if present.
- Installs `templ` if missing.
- Runs `templ generate`.
- Builds `bin/openvibely`.
- Starts the server.
- Tails `logs/openvibely.log`.

The default URL is `http://localhost:3001`.

## Developer Workflow

Use this only if you are working on the OpenVibely codebase itself:

```bash
make install-tools
make dev
```

`make install-tools` installs additional developer tools such as `air`, `swag`, and the optional `goose` CLI. Normal app startup does not require these.

## Next Step

After startup, open the web app and configure at least one model from the `Models` screen. Then create a project from the sidebar and use `Chat` or `Tasks` to begin work. See [First-Time Setup](first-time-setup.html).


---

# Quickstart

Source: /quickstart.html

Use this UI-first flow to get from a fresh OpenVibely instance to a running AI coding task.

## 1. Start OpenVibely

```bash
./start.sh
```

Open `http://localhost:3001` in your browser.

## 2. Add A Model In The App

Open `Models` from the sidebar and create a model configuration. OpenVibely supports user-facing configs for Anthropic, OpenAI, and Ollama.

| Provider | Typical Setup |
|---|---|
| Anthropic | CLI, OAuth, or API key auth. |
| OpenAI | CLI, OAuth, or API key auth. |
| Ollama | Local model server, defaulting to `http://localhost:11434` when no base URL is set. |

Set a default model if you want new tasks to work without choosing a model every time.

## 3. Create A Project From The Sidebar

Use the project selector area in the sidebar to create a project. A project gives Chat, Tasks, Schedule, Workers, Alerts, Memory, Insights, and Channels their shared workspace.

Choose either a local repository path or a repository URL. Local paths are enabled by default in desktop mode, but server mode requires `OPENVIBELY_ENABLE_LOCAL_REPO_PATH`.

## 4. Start From Chat Or Tasks

| If You Know The Exact Work | If You Need To Explore First |
|---|---|
| Open `Tasks`, click `+ Add Task`, enter a title and prompt, choose a model or agent if needed, then create the task. | Open `Chat`, ask about the project or describe the goal, attach files if useful, then let the conversation guide task creation. |

## 5. Run And Watch Progress

On the Tasks page, run the task and watch it move through queued/running/completed or failed states. The UI updates from live events, and Alerts can notify you when failures or follow-up events happen.

## 6. Review Before Shipping

Open the task detail view to inspect the prompt, thread, execution output, attachments, changed files, review comments, worktree state, and pull request options when a repository is attached.

## Next Steps

| Want To... | Read Next |
|---|---|
| Understand the main surfaces | [Projects](projects.html), [Chat](chat.html), and [Tasks](tasks.html) |
| Configure reusable AI behavior | [Agents](agents.html) and [Models](models.html) |
| Automate recurring work | [Schedule](schedule.html) and [Scheduled Tasks](scheduled-tasks.html) |
| Review code safely | [Git Worktrees](git-worktrees.html) and [Task Lifecycle](task-lifecycle.html) |


---

# First-Time Setup

Source: /first-time-setup.html

OpenVibely works best when setup follows the product dependency order: model access first, then a project, then the daily workflow screens.

## Setup Order

1. Add at least one model from the `Models` screen.
2. Create or import a project from the sidebar project controls.
3. Optionally create reusable agents from `Agents`.
4. Start work from `Chat` when you need to plan, or `Tasks` when the work is already clear.
5. Tune `Workers` if tasks need stricter concurrency controls.
6. Add channels, schedules, memory, and automation after the core loop works.

## Why Models Come First

Tasks and chat need a model config to execute. Models also carry capacity settings such as `max_workers`, `worker_timeout`, and `auto_start_tasks`, so adding a reliable default model early makes the rest of setup predictable.

## Safe Defaults

- Use a local project path for quick experiments when local path mode is available.
- Keep auto-merge off until you trust the task output and review flow.
- Start with one or two workers before raising concurrency.
- Configure auth before exposing a server on the public internet.
- Enable memory only for projects with a real local repository path, because memory files are written under that repo's `.openvibely/memory` directory.

## Common First Project Flow

```text
Model -> Project -> Chat or Task -> Run -> Review diff -> Merge or open PR
```

## What To Configure Later

| Feature | Add It When |
|---|---|
| Agents | You repeat the same prompting, tools, permissions, or style across tasks. |
| Schedule | Work should run later or repeat. |
| Channels | A team should create or monitor work from Slack, Telegram, GitHub, or webhooks. |
| Memory | Future tasks should reuse project knowledge captured from previous work. |
| Automation | You want scheduled runs, task chains, or structured multi-agent workflows. |


---

# Learning Paths

Source: /learning-paths.html

Choose the path that matches what you want to accomplish in the OpenVibely web app.

## Local Solo User

- Install with `./start.sh`.
- Open the web UI and add an Anthropic, OpenAI, or Ollama model.
- Create a local path project from the sidebar.
- Use Chat to explore the repository or Tasks to create a clear unit of work.
- Review generated changes before merging.

## Team Or Server Operator

- Read [Deployment Modes](deployment.html), [Authentication](authentication.html), and [Configuration](configuration.html).
- Set storage, repository root, base URL, and auth variables deliberately.
- Configure GitHub, Slack, Telegram, or webhooks as needed.
- Tune worker capacity by global, project, and model limits.
- Use Alerts and Insights to monitor the instance after work starts running.

## Agent Builder

- Read [Agents](agents.html), [Models](models.html), [Memory](memory.html), and [Personalities](personalities.html).
- Define system prompts, tools, skills, MCP servers, routing hints, and permissions.
- Use scoped file permissions when an agent should only work in a specific directory.
- Test agents on normal Tasks before using them in larger workflows.

## Automation Designer

- Read [Scheduled Tasks](scheduled-tasks.html), [Task Chaining](task-chaining.html), and [Workflows](workflows.html).
- Start with explicit schedules or task chains before adding broader workflow coordination.
- Use Alerts, Reflection, and Analytics to audit what ran.

## Contributor Or Integrator

- Start with the product pages first so the UI workflow is clear.
- Use Developer Reference only after you understand how users create projects, chat, run tasks, review changes, and configure channels in the app.


---

# Dashboard

Source: /dashboard.html

The Dashboard is the project landing surface. It summarizes the selected project and gives users a fast path into the task board.

## What Users See

When a project is selected, the Dashboard shows task counts by category and a primary action to view tasks. If no projects exist yet, the UI prompts the user to create one.

| UI Element | Purpose |
|---|---|
| Project name | Confirms which workspace the dashboard is summarizing. |
| Category cards | Show counts for OpenVibely task categories and link into filtered task views. |
| View Tasks button | Opens the Tasks page for the selected project. |
| Empty state | Tells first-time users to create a project before work can begin. |

## When To Use It

Use Dashboard when you want a quick project-level snapshot before jumping into tasks. For deeper activity views, use the Insights section: Grades, Pulse, Reflection, and Analytics.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Projects](projects.html) | Dashboard depends on the selected project. |
| [Tasks](tasks.html) | Category cards lead into the task board. |
| [Insights](insights.html) | More detailed health, history, and analytics views live there. |


---

# Projects

Source: /projects.html

Projects are the workspace boundary in the OpenVibely UI. The selected project controls what Chat, Tasks, Schedule, Workers, Alerts, Memory, Insights, Channels, and many settings operate on.

## What Users Do

Use the project selector in the sidebar to switch workspaces. Use the plus button to create a new project, and the settings button to edit the current project.

| UI Action | Product Effect |
|---|---|
| Select a project | Updates project-scoped pages such as Chat, Tasks, Schedule, Models, Agents, Workers, Alerts, Insights, and Channels. |
| Create a project | Adds a workspace with a name, description, repository source, optional default model, and optional worker limit. |
| Edit project settings | Changes repository details, defaults, and project-level controls. |
| Switch project while editing | The app warns if modals with unsaved changes are open. |

## Repository Sources

OpenVibely supports local path projects and repository URL projects.

| Source | Use It When |
|---|---|
| Local repository path | The OpenVibely process can access the checkout directly for worktrees, diffs, and memory. |
| Repository URL | You want OpenVibely to work from a remote Git source such as GitHub. |

Local path access is explicit because it lets the server read local filesystem paths. Desktop mode enables local paths by default. Server mode requires `OPENVIBELY_ENABLE_LOCAL_REPO_PATH`.

## Project-Scoped Features

| Feature | How The Project Matters |
|---|---|
| Chat | Conversations run with the selected project context. |
| Tasks | Board categories, task execution, review, and schedules belong to the project. |
| Memory | Repository-local memory is stored under `.openvibely/memory` when memory is enabled. |
| Workers | Project worker limits prevent one workspace from consuming all execution capacity. |
| Channels | Slack, Telegram, GitHub, and webhooks can be connected to project work. |
| Insights | Grades, Pulse, Reflection, and Analytics summarize project activity. |

## First Project Checklist

- Give the project a clear name that matches the repository or product area.
- Add a repository path or URL before expecting worktree diffs and review flows.
- Choose a default model if most tasks should use the same provider.
- Set a worker limit if the project should not consume unlimited execution slots.
- Add channels only after the project is stable enough for team use.


---

# Chat

Source: /chat.html

Chat is the project-scoped conversation surface. It is meant for exploration, planning, follow-up, and turning natural language into executable work without leaving the selected project.

## What Users Do

Open `Chat` from the Workspace section of the sidebar. Pick the project first, then use the chat input to ask questions, plan changes, attach files, or orchestrate work.

| UI Capability | What It Enables |
|---|---|
| Project-scoped messages | Keep conversation grounded in the selected project. |
| Model and agent controls | Choose `Auto`, the default model, or a specific configured agent/model when available. |
| Chat modes | Choose `Orchestrate` when you want OpenVibely to take action, or `Plan` when you want safer planning and analysis first. |
| Attachments | Add files as extra context for the conversation. |
| Streaming responses | Watch answers arrive live instead of waiting for a full page refresh. |
| Clear history | Reset the conversation for the selected project when needed. |

## Plan And Orchestrate Modes

The chat input includes a mode selector with two options. OpenVibely defaults to `Orchestrate` when no mode is selected, and the selected mode is remembered per project in the browser.

| Mode | Use It When | Behavior |
|---|---|---|
| `Orchestrate` | You want Chat to help create, inspect, or coordinate real project work. | Enables action-oriented chat tools such as creating and managing tasks, reading project state, and coordinating workflow actions. |
| `Plan` | You want to think through an approach before anything is created or changed. | Keeps the conversation planning-oriented and limits action tools so the assistant can analyze, propose steps, and refine the plan first. |

A good default workflow is to start in `Plan` for vague or risky work, then switch to `Orchestrate` when the next task is clear.

## When To Use Chat

Use Chat when the task is not fully formed yet. Good examples include asking what changed in a project, breaking a vague goal into tasks, comparing implementation options, or asking OpenVibely to create follow-up work from a discussion.

Use Tasks instead when you already know the exact unit of work and want board state, scheduling, run/cancel controls, worktree review, chaining, or pull request actions.

## Typical Flow

1. Select the project in the sidebar.
2. Open Chat.
3. Pick `Plan` or `Orchestrate` from the chat input controls.
4. Ask a question or describe the goal.
5. Attach files if they help explain the request.
6. Use the response to continue planning, create tasks, or inspect existing project work.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Chat can lead into executable task work. |
| [Attachments](attachments.html) | Files can be attached to chat and task context. |
| [Agents](agents.html) | Agents define reusable behavior for execution and orchestration. |


---

# Tasks

Source: /tasks.html

Tasks are the main execution surface in OpenVibely. The Tasks page is a project board where users create AI coding work, run it, monitor progress, review output, and decide what happens to generated changes.

## The Task Board

Open `Tasks` from the Workspace section of the sidebar. The board shows project work in user-facing categories.

| Board Area | What It Means |
|---|---|
| Backlog | Planned work that is not currently active. |
| Active | Work the project is currently focused on. |
| Completed | Work that has finished and can be reviewed historically. |

Scheduled tasks are managed from the Schedule page. Chat tasks are internal to chat flows and are not normal board cards.

## Creating A Task

Click `+ Add Task` and fill out the modal.

| Field | User Impact |
|---|---|
| Title | Names the work on the board and task detail screen. |
| Prompt | Tells the model what to do. |
| Model | Overrides the default model for this task when needed. |
| Agent | Uses a reusable execution profile, or lets the router select automatically. |
| Category | Places the card in Backlog or Active. |
| Priority | Helps order and triage work. |
| Tag | Marks the task as a feature or bug when useful. |
| Auto-merge | Allows completed work to merge to the target branch when configured. |
| Attachments | Adds files as extra task context. |

The UI keeps the modal open and shows an inline error if the title conflicts with an existing task in the project.

## Running And Monitoring

Tasks move through statuses such as pending, queued, running, completed, failed, cancelled, and blocked. The page listens for live task events so board state can refresh while work is happening.

Use task detail views to inspect execution output, thread messages, attachments, changed files, review comments, and worktree state.

## Reviewing Work

When a project has a repository attached, task execution can produce worktree-backed changes. Review those changes before merging or creating a pull request.

| Review Surface | Use It For |
|---|---|
| Thread | Follow the conversation and follow-up messages around the task. |
| Execution detail | Inspect model output, errors, and run history. |
| Changes | See modified files and diffs. |
| Review comments | Track comments attached to generated code. |
| Worktree actions | Merge, clean up, resolve conflicts, or create a PR when supported. |

## Related Pages

| Page | Why It Matters |
|---|---|
| [Task Lifecycle](task-lifecycle.html) | Explains statuses and terminal states. |
| [Git Worktrees](git-worktrees.html) | Explains isolated repository changes. |
| [Schedule](schedule.html) | Runs tasks later or repeatedly. |
| [Task Chaining](task-chaining.html) | Connects dependent task work. |


---

# Schedule

Source: /schedule.html

The Schedule page manages one-time and recurring task execution for the selected project. Scheduled work is intentionally handled outside normal task category selection so users can reason about time-based automation separately from the task board.

## What Users Do

Open `Schedule` from the Workspace section of the sidebar.

| UI Action | Product Effect |
|---|---|
| Create a schedule | Picks a task and a time for it to run. |
| Choose recurrence | Runs the task once or repeats it at an interval. |
| Enable or disable | Controls whether future runs should happen. |
| Reschedule | Changes when the task should run next. |
| Delete schedule | Removes the future automation without deleting the underlying task. |

## Repeat Types

| Repeat Type | Use It For |
|---|---|
| Once | A single future run. |
| Seconds | High-frequency testing or development-only loops. |
| Minutes | Short operational intervals. |
| Hours | Repeated maintenance throughout a day. |
| Daily | Daily checks or recurring implementation tasks. |
| Weekly | Weekly cleanup, reporting, or backlog review. |
| Monthly | Long-running maintenance cadence. |

## How Schedule Relates To Tasks

A schedule belongs to a task. The task defines the prompt, model, agent, attachments, repository context, and review behavior. The schedule only controls when and how often that task should run.

Use the task board for immediate work. Use Schedule when the timing matters.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Scheduled work runs existing task definitions. |
| [Scheduled Tasks](scheduled-tasks.html) | Deeper automation guidance for recurring work. |
| [Alerts](alerts.html) | Failed scheduled runs can create alerts. |
| [Memory](memory.html) | Some schedule-adjacent controls may surface project memory behavior. |


---

# Agents

Source: /agents.html

Agents are reusable AI worker profiles. In the UI, they let users capture how a task should be approached instead of rewriting the same system prompt, tools, permissions, skills, and routing hints for every run.

## What Users Do In Agents

Open `Agents` from the System section of the sidebar. Create an agent manually, generate one from a prompt, edit an existing profile, attach skills or plugins, and choose whether tasks should use that agent explicitly or let routing select one.

| Agent Area | Product Meaning |
|---|---|
| Identity | Name, description, key, scope, and project association help users find the right profile. |
| Instructions | System prompt and model defaults shape how the agent works. |
| Tools | File, shell, web, notebook, scoped-file, and management tools define what the agent can do. |
| Skills | Reusable instructions and slash-command style capabilities. |
| Plugins and MCP | Marketplace-backed integrations and runtime tool servers. |
| Routing | Describes when the agent is good, when to avoid it, and how confident routing should be. |
| Permissions | Controls what workflow capabilities the agent is allowed to use. |
| Lifecycle hooks | Adds behavior around task execution events. |

## Scopes

| Scope | When To Use It |
|---|---|
| Global | The agent should be reusable across projects. |
| Project | The agent is specific to one repository or workspace. |

## How Agents Fit Tasks

When creating a task, users can choose an agent or leave selection on auto-routing. An agent can also define model behavior, so task execution can inherit a consistent combination of instructions, tools, and provider settings.

## Best Practices

- Name agents by the work they perform, not by an implementation detail.
- Keep instructions focused enough that users can predict the agent’s behavior.
- Use permissions and scoped file settings to make consequences explicit.
- Prefer routing hints when multiple agents could plausibly handle similar work.
- Use project-scoped agents for repository-specific conventions.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Tasks can run with a selected agent. |
| [Models](models.html) | Agents can inherit or choose model behavior. |
| [Personalities](personalities.html) | Personality settings affect tone and behavior. |
| [Workflows](workflows.html) | Multi-agent workflows coordinate agents across larger work. |


---

# Models

Source: /models.html

Models tell OpenVibely how to run AI work. Users configure them from the Models screen, then pick them as project defaults, task-specific choices, or agent defaults.

## What Users Do In Models

Open `Models` from the System section of the sidebar and create a model config.

| UI Concept | Product Effect |
|---|---|
| Provider | Chooses Anthropic, OpenAI, or Ollama. |
| Auth method | Uses CLI auth, OAuth, API key, or local Ollama configuration depending on provider. |
| Model identifier | Selects the provider model used for execution. |
| Default model | Lets tasks run without choosing a model every time. |
| Reasoning, tokens, temperature | Tunes model behavior where supported. |
| Max workers | Limits how much concurrent work this model can run. |
| Worker timeout | Prevents stalled model executions from holding capacity forever. |
| Auto-start tasks | Allows tasks created with the model to start immediately when configured. |

## Supported Providers

| Provider | Typical Use |
|---|---|
| Anthropic | Hosted Claude models through CLI, OAuth, or API key auth. |
| OpenAI | Hosted OpenAI/Codex-compatible flows through CLI, OAuth, or API key auth. |
| Ollama | Local models through a local or configured Ollama base URL. |

A `test` provider exists in source code for tests and is not documented as a normal production provider.

## Choosing Defaults

Set an app-level default model if most work should use the same provider. Set a project default when a repository should prefer a different model. Pick a task model only when the task needs a one-off override.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Quickstart](quickstart.html) | The first task requires at least one usable model. |
| [Agents](agents.html) | Agents can inherit or choose model behavior. |
| [Workers](workers.html) | Model configs participate in capacity control. |
| [Model Providers](model-providers.html) | Provider-specific setup details live there. |


---

# Workers

Source: /workers.html

Workers control how much AI work OpenVibely can run at once. In the UI, worker settings help teams avoid overwhelming a model provider, a local machine, or a single project.

## What Users Configure

Open `Workers` from the System section of the sidebar.

| Capacity Layer | What It Protects |
|---|---|
| Global capacity | Overall execution slots across the instance. |
| Project limits | Prevent one selected project from consuming all execution capacity. |
| Model limits | Prevent one provider or model config from being overloaded. |
| Worker timeout | Stops stalled executions from holding capacity forever. |

## When To Change Worker Settings

- Lower limits when using expensive hosted models.
- Lower limits when a provider rate-limits heavily.
- Raise limits when you have enough machine capacity and provider quota.
- Set project limits when one repository should not block work in others.
- Use model limits when local Ollama or a specific hosted provider is slower than the rest.

## How It Feels In The App

When capacity is available, tasks can move from queued to running. When capacity is constrained, tasks wait in the queue until a worker slot is available. Alerts and task statuses help users notice stuck or failed work.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Workers execute tasks from the board. |
| [Models](models.html) | Model configs can define per-model worker limits. |
| [Projects](projects.html) | Projects can define project-level worker limits. |


---

# Alerts

Source: /alerts.html

Alerts surface project-scoped events that need attention. The sidebar badge shows unread alerts, and live app events can update the badge while users are working.

## What Users See

Open `Alerts` from the System section of the sidebar.

| UI Element | Purpose |
|---|---|
| Unread badge | Shows when the selected project has alerts that have not been read. |
| Alert list | Shows failures, follow-up requests, and custom app-generated notices. |
| Mark read | Clears attention from one alert. |
| Mark all read | Clears all current unread alerts for the project. |
| Delete | Removes alerts that are no longer useful. |

## Alert Types

| Type | Meaning |
|---|---|
| `task_failed` | A task failed and likely needs inspection. |
| `task_needs_followup` | A task produced or requires follow-up work. |
| `custom` | App logic created a custom alert. |

## Severities

| Severity | Meaning |
|---|---|
| `info` | Informational. |
| `warning` | Attention recommended. |
| `error` | Failure or high-priority issue. |

## How Alerts Fit The Workflow

Alerts are not a replacement for the task board. Use them as a notification layer: they point you back to a task, execution, or project event that deserves attention. When a task fails, open the task detail page to inspect execution output, thread history, and any generated changes.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Most alerts point back to task activity. |
| [Workers](workers.html) | Capacity and timeouts can affect failures and delays. |
| [Insights](insights.html) | Longer-term trends appear in insight surfaces. |


---

# Insights

Source: /insights.html

Insights are the analysis and reflection surfaces in the OpenVibely sidebar. They help users understand project activity after tasks, schedules, agents, and channels have started producing work.

## Sidebar Pages

| UI Label | What Users Use It For |
|---|---|
| Grades | View proactive insights, health checks, knowledge extraction, and idea grading. |
| Pulse | See upcoming work and generated pulse summaries. |
| Reflection | Review historical task activity and generated reflections. |
| Analytics | Understand execution rates, duration trends, agent usage, frequent tasks, and failure trends. |

## How Insights Fit The Workflow

Use the task board for live execution. Use Insights when you want to step back and answer questions like whether tasks are succeeding, which agents or models are most active, what work is coming up, and what historical trends are emerging.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Insights summarize task activity. |
| [Alerts](alerts.html) | Shows failures and follow-up events that may also appear in trends. |


---

# Task Lifecycle

Source: /task-lifecycle.html

A task moves from an idea into queued work, active execution, review, and a final result. The UI exposes that lifecycle through the board, task detail page, thread, changes view, schedules, and review actions.

## Status Flow

Typical task execution moves from `pending` to `queued` to `running`, then to a terminal status: `completed`, `failed`, or `cancelled`. Chained child tasks may begin as `blocked` until their parent condition is met.

## User-Visible Lifecycle Areas

- Task card on the board.
- Task detail status and execution history.
- Thread view for follow-up messages.
- Changes view for diffs and live file changes.
- Schedule tab when recurring execution is configured.
- Chain configuration for delegated child work.
- Worktree controls for merge, pull request, conflict resolution, abort, and cleanup.
- Review comments and submitted review notes.

## How Users Should Read State

| State | What To Do |
|---|---|
| `pending` | Review the prompt, project, model, agent, and priority before running. |
| `queued` | Check worker capacity if the task waits longer than expected. |
| `running` | Watch the thread and file-change indicators for progress. |
| `completed` | Review output and changed files before merging or opening a pull request. |
| `failed` | Open the task detail view, read the failure, adjust the prompt/configuration, and retry if appropriate. |
| `cancelled` | Confirm no review action is needed, then archive or revise the task. |
| `blocked` | Inspect the parent task or chain condition before expecting it to run. |

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Main board and task detail workflows. |
| [Git Worktrees](git-worktrees.html) | Reviewable file changes after execution. |
| [Workers](workers.html) | Capacity affects when queued work starts. |


---

# Git Worktrees

Source: /git-worktrees.html

OpenVibely uses per-task repository isolation so AI-generated changes can be reviewed before they are merged or turned into pull requests.

## Why Worktrees Matter

A task should not quietly rewrite the main checkout. Worktree-backed execution gives each task a place to make changes, track branch/base information, show diffs, and support review actions.

| Concept | User Impact |
|---|---|
| Task worktree | Isolates generated files for one task. |
| Task branch | Gives the work a branch identity for merge or pull request flows. |
| Base branch and commit | Preserve what the task started from. |
| Merge target | Defines where reviewed work should land. |
| Merge status | Shows whether merging is pending, merged, failed, or conflicted. |
| Auto-merge | Lets eligible completed work merge automatically when enabled. |

## Review Flow

1. Run a task attached to a repository-backed project.
2. Open the task detail view.
3. Inspect thread output and changed files.
4. Read or add review comments when relevant.
5. Merge, create a pull request, resolve conflicts, abort, or clean up the worktree depending on the result.

## Review Discipline

Leave auto-merge disabled until the team trusts the project, model, and agent combination. Review diffs and submitted comments before merging generated changes.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Tasks](tasks.html) | Worktree actions live in task review flows. |
| [GitHub](github.html) | GitHub integration supports pull request workflows. |
| [Task Lifecycle](task-lifecycle.html) | Worktrees are part of the larger execution lifecycle. |


---

# Attachments

Source: /attachments.html

Attachments add file context to chat messages and tasks. They are contextual inputs for a conversation or execution, not a general-purpose project file store.

## Where Users Add Attachments

| Surface | What Attachments Do |
|---|---|
| Chat | Give the conversation extra context while planning, asking questions, or orchestrating work. |
| Tasks | Give the task execution extra files to consider alongside the prompt and project context. |

## What The UI Shows

Attachment components include file lists, empty states, image previews, download links, delete controls, and file-size formatting. The task creation modal supports multiple files with a max-size hint.

## Good Attachment Use Cases

- Add a design note or issue description to a task.
- Attach a screenshot or sample output to explain a bug.
- Provide a spec or migration note during chat planning.
- Add temporary context that should not become project memory.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Chat](chat.html) | Chat messages can include attachments. |
| [Tasks](tasks.html) | Tasks can include attachments at creation and in detail flows. |
| [Memory](memory.html) | Memory is durable project knowledge; attachments are per-conversation or per-task context. |


---

# Memory

Source: /memory.html

Memory lets OpenVibely retain useful project knowledge across future chat and task work. It is project-local and repository-backed, so memory belongs to the selected project rather than to the whole server.

## What Users Should Know

| Concept | User Impact |
|---|---|
| Project setting | Memory is enabled or disabled per project. |
| Repository-backed files | Extracted knowledge is stored under `.openvibely/memory` in the project repository. |
| No fallback store | A project needs a local repository path for memory files. |
| Extraction | Completed tasks, chat, and thread interactions can produce reusable knowledge. |
| Consolidation | Existing memory can be cleaned up and combined into more useful project notes. |

## How It Fits The UI

Use project settings and memory controls to decide whether a project should keep durable knowledge. Treat memory as part of the repository's working context: it can help future work, but it should not become a place for secrets, temporary attachments, or unreviewed policy decisions.

## Agent Permissions

Agents can be allowed to read or write project memory. These permissions matter because they change what durable knowledge an agent can use or update during work.

## Recommended Use

1. Enable memory only for projects where persistent context is useful.
2. Keep sensitive data out of task prompts and chat if it should not become durable context.
3. Let completed work produce memory when it captures repeatable project knowledge.
4. Review memory files in the repository if the project relies on them heavily.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Projects](projects.html) | Memory is scoped to a project. |
| [Agents](agents.html) | Agents can be configured with memory permissions. |
| [Attachments](attachments.html) | Attachments are temporary context; memory is durable project knowledge. |


---

# Personalities

Source: /personalities.html

Personalities tune broad interaction style and behavior preferences in OpenVibely. They are different from agents: personalities shape tone and defaults, while agents define durable execution policy, tools, permissions, skills, and routing behavior.

## When To Use Personalities

Use personalities when users want the app or assistant behavior to feel different across broad interaction modes, such as more concise responses, more careful explanations, or a preferred collaboration style.

Use agents when the behavior is tied to a repeatable job, repository convention, tool set, permission scope, or task execution strategy.

## How They Fit The UI

The Personality screen lets users select, save, create, update, and delete custom personality settings. The selected personality should be treated as an app-level preference, not as a substitute for explicit task prompts or agent configuration.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Agents](agents.html) | Agents are the correct place for execution rules and tool policy. |
| [Chat](chat.html) | Personality can affect how conversations feel. |
| [Tasks](tasks.html) | Task prompts and agents remain the primary control for execution behavior. |


---

# Scheduled Tasks

Source: /scheduled-tasks.html

Scheduled tasks are normal tasks with a configured run time and optional recurrence. They are managed from the Schedule page and preserve the task’s prompt, model, agent, attachments, and project context.

## Supported Recurrence

OpenVibely supports one-time, second-based, minute-based, hourly, daily, weekly, and monthly schedules. Daily, weekly, and monthly scheduling preserve local time-of-day across daylight-saving transitions by converting through local time.

## How To Think About Scheduling

| Choice | Meaning |
|---|---|
| One-time | Run the task once in the future. |
| Recurring | Re-run the same task definition on a cadence. |
| Disable | Keep the schedule record but stop future runs. |
| Delete | Remove the automation. |

## Good Uses

- Run periodic maintenance prompts.
- Schedule backlog or health checks.
- Repeat documentation, testing, or cleanup tasks.
- Start a known task outside normal working hours.

## Cautions

- A recurring schedule can repeatedly create model cost and repository changes.
- Review the task prompt and auto-merge setting before scheduling.
- Use Alerts and Insights to monitor failures and trends over time.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Schedule](schedule.html) | The UI surface for managing scheduled task runs. |
| [Tasks](tasks.html) | Scheduled work runs existing task definitions. |
| [Alerts](alerts.html) | Failed runs can create alerts. |


---

# Task Chaining

Source: /task-chaining.html

Task chaining lets a parent task create or unblock a child task when a trigger condition is met. This supports planner-to-implementer handoffs and multi-step delegation.

## Chain Configuration

| Field | Purpose |
|---|---|
| `enabled` | Whether chaining is active |
| `trigger` | Trigger condition such as `on_completion` or `on_planning_complete` |
| `child_agent_id` | Agent to use for child task; empty means default |
| `child_model` | Model override for the child |
| `child_category` | Category for child task; empty means same as parent |
| `child_title` | Explicit title, otherwise derived from parent |
| `child_prompt_prefix` | Prefix added to parent output for child prompt |
| `child_chain_config` | Nested chain configuration for multi-level workflows |

## Lifecycle Behavior

Child tasks can be pre-created for visibility and marked `blocked` until the parent reaches the configured trigger. `lineage_depth`, `base_branch`, and `base_commit_sha` preserve chain context for repository work.

## When To Use Chaining

Use chaining when one task's output should directly feed a known next step. Use [Multi-Agent Workflows](workflows.html) when you need explicit parallelism, votes, gates, handoffs, budgets, or adaptive routing.


---

# Multi-Agent Workflows

Source: /workflows.html

Workflows coordinate multi-step, multi-agent execution. They are more structured than task chaining and are meant for work that needs explicit stages, quality gates, retries, budgets, or handoffs.

## Strategies

| Strategy | Meaning |
|---|---|
| Sequential | Run steps in order. |
| Parallel | Run independent steps concurrently. |
| Hybrid | Mix sequential and parallel stages. |
| Adaptive | Let the system choose based on task analysis. |

## Step Types

| Step Type | Purpose |
|---|---|
| Execute | Run a task with an agent. |
| Review | Review a previous output. |
| Vote | Let multiple agents vote on a decision. |
| Merge | Combine outputs from parallel steps. |
| Gate | Enforce pass/fail quality behavior. |
| Handoff | Summarize context for the next agent. |

## Workflow Controls

Workflow configuration can include max retries, quality threshold, cost budget, timeout, auto-rollback, and adaptive routing. These controls matter because workflows can generate more work than a single task.

## When To Use Workflows

Use workflows when the work has a known structure and needs coordination. Use task chaining when one task should simply trigger a known next task.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Agents](agents.html) | Workflows coordinate agents. |
| [Task Chaining](task-chaining.html) | Chaining is simpler parent-child automation. |


---

# Channels Overview

Source: /channels.html

Channels let people create, monitor, and respond to OpenVibely work from the tools they already use. The web app remains the best place to configure channels, review generated changes, and manage project settings.

## What Channels Are For

| Channel | What It Enables |
|---|---|
| GitHub | Connect repositories, import project sources, and open pull requests from reviewed task changes. |
| Slack | Let approved team members create and track work from Slack conversations. |
| Telegram | Control OpenVibely from a mobile bot and receive task responses when enabled. |
| Webhooks | Let external systems create project-scoped tasks from structured events. |

## How To Set Them Up

Open `Channels` from the System section of the app sidebar. Configure one channel at a time, test the connection when the UI offers a test action, and connect each channel to the projects where it should be allowed to create or monitor work.

## Shared Concepts

- Channels should be treated as alternate front doors into the same project/task workflows users see in the web app.
- Slack and Telegram support authorized users so only approved people can interact with OpenVibely from chat tools.
- GitHub is both a channel and a repository provider, so it affects project setup and pull request review flows.
- Webhooks are best for trusted automation systems that need to create repeatable task requests.

## Recommended Rollout

1. Start with one project and one channel.
2. Add only the users or systems that should be allowed to create work.
3. Run a low-risk task through the channel.
4. Review the task in the web app before merging or opening a pull request.
5. Expand channel usage once the team understands where generated work appears.

## Related Pages

| Page | Why It Matters |
|---|---|
| [GitHub](github.html) | Repository access and pull request workflows. |
| [Slack](slack.html) | Team chat setup and authorized users. |
| [Telegram](telegram.html) | Mobile bot setup and response behavior. |
| [Webhooks](webhooks.html) | Event-driven task creation. |


---

# GitHub

Source: /github.html

GitHub connects OpenVibely to repositories and review workflows. Use it when projects should be created from GitHub sources or when completed task changes should become pull requests.

## What Users Do In The App

Open `Channels`, choose GitHub, and follow the connection flow for your instance. After GitHub is connected, users can import or resolve repositories during project setup and create pull requests from task changes after reviewing the diff.

## Where GitHub Shows Up

| Area | User Experience |
|---|---|
| Project setup | Choose or clone a GitHub repository as the source for a project. |
| Task review | Inspect generated changes in the task detail view before sending anything upstream. |
| Pull requests | Turn reviewed task worktree changes into a GitHub pull request. |
| Repository maintenance | Re-clone or resolve repository metadata when a project source changes. |

## Recommended Workflow

1. Connect GitHub from `Channels`.
2. Create or update a project with the intended repository source.
3. Run a task against that project.
4. Open the task detail view and review the thread, changed files, and review comments.
5. Create a pull request only after the generated changes look ready for repository review.

## Configuration Notes

Operators can preconfigure GitHub App settings with `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, and `GITHUB_APP_PRIVATE_KEY`. Users should not need to understand those values during normal project/task work.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Projects](projects.html) | GitHub repositories can become project sources. |
| [Git Worktrees](git-worktrees.html) | Task changes are isolated before merge or PR actions. |
| [Tasks](tasks.html) | Pull request actions live in task review flows. |


---

# Slack

Source: /slack.html

Slack lets approved team members create and monitor OpenVibely work from team conversations while keeping review and configuration in the web app.

## What Users Do In The App

Open `Channels`, choose Slack, then configure the connection using OAuth or manual tokens depending on how the instance is operated. After the connection is saved, add authorized users and test the connection before relying on Slack for team workflows.

## What Slack Enables

| Capability | User Impact |
|---|---|
| Team chat entry point | People can request project work without opening the web app first. |
| Authorized users | Only approved Slack users can interact with OpenVibely. |
| Connection test | Operators can confirm the bot is reachable before inviting broad use. |
| Project-aware work | Slack-created work still lands in OpenVibely projects and task review flows. |

## Setup Flow

1. Create or choose the Slack app used for OpenVibely.
2. Configure OAuth or manual bot-token settings in `Channels`.
3. Provide the app-level token required for Socket Mode when using Socket Mode.
4. Save the configuration and test the connection.
5. Add authorized users.
6. Create a low-risk test task and review it in the OpenVibely web app.

## Configuration Notes

Operators may provide `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_APP_TOKEN`, and `SLACK_BOT_TOKEN` through environment configuration. The UI should remain the source of truth for whether Slack is connected and who is authorized.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Channels Overview](channels.html) | Shared rollout guidance for external channels. |
| [Projects](projects.html) | Slack work should be tied to a project. |
| [Tasks](tasks.html) | Slack-created work is reviewed as normal task work. |


---

# Telegram

Source: /telegram.html

Telegram provides mobile bot control for OpenVibely. It is useful for lightweight task creation, status checks, and optional task responses when users are away from the web app.

## What Users Do In The App

Open `Channels`, choose Telegram, save a bot token, test the bot, and add authorized users. If response sending is enabled, task completion or failure messages can be sent back through Telegram.

## What Telegram Enables

| Capability | User Impact |
|---|---|
| Mobile control | Create or follow work from a Telegram chat. |
| Authorized users | Restrict bot access to known users. |
| Send responses toggle | Decide whether task responses are sent back through Telegram. |
| Project/task continuity | Telegram-created work still appears in the same OpenVibely task board. |

## Setup Flow

1. Use BotFather to create a bot and get its token.
2. Save the token in the Telegram channel settings.
3. Test the connection.
4. Add authorized Telegram users.
5. Decide whether task responses should be sent back through Telegram.
6. Run a small test request and review the resulting task in the web app.

## Configuration Notes

Operators can bootstrap Telegram with `TELEGRAM_BOT_TOKEN`. The channel settings remain the user-facing place to test, authorize, and remove Telegram access.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Channels Overview](channels.html) | Shared rollout guidance for external channels. |
| [Tasks](tasks.html) | Telegram-created work becomes normal task work. |
| [Alerts](alerts.html) | Task failures and follow-up needs should still be watched in the app. |


---

# Webhooks

Source: /webhooks.html

Webhooks let trusted external systems create project-scoped OpenVibely tasks. Use them for event-driven work such as deployment follow-ups, monitoring alerts, issue triage, or scheduled jobs from another tool.

## What Users Configure

Open `Channels`, choose Webhooks, and create a webhook for the project that should receive work. Each webhook has a display name, enabled state, secret, prompt shaping options, and default priority.

| Field | User Impact |
|---|---|
| Project | Chooses where created tasks appear. |
| Name | Helps operators recognize the external system. |
| Enabled | Turns task creation on or off without deleting the webhook. |
| Secret | Lets the sender prove it is allowed to use the webhook. |
| System instructions | Guides how OpenVibely should interpret incoming events. |
| Title template | Controls the generated task title. |
| Prompt template | Controls the generated task prompt. |
| Default priority | Sets the priority for created tasks. |

## Recommended Workflow

1. Create a webhook for one project.
2. Copy the generated URL/token and secret into the external system.
3. Send a test payload from the UI or the external system.
4. Confirm the created task appears in the intended project.
5. Review the generated title and prompt before enabling broader automation.

## Safety Guidance

Keep webhooks project-specific and rotate secrets if they are exposed. Disable a webhook when an external system no longer needs to create tasks.

## Related Pages

| Page | Why It Matters |
|---|---|
| [Channels Overview](channels.html) | Webhooks are one of several external entry points. |
| [Projects](projects.html) | Every webhook-created task lands in a project. |
| [Tasks](tasks.html) | Webhook-created work is reviewed and run as normal task work. |


---

# Model Providers

Source: /model-providers.html

Model providers are configured through the Models UI and stored as `LLMConfig` records.

## Provider Matrix

| Provider | Code Value | Key Details |
|---|---|---|
| Anthropic | `anthropic` | CLI, OAuth, API key; Anthropic API key can also serve as vision fallback when no vision-capable model is configured |
| OpenAI | `openai` | CLI, OAuth, API key; OAuth includes account/workspace tracking |
| Ollama | `ollama` | Local provider with configurable base URL and default `http://localhost:11434` |

## OAuth Variables

Hosted OAuth can use provider-specific client IDs, client secrets, authorization URLs, token URLs, and scopes. `APP_BASE_URL` controls public callback origins, and `OAUTH_REDIRECT_MODE` controls hosted vs localhost/manual behavior.

## Reasoning Effort

`OPENVIBELY_CODEX_REASONING_EFFORT` is a fallback for Codex requests when model config does not set one. Allowed values documented in the README are `low`, `medium`, `high`, and `xhigh`, with fallback `high`.


---

# Configuration

Source: /configuration.html

OpenVibely is configured primarily with environment variables. `start.sh` loads `.env` when present, then starts the server.

## Runtime Variables

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `3001` in server mode, `0` in desktop mode | HTTP port; desktop uses ephemeral by default |
| `DATABASE_PATH` | `./openvibely.db` or app-data path in desktop | SQLite database path |
| `DATABASE_URL` | empty | Loaded but not used by server startup |
| `ENVIRONMENT` | `development` | Runtime label |
| `PROJECT_REPO_ROOT` | `./repos` or app-data repos path | Managed clone root |
| `OPENVIBELY_APP_DATA_DIR` | mode-specific | Overrides app-data root and changes DB/repo defaults |
| `OPENVIBELY_ENABLE_LOCAL_REPO_PATH` | false in server, true in desktop | Enables local path project source mode |

## Auth Variables

| Variable | Purpose |
|---|---|
| `AUTH_ENABLED` | Explicit built-in login toggle |
| `AUTH_USERNAME` | Login username |
| `AUTH_PASSWORD` | Login password |
| `AUTH_SESSION_SECRET` | HMAC secret for `ov_session` cookie |
| `AUTH_SESSION_TTL` | Session lifetime, default `24h` |

If `AUTH_ENABLED` is unset, auth is inferred enabled when both username and password are present. If auth is enabled, username, password, and session secret are required.

## Integration Variables

- `ANTHROPIC_API_KEY`
- `TELEGRAM_BOT_TOKEN`
- `GITHUB_APP_ID`
- `GITHUB_APP_SLUG`
- `GITHUB_APP_PRIVATE_KEY`
- `SLACK_CLIENT_ID`
- `SLACK_CLIENT_SECRET`
- `SLACK_APP_TOKEN`
- `SLACK_BOT_TOKEN`

## Deployment Variables

- `APP_BASE_URL`
- `OAUTH_REDIRECT_MODE`
- Provider OAuth client IDs, secrets, authorize URLs, token URLs, and scopes.
- Git SSL variables: `GIT_SSL_CAINFO`, `SSL_CERT_FILE`, and `GIT_SSL_NO_VERIFY`.


---

# Deployment Modes

Source: /deployment.html

OpenVibely uses one shared Go backend for server and desktop deployments. The backend wires the database, repositories, services, HTTP routes, workers, scheduler, and event streams.

## Server Mode

Server mode is the default web, VPS, and Docker path.

```bash
./start.sh
```

Important defaults:

| Setting | Default |
|---|---|
| Port | `3001` |
| DB path | `./openvibely.db` |
| Repo root | `./repos` |
| Local repo paths | Disabled unless enabled by env |

## Desktop Mode

Desktop mode uses Wails and OS app-data directories. The backend binds to an ephemeral port by default, and the Wails WebView loads the backend URL.

| OS | App Data Path |
|---|---|
| macOS | `~/Library/Application Support/OpenVibely` |
| Linux | `~/.local/share/openvibely` unless `XDG_DATA_HOME` is set |
| Windows | `%LOCALAPPDATA%\OpenVibely` or `%APPDATA%\OpenVibely` fallback |

Desktop defaults local repo paths to enabled.

## Docker / VPS

Use server mode with explicit persistent paths, auth, TLS termination, and `APP_BASE_URL` for hosted OAuth callback behavior.

## OAuth By Mode

- Server/VPS: set `APP_BASE_URL` to the public origin.
- Desktop: usually leave `APP_BASE_URL` unset and use localhost callback behavior.
- Manual fallback: set `OAUTH_REDIRECT_MODE=localhost_manual` when provider callback restrictions require manual paste.


---

# Authentication

Source: /authentication.html

OpenVibely includes built-in login middleware controlled by environment variables.

## Enablement Rules

| Case | Behavior |
|---|---|
| `AUTH_ENABLED=true` | Auth enabled explicitly |
| `AUTH_ENABLED=false` | Auth disabled explicitly |
| `AUTH_ENABLED` unset and username/password set | Auth inferred enabled |
| `AUTH_ENABLED` unset and username/password missing | Auth disabled |

When auth resolves enabled, startup requires `AUTH_USERNAME`, `AUTH_PASSWORD`, and `AUTH_SESSION_SECRET`. Missing required values cause startup failure.

## Session Settings

| Variable | Purpose |
|---|---|
| `AUTH_SESSION_SECRET` | Signs the `ov_session` cookie |
| `AUTH_SESSION_TTL` | Go duration string; invalid or non-positive values fall back to `24h` |

## UI Behavior

The sidebar calls `/auth/me` to show the authenticated user menu when auth is active. Logout posts to `/logout`.

## Production Guidance

- Always set `AUTH_ENABLED=true` explicitly for internet-facing deployments.
- Use a long random `AUTH_PASSWORD`.
- Use at least 32 random bytes for `AUTH_SESSION_SECRET`.
- Terminate TLS at a reverse proxy or load balancer.
- Keep secrets in environment variables or a secret manager, not committed files.


---

# Troubleshooting

Source: /troubleshooting.html

This page collects common operational issues that follow from the source-verified configuration and workflow model.

## Server Does Not Start

- Confirm Go `1.26.3+` is installed.
- If auth is enabled, confirm `AUTH_USERNAME`, `AUTH_PASSWORD`, and `AUTH_SESSION_SECRET` are all set.
- Check `logs/openvibely.log` when using `./start.sh`.
- Ensure the selected `PORT` is available.

## OAuth Returns To Localhost On A VPS

- Set `APP_BASE_URL` to your public origin, for example `https://app.example.com`.
- Use `OAUTH_REDIRECT_MODE=auto` or `hosted`.
- Ensure provider callback URLs match the app callback routes.

## Local Repository Paths Are Missing

- In server mode, set `OPENVIBELY_ENABLE_LOCAL_REPO_PATH=true`.
- In desktop mode, local paths are enabled by default.

## Memory Does Not Write

- Confirm the project has a local `repo_path`.
- Confirm memory is enabled for the project.
- Check extraction or consolidation run status for `error`.
- Remember memory writes to `.openvibely/memory` inside the selected repo.

## Tasks Stay Queued

- Check global worker capacity.
- Check project `max_workers`.
- Check model `max_workers` and `worker_timeout`.
- Confirm the selected model credentials are valid.


---

# API Reference

Source: /api-reference.html

OpenVibely exposes a REST API and Swagger UI. The app registers Swagger at `/swagger/*`, and the README documents the local Swagger URL as `http://localhost:3001/swagger/index.html` when using `./start.sh`.

## Important API Areas

| Area | Example Routes |
|---|---|
| Projects | `GET /api/projects` |
| Chat | `POST /api/chat/message`, `GET /api/chat/message/:id` |
| Analytics | `/api/analytics/*` |
| Capacity | `/api/capacity/*` |
| Lifecycle | `/api/tasks/:id/lifecycle-executions`, `/api/lifecycle-executions/:id/events` |
| Workflows | `/api/workflows/*` |
| Collisions | `/api/collisions/*` |

## Example Chat API Call

```bash
curl -X POST http://localhost:3001/api/chat/message \
  -F "message=Summarize the current task board" \
  -F "project_id=default"
```

## Swagger Source

The repository contains generated Swagger artifacts under `docs/swagger.yaml` and `docs/swagger.json`, and runtime Swagger UI is served from the app.


---

# Routes

Source: /routes.html

This reference summarizes the major route groups registered by OpenVibely. Use runtime Swagger for detailed API schemas.

## UI Routes

| Area | Routes |
|---|---|
| Dashboard | `/`, `/dashboard`, `/dashboard-mockup`, `/analytics` |
| Projects | `/projects`, `/projects/new`, `/projects/:id/edit` |
| Tasks | `/tasks`, `/tasks/:taskId`, task executions, status, changes, thread, run, cancel, category, reorder, chain |
| Schedule | `/schedule`, `/tasks/:taskId/schedule`, `/schedules/:id`, `/schedules/:scheduleId/reschedule` |
| Agents | `/agents`, `/agents/generate`, plugin state/marketplaces/install, lifecycle hooks, skills JSON |
| Models | `/models`, `/models/ollama/available`, model OAuth routes |
| Workers | `/workers`, worker stats routes |
| Channels | `/channels`, GitHub, Slack, Telegram, webhooks |
| Personality | `/personality`, custom personality routes |
| Worktrees | `/tasks/:taskId/worktree`, merge, PR, resolve, abort, cleanup, settings |
| Chat | `/chat`, `/chat/send`, chat attachments, clear history |
| Alerts | `/alerts`, unread count, read/delete actions |
| Workflows | `/workflows`, workflow steps, and executions |
| Insights | `/insights`, `/upcoming`, `/history`, `/suggestions`, `/backlog` |
| Events | `/events/live`, `/events/chat/:exec_id` |

## Swagger

Swagger UI is served at `/swagger/*`.


---

# Environment Variables

Source: /environment.html

This is a concise reference. See [Configuration](configuration.html) for explanations and recommended usage.

## Runtime

| Variable | Default |
|---|---|
| `PORT` | `3001` server, `0` desktop |
| `DATABASE_PATH` | `./openvibely.db` or app-data path |
| `DATABASE_URL` | empty |
| `ENVIRONMENT` | `development` |
| `PROJECT_REPO_ROOT` | `./repos` or app-data path |
| `OPENVIBELY_APP_DATA_DIR` | empty unless set |
| `OPENVIBELY_ENABLE_LOCAL_REPO_PATH` | false server, true desktop when unset |
| `OPENVIBELY_PLUGIN_ROOT` | app-local plugin root when unset |
| `OPENVIBELY_CODEX_REASONING_EFFORT` | `high` fallback |

## Auth

| Variable | Default |
|---|---|
| `AUTH_ENABLED` | inferred from username/password when unset |
| `AUTH_USERNAME` | empty |
| `AUTH_PASSWORD` | empty |
| `AUTH_SESSION_SECRET` | empty |
| `AUTH_SESSION_TTL` | `24h` |

## OAuth And Providers

| Variable Group | Examples |
|---|---|
| Base URL and redirect | `APP_BASE_URL`, `OAUTH_REDIRECT_MODE` |
| Anthropic OAuth | `ANTHROPIC_OAUTH_CLIENT_ID`, `ANTHROPIC_OAUTH_CLIENT_SECRET`, authorize/token URL, scopes |
| OpenAI OAuth | `OPENAI_OAUTH_CLIENT_ID`, `OPENAI_OAUTH_CLIENT_SECRET`, authorize/token URL, scopes |
| Provider bootstrap | `ANTHROPIC_API_KEY` |

## Channels

| Channel | Variables |
|---|---|
| Telegram | `TELEGRAM_BOT_TOKEN` |
| GitHub | `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_PRIVATE_KEY` |
| Slack | `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN` |

## Git SSL

- `GIT_SSL_CAINFO`
- `SSL_CERT_FILE`
- `GIT_SSL_NO_VERIFY`


---

# Glossary

Source: /glossary.html

| Term | Meaning |
|---|---|
| Agent | Reusable execution profile with prompts, tools, skills, permissions, and optional lifecycle behavior |
| Alert | Project-scoped notification such as task failure or follow-up needed |
| Channel | External integration such as GitHub, Slack, Telegram, or webhooks |
| Chat | Project-scoped conversational orchestration UI |
| Memory | Project-local durable knowledge written under `.openvibely/memory` in the selected repo |
| Model Config | Provider and authentication configuration used to run AI work |
| Project | Workspace boundary for repository, tasks, schedules, chat, memory, workers, and integrations |
| Schedule | One-time or recurring task execution plan |
| Task | Unit of AI work with prompt, status, category, execution history, and optional repository changes |
| Task Chain | Parent-child task relationship where a trigger creates or unblocks follow-up work |
| Template | Reusable task or workflow configuration |
| Worktree | Isolated git checkout used for one task's generated changes |
| Workflow | Structured multi-agent execution with steps, strategies, gates, votes, and handoffs |
| Worker | Execution capacity slot controlled globally, by project, and by model |


---

# LLM Index

Source: /llms.html

The generated docs site publishes two LLM-readable files.
## Files

| File | Purpose |
|---|---|
| `llms.txt` | Short navigable index of docs pages |
| `llms-full.txt` | Concatenated full text of docs pages |

## Why This Exists

OpenVibely is an agent-oriented product, so docs should be easy for humans and AI coding agents to consume. These files make it easier for assistants, search systems, and internal tooling to answer questions from the docs site instead of guessing from partial context.