{"id":51141337,"url":"https://github.com/ccordine/omnidex","last_synced_at":"2026-06-25T23:30:35.933Z","repository":{"id":359170636,"uuid":"1234844973","full_name":"ccordine/omnidex","owner":"ccordine","description":"A fully customizable SCRUM-based AI Agent Framework for deterministic automation, specialist model routing, memory, tools, and queue-backed workflows.","archived":false,"fork":false,"pushed_at":"2026-06-14T15:25:07.000Z","size":36227,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T17:18:01.713Z","etag":null,"topics":["agents","ai-tools","automation","cli","developer-tools-ai-agent","go","llm","local","local-fist","ollama","openai","pgvector","postgres"],"latest_commit_sha":null,"homepage":"https://cordine.site/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccordine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T18:02:23.000Z","updated_at":"2026-06-14T15:25:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ccordine/omnidex","commit_stats":null,"previous_names":["ccordine/omnidex"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ccordine/omnidex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccordine%2Fomnidex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccordine%2Fomnidex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccordine%2Fomnidex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccordine%2Fomnidex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccordine","download_url":"https://codeload.github.com/ccordine/omnidex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccordine%2Fomnidex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34796761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-tools","automation","cli","developer-tools-ai-agent","go","llm","local","local-fist","ollama","openai","pgvector","postgres"],"created_at":"2026-06-25T23:30:35.307Z","updated_at":"2026-06-25T23:30:35.920Z","avatar_url":"https://github.com/ccordine.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Omnidex\n\n**Current release:** `v0.3.0` Venusaur\n\nOmnidex is a local-first platform for **evidence-led development** and **human-in-the-loop project planning**.\n\nAt the Venusaur layer, it works as an augmented planner and research tool: you explore topics, review AI-generated task cards, promote the work you want done, and let build agents execute approved cards — while deterministic code still owns policy, evidence, and completion.\n\nUnder the hood it remains an agent runtime: plan, patch, verify, observe, and continue until evidence says the task is done.\n\n## Two layers\n\n| Layer | What it does |\n| --- | --- |\n| **Project planner** (web UI) | Research, architect, draft backlog cards, scan the board. You review before anything hits Ready. |\n| **Agent runtime** (`omni`, workers) | Execute approved work with specialists, memory, recipes, evidence ledgers, and Pathfinder recovery. |\n\nCore pieces:\n\n- **`omni`**: deterministic local CLI for chat, command execution, research, install/update, and workspace-aware automation.\n- **Web cockpit**: general chat, projects, scrum board, Project Chat, draft queue, card channel pilot, data channels, data-source admin, flow metrics.\n- **`agent-core`**: API + Postgres queue + worker pipeline for service-backed workflows.\n- **`agent-cli`**: queue/API CLI for enqueueing and inspecting core jobs.\n\nLicense: MIT.\n\n## Venusaur workflow (start here)\n\n```bash\ncd omnidex\ncp default.env .env\ndocker compose up --build -d core\n# open http://localhost:8090 → Projects → pick/create a project\n```\n\n1. **Project Chat** — research a topic (`Research` or **Research \u0026 draft** / `/batch`).\n2. **Draft queue** — review suggested cards; **Add** or **Add all** to the backlog.\n3. **Scrum board** — edit cards, drag approved work to **Ready**, **Play** to run the agent.\n4. **Card Channel** — steer running work without replaying full agent logs.\n5. Keep chatting — *\"continue research on …\"* — more drafts accumulate for review.\n\nFull guide: [docs/SCRUM_PLANNER.md](docs/SCRUM_PLANNER.md)\n\nExample prompts:\n\n- *Research login systems for our Go app and draft backlog cards for each approach.*\n- *Research music theory intervals — draft study cards, not implementation.*\n- *Break the auth epic into setup / middleware / tests / docs cards.*\n\n## Dynamic AI agent framework\n\nOmnidex is moving from a single-purpose local assistant into a dynamic AI agent framework with a GUI-first control plane. The web UI is not a thin skin over the CLI; it is where projects, data, agent configuration, memory, tickets, and live human steering meet.\n\nThe goal is to let a human describe intent in normal language, then let deterministic services decide what kind of agent run is appropriate:\n\n- **Research assistant** when the user is in general chat and only needs web search, synthesis, memory creation, or lightweight follow-up.\n- **Project planning assistant** when the user is inside a project and wants to turn research into backlog cards.\n- **Build agent** when a card has been promoted and the repository/workspace context matters.\n- **Data analyst** when the user asks questions against configured read-only databases.\n- **Reviewer/debugger** when the user asks the system to analyze a project and generate cleanup/refactor/error cards.\n\nThe framework separates those modes instead of forcing every request through a code workspace. General chat can research without a project directory. Project and card agents get project context, repo files, recipes, model settings, and agent settings. Data channels get database schema and read-only query tools. The same job queue, evidence model, memory system, and live UI update layer tie the modes together.\n\n### GUI-first cockpit\n\nThe web cockpit is the primary operator interface:\n\n- **Chat** is the general assistant surface. It can answer, research, use web search, store useful memories, and work without a project selected.\n- **Projects** organize real workspaces. A project owns its directory, codebase map, recipe, model config, agent config, scrum board, git status, debugger/analyzer runs, and auto-work settings.\n- **Scrum** is the human-in-the-loop execution board. Cards move through backlog, ready/assigned, in progress, review, blocked, and done.\n- **Data** provides natural-language database channels for configured read-only sources.\n- **Jobs, Memory, Metrics, and Admin** expose the queue, durable knowledge, model/agent defaults, secrets, data sources, host bridge state, and operational health.\n\nThe UI is built around live partial updates rather than full-page refreshes. RecyclrJS targets small regions such as a card modal tab, channel stream, toolbar, data result, or board column so the interface can update while preserving the user's current modal, tab, and scroll position.\n\n### Project and scrum interface\n\nThe scrum board turns project work into explicit, reviewable units. A card is more than a title:\n\n- title and description\n- checklist and test criteria\n- generated or manually edited ticket body\n- planning/coaching notes\n- tags and suggested tags\n- card channel conversation\n- model and agent overrides\n- recipe JSON\n- reference files and directories from the repo\n- uploaded card-specific files such as PDFs, docs, screenshots, or other context artifacts\n- live job state, console stream, and flow metrics\n\nThe intended loop is:\n\n1. Use **Project Chat** to research a topic, inspect direction, or draft a batch of cards.\n2. Review the draft queue and promote only the useful work.\n3. Attach files, folders, recipes, tests, and implementation notes to each card.\n4. Move a card to assigned/in progress and press **Play**, or let auto-work pull from configured columns.\n5. Steer the same running agent from the card channel without losing the card's isolated history.\n6. Let completed work land in **Review**, inspect the output, then mark it done or send it back through the loop.\n\nCards are intentionally editable. AI-generated tickets are a starting point, not a lock-in. The user can rewrite the ticket, add constraints, attach files, change the agent, and re-run with a clearer scope.\n\n### Live card channels\n\nEach card has an isolated channel used for both planning and execution steering. The channel is designed for long-lived task context:\n\n- messages are attached to the card, not only the browser session\n- running agents can stream status, reasoning summaries, commands, file changes, and final output\n- channel messages can move a card into active work when the user is steering a ticket\n- context minification keeps the useful history without replaying every raw token forever\n- project/card configuration decides whether Omnidex, Codex, Cursor, or another configured agent executes the work\n\nThis makes a card feel less like a static Jira ticket and more like a bounded agent workspace with human supervision.\n\n### Data source integration\n\nOmnidex also treats databases as first-class agent surfaces. Admins can configure read-only data sources, currently focused on PostgreSQL-style connections, then explore and query them from the GUI.\n\nData-source capabilities include:\n\n- read-only connection configuration in **Admin -\u003e Data sources**\n- connection testing\n- raw schema loading\n- AI-assisted schema/catalog exploration\n- direct SQL query execution with SELECT/WITH restrictions\n- natural-language questions that queue a data query job\n- data channels for repeated conversations against the same source\n- rendered answers, SQL, tables, row counts, query evidence, and chartable results\n\nThe important design point is that a user can ask human-language questions such as \"which accounts had the largest week-over-week drop?\" while the system records the SQL and evidence used to answer. This keeps the interaction approachable without hiding the query plan from technical users.\n\n### Human language as the routing layer\n\nThe new direction is that users should not need to pick a low-level pipeline for ordinary work. They should be able to ask:\n\n- \"Research auth options and draft implementation cards.\"\n- \"Analyze this repo for obvious bugs and refactor candidates.\"\n- \"Why did revenue dip last week?\"\n- \"Attach this PDF to the ticket and have the agent account for it.\"\n- \"Keep working on this card, but check the migration files first.\"\n- \"Remember the findings from this research topic for next time.\"\n\nOmnidex then routes the request to the correct bounded context: no workspace for general research, project workspace for build work, card history for ticket steering, database schema for data questions, and memory retrieval when historical context matters.\n\n### Configuration hierarchy\n\nThe framework is configurable at multiple scopes:\n\n- **Default/workspace config** for global model and agent defaults.\n- **Project config** for repository-specific models, agents, recipes, and auto-work behavior.\n- **Card config** for per-ticket overrides.\n- **Run config** for one-off decisions like faster mode, deeper reasoning, sandbox behavior, approval policy, network access, or external-agent selection.\n\nThis lets lightweight research use a fast native route while a risky project card can use a stricter build agent with stronger reasoning and explicit workspace constraints.\n\n### Memory, evidence, and accountability\n\nAcross chat, scrum, data, and CLI runs, Omnidex keeps deterministic systems in charge of state:\n\n- the queue owns job and step lifecycle\n- memories preserve reusable research, preferences, procedures, and project knowledge\n- evidence records commands, web/data findings, outputs, and verification details\n- cards and data channels retain the human-facing conversation\n- deterministic transition logic moves tickets between columns based on job outcomes\n\nThe practical result: AI can propose and execute, but Omnidex keeps the audit trail, state transitions, and human approval surfaces explicit.\n\n## Why this design\n\n- **Human gates execution**: the planner generates work; you curate the queue; agents run what you promoted.\n- **Deterministic control plane**: models propose structured outputs; code validates, gates, executes, and records evidence.\n- **Hot-swappable model roles**: each specialist can use the model best suited to its job (instant vs thinking in Project Chat too).\n- **Minimal context by default**: channel pilot and structured commands use summary/minification instead of raw transcript replay.\n- **Evidence ledger by default**: work is explainable after the fact, including rejected commands and remaining objectives.\n- **Relevance-first retrieval**: tags + pgvector similarity (`memory_chunks.embedding`) before analysis/response.\n- **Queue-native processing**: workers lease steps with `FOR UPDATE SKIP LOCKED`.\n\n## Agent runtime (CLI)\n\nSpecialist roles handle bounded jobs such as prompt interpretation, planning, shell command selection, summarization, done checks, retrieval, analysis, and verification.\n\n- Model routing is configurable per role, so fast utility models and deeper reasoning models can be swapped independently.\n- Skills and tools extend what Omnidex can do while deterministic code owns policy, execution, evidence, and state transitions.\n- Evidence ledgers record objectives, commands, rejected commands, observed output, pending work, and final responses.\n- Run traces summarize model calls, command counts, rejections, loop exhaustion, and completion-check pressure from existing session events.\n- Development loops convert discovered failures into regression targets, make scoped changes, run targeted verification, and continue from concrete observations instead of starting over.\n- Pathfinder is the high-reward problem-solving layer for stalled runs: it diagnoses the real blocker, scores candidate strategies, and hands one validated next action back to the normal runtime.\n\n## Try This: Frontend Project (CLI)\n\n```bash\nmkdir demo-calculator \u0026\u0026 cd demo-calculator\nomni chat\n```\n\nPrompt:\n\n```text\nCreate a small npm frontend project using Stimulus, RecyclrJS, Tailwind CSS, and webpack.\nInitialize npm, install dependencies, create a minimal calculator page, wire a Stimulus controller,\nuse RecyclrJS, run a build or smoke test, and summarize the evidence.\n```\n\nThen export the evidence ledger:\n\n```bash\nomni ledger export --out evidence-ledger.json\nomni run:trace latest\nomni bench report\n```\n\nUseful deterministic surfaces:\n\n```bash\nomni fastpath project.probe\nomni index build\nomni patch apply --file change.diff --dry-run\nomni fingerprint --text \"npm error code E404\"\nomni ollama prewarm --json\n```\n\nSee `docs/SCRUM_PLANNER.md`, `docs/DEVELOPMENT_LOOPS.md`, `docs/VALIDATED_PLAYBOOKS.md`, `docs/EVIDENCE_LEDGER.md`, `docs/RUN_TRACE.md`, `docs/FAST_PATHS.md`, `docs/WORKSPACE_INDEX.md`, `docs/COMMAND_CACHE.md`, `docs/PATCH_MODE.md`, `docs/FAILURE_FINGERPRINTS.md`, `docs/OLLAMA_PREWARM.md`, `docs/COMMAND_POLICY.md`, `docs/RECIPES.md`, `docs/BENCHMARKS.md`, `docs/ROADMAP.md`, and `SECURITY.md`.\n\nFor embedding Omnidex into other apps as a local memory-backed chat/RP/support service, see `docs/LOCAL_SERVICE_CHANNELS.md`.\n\n## Pipeline\n\nDefault step pipelines by type:\n- `assistant`: `plan -\u003e tooling -\u003e workspace_scan -\u003e tag -\u003e retrieve -\u003e web_search -\u003e analyze -\u003e assist -\u003e verify`\n- `chat`: `plan -\u003e tooling -\u003e workspace_scan -\u003e tag -\u003e retrieve -\u003e web_search -\u003e analyze -\u003e roleplay -\u003e verify`\n- `story`: `plan -\u003e tooling -\u003e workspace_scan -\u003e tag -\u003e retrieve -\u003e web_search -\u003e analyze -\u003e narrate -\u003e verify`\n\nWorker runtime uses a stage-driven orchestrator with stable per-stage context contracts:\n- `tooling` -\u003e writes `tooling`\n- `workspace_scan` -\u003e writes `workspace`\n- `tag` -\u003e writes `tags`\n- `retrieve` -\u003e writes `retrieval`\n- `plan` -\u003e writes `plan`\n- `web_search` -\u003e writes `web_search`\n- `analyze` -\u003e writes `analyzer`\n- `assist|roleplay|narrate` -\u003e writes that action key\n- `verify` -\u003e writes `verification`\n\nThis keeps queue/API compatibility while making execution flow linear and easier to reason about/extend.\n\n## Pathfinder\n\nPathfinder is Omnidex's meta-problem-solving specialist. It is invoked when the normal routine stalls, loops, hits repeated false completion, encounters invalid file assumptions, or needs a better strategy than asking the generic planner for another command.\n\nPathfinder receives a `ProblemCase` built from current evidence: the user goal, phase, pending objectives, objective ledger, worksite survey, prep context, codebase route, recent observations, failed/rejected commands, false-done count, loop state, available tools, constraints, and success condition.\n\nIt returns a `BreakthroughPacket`:\n\n- diagnosis and real blocker\n- assumptions and evidence used\n- at least three candidate strategies with practical scores\n- selected strategy and expected progress\n- next action such as inspect, research, proof-contract update, patch, verification, external-agent delegation, objective/context adjustment, ask-user, or fail-with-evidence\n- forbidden paths and proof needed after the action\n\nPathfinder cannot mark objectives complete. Its output must pass deterministic packet validation, then any action is dispatched through normal Omnidex policy. Completion still requires machine-checkable evidence from proof commands, artifact validation, scope checks, and objective predicates.\n\nLive progress reports these pipeline phases explicitly:\n- `planning`: `plan`\n- `execution`: `tooling`, `workspace_scan`, `tag`, `retrieve`, `web_search`, `analyze`, `assist|roleplay|narrate`\n- `review`: `verify`\n\n`web_search` uses fixed provider routes (Yahoo, Google, Reddit-via-Google) and query normalization (`spaces/commas -\u003e +`, strip non-alphanumeric symbols, collapse duplicate `+`).\n\n`plan` derives a deterministic JSON execution plan, `tooling` audits host capability and install hints, `workspace_scan` snapshots repository context, and `verify` enforces grounding checks (with optional persistent replan recovery).\n\nJobs can still pause/continue through `feedback`, be steered with `interrupt`, or be reset with `replan`.\n\nSee `internal/worker/RUNTIME.md` for stage contracts and extension points.\n\nMemory is typed so retrieval can prioritize durable guidance:\n- `instruction` (rules/policies)\n- `procedural` (how-to workflows)\n- `reference` (books/docs/transcripts/subtitles)\n- `preference` (user/project tendencies)\n- `episodic` (interaction history)\n\nAfter each response, core can infer long-term memories (`procedural` / `instruction` / `preference`) and store or correct near-duplicate inferred entries.\n\nTables are in `migrations/001_init.sql` and created automatically on startup when `MIGRATE_ON_STARTUP=true`.\n\n## Quick start (Docker)\n\n```bash\ncd omnidex\ncp default.env .env\ndocker compose up --build\n```\n\nDo not set `PATH=` in `.env` for compose — see [Docker troubleshooting](#docker-troubleshooting) and `default.env` comments.\n\nCore API is exposed on `http://localhost:8090`.\nPostgres and Redis stay on the internal backend Docker network (`omnidex-backend`) and are not published to the host by default. The core service is the only normal host-facing service.\n\n### Docker troubleshooting\n\n#### `agent-core`: executable file not found in `$PATH`\n\nThis usually means **host `.env` set `PATH=`** (often for Cursor/npm on the host bridge) and Docker Compose injected it into the core container. A host PATH like `/home/you/.local/share/mise/shims:/usr/bin:/bin` does not include `/usr/local/bin`, where the image installs `agent-core`.\n\nFix:\n\n1. **Remove `PATH=` from `.env`** (recommended). Put host-only PATH in `~/.config/omni/host-bridge.env` instead:\n\n```bash\n# ~/.config/omni/host-bridge.env — host bridge only, not core .env\nOMNI_CURSOR_NODE_BIN=/home/you/.local/share/mise/installs/node/VERSION/bin/node\nOMNI_CURSOR_NPM_BIN=/home/you/.local/share/mise/installs/node/VERSION/bin/npm\nPATH=/home/you/.local/share/mise/shims:/usr/bin:/bin\n```\n\n2. **Rebuild and restart** after pulling a fix or editing `.env`:\n\n```bash\ndocker compose up --build -d core\n```\n\nThe image runs `/usr/local/bin/agent-core` directly and `docker-compose.yml` pins container `PATH`; either should survive a stray host `PATH` in `.env`.\n\nVerify the binary exists:\n\n```bash\ndocker compose run --rm --entrypoint sh core -c 'ls -la /usr/local/bin/agent-core'\n```\n\n#### Cannot connect to the Docker daemon (`unix:///var/run/docker.sock`)\n\nThe engine is not running, or your shell user cannot access the socket.\n\n1. **Start Docker** (Arch Linux example):\n\n```bash\nsudo systemctl start docker\nsudo systemctl enable docker\nsystemctl is-active docker\n```\n\n2. **Add your user to the `docker` group** (one-time), then open a **new login session** (log out/in, or `newgrp docker`):\n\n```bash\nsudo usermod -aG docker \"$USER\"\nnewgrp docker   # or restart the terminal / re-login\ngroups | grep docker\n```\n\n3. **Check the socket**:\n\n```bash\nls -l /var/run/docker.sock\n```\n\nYou want `root docker` ownership and your user in group `docker`.\n\n4. **Temporary workaround**: `sudo docker compose up --build -d core` (not ideal long-term).\n\n5. **Rootless Docker**: if you use rootless, point the client at the user socket:\n\n```bash\nexport DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock\n```\n\nOn macOS/Windows, start **Docker Desktop** before `docker compose`; the Homebrew `docker` package is client-only.\n\n#### General rebuild after updates\n\n```bash\ndocker compose up --build -d core\ndocker compose ps\ndocker compose logs -f core --tail 50\n```\n\nOr from an install path: `./update.sh` / `omni update` (requires a working Docker daemon).\n\n### Isolated CLI/toolbox container\n\nFor safer agent work, you can run the core service in Docker and run the CLI from a separate disposable container on the same Docker network. In that setup, Omnidex sees only the files and tools mounted into the CLI container. Your host source tree, host package managers, and host system dependencies are not touched unless you explicitly mount them writable.\n\nThe recommended local topology is:\n\n```text\nnative host Ollama\n  \u003c- reached through host.docker.internal:11434\nDocker core container\n  \u003c- reached through http://core:8090 on the compose network\ndisposable CLI/toolbox container\n```\n\nKeep Ollama running natively on the system when possible, especially for GPU access, driver stability, and model cache reuse. The core container should connect outward to that host Ollama instance with `OLLAMA_BASE_URL=http://host.docker.internal:11434`; Ollama does not need to run inside the Docker network.\n\nStart the core:\n\n```bash\ndocker compose up --build -d core\n```\n\nThen run a CLI/toolbox container on the compose edge network. The exact network name is usually `\u003crepo\u003e_omnidex-edge`; from this repo it is commonly `omnidex_omnidex-edge`:\n\n```bash\ndocker network ls --filter name=omnidex-edge\n```\n\nExample service-backed CLI run:\n\n```bash\nmkdir -p \"$HOME/omnidex-sandbox\"\n\ndocker run --rm -it \\\n  --network omnidex_omnidex-edge \\\n  -e CORE_URL=http://core:8090 \\\n  -v \"$PWD\":/src/omnidex:ro \\\n  -v \"$HOME/omnidex-sandbox\":/workspace \\\n  -w /src/omnidex \\\n  golang:1.24.1-bookworm \\\n  go run ./cmd/cli enqueue --pipeline assistant --workspace on --approval auto --verify auto \\\n    \"Inspect /workspace and suggest the next safe development task.\"\n```\n\nFor local deterministic `omni` work inside the same kind of isolated container:\n\n```bash\ndocker run --rm -it \\\n  --network omnidex_omnidex-edge \\\n  -e CORE_URL=http://core:8090 \\\n  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \\\n  -v \"$PWD\":/src/omnidex:ro \\\n  -v \"$HOME/omnidex-sandbox\":/workspace \\\n  -w /workspace \\\n  golang:1.24.1-bookworm \\\n  bash -lc 'cd /src/omnidex \u0026\u0026 go run ./cmd/omni chat'\n```\n\nUse a writable mount only for the project you want Omnidex to edit. Mount the Omnidex source read-only, mount throwaway dependency caches if you want repeatable installs, and avoid mounting `/`, `$HOME`, Docker sockets, SSH keys, cloud credentials, or production repositories into the toolbox container.\n\n### Local service channels\n\nCore exposes non-agent channel routes for applications that need a local assistant, support bot, roleplay participant, narrator, or instruction-following model with memory:\n\n- `POST /v1/channels`\n- `GET /v1/channels`\n- `POST /v1/channels/{id}/messages`\n- `GET /v1/channels/{id}/messages`\n\nChannels use configured model/persona/system/context/tags, retrieve channel-scoped memory, call the selected model, store recent messages, and persist conversation turns as memory. They do not run shell commands or agent jobs.\n\nSee `docs/LOCAL_SERVICE_CHANNELS.md` for install steps and JavaScript, Python, Go, support, and roleplay examples.\n\n### Ollama connectivity from Docker\n\nRecommended: run Ollama natively on the host and let the Dockerized core connect to it through Docker's host gateway. Keep:\n- `OLLAMA_BASE_URL=http://host.docker.internal:11434`\n\nIf Ollama runs in another container, set `OLLAMA_BASE_URL` to that service URL.\n\nLinux note: if jobs fail with `connect: connection refused` to `host.docker.internal:11434`, Ollama is usually bound to `127.0.0.1` only. Expose it on all interfaces and restart:\n\n```bash\nOLLAMA_HOST=0.0.0.0:11434 ollama serve\n```\n\nIf you run Ollama as a systemd service, set `OLLAMA_HOST=0.0.0.0:11434` in the service environment override, then restart the service.\n\n#### Troubleshooting tips\n\nIf chat or research jobs fail with Ollama timeouts, `/api/tags` errors, or `generation provider ollama is unreachable from core`:\n\n1. **Rebuild and restart core**\n\n```bash\ndocker compose up --build -d core\n```\n\n2. **Check `.env`** — If you still have `OLLAMA_BASE_URL=http://172.20.0.1:11434` and that gateway is wrong, either remove it (use the default `http://host.docker.internal:11434`) or fix the IP. Core also auto-probes fallbacks at startup (`host.docker.internal`, the Docker bridge gateway, then localhost); check core logs for `ollama endpoint resolved`.\n\n3. **Ensure Ollama listens on all interfaces on the host**\n\n```bash\nOLLAMA_HOST=0.0.0.0:11434 ollama serve\n```\n\n4. **Verify from inside the core container**\n\n```bash\ndocker compose exec core wget -qO- --timeout=5 http://host.docker.internal:11434/api/tags\n```\n\nIf your compose project uses a different container name, substitute it (for example `docker exec omni-nxt-core-1 ...`).\n\n6. **Arch Linux + UFW** — If probes **time out** (not `connection refused`) from inside the container while `curl http://127.0.0.1:11434/api/tags` works on the host, UFW is usually blocking Docker bridge traffic. Allow host ports from Docker networks:\n\n```bash\nscripts/ufw-docker-host.sh\n# or manually:\nsudo ufw allow from 172.16.0.0/12 to any port 11434,8091 proto tcp\ndocker compose up -d core\n```\n\n7. **Read the startup logs**\n\n- If **all candidates failed**, Ollama is not reachable from Docker at all — that is a host networking/binding issue, not the UI.\n- If logs show a **successful resolved URL**, chat should queue immediately even when Status briefly still shows Ollama as down.\n\nThe web UI Status panel includes a Research Health card backed by `GET /v1/status/research`. It checks whether the core can reach Ollama at `OLLAMA_BASE_URL`, reports configured/missing generation and embedding models, probes configured web search providers, and surfaces Ollama reachability warnings.\n\nIf a configured Ollama generation model is missing, Omnidex pulls it through Ollama's `/api/pull` endpoint and retries the request. First use can take as long as the model download. You can avoid that delay by pre-pulling:\n\n```bash\nollama pull qwen2.5:7b\nollama pull nomic-embed-text\n```\n\n### Ollama GPU setup and stress testing\n\nOmnidex can drive many sequential specialist calls. A weak or half-configured Ollama setup may look fine for one chat request, then fail during long planning, research, verification, or memory-indexing runs. Before using Omnidex for serious agent loops, verify Ollama under sustained load.\n\nRecommended checks:\n\n```bash\nollama --version\nollama list\nollama pull qwen2.5-coder:7b\nollama pull qwen2.5:7b\nollama pull nomic-embed-text\nomni ollama prewarm --json\n```\n\nFor memory retrieval, use an embedding model whose output dimension matches the database schema. The default local vector column is `vector(768)`, so `nomic-embed-text` is a good Ollama default:\n\n```bash\nOLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\nOn Linux AMD systems, confirm the server is actually using the GPU instead of silently falling back to CPU. Useful tools include:\n\n```bash\nollama ps\njournalctl -u ollama -f\nls -l /dev/dri /dev/kfd\ngroups\n```\n\nDuring a long generation, watch GPU utilization with one of:\n\n```bash\namdgpu_top\nradeontop\nwatch -n 1 rocm-smi\n```\n\nThe exact AMD path depends on GPU generation, kernel, Mesa, ROCm, and Ollama build. Official Ollama docs currently describe AMD ROCm support on Linux and note additional AMD coverage through Vulkan. On Arch Linux, the most practical paths are usually:\n\n- `ollama-rocm` when the GPU is supported by ROCm and `/dev/kfd` access is working.\n- a Vulkan-enabled Ollama build/package when ROCm does not fully support the device or does not use the whole GPU.\n- CPU fallback only as a last resort for small models or debugging.\n\nFor Arch Linux AMD laptops/desktops, including Framework Laptop 16 GPU configurations, check:\n\n```bash\npacman -Qs 'ollama|rocm|vulkan|mesa|amdgpu'\nvulkaninfo --summary\nrocminfo\n```\n\nIf Ollama runs as a systemd service, put GPU and networking settings in an override:\n\n```bash\nsudo systemctl edit ollama\n```\n\nExample override:\n\n```ini\n[Service]\nEnvironment=\"OLLAMA_HOST=0.0.0.0:11434\"\nEnvironment=\"OLLAMA_KEEP_ALIVE=30m\"\nEnvironment=\"OLLAMA_EMBEDDING_MODEL=nomic-embed-text\"\n```\n\nThen reload and restart:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl restart ollama\njournalctl -u ollama -f\n```\n\nIf you use a Vulkan-enabled Ollama build, set the Vulkan flag required by that build/package in the same override. Some builds use:\n\n```ini\n[Service]\nEnvironment=\"OLLAMA_VULKAN=1\"\n```\n\nDo not assume Vulkan or ROCm is active because the model runs. Prove it with utilization during generation and by checking Ollama logs for the selected backend. For Omnidex stress testing, run several long prompts or research jobs back to back and watch for:\n\n- `context canceled`\n- HTTP 500/connection reset errors from Ollama\n- model pulls during active jobs\n- repeated CPU fallback\n- thermal throttling\n- VRAM exhaustion or partial offload warnings\n\nHelpful references:\n- Ollama GPU docs: `https://docs.ollama.com/gpu`\n- Ollama Linux docs: `https://docs.ollama.com/linux`\n- Ollama troubleshooting: `https://docs.ollama.com/troubleshooting`\n- Arch package notes for Ollama/ROCm/Vulkan from your distribution packages\n\n### Remote model providers\n\nOmnidex supports these model sources for generation:\n\n| Provider | `LLM_PROVIDER` values | Required credential | Default model |\n| --- | --- | --- | --- |\n| Ollama | `ollama`, `local` | none | `llama3.2` in core, CLI defaults vary by role |\n| OpenAI-compatible OpenAI API | `openai`, `chatgpt`, `chat-gpt` | `OPENAI_API_KEY` | `gpt-4.1-mini` |\n| Microsoft Azure AI / Azure OpenAI | `azure`, `azureai`, `azure-openai`, `microsoft`, `windows-ai` | `AZURE_AI_API_KEY` or `AZURE_OPENAI_API_KEY` | deployment/model from `AZURE_AI_MODEL` or `AZURE_OPENAI_DEPLOYMENT` |\n| xAI Grok | `xai`, `x-ai`, `grok`, `grock` | `XAI_API_KEY` or `GROK_API_KEY` | `grok-4.3` |\n| Google Gemini | `google`, `gemini`, `googleai`, `google-ai` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `gemini-2.0-flash` |\n| Anthropic Claude | `anthropic`, `claude` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |\n| Hugging Face Inference Providers | `huggingface`, `hugging-face`, `hf` | `HUGGINGFACE_API_KEY` or `HF_TOKEN` | `openai/gpt-oss-20b:fastest` |\n\nGeneration and embeddings are routed separately. `LLM_PROVIDER` controls chat, planning, summarization, specialists, and response generation. `EMBEDDING_PROVIDER` controls memory vectors and retrieval embeddings. Anthropic and xAI/Grok are generation-only in Omnidex right now; use Ollama, OpenAI, Google, or Hugging Face for embeddings.\n\nTo run with OpenAI instead of Ollama:\n- `LLM_PROVIDER=openai`\n- `OPENAI_API_KEY=...`\n- optional `OPENAI_MODEL=gpt-4.1-mini`\n- optional `OPENAI_EMBEDDING_MODEL=text-embedding-3-small`\n\nTo run with Microsoft Azure AI / Azure OpenAI:\n- `LLM_PROVIDER=azure`, `LLM_PROVIDER=azure-openai`, `LLM_PROVIDER=microsoft`, or `LLM_PROVIDER=windows-ai`\n- `AZURE_AI_API_KEY=...` or `AZURE_OPENAI_API_KEY=...`\n- for the current Azure OpenAI v1-compatible API, set `AZURE_OPENAI_ENDPOINT=https://\u003cresource\u003e.openai.azure.com`, `AZURE_AI_API_STYLE=v1`, and `AZURE_OPENAI_DEPLOYMENT=\u003cchat-deployment\u003e`\n- for older Azure OpenAI deployment routes, set `AZURE_AI_API_STYLE=azure_openai`, `AZURE_OPENAI_ENDPOINT=https://\u003cresource\u003e.openai.azure.com`, and `AZURE_OPENAI_DEPLOYMENT=\u003cchat-deployment\u003e`\n- optional `AZURE_OPENAI_EMBEDDING_DEPLOYMENT=\u003cembedding-deployment\u003e` when using Azure for memory vectors\n- optional `AZURE_AI_API_VERSION=2024-10-21` for deployment routes\n- for Azure AI Foundry model inference, set `AZURE_AI_BASE_URL=https://\u003cresource\u003e.services.ai.azure.com`, `AZURE_AI_API_STYLE=foundry`, and `AZURE_AI_MODEL=\u003cmodel-or-deployment\u003e`\n\nTo run with xAI Grok:\n- `LLM_PROVIDER=xai`, `LLM_PROVIDER=grok`, or `LLM_PROVIDER=grock`\n- `XAI_API_KEY=...` or `GROK_API_KEY=...`\n- optional `XAI_BASE_URL=https://api.x.ai/v1`\n- optional `XAI_MODEL=grok-4.3`\n- keep `EMBEDDING_PROVIDER=ollama|openai|google|huggingface`, because Grok generation uses xAI's OpenAI-compatible chat-completions API while Omnidex memory vectors need a configured embedding provider.\n\nTo run with Google Gemini:\n- `LLM_PROVIDER=google` or `LLM_PROVIDER=gemini`\n- `GOOGLE_API_KEY=...` or `GEMINI_API_KEY=...`\n- optional `GOOGLE_MODEL=gemini-2.0-flash`\n- optional `GOOGLE_EMBEDDING_MODEL=text-embedding-004`\n\nTo run with Anthropic Claude:\n- `LLM_PROVIDER=anthropic` or `LLM_PROVIDER=claude`\n- `ANTHROPIC_API_KEY=...`\n- optional `ANTHROPIC_MODEL=claude-sonnet-4-20250514`\n- keep `EMBEDDING_PROVIDER=ollama|openai|google|huggingface`, because Anthropic does not provide a native embeddings API.\n\nTo run with Hugging Face Inference Providers:\n- `LLM_PROVIDER=huggingface` or `LLM_PROVIDER=hf`\n- `HUGGINGFACE_API_KEY=...` or `HF_TOKEN=...`\n- optional `HUGGINGFACE_MODEL=openai/gpt-oss-20b:fastest`\n- optional `HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2`\n\n`EMBEDDING_PROVIDER` can be set independently from `LLM_PROVIDER` when you want one provider for generation and another provider for memory vectors. This is required for Anthropic and useful when you want stable `vector(768)` memory dimensions while testing different generation models.\n\nCommon setups:\n\n```env\n# Fully local generation and embeddings.\nLLM_PROVIDER=ollama\nOLLAMA_BASE_URL=http://host.docker.internal:11434\nOLLAMA_MODEL=qwen2.5-coder:7b\nEMBEDDING_PROVIDER=ollama\nOLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\n```env\n# OpenAI for generation, local Ollama embeddings for stable memory dimensions.\nLLM_PROVIDER=openai\nOPENAI_API_KEY=sk-...\nOPENAI_MODEL=gpt-4.1-mini\nOPENAI_MODEL_REASONING=gpt-4.1\nOPENAI_MODEL_PLANNER=gpt-4.1\nEMBEDDING_PROVIDER=ollama\nOLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\n```env\n# Grok for generation, local Ollama embeddings.\nLLM_PROVIDER=xai\nXAI_API_KEY=xai-...\nXAI_MODEL=grok-4.3\nXAI_MODEL_FAST=grok-4.3\nEMBEDDING_PROVIDER=ollama\nOLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\n```env\n# Claude for generation, OpenAI embeddings.\nLLM_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-...\nANTHROPIC_MODEL=claude-sonnet-4-20250514\nANTHROPIC_MODEL_FAST=claude-3-5-haiku-latest\nEMBEDDING_PROVIDER=openai\nOPENAI_API_KEY=sk-...\nOPENAI_EMBEDDING_MODEL=text-embedding-3-small\n```\n\n```env\n# Gemini for generation and embeddings.\nLLM_PROVIDER=gemini\nGEMINI_API_KEY=...\nGEMINI_MODEL=gemini-2.0-flash\nGEMINI_MODEL_REASONING=gemini-2.5-pro\nEMBEDDING_PROVIDER=google\nGEMINI_EMBEDDING_MODEL=text-embedding-004\n```\n\n```env\n# Hugging Face Inference Providers.\nLLM_PROVIDER=hf\nHF_TOKEN=hf_...\nHF_MODEL=openai/gpt-oss-20b:fastest\nHF_MODEL_FAST=meta-llama/Llama-3.1-8B-Instruct:fireworks-ai\nEMBEDDING_PROVIDER=huggingface\nHF_EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2\n```\n\n### External coding agents: Cursor and Codex\n\nOmnidex can delegate implementation work to Cursor or Codex as bounded external coding agents. These agents are not the planner, validator, or completion authority. Omnidex still owns workspace survey, memory lookup, context compaction, objective evidence, proof commands, artifact validation, scope validation, and final completion decisions.\n\nThe external-agent flow is:\n\n```text\nOmnidex prepares a mission packet\n  -\u003e Cursor/Codex receives exact task, edit surface, read-only context, forbidden actions, and proof contract\n  -\u003e Cursor/Codex edits files as an implementation worker\n  -\u003e Omnidex streams agent events into the timeline\n  -\u003e Omnidex runs local proof commands and artifact checks\n  -\u003e Omnidex accepts, rejects, or repairs from deterministic evidence\n```\n\nExternal agent output is recorded as implementation evidence only. A streamed `completed` event means the worker claims its implementation is ready for validation; it does not mean the Omnidex objective is done.\n\nExternal agent delegation is opt-in. If no agent is explicitly enabled and selected, Omnidex uses its local coding system and deterministic handlers.\n\nCursor delegation requires both selection and enablement:\n\n```env\nOMNI_ARCHITECT_AGENT=cursor\nOMNI_ENABLE_CURSOR_ARCHITECT=true\nCURSOR_API_KEY=...\nOMNI_CURSOR_MODEL=composer-2\nOMNI_CURSOR_TIMEOUT=90m\nOMNI_CURSOR_INSTALL_TIMEOUT=10m\nOMNI_CURSOR_SDK_RUNNER_DIR=\nOMNI_CURSOR_NODE_BIN=node\nOMNI_CURSOR_NPM_BIN=npm\nOMNI_DISABLE_CURSOR_ARCHITECT=false\n```\n\nCodex delegation also requires both selection and enablement:\n\n```env\nOMNI_ARCHITECT_AGENT=codex\nOMNI_ENABLE_CODEX_ARCHITECT=true\nCODEX_API_KEY=...\n# OPENAI_API_KEY is also accepted when CODEX_API_KEY is unset.\nOMNI_CODEX_MODEL=gpt-5.3-codex\nOMNI_CODEX_TIMEOUT=90m\nOMNI_CODEX_INSTALL_TIMEOUT=10m\nOMNI_CODEX_SDK_RUNNER_DIR=\nOMNI_CODEX_NODE_BIN=node\nOMNI_CODEX_NPM_BIN=npm\nOMNI_CODEX_BIN=codex\nOMNI_DISABLE_CODEX_ARCHITECT=false\n```\n\nSet `OMNI_ARCHITECT_AGENT=none` or leave it unset to force local Omnidex execution even when SDK credentials are present.\n\nMission packets are compact by design. They include:\n\n- `task`, `mode`, `workspace`, and `target_root`\n- detected worksite state, package manager, and frameworks\n- exact edit surface and read-only context files\n- requested objectives\n- proof commands, artifact checks, and evidence predicates\n- forbidden actions such as sibling project creation, unrequested dependencies, backend/routing additions, test weakening, and completion claims\n- prepared context from route planning, documentation briefs, and relevant memories\n\nHuman correction is treated as higher-authority current-run context. The safe baseline behavior is cancel and restart: Omnidex cancels the active external session, runs cleanup, revises the mission packet with the correction, refreshes the allowed/forbidden scope, and starts a new external session. Same-session interrupt/resume can be added per adapter when the underlying SDK supports it reliably.\n\nOperational rules:\n\n- Do not expose external-agent execution in untrusted/public environments.\n- External agents must not push git, create sibling projects, or install unrequested dependencies.\n- Shell/process cleanup matters after cancel, failure, or completion.\n- Local proof gates remain mandatory: build/test/smoke commands, artifact validation, scope/dependency checks, and objective evidence predicates.\n\n### CLI agent mode\n\nAfter install, use the core-backed agent chat from any workspace:\n\n```bash\nomni agent --profile architect\n```\n\n`omni agent` is a bridge to `agent-cli chat`, so it uses the core configuration stack: env, workspace defaults from Admin, project/card config when present, and per-run CLI overrides. The local deterministic `omni chat` command remains available separately.\n\nUseful one-shot starts:\n\n```bash\nomni agent --agent codex --agent-model gpt-5.3-codex --codex-reasoning-effort high\nomni agent --agent cursor --agent-model composer-2\nomni agent --agent omnidex --reasoning deep\n```\n\nInside the interactive chat:\n\n```text\n/agent codex\n/model gpt-5.3-codex\n/reasoning deep\n/set codex_reasoning_effort high\n/set codex_sandbox workspace-write\n/settings\n/interrupt add this constraint to the active run\n/replan restart with this corrected scope\n/cancel stop this run\n```\n\nThe installed aliases also include `oagent`, `oagentcodex`, `oagentcursor`, and `oagentomni`.\n\n### Workspace scan from Docker\n\nBy default compose mounts your parent directory read-only into `/workspace` and the core scans from there.\nSet `HOST_WORKSPACE_PATH` to control what gets mounted.\n\n### Web search tuning\n\nEnvironment variables:\n- `WEB_SEARCH_ENABLED=true|false`\n- `WEB_SEARCH_PROVIDERS=duckduckgo,google,reddit`\n- `WEB_SEARCH_TIMEOUT=15s`\n- `WEB_SEARCH_PER_SOURCE_BUDGET=3000`\n- `WEB_SEARCH_TOTAL_BUDGET=6000`\n- `WORKSPACE_SCAN_ENABLED=true|false`\n- `WORKSPACE_ROOT=/workspace`\n- `WORKSPACE_MAX_FILES=5000`\n- `WORKSPACE_CONTEXT_BUDGET=6000`\n\n### Model routing and cognition\n\nEnvironment variables use the selected generation provider as a prefix. For example, when `LLM_PROVIDER=openai`, `MODEL_PLANNER` is read from `OPENAI_MODEL_PLANNER`; when `LLM_PROVIDER=google`, it is read from `GOOGLE_MODEL_PLANNER` or `GEMINI_MODEL_PLANNER`; when `LLM_PROVIDER=ollama`, it is read from `OLLAMA_MODEL_PLANNER` or `OMNI_PLANNER_MODEL`.\n\nRouting fallback order:\n- `*_MODEL` is the default generation model.\n- `*_MODEL_FAST` defaults to `*_MODEL`.\n- `*_MODEL_REASONING` defaults to `*_MODEL`.\n- `*_MODEL_TAGGER` defaults to fast.\n- `*_MODEL_SEARCH` defaults to fast.\n- `*_MODEL_MEMORY` defaults to fast.\n- `*_MODEL_ANALYZER`, `*_MODEL_PLANNER`, and `*_MODEL_RESPONDER` default to reasoning.\n- specialist models default to the closest role model unless explicitly configured.\n\nRole-specific model variables let you tune cost, speed, and quality without changing code:\n\n```env\n# Example: cheap fast model, stronger planner, strong shell/code specialist.\nOLLAMA_MODEL=qwen2.5-coder:7b\nOLLAMA_MODEL_FAST=qwen2.5:7b\nOLLAMA_MODEL_REASONING=qwen2.5:14b\nOLLAMA_MODEL_PLANNER=qwen2.5-coder:14b\nOLLAMA_MODEL_EVALUATOR=qwen2.5:7b\nOLLAMA_MODEL_SPECIALIST_SHELL_EXECUTION=qwen2.5-coder:14b\nOLLAMA_MODEL_SPECIALIST_WEB_RESEARCH=qwen2.5:7b\nOLLAMA_MODEL_SPECIALIST_MEMORY_RETRIEVAL=qwen2.5:7b\n```\n\nThe same suffixes work for hosted providers:\n\n```env\nLLM_PROVIDER=openai\nOPENAI_MODEL=gpt-4.1-mini\nOPENAI_MODEL_FAST=gpt-4.1-mini\nOPENAI_MODEL_REASONING=gpt-4.1\nOPENAI_MODEL_PLANNER=gpt-4.1\nOPENAI_MODEL_SPECIALIST_SHELL_EXECUTION=gpt-4.1\nOPENAI_MODEL_SPECIALIST_WEB_RESEARCH=gpt-4.1-mini\n```\n\nSupported environment variables:\n- `LLM_PROVIDER=ollama|openai|azure|xai|google|anthropic|huggingface`\n- `EMBEDDING_PROVIDER=ollama|openai|azure|google|huggingface`\n- `OPENAI_API_KEY` (required when `LLM_PROVIDER=openai`)\n- `OPENAI_BASE_URL` (default `https://api.openai.com/v1`)\n- `OPENAI_MODEL` (default fallback when provider is OpenAI)\n- `OPENAI_MODEL_FAST`\n- `OPENAI_MODEL_REASONING`\n- `OPENAI_MODEL_TAGGER`\n- `OPENAI_MODEL_PLANNER`\n- `OPENAI_MODEL_ANALYZER`\n- `OPENAI_MODEL_RESPONDER`\n- `OPENAI_MODEL_SEARCH`\n- `OPENAI_MODEL_MEMORY`\n- `OPENAI_EMBEDDING_MODEL`\n- `AZURE_AI_API_KEY` / `AZURE_OPENAI_API_KEY` (required when `LLM_PROVIDER=azure`)\n- `AZURE_AI_BASE_URL` / `AZURE_OPENAI_ENDPOINT` (required when `LLM_PROVIDER=azure`)\n- `AZURE_AI_API_VERSION` / `AZURE_OPENAI_API_VERSION` (defaults to `2024-10-21` for Azure OpenAI deployment routes and `2024-05-01-preview` for Foundry)\n- `AZURE_AI_API_STYLE` / `AZURE_OPENAI_API_STYLE` (`v1`, `azure_openai`, or `foundry`; defaults to `foundry` for `*.services.ai.azure.com`, to `v1` when the base URL contains `/openai/v1`, otherwise Azure OpenAI deployment routes)\n- `AZURE_AI_MODEL` / `AZURE_OPENAI_DEPLOYMENT`\n- `AZURE_AI_MODEL_FAST`, `AZURE_AI_MODEL_REASONING`, `AZURE_AI_MODEL_TAGGER`, `AZURE_AI_MODEL_PLANNER`, `AZURE_AI_MODEL_ANALYZER`, `AZURE_AI_MODEL_RESPONDER`, `AZURE_AI_MODEL_SEARCH`, `AZURE_AI_MODEL_MEMORY`\n- `AZURE_AI_EMBEDDING_MODEL` / `AZURE_OPENAI_EMBEDDING_DEPLOYMENT`\n- `XAI_API_KEY` / `GROK_API_KEY` (required when `LLM_PROVIDER=xai|grok|grock`)\n- `XAI_BASE_URL` / `GROK_BASE_URL` (default `https://api.x.ai/v1`)\n- `XAI_MODEL` / `GROK_MODEL`\n- `XAI_MODEL_FAST`, `XAI_MODEL_REASONING`, `XAI_MODEL_TAGGER`, `XAI_MODEL_PLANNER`, `XAI_MODEL_ANALYZER`, `XAI_MODEL_RESPONDER`, `XAI_MODEL_SEARCH`, `XAI_MODEL_MEMORY`\n- `XAI_EMBEDDING_PROVIDER` / `GROK_EMBEDDING_PROVIDER` (default `ollama` when `LLM_PROVIDER=xai|grok|grock`)\n- `GOOGLE_API_KEY` / `GEMINI_API_KEY` (required when `LLM_PROVIDER=google`)\n- `GOOGLE_BASE_URL` (default `https://generativelanguage.googleapis.com/v1beta`)\n- `GOOGLE_MODEL` / `GEMINI_MODEL`\n- `GOOGLE_MODEL_FAST`, `GOOGLE_MODEL_REASONING`, `GOOGLE_MODEL_TAGGER`, `GOOGLE_MODEL_PLANNER`, `GOOGLE_MODEL_ANALYZER`, `GOOGLE_MODEL_RESPONDER`, `GOOGLE_MODEL_SEARCH`, `GOOGLE_MODEL_MEMORY`\n- `GOOGLE_EMBEDDING_MODEL` / `GEMINI_EMBEDDING_MODEL`\n- `ANTHROPIC_API_KEY` (required when `LLM_PROVIDER=anthropic`)\n- `ANTHROPIC_BASE_URL` (default `https://api.anthropic.com/v1`)\n- `ANTHROPIC_VERSION` (default `2023-06-01`)\n- `ANTHROPIC_MAX_TOKENS` (default `4096`)\n- `ANTHROPIC_MODEL` / `CLAUDE_MODEL`\n- `ANTHROPIC_MODEL_FAST`, `ANTHROPIC_MODEL_REASONING`, `ANTHROPIC_MODEL_TAGGER`, `ANTHROPIC_MODEL_PLANNER`, `ANTHROPIC_MODEL_ANALYZER`, `ANTHROPIC_MODEL_RESPONDER`, `ANTHROPIC_MODEL_SEARCH`, `ANTHROPIC_MODEL_MEMORY`\n- `ANTHROPIC_EMBEDDING_PROVIDER` (default `ollama` when `LLM_PROVIDER=anthropic`)\n- `HUGGINGFACE_API_KEY` / `HF_TOKEN` (required when `LLM_PROVIDER=huggingface`)\n- `HUGGINGFACE_BASE_URL` (default `https://router.huggingface.co`)\n- `HUGGINGFACE_MODEL` / `HF_MODEL`\n- `HUGGINGFACE_MODEL_FAST`, `HUGGINGFACE_MODEL_REASONING`, `HUGGINGFACE_MODEL_TAGGER`, `HUGGINGFACE_MODEL_PLANNER`, `HUGGINGFACE_MODEL_ANALYZER`, `HUGGINGFACE_MODEL_RESPONDER`, `HUGGINGFACE_MODEL_SEARCH`, `HUGGINGFACE_MODEL_MEMORY`\n- `HUGGINGFACE_EMBEDDING_MODEL` / `HF_EMBEDDING_MODEL`\n- `OLLAMA_MODEL` / `OMNI_MODEL` / `OMNI_CONVERSATION_MODEL` (default conversation fallback; CLI default `qwen2.5-coder:7b`)\n- `OLLAMA_MODEL_FAST`\n- `OLLAMA_MODEL_REASONING`\n- `OLLAMA_MODEL_TAGGER`\n- `OLLAMA_MODEL_ANALYZER`\n- `OLLAMA_MODEL_RESPONDER`\n- `OLLAMA_MODEL_SEARCH`\n- `OLLAMA_MODEL_MEMORY`\n- `OLLAMA_MODEL_PLANNER` / `OMNI_PLANNER_MODEL` (structured command planner; CLI default `qwen2.5-coder:14b`)\n- `OLLAMA_MODEL_EVALUATOR` / `OMNI_EVALUATOR_MODEL` (structured response self-evaluator; CLI default `qwen2.5:7b`)\n- `OLLAMA_MODEL_SPECIALIST_SHELL_EXECUTION` / `OMNI_SHELL_SPECIALIST_MODEL` (shell command specialist; CLI default `qwen2.5-coder:7b`)\n- `OLLAMA_MODEL_SPECIALIST_PLANNER`\n- `OLLAMA_MODEL_SPECIALIST_TOOLING`\n- `OLLAMA_MODEL_SPECIALIST_FILESYSTEM_RESEARCH`\n- `OLLAMA_MODEL_SPECIALIST_INTENT_TAGGING`\n- `OLLAMA_MODEL_SPECIALIST_MEMORY_RETRIEVAL`\n- `OLLAMA_MODEL_SPECIALIST_WEB_RESEARCH`\n- `OLLAMA_MODEL_SPECIALIST_ANALYSIS`\n- `OLLAMA_MODEL_SPECIALIST_RESPONSE`\n- `OLLAMA_MODEL_SPECIALIST_REVIEW_VERIFICATION`\n- `OLLAMA_MODEL_SPECIALIST_MEDIA_CONTROL`\n- `OLLAMA_MODEL_SPECIALIST_BROWSER_INSPECTION`\n- `OLLAMA_MODEL_SPECIALIST_SCREEN_VISION`\n- `OLLAMA_MODEL_SPECIALIST_AUDIO_NOTES`\n- `OLLAMA_MODEL_VISION` (used by `screen-read --vision`; default `llava:latest`)\n- `OMNI_EVALUATOR_THRESHOLD` (integer 0..100; default `70`)\n- `OMNI_PLANNER_NUM_CTX` (default `4096`)\n- `OMNI_EVALUATOR_NUM_CTX` (default `2048`)\n- `OMNI_DISABLE_EVALUATOR=true` disables the self-evaluator.\n- `STOP_ON_SUFFICIENT_CONTEXT=true|false` (skip web search in auto mode when memory context is already sufficient)\n- `SUFFICIENT_CONTEXT_CHARS=1400`\n- `MEMORY_INFERENCE_ENABLED=true|false`\n- `MEMORY_INFERENCE_MAX_ITEMS=3`\n- `TOURNAMENT_ENABLED=true|false` (default `true`; hierarchical long-context reduction)\n- `TOURNAMENT_CHUNK_CHARS=2200` (leaf chunk size)\n- `TOURNAMENT_SUMMARY_CHARS=750` (target output size per tournament summary)\n- `TOURNAMENT_MAX_ROUNDS=4` (recursive summarization cap)\n- `TOURNAMENT_VERIFY_RELEVANCE=true|false` (second-pass support check on original chunks)\n\n### Core runtime tuning\n\nEnvironment variables:\n- `WRAPPER_ONLY=true|false` (default `false`; when `true`, disables DB/worker/queue routes and exposes only stateless wrapper endpoints)\n- `WORKER_COUNT=3`\n- `WORKER_POLL_INTERVAL=2s`\n- `REQUEST_TIMEOUT=90s`\n- `REALTIME_MAX_CLIENTS=512` (caps live websocket/SSE subscriptions)\n- `REALTIME_STREAM_MAX_AGE=30m` (recycles browser realtime streams; clients reconnect automatically)\n- `REALTIME_HEARTBEAT=25s`\n- `REALTIME_WRITE_TIMEOUT=10s`\n- `RETRIEVAL_LIMIT=8`\n- `CONTEXT_CHAR_BUDGET=4000`\n- `HALLUCINATION_RETRY_LIMIT=2` (verification retries flagged as hallucination before forcing an Ollama restart attempt when provider is Ollama)\n- `OLLAMA_RESTART_COMMAND=` (optional command or `||`-separated fallback chain, e.g. `docker compose restart ollama || systemctl restart ollama`)\n- `OLLAMA_RESTART_TIMEOUT=20s` (per restart command timeout)\n- `MIGRATE_ON_STARTUP=true|false`\n\n## Host dependency bootstrap\n\nInstall host-side dependencies for core + local automations:\n\n```bash\ncd omnidex\n./scripts/setup-host-deps.sh --profile all -y\n```\n\n`--profile local` now includes networking diagnostics tools used by chat automation (for example `ip/ifconfig`, `ss/netstat/lsof`, `dig/nslookup/host`, `traceroute`, `whois`, `nmap`, `nmcli` where available).\n\nInclude local whisper transcription support (`whisper` CLI via pip):\n\n```bash\n./scripts/setup-host-deps.sh --profile all --with-whisper -y\n```\n\nPreview only (no changes):\n\n```bash\n./scripts/setup-host-deps.sh --dry-run --profile all --with-whisper\n```\n\nmacOS uses the same shell script through Homebrew:\n\n```bash\nbrew install git go make curl jq ripgrep node docker docker-compose\n./scripts/setup-host-deps.sh --profile core -y\n```\n\nDocker on macOS still requires Docker Desktop or another running Docker engine; the Homebrew `docker` package only installs the client tools. Start Docker Desktop before running compose-backed core workflows.\n\nWindows has a native PowerShell dependency bootstrap for Git, Go, Node, Docker Desktop, jq, ripgrep, ffmpeg, VLC, Tesseract, Python, and optional Whisper:\n\n```powershell\nSet-ExecutionPolicy -Scope Process Bypass\n.\\scripts\\setup-host-deps.ps1 -Profile core -Yes\n.\\scripts\\setup-host-deps.ps1 -Profile all -WithWhisper -Yes\n```\n\nThe Windows script prefers `winget`, then Scoop, then Chocolatey. Local automation support on Windows is partial because Linux desktop tools such as `pactl`, `playerctl`, `iproute`, `nmcli`, and screenshot utilities do not map directly.\n\nBuild release archives for macOS and Windows from any host with Go installed:\n\n```bash\n./scripts/build-release.sh --version v0.3.0 --codename Venusaur --target darwin/arm64 --target windows/amd64\n```\n\nDefault release targets are Linux, macOS, and Windows for `amd64` and `arm64`; outputs are written to `dist/` with `SHA256SUMS`. The current release line is **`v0.3.0` Venusaur** (augmented planner \u0026 scrum). Previous releases: `v0.2.0` Ivysaur, `v0.1.0-alpha` Bulbasaur. Omnidex uses pride release codenames based on National Dex order. See [docs/RELEASE_VERSIONING.md](docs/RELEASE_VERSIONING.md).\n\n## Install to ~/.omnidex\n\nInstall Omnidex into a user-local directory (default: `~/.omnidex`), build binaries, install dependencies, and auto-load aliases on shell startup:\n\n```bash\n./install.sh\n```\n\nThe installer places `omni` in `~/.omnidex/bin` and prepends that directory to `PATH` through the managed shell-init block. Running `omni` from any directory uses that shell directory as the active working directory for deterministic file and command work.\n\nNon-interactive install with explicit flags:\n\n```bash\n./install.sh --prefix ~/.omnidex --deps-profile all --yes\n```\n\nUpdate an existing Omnidex repo/install to latest and rebuild the core Docker image:\n\n```bash\ncd ~/.omnidex\n./update.sh\n```\n\nFrom any directory after install, the same managed updater is available through `omni`:\n\n```bash\nomni update\n```\n\nTo update only the installed source and host binaries (`omni`, `agent-cli`, `agent-core`) without requiring Docker Compose:\n\n```bash\nomni update --host-only\n```\n\nOptional update flags:\n\n```bash\n./update.sh --branch main --service core --no-cache\n```\n\nYou can run the same workflow via CLI command wrappers:\n\n```bash\nomni update --branch main --service core --no-cache\nacli build --race -v\nacli uninstall --yes\nacli migrate:fresh --yes\n```\n\nNotes:\n- Installer adds a managed shell-init block to existing `~/.bashrc`, `~/.bash_profile`, `~/.profile`, and `~/.zshrc` files (or creates one fallback file if none exist).\n- Shell-init block exports `OMNIDEX_DIR`, prepends `~/.omnidex/bin` to `PATH`, and sources `agent_aliases.sh`; this exposes the global `omni` binary plus `agent-cli` helper aliases.\n- `aupdate` runs `~/.omnidex/update.sh` through your loaded aliases.\n- `update.sh` expects `.git` in the install path; installer copies `.git` when installing from a git checkout. It pulls latest refs, refreshes installed script permissions, rebuilds host binaries, and restarts the host bridge user service when installed (`omni-host-bridge`).\n- Skip dependency install with `--skip-deps`.\n- Include whisper CLI bootstrap with `--with-whisper`.\n\nUninstall (remove shell-init integration + install directory):\n\n```bash\n./uninstall.sh\n```\n\nOptional uninstall flags:\n\n```bash\n./uninstall.sh --prefix ~/.omnidex --purge-config --yes\n```\n\n## Local dev\n\n```bash\ncd omnidex\ngo mod tidy\n./scripts/build-core.sh\ngo build -o bin/omni ./cmd/omni\ngo build -o bin/agent-cli ./cmd/cli\n```\n\nRun core locally:\n\n```bash\n# use a host-reachable Postgres instance for local core runs\nDATABASE_URL='postgres://agent:agent@localhost:5432/agent?sslmode=disable' \\\nOLLAMA_BASE_URL='http://localhost:11434' \\\n./core\n```\n\nIf you specifically need to use the compose-managed Postgres from the host, add a local `docker-compose.override.yml` that publishes `5433:5432`.\n\n## CLI walkthrough (with aliases)\n\nLoad helper aliases:\n\n```bash\nsource ./agent_aliases.sh\n```\n\nAlias note: `omni` preserves your shell working directory for deterministic local work. `acli` and the `a*` helper aliases preserve your working directory while targeting the queue/API CLI.\n\nInstall dependencies via alias:\n\n```bash\nasetupdeps --profile all -y\n```\n\nSet core URL (optional; defaults to `http://localhost:8090`):\n\n```bash\nasetcore http://localhost:8090\n```\n\nStart deterministic local chat:\n\n```bash\nomni\n# or explicitly:\nomni chat\n```\n\nThe deterministic CLI stores workspace sessions under `~/.omni/sessions`, run logs under `~/.omni/runs`, and uses the directory where you launched `omni` as the active working directory.\n\nLegacy queue/API chat remains available through `acli`:\n\n```bash\nacli chat --session daily-chat\n# architect profile (recommended for vague implementation requests):\n# acli chat --profile architect --session build-thread\n# live stage/event progress is shown by default (disable with --progress=false)\n# progress output is rendered as an activity timeline (Inspect/Explore/Run) during each turn\n# action confirmation is on by default: chat asks \"So you want me to...\" before execution (disable with --confirm-actions=false)\n# local capability routing is semantic (examples below are illustrative, not exact trigger phrases)\n# slash commands inside chat:\n# /help, /session, /session \u003cid\u003e, /new, /last, /exit\n# while waiting_input: /interrupt \u003c...\u003e, /replan \u003c...\u003e, /cancel [reason]\n# local media automation (enabled by default in chat):\n# \"play the next episode of star trek\"\n# \"what just happened in the show?\"\n# \"what did they just say about warp core?\"\n# local browser automation (enabled by default in chat):\n# \"show my open browser tabs\"\n# \"read the javascript console for 5 seconds\"\n# local screen automation (enabled by default in chat):\n# \"what's on my screen?\"\n# \"read my screen text\"\n# local shell automation (enabled by default in chat):\n# \"create a file named test\"\n# \"rename test to test-2\"\n# \"run `pwd`\"\n# \"run go test ./...\"\n# \"run docker compose up --build -d\"\n# local shell edit actions now include git diff summaries/snippets when in a git repo\n# \"walk me through current changes in this repo\"\n# \"where did I leave off in this project?\"\n# \"show changed files in chronological order\"\n# repo walkthrough can discover/select a nearby repo when you're not inside one\n# \"what is my ip?\"\n# \"what ports are open?\"\n# \"what ports are open with process names?\"   # requires sudo permission + sudo auth\n# \"determine my location based on my connection\"\n# \"am I on VPN right now?\"\n# \"show network tools catalog\"\n# \"install network tools\"                     # runs setup-host-deps local profile if script exists\n# \"what were we just talking about?\"          # uses recent same-session conversation context\n# host environment discovery (automatic):\n# OS, arch, distro, discovered package managers, available tools, and selected installed packages\n# capability snapshot is auto-synced to memory (procedural) for reuse in later planning/tooling steps\n\n# quick service status checks:\n# omni status\n# omni core:status\n# omni queue:status\n# omni ollama:status\n# omni web:status\n\n# service lifecycle controls (compose):\n# omni --service core up\n# omni --service core build\n# omni --service core restart\n# omni --service core down\n# omni service:core logs --follow\n# omni service --service all down\n# omni --service core migrate:fresh --yes\n\n# edit runtime config (.env) in vim:\n# omni config\n# omni config --editor \"vim\"\n# omni config --print\n```\n\nRun a typical end-to-end flow:\n\n1. Enqueue a job:\n\n```bash\naqd \"Design a migration plan for auth service split\"\n```\n\n2. Grab latest job id:\n\n```bash\nalast\n```\n\n3. Watch live progress with detailed step/context output:\n\n```bash\nawlatestv\n# or: awv \u003cjob-id\u003e\n```\n\n4. If the job asks for clarification/input:\n\n```bash\nafb \u003cjob-id\u003e \"Use PostgreSQL 16 and keep API surface unchanged.\"\n```\n\n5. If you want to steer a running step with extra context:\n\n```bash\naint \u003cjob-id\u003e \"Prefer minimal diffs and avoid new dependencies.\"\n```\n\n6. If you need a full replan from the `plan` step:\n\n```bash\nareplan \u003cjob-id\u003e \"Replan for a phased rollout with rollback checkpoints.\"\n```\n\n7. If you need to stop execution immediately:\n\n```bash\nacancel \u003cjob-id\u003e \"Cancel this run\"\n```\n\n8. Inspect final state/result:\n\n```bash\nashow \u003cjob-id\u003e\n```\n\n9. Continue the thread with a follow-up instruction:\n\n```bash\nacont \u003cjob-id\u003e \"Now draft the implementation tasks for sprint planning.\"\n```\n\n### Alias cheat sheet\n\n| Alias | Expands to |\n|---|---|\n| `omni ...` | deterministic local Omnidex CLI (`bin/omni` or `go run ./cmd/omni`) |\n| `omnidex ...` | same as `omni ...` |\n| `acli ...` | queue/API CLI (`agent-cli` or `go run ./cmd/cli`) |\n| `asetcore \u003curl\u003e` | `export CORE_URL=\u003curl\u003e` |\n| `asetupdeps ...` | `./scripts/setup-host-deps.sh ...` |\n| `aq \"...\"` | `enqueue --pipeline assistant --web auto --workspace auto` |\n| `aqf \"...\"` | `enqueue assistant + --reasoning fast` |\n| `aqd \"...\"` | `enqueue assistant + --reasoning deep` |\n| `aqarch \"...\"` | `enqueue --profile architect --pipeline assistant ...` |\n| `achat \"...\"` | `enqueue --pipeline chat --web auto --workspace auto` |\n| `achatarch ...` | `chat --profile architect ...` |\n| `achatrepl ...` | `chat ...` |\n| `astro \"...\"` | `enqueue --pipeline story --web auto --workspace auto` |\n| `alist` | `list` |\n| `arun` | `list --status running` |\n| `awaiting` | `list --status waiting_input` |\n| `ashow \u003cid\u003e` | `show \u003cid\u003e` |\n| `awatch \u003cid\u003e` | `watch \u003cid\u003e` |\n| `awv \u003cid\u003e` | `watch --interval 2s --verbose --max-chars 1600 \u003cid\u003e` |\n| `afb \u003cid\u003e \"...\"` | `feedback \u003cid\u003e \"...\"` |\n| `aint \u003cid\u003e \"...\"` | `interrupt \u003cid\u003e \"...\"` |\n| `areplan \u003cid\u003e \"...\"` | `replan \u003cid\u003e \"...\"` |\n| `acont \u003cid\u003e \"...\"` | `continue \u003cid\u003e \"...\"` |\n| `acancel \u003cid\u003e [\"reason\"]` | `cancel \u003cid\u003e [\"reason\"]` |\n| `aremember ...` | `remember ...` |\n| `aingest ...` | `ingest ...` |\n| `amediaindex ...` | `media-index ...` |\n| `amediasearch ...` | `media-search ...` |\n| `abrowserscan ...` | `browser-scan ...` |\n| `ascreenread ...` | `screen-read ...` |\n| `aresearch ...` | `research ...` |\n| `aperms ...` | `permissions ...` |\n| `anotes ...` | `audio-notes ...` |\n| `alast` | print latest job id |\n| `aslatest` | `show \u003clatest-id\u003e` |\n| `awlatest` | `watch \u003clatest-id\u003e` |\n| `awlatestv` | verbose `watch \u003clatest-id\u003e` |\n\n## CLI reference (raw commands)\n\nSet core URL (optional; default is `http://localhost:8090`):\n\n```bash\nexport CORE_URL=http://localhost:8090\n```\n\nQueue instructions:\n\n```bash\ngo run ./cmd/cli enqueue --pipeline assistant --web auto --workspace auto --approval auto --verify auto --verify-iterations 2 --session auth-thread \"Refactor auth flow and suggest migration plan\"\n# architect profile for end-to-end implementation pressure:\ngo run ./cmd/cli enqueue --profile architect --session auth-thread \"Implement the requested feature fully, run tests, and summarize verification evidence\"\n```\n\nInteractive chat mode:\n\n```bash\ngo run ./cmd/cli chat --session daily-chat --reasoning fast\n# architect profile (deep reasoning + workspace on + verify on + approval on + verbose):\n# go run ./cmd/cli chat --profile architect --session build-thread\n# disable local media automation if needed:\n# go run ./cmd/cli chat --local-media=false\n# disable local browser automation if needed:\n# go run ./cmd/cli chat --local-browser=false\n# disable local screen automation if needed:\n# go run ./cmd/cli chat --local-screen=false\n# disable local shell automation if needed:\n# go run ./cmd/cli chat --local-shell=false\n# disable local audio-notes automation if needed:\n# go run ./cmd/cli chat --local-audio=false\n```\n\nHost discovery metadata is attached automatically to `chat` and `enqueue` jobs:\n- `host_env_os`, `host_env_arch`, `host_env_kernel`, `host_env_distro`\n- `host_env_shell`, `host_env_user`, `host_env_identity`, `host_env_cwd`, `host_env_package_manager`, `host_env_package_managers`\n- `host_clock_local`, `host_clock_utc`, `host_clock_tz`, `host_clock_weekday`, `host_clock_epoch`\n- `host_tools_available`\n- `host_packages_installed` (lightweight curated package probe)\n\nChat sessions also include short-term recent conversation context (same `session_id`) in plan/analyze/response prompts so follow-up questions can reference what was just discussed.\nFinal model responses now include a `Sources:` section by default, summarizing which context blocks were used (instruction, recent conversation, retrieval, workspace, web search, tooling, and executed tests when applicable).\n\nTime-sensitive instructions (`latest`, `today`, `as of`, `current`, etc.) are treated as freshness-sensitive:\n- web-search auto mode prefers fresh search for those requests\n- local clock/date-only questions (e.g., \"what time is it\") use host clock context without forcing web search\n\nChat-mode controls (entered at the prompt):\n- `/help`, `/session`, `/session \u003cid\u003e`, `/new`, `/last`, `/exit`\n- During waiting input: `/interrupt \u003c...\u003e`, `/replan \u003c...\u003e`, `/cancel [reason]`, or plain feedback text\n\nLocal invasive-tool permissions are stored in one registry file (default: `~/.config/omni/permissions.json`, with fallback to `.omni/permissions.json` if needed):\n\n```bash\ngo run ./cmd/cli permissions list\ngo run ./cmd/cli permissions grant local.shell.exec\ngo run ./cmd/cli permissions grant local.shell.sudo\ngo run ./cmd/cli permissions grant local.screen.capture\ngo run ./cmd/cli permissions deny local.browser.console\ngo run ./cmd/cli permissions unset local.screen.capture\n```\n\nForce web-search on a job (or turn it off):\n\n```bash\ngo run ./cmd/cli enqueue --pipeline assistant --web on \"Find current PostgreSQL 16 pgvector indexing guidance\"\ngo run ./cmd/cli enqueue --pipeline assistant --web off \"Rewrite this paragraph\"\n```\n\nControl reasoning depth per job:\n\n```bash\ngo run ./cmd/cli enqueue --pipeline assistant --reasoning deep \"Design migration strategy with tradeoffs\"\ngo run ./cmd/cli enqueue --pipeline assistant --reasoning fast \"Summarize this note in 3 bullets\"\n```\n\nOverride step models per job when needed:\n\n```bash\ngo run ./cmd/cli enqueue --pipeline assistant --reasoning deep --model-plan llama3.2 --model-analyze llama3.2 --model-response llama3.1:8b \"Compare tradeoffs and draft final recommendation\"\n```\n\nQueue-level behavior controls via metadata:\n- `workspace_scan`: `auto|on|off`\n- `allow_missing_tools`: `true|false`\n- `approval_mode`: `auto|force|off`\n- `verification_mode`: `auto|force|off`\n- `verification_iterations`: `1..4`\n- `hallucination_retry_limit`: `1..6` (overrides `HALLUCINATION_RETRY_LIMIT` per job)\n- `ollama_restart_command`: optional command or `||`-separated fallback chain\n- `session_id`: string\n\nEquivalent CLI flags:\n- `--workspace auto|on|off`\n- `--allow-missing-tools`\n- `--approval auto|on|off`\n- `--verify auto|on|off`\n- `--verify-iterations 1-4`\n- `--session \u003cid\u003e`\n\nWhen `--workspace on` is used and workspace settings are missing, the job pauses and asks for corrected workspace config or confirmation to continue without scan.\n\nList jobs:\n\n```bash\ngo run ./cmd/cli list --status running\n```\n\nInspect one job:\n\n```bash\ngo run ./cmd/cli show 12\n```\n\nWatch job progress:\n\n```bash\ngo run ./cmd/cli watch --interval 2s 12\n# live stage/event progress is on by default (disable with --progress=false)\n```\n\nWatch with detailed step outputs and context updates:\n\n```bash\ngo run ./cmd/cli watch --interval 2s --verbose --max-chars 1600 12\n```\n\nIf a job pauses for clarification/tooling input, continue it:\n\n```bash\ngo run ./cmd/cli feedback 12 \"Use the /srv/app workspace and proceed without playwright.\"\n```\n\nInterrupt a running job with extra context:\n\n```bash\ngo run ./cmd/cli interrupt 12 \"Prefer TypeScript, and keep changes backward compatible.\"\n```\n\nIf a step is currently running, `interrupt` preempts it and re-queues that step with the injected context.\n\nForce a full replan from the `plan` step:\n\n```bash\ngo run ./cmd/cli replan 12 \"Replan this for a phased rollout with rollback checkpoints.\"\n```\n\nKill switch for an in-flight job:\n\n```bash\ngo run ./cmd/cli cancel 12 \"No longer needed\"\n```\n\nContinue an existing thread/session with a follow-up instruction:\n\n```bash\ngo run ./cmd/cli continue 12 \"Now write implementation tasks for sprint planning.\"\n```\n\nApproval workflow for risky actions:\n\n```bash\ngo run ./cmd/cli enqueue --pipeline assistant --approval on \"Reset production DB and recreate schema\"\n# when prompted:\ngo run ./cmd/cli feedback 12 \"APPROVE: execute only after backup verification\"\n```\n\nSeed memory with tags and kind:\n\n```bash\ngo run ./cmd/cli remember --kind instruction --tags auth,oauth \"Always rotate refresh tokens before access token expiry.\"\n```\n\nIngest files directly into reference memory (supports `.pdf`, `.docx`, `.srt`, `.vtt`, and text-like files):\n\n```bash\ngo run ./cmd/cli ingest --kind reference --tags lore,book ./docs/worldbook.pdf\ngo run ./cmd/cli ingest --kind reference --tags subtitles ./media/episode01.srt\n```\n\nIndex an entire media library into memory using subtitle files (episode metadata + timestamped subtitle chunks):\n\n```bash\ngo run ./cmd/cli media-index --root ~/Media/StarTrek --source media --tags tv,subtitles\n# preview only:\ngo run ./cmd/cli media-index --root ~/Media/StarTrek --dry-run\n```\n\nSearch subtitle lines directly with surrounding context:\n\n```bash\ngo run ./cmd/cli media-search --root ~/Media/StarTrek --context 2 --limit 20 \"engage\"\n```\n\nScan local browser processes and read debuggable tabs:\n\n```bash\ngo run ./cmd/cli browser-scan\ngo run ./cmd/cli browser-scan --json\n```\n\nCapture live JavaScript console events from debuggable tabs:\n\n```bash\ngo run ./cmd/cli browser-scan --console --seconds 5 --limit 120\n```\n\nNote: tab URL and console capture requires a browser exposing a local DevTools endpoint (for example Chromium with `--remote-debugging-port=9222`).\n\nRead the current screen (OCR text and optional vision summary):\n\n```bash\ngo run ./cmd/cli screen-read --ocr\ngo run ./cmd/cli screen-read --vision --model llava:latest\ngo run ./cmd/cli screen-read --ocr --vision --prompt \"focus on error messages and active window\"\n```\n\nNote: screen capture needs a local screenshot utility (`grim`, `gnome-screenshot`, `maim`, `scrot`, or ImageMagick `import`). OCR needs `tesseract`.\nScreen/browser/media invasive actions prompt once for permission and persist decisions in the permissions registry.\n\nLong-running call notes from mic/speaker audio (capture now, stop later, then transcript + memory):\n\n```bash\ngo run ./cmd/cli audio-notes doctor\ngo run ./cmd/cli audio-notes start --mic --speaker\n# ... after your call:\ngo run ./cmd/cli audio-notes stop --store-memory --tags meeting,notes\ngo run ./cmd/cli audio-notes search \\\"action items\\\"\n```\n\nThis stores timestamped quotes with source (`mic` / `speaker`) under `.omni/audio-notes/\u003csession\u003e/`.\nIn interactive `chat`, you can also use natural commands like `take notes during this call`, `stop taking notes`, and `notes status` when `--local-audio` is enabled (default).\n\nBuild a long-lived knowledge base for a topic (auto web research + memory ingest + freshness tracking):\n\n```bash\ngo run ./cmd/cli research --tags games,rpg --refresh-days 14 \"Cyberpunk 2077\"\n# force a refresh even if still fresh:\ngo run ./cmd/cli research --force \"Cyberpunk 2077\"\n```\n\nThis stores chunked research memories with topic tags and writes freshness metadata to `.omni/research-index.json`.\n\n## API endpoints\n\n### Project planner \u0026 scrum (Venusaur)\n\n- `GET /v1/projects/{id}/planning-chat`\n- `POST /v1/projects/{id}/planning-chat`\n- `PATCH /v1/projects/{id}/planning-chat`\n- `POST /v1/projects/{id}/planning-chat/drafts`\n- `GET/PUT /v1/scrum`\n- `POST /v1/scrum/cards`\n- `POST /v1/scrum/cards/{id}/play|pause|move|chat|coach|…`\n- `GET /v1/scrum/flow-metrics`\n\nSee [docs/SCRUM_PLANNER.md](docs/SCRUM_PLANNER.md).\n\n### Data sources and human-language querying\n\n- `GET /v1/data-sources`\n- `GET /v1/data-sources/{id}/channels`\n- `POST /v1/data-sources/{id}/channels`\n- `GET /v1/data-sources/{id}/channels/{channelID}/messages`\n- `POST /v1/data-sources/{id}/channels/{channelID}/messages`\n- `GET /v1/admin/data-sources`\n- `POST /v1/admin/data-sources`\n- `PUT /v1/admin/data-sources/{id}`\n- `DELETE /v1/admin/data-sources/{id}`\n- `POST /v1/admin/data-sources/{id}/test`\n- `GET /v1/admin/data-sources/{id}/schema`\n- `GET /v1/admin/data-sources/{id}/catalog`\n- `POST /v1/admin/data-sources/{id}/explore`\n- `POST /v1/admin/data-sources/{id}/query`\n- `POST /v1/admin/data-sources/{id}/ask`\n\n### Core jobs \u0026 wrappers\n\n- `GET /healthz`\n- `POST /v1/instruct` (stateless prompt wrapper)\n- `POST /v1/roleplay` (stateless in-character wrapper)\n- `POST /v1/narrate` (stateless narration wrapper)\n- `POST /v1/reasoning` (3-stage stateless reasoning chain: parse -\u003e deliberate -\u003e final)\n- `POST /v1/jobs`\n- `GET /v1/jobs?status=\u0026limit=\u0026offset=`\n- `GET /v1/jobs/{id}`\n- `POST /v1/jobs/{id}/feedback`\n- `POST /v1/jobs/{id}/interrupt`\n- `POST /v1/jobs/{id}/replan`\n- `POST /v1/jobs/{id}/cancel`\n- `POST /v1/memory`\n\nWhen `WRAPPER_ONLY=true`, only `/healthz`, `/v1/instruct`, `/v1/roleplay`, `/v1/narrate`, and `/v1/reasoning` are registered.\n\n### Example stateless wrapper body\n\n```json\n{\n  \"model\": \"llama3.2\",\n  \"system\": \"You are the narrator for a grounded fantasy scene.\",\n  \"prompt\": \"Narrate what happens when the ranger opens the vault door.\",\n  \"context\": {\n    \"setting\": \"Ancient underground vault\",\n    \"characters\": [\"Ranger\", \"Scholar\"],\n    \"event_history\": [\"They bypassed the rune lock\", \"A low hum started in the chamber\"]\n  },\n  \"history\": [\n    {\"role\": \"user\", \"content\": \"The ranger checks for traps.\"},\n    {\"role\": \"assistant\", \"content\": \"She finds a hidden wire and cuts it safely.\"}\n  ]\n}\n```\n\n### Instruct integration: enqueue jobs/tasks\n\n`/v1/instruct` can optionally bridge into the async job queue by sending an `integration` block.\nWhen present, Omnidex will queue a job and return an integration payload (instead of running the stateless LLM wrapper path).\n\n```json\n{\n  \"prompt\": \"Create a migration plan for splitting monolith services\",\n  \"integration\": {\n    \"action\": \"enqueue_job\",\n    \"pipeline\": \"assistant\",\n    \"metadata\": {\n      \"source\": \"instruct-route\",\n      \"web_search\": \"auto\",\n      \"reasoning_level\": \"deep\"\n    }\n  }\n}\n```\n\nSupported integration actions:\n- `enqueue_job` (aliases: `queue_job`, `enqueue_task`, `job`, `task`)\n\nNotes:\n- `integration.instruction` can override `prompt`; otherwise `prompt` is used as the queued instruction.\n- `integration.pipeline` defaults to `assistant`.\n- `integration.metadata` must be a JSON object.\n- Queue integration requires DB/worker mode (`WRAPPER_ONLY=false`).\n\n### Example enqueue body\n\n```json\n{\n  \"instruction\": \"Create a migration plan for splitting monolith services\",\n  \"pipeline\": \"assistant\",\n  \"metadata\": {\n    \"source\": \"cli\",\n    \"web_search\": \"auto\",\n    \"search_query\": \"postgresql 16 pgvector indexing best practices\",\n    \"reasoning_level\": \"deep\",\n    \"workspace_scan\": \"auto\",\n    \"allow_missing_tools\": false,\n    \"approval_mode\": \"auto\",\n    \"verification_mode\": \"auto\",\n    \"verification_iterations\": 2,\n    \"hallucination_retry_limit\": 2,\n    \"session_id\": \"auth-thread\",\n    \"model_plan\": \"llama3.2:latest\",\n    \"model_analyze\": \"llama3.2:latest\",\n    \"model_response\": \"llama3.1:8b\"\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccordine%2Fomnidex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccordine%2Fomnidex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccordine%2Fomnidex/lists"}