OwlCoda

English · 中文

From evidence to an admitted business result — with replaceable AI executors and explicit authority boundaries.

OwlCoda is being built as a local-first AI Business Execution System. It owns the business semantics and causal transaction boundaries that turn point-in-time evidence into a reviewable result. Models and coding agents are replaceable executors; an executor session is not the product identity.

The current public release, owlcoda@0.18.0, is the runtime and harness foundation of that direction. Today it is a useful local AI coding workbench: a native terminal REPL with 42+ tools, 69+ slash commands, session persistence, learned skills, model routing, and production-grade middleware. It does not claim that the full business-execution product, production connectors, or BusinessAction authority are publicly shipped.

Privacy by default. Sessions stay in ~/.owlcoda/. There is no OwlCoda account and no OwlCoda server. Training-data collection is opt-in (off by default), PII-sanitized before it touches disk, and never uploaded.

Product direction

OwlCoda keeps each promotion explicit:

Evidence
  -> WorkCase
  -> Execution Admission
  -> Execution / Attempt
  -> replaceable Executor
  -> Result Candidate
  -> Result Admission
  -> WorkResult
  -> Qualification
  -> Human Review
  -/-> BusinessAction (separate authority required)

Passing one stage never silently grants the next. OwlRunKit makes delivery progression verifiable, transferable, and recoverable across agents and sessions, but it never becomes OwlCoda's Business Truth or grants Git, release, deployment, production, money, automation, or business authority.

One control plane for every model

owlcoda admin opens a browser console where you wire up any model and OwlCoda routes to it. Cloud brands connect in one click — Kimi, DeepSeek, GPT, Claude, Gemini, Grok, GLM, MiniMax — with the endpoint, default model, and aliases filled in from a template; paste a key and you're live. Anything else — a model on your own machine or any custom OpenAI-/Anthropic-compatible endpoint — goes through the custom lane. Routing, fallback, health, cost, and audit all sit behind the same console.

Install

npm install -g owlcoda@latest
owlcoda            # first run opens setup when no model is configured
owlcoda admin      # browser admin: configure a local runtime or cloud provider

Requirements: Node.js >=20.19.0 (Node 22+ recommended) and one LLM backend — a local runtime (Ollama / LM Studio / vLLM / any OpenAI-compatible endpoint) or a cloud provider's API key.

If your global npm prefix isn't writable, use a user-level prefix:

npm config set prefix ~/.local && export PATH=~/.local/bin:$PATH
npm install -g owlcoda@latest

Quickstart — owlmlx local runtime

With owlmlx already running on :8066, initialize OwlCoda against that runtime:

owlcoda init --endpoint http://127.0.0.1:8066
owlcoda

OwlCoda's committed local default is owlmlx on http://127.0.0.1:8066. Ollama uses http://127.0.0.1:11434/v1; LM Studio uses http://127.0.0.1:1234/v1; vLLM uses http://127.0.0.1:8000/v1. Cloud providers are configured in owlcoda admin.

Images and Kimi K2.7

Vision-capable OpenAI-compatible models can receive local images from the REPL. Paste a local image path, insert one with @image.png, or use a Markdown image reference like ![shot](./shot.png); OwlCoda sends the image as a base64 multimodal content block. Supported extensions are png, jpg/jpeg, webp, and gif.

For Kimi K2.7 Code, set MOONSHOT_API_KEY or add the Kimi K2.7 Code provider in owlcoda admin, then use --model kimi27 or --model kimi-k2.7-code.

Don't start by asking it to rewrite a large project. In a repo you know, begin read-only, then give it one small, clearly-scoped change:

cd your-project
owlcoda -p "Read this project and tell me the entry point, test command, and main directories. Do not modify files."

What the current public runtime provides

The 0.18 runtime sits between your models and your real project. The model can act, but every action passes through a boundary, leaves an artifact, and is recorded — so a long-running agent is not trusted on its word alone.

• Bring your own models. Local runtimes and cloud providers collapse into one model registry with routing, fallback, retry, circuit-breaking, and per-model timeouts.
• Native REPL. 42+ tools (Bash, Read/Write/Edit, Glob, Grep, Task, MCP-served tools, agent dispatch) and 69+ slash commands, with session persistence, search, tags, and branching.
• Learned skills. Complex sessions are distilled into reusable skills and matched back into the system prompt on similar tasks. Manage them with owlcoda skills.
• Training-data pipeline (opt-in). Sessions can be scored, PII-sanitized, and exported to local JSONL for fine-tuning — off by default, local-only.
• Browser admin & diagnostics. owlcoda admin for model configuration; owlcoda doctor / health / audit / inspect for runtime diagnostics.

Capability labels (supported / partial / manual-only / unsupported) are declared in src/capabilities.ts and kept honest against runtime behavior.

Product truth and distribution authority live in docs/PRODUCT-TRUTH.md.

Common commands

owlcoda                          # interactive REPL (native)
owlcoda -m fast                  # pick a model by id / alias / partial match
owlcoda -p "list all .ts files"  # headless (non-interactive)
owlcoda init                     # write config.json (auto-detects models)
owlcoda admin                    # browser admin
owlcoda doctor [--json]          # environment diagnostics; JSON includes build/schema identity
owlcoda models                   # tiered model list + route probing
owlcoda --resume last            # resume the previous session
owlcoda skills                   # list learned skills
owlcoda --help                   # full command list

Configuration

owlcoda init writes config.json; see config.example.json for the full shape. If a platform catalog.json is reachable, models load automatically with no manual models array.

{
  "port": 8019,
  "routerUrl": "http://127.0.0.1:8066",
  "models": [
    {
      "id": "Qwen3.6-27B",
      "label": "Qwen3.6 27B (owlmlx)",
      "backendModel": "Qwen3.6-27B",
      "endpoint": "http://127.0.0.1:8066/v1",
      "aliases": ["balanced", "default"],
      "default": true
    }
  ]
}

Kimi CLI, Cursor Agent CLI, and Codex CLI can be registered explicitly as bounded model executors for POST /v1/structured-output:

{
  "models": [
    {
      "id": "kimi-cli",
      "label": "Kimi CLI",
      "backendModel": "kimi-code/kimi-for-coding",
      "aliases": ["kimi-cli"],
      "tier": "custom",
      "executor": { "kind": "kimi-cli", "executable": "kimi" }
    },
    {
      "id": "cursor-agent",
      "label": "Cursor Agent CLI",
      "backendModel": "auto",
      "aliases": ["cursor-agent"],
      "tier": "custom",
      "executor": { "kind": "cursor-agent", "executable": "cursor-agent" }
    },
    {
      "id": "codex-cli",
      "label": "Codex CLI",
      "backendModel": "gpt-5.6-sol",
      "aliases": ["codex-cli"],
      "tier": "custom",
      "executor": { "kind": "codex-cli", "executable": "codex" }
    }
  ]
}

Use model aliases available in the installed CLIs. These routes are non-streaming, local-read-only structured-output calls; they do not expose a general coding-agent or arbitrary command API. GET /v1/models reports each configured CLI's executable, version, and authentication availability.

Selected environment variables:

Variable	Purpose	Default
OWLCODA_PORT	Proxy listen port	8019
OWLCODA_HOME	Data directory	~/.owlcoda
OWLCODA_LOG_LEVEL	Log level	info
OWLCODA_RENDER_MODE	safe (per-line repaint, default) or diff	safe

Known limitations

• Transcript scrollback isn't wired to the mouse wheel yet under terminal multiplexers (tmux/screen). Use PgUp / PgDn / Ctrl+↓ or /history inside the app.
• Streaming cross-model fallback stops after visible output — connection, 5xx, and pre-first-token failures can continue on an eligible model when automatic fallback is enabled. Mid-stream failures stay explicit to avoid replaying or mixing output from different models.
• /cost USD figures are a reference only — local inference is effectively free; the dollar number uses cloud pricing for comparison.
• LSP tools need a language server you install yourself (e.g. typescript-language-server, pyright, rust-analyzer, gopls), wired via plugin config.
• Remote OAuth MCP servers aren't supported yet; stdio MCP servers (via .mcp.json) work.

HTTP API

The proxy exposes an Anthropic-compatible POST /v1/messages and an OpenAI-compatible POST /v1/chat/completions, plus GET /v1/models, /metrics (Prometheus), /health, and /openapi.json. The full surface is reflected in GET /openapi.json.

License

From the 0.15.0 boundary, OwlCoda source is released under GPL-3.0-or-later. Commercial, OEM, or embedded distribution uses a separate license handled by the maintainer.

This repository is the public source, issue, release, and trust surface for GPL releases. npm packages may ship compiled dist/ only; see SOURCE.md for the corresponding-source requirement. Historical published versions keep the license they were published under.

Links

• Website: owlcoda.com
• Delivery continuity: OwlRunKit
• Issues & PRs: github.com/yeemio/owlcoda/issues
• Contributing: CONTRIBUTING.md · Security: SECURITY.md
• Demo: World Cup predictor — a five-role model debate (recon, vision, pro, anti, judge) orchestrated through OwlCoda

Development

npm run dev     # tsx hot-reload
npm test        # run tests
npm run build   # TypeScript compile