@lovenyberg/ove 0.1.1 → 0.2.1

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Ove
 
-Your grumpy but meticulous dev companion — routes chat messages to Claude Code CLI in isolated worktrees.
+Your grumpy but meticulous dev companion — routes chat messages to AI coding agents (Claude Code CLI or OpenAI Codex CLI) in isolated worktrees.
 
 ## Stack
 - Bun + TypeScript
@@ -11,12 +11,13 @@ Your grumpy but meticulous dev companion — routes chat messages to Claude Code
 - Bun.serve for HTTP API + Web UI
 - gh CLI for GitHub polling
 - bun:sqlite for task queue
-- claude -p CLI for code tasks
+- claude -p CLI for code tasks (default runner)
+- codex exec CLI for code tasks (alternative runner)
 
 ## Structure
 - src/adapters/ — chat platform adapters (Slack, WhatsApp, Telegram, Discord, CLI) and event adapters (GitHub, HTTP API)
 - src/queue.ts — SQLite task queue
-- src/runners/ — agent runner implementations (Claude, future Codex)
+- src/runners/ — agent runner implementations (Claude, Codex)
 - src/repos.ts — git clone/pull/worktree management
 - src/router.ts — message → task mapping
 - src/config.ts — repo/user configuration

package/README.md

@@ -13,6 +13,8 @@
 
 Talk to Ove from Slack, WhatsApp, Telegram, Discord, GitHub issues, a Web UI, or the terminal — he'll grumble about it, but he'll review your PRs, fix your issues, run your tests, brainstorm ideas, and scaffold new projects. Properly.
 
+**Just chat.** You don't need to memorize commands. Talk to Ove like you'd talk to a colleague — ask questions, describe what you need, paste error messages, think out loud. He understands natural language. The commands below are shortcuts, not requirements.
+
 ## Quick Start
 
 ```bash
@@ -23,11 +25,23 @@ ove start
 
 ## Prerequisites
 
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (default runner)
+- Or [OpenAI Codex CLI](https://github.com/openai/codex) installed and authenticated (alternative runner)
 - [GitHub CLI](https://cli.github.com) (`gh`) installed and authenticated
 - SSH access to your git repos
 
-## Commands
+## Usage
+
+Talk to Ove the way you'd talk to a teammate. These all work:
+
+```
+"can you check what's failing in the auth tests on my-app?"
+"the login page is broken, users get a 500 after submitting"
+"how does the payment webhook work in my-app?"
+"refactor the user service, it's getting messy"
+```
+
+Ove figures out the intent, picks the right repo, and gets to work. For common tasks, there are also shorthand commands:
 
 ```
 review PR #N on <repo>      Code review with inline comments
@@ -60,7 +74,7 @@ ove init
 ove start
 ```
 
-Requires [Bun](https://bun.sh), Claude Code CLI, and GitHub CLI on your machine.
+Requires [Bun](https://bun.sh), Claude Code CLI (or Codex CLI), and GitHub CLI on your machine.
 
 ### Docker
 
@@ -70,11 +84,11 @@ docker compose up -d        # start container
 docker compose logs -f      # watch logs
 ```
 
-The image includes Bun, git, and Claude CLI. Mounts `config.json`, `.env`, `repos/`, and SSH keys from the host.
+The image includes Bun, git, and Claude CLI (install Codex CLI separately if needed). Mounts `config.json`, `.env`, `repos/`, and SSH keys from the host.
 
 ### VM
 
-Ove runs well on a small VM (2 CPU, 4 GB RAM). Install Bun, Claude Code, and GitHub CLI, then run as a systemd service:
+Ove runs well on a small VM (2 CPU, 4 GB RAM). Install Bun, Claude Code (or Codex CLI), and GitHub CLI, then run as a systemd service:
 
 ```bash
 git clone git@github.com:jacksoncage/ove.git && cd ove
@@ -146,6 +160,7 @@ sudo systemctl enable --now ove
     "cli:local": { "name": "alice", "repos": ["my-app"] }
   },
   "claude": { "maxTurns": 10 },
+  "runner": { "name": "claude" },
   "cron": [
     {
       "schedule": "0 9 * * 1-5",
@@ -157,6 +172,23 @@ sudo systemctl enable --now ove
 }
 ```
 
+### Runner Selection
+
+By default Ove uses Claude Code CLI. To use OpenAI Codex instead, set the `runner` field globally or per-repo:
+
+```json
+{
+  "runner": { "name": "codex", "model": "o3" },
+  "repos": {
+    "my-app": {
+      "runner": { "name": "claude" }
+    }
+  }
+}
+```
+
+Per-repo `runner` overrides the global default. Supported runners: `"claude"` (default), `"codex"`.
+
 Static cron jobs go in `config.json`. Users can also create schedules via chat — these are stored in SQLite and managed with `list schedules` / `remove schedule #N`.
 
 ## Testing
@@ -172,7 +204,7 @@ bun test    # 150 tests
 3. Router parses intent and extracts repo/args
 4. Task gets queued in SQLite (one per repo at a time)
 5. Worker creates an isolated git worktree
-6. Runs `claude -p` with streaming NDJSON output
+6. Runs the configured agent runner (`claude -p` or `codex exec`) with streaming JSON output
 7. Status updates stream back (chat: edits a message, HTTP: SSE, GitHub: single comment)
 8. Result sent back, worktree cleaned up
 

package/bin/ove.ts

@@ -1,10 +1,28 @@
 #!/usr/bin/env bun
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { validateConfig, runSetup } from "../src/setup";
 
+async function checkForUpdate(): Promise<void> {
+  try {
+    const pkgPath = join(import.meta.dir, "..", "package.json");
+    const { name, version: current } = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) return;
+    const { version: latest } = await res.json() as { version: string };
+    if (latest && latest !== current) {
+      process.stdout.write(`\n  Update available: ${current} → ${latest}\n`);
+      process.stdout.write(`  Run: npm install -g ${name}\n\n`);
+    }
+  } catch {
+    // Silent fail — don't block startup for update checks
+  }
+}
+
 const args = process.argv.slice(2);
 const command = args[0];
 
@@ -23,7 +41,8 @@ if (command === "init") {
 }
 
 if (command === "start" || !command) {
-  process.stdout.write("\n  Checking config...\n");
+  await checkForUpdate();
+  process.stdout.write("  Checking config...\n");
   const { valid, issues } = validateConfig();
 
   if (!valid) {

package/config.example.json

@@ -18,6 +18,9 @@
   "claude": {
     "maxTurns": 25
   },
+  "runner": {
+    "name": "claude"
+  },
   "mcpServers": {
     "filesystem": {
       "command": "npx",

package/docs/examples.md

@@ -1,8 +1,56 @@
 # Example Interactions
 
-Examples showing Ove across different transports and command types.
+Examples showing Ove across different transports. You can use shorthand commands or just chat naturally — Ove understands both.
 
-## PR Review
+## Natural Conversation
+
+You don't need commands. Just describe what you need, like you'd tell a colleague.
+
+**Slack DM:**
+```
+alice: the login page is broken, users get a 500 after submitting the form
+ove:   Task queued (aaa11111). Working on it...
+       > Grep: "login" in src/
+       > Read: src/routes/auth.ts
+       > Read: src/middleware/session.ts
+ove:   Found the issue — the session middleware wasn't awaiting the
+       database call on line 34 of src/middleware/session.ts. Created
+       PR #47 with the fix and added a test:
+       https://github.com/org/my-app/pull/47
+```
+
+**Telegram:**
+```
+alice: can you add input validation to the user registration endpoint in my-app?
+ove:   Task queued (bbb22222). Working on it...
+       > Read: src/routes/users.ts
+       > Edit: src/routes/users.ts
+       > Write: src/routes/users.test.ts
+       > Bash: bun test
+ove:   Done. Added zod validation for email, password length, and
+       username format. All 48 tests pass. PR #48:
+       https://github.com/org/my-app/pull/48
+```
+
+**Discord:**
+```
+alice: how does the caching layer work in my-app? I need to understand
+       it before I make changes
+ove:   Looking into it...
+       > Glob: **/*cache*
+       > Read: src/cache/redis.ts
+       > Read: src/cache/keys.ts
+       > Read: src/middleware/cache.ts
+ove:   The caching layer has 3 parts:
+       1. src/cache/redis.ts — Redis client wrapper with connection pooling
+       2. src/cache/keys.ts — key generation with TTL per resource type
+       3. src/middleware/cache.ts — Express middleware that caches GET
+          responses by URL + user role
+       Cache invalidation happens on POST/PUT/DELETE via the afterWrite
+       hook in the base repository class.
+```
+
+## PR Review (shorthand)
 
 **Slack DM:**
 ```
@@ -128,7 +176,9 @@ alice: remove schedule #1
 ove:   Schedule #1 removed.
 ```
 
-## Free-form
+## More Free-form Examples
+
+Anything you type works. Ove parses intent from natural language.
 
 ```
 alice: what does the auth middleware do in my-app
@@ -143,6 +193,18 @@ ove:   The auth middleware in my-app:
        Located in src/middleware/auth.ts (42 lines).
 ```
 
+```
+alice: the CI is red on main, can you check what's going on?
+ove:   Task queued (ggg77777). Working on it...
+       > Bash: gh run list --limit 5
+       > Bash: gh run view 12345 --log-failed
+       > Read: src/api.test.ts
+ove:   The test "should return 404 for unknown routes" is failing
+       because the new /health endpoint was added without updating
+       the route count assertion. Line 89 in src/api.test.ts expects
+       12 routes but there are now 13. Want me to fix it?
+```
+
 ## HTTP API
 
 **Send a task via curl:**

package/docs/index.html

@@ -3,6 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" href="favicon.ico">
   <title>Ove — Your Grumpy Dev Companion</title>
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -593,8 +594,8 @@
       <h1>Ove</h1>
       <div class="hero-subtitle">Dev companion</div>
       <p class="hero-quote">
-        "Fine. I'll fix it. But I'm not happy about it."
-        <span>— Ove, on every pull request</span>
+        "Just tell me what's wrong. I'll figure it out."
+        <span>— Ove, on every conversation</span>
       </p>
       <div class="hero-actions">
         <a class="btn" href="#getting-started">Get started</a>
@@ -620,6 +621,15 @@
     <h2>What Ove Does</h2>
     <p class="section-note">He grumbles, but he gets it done. Properly.</p>
 
+    <p>Talk to Ove like you'd talk to a colleague. Ask questions, describe problems, paste error logs, think out loud &mdash; he understands natural language. No need to memorize commands. Just chat.</p>
+
+<pre data-label="just chat">"the login page throws a 500 after submitting"
+"can you check what's breaking the auth tests on my-app?"
+"how does the payment webhook work?"
+"refactor the user service, it's getting messy"</pre>
+
+    <p>Ove figures out the intent, picks the right repo, and gets to work. For common tasks, there are also shorthand commands &mdash; but they're shortcuts, not requirements.</p>
+
     <div class="features">
       <div class="feature">
         <div class="feature-label">01 &mdash; Review</div>
@@ -671,7 +681,8 @@
 
     <h3>Prerequisites</h3>
     <ol class="steps">
-      <li><a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code CLI</a> installed and authenticated</li>
+      <li><a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code CLI</a> installed and authenticated (default runner)</li>
+      <li>Or <a href="https://github.com/openai/codex">OpenAI Codex CLI</a> installed and authenticated (alternative runner)</li>
       <li><a href="https://cli.github.com">GitHub CLI</a> (<code>gh</code>) installed and authenticated</li>
       <li>SSH access to your Git repos</li>
     </ol>
@@ -721,6 +732,7 @@ sudo systemctl enable --now ove</pre>
     "cli:local": { "name": "alice", "repos": ["my-app"] }
   },
   "claude": { "maxTurns": 10 },
+  "runner": { "name": "claude" },
   "cron": [
     {
       "schedule": "0 9 * * 1-5",
@@ -731,6 +743,8 @@ sudo systemctl enable --now ove</pre>
   ]
 }</pre>
 
+    <p>Set <code>"runner"</code> globally to <code>{"name": "codex"}</code> to use OpenAI Codex, or override per-repo with a <code>"runner"</code> field inside the repo config. Supported runners: <code>claude</code> (default), <code>codex</code>.</p>
+
     <p>Static cron jobs go in <code>config.json</code>. Users can also create schedules from chat &mdash; just say something like <code>lint and check every day at 9</code>. These are stored in SQLite and managed with <code>list schedules</code> / <code>remove schedule #N</code>.</p>
 
     <div class="ove-says">
@@ -741,7 +755,7 @@ sudo systemctl enable --now ove</pre>
 
   <section class="section">
     <h2>Commands</h2>
-    <p class="section-note">Say what you need. Keep it simple. Ove doesn't do ambiguity.</p>
+    <p class="section-note">Shortcuts for common tasks. You can also just type what you need in plain language.</p>
 
     <dl class="cmd-grid">
       <dt>review PR #N on &lt;repo&gt;</dt>
@@ -782,7 +796,7 @@ sudo systemctl enable --now ove</pre>
       <li><span class="step-n">2</span><span class="step-arrow">&rsaquo;</span> Router parses intent and extracts repo/args</li>
       <li><span class="step-n">3</span><span class="step-arrow">&rsaquo;</span> Task gets queued in SQLite &mdash; one per repo at a time</li>
       <li><span class="step-n">4</span><span class="step-arrow">&rsaquo;</span> Worker creates an isolated git worktree</li>
-      <li><span class="step-n">5</span><span class="step-arrow">&rsaquo;</span> Runs <code>claude -p</code> with streaming NDJSON output</li>
+      <li><span class="step-n">5</span><span class="step-arrow">&rsaquo;</span> Runs the configured runner (<code>claude -p</code> or <code>codex exec</code>) with streaming JSON output</li>
       <li><span class="step-n">6</span><span class="step-arrow">&rsaquo;</span> Status updates stream back &mdash; chat edits, SSE, or GitHub comment</li>
       <li><span class="step-n">7</span><span class="step-arrow">&rsaquo;</span> Result sent back, worktree cleaned up</li>
     </ol>
@@ -846,7 +860,7 @@ sudo systemctl enable --now ove</pre>
     <p class="section-note">Pick your method. They all work. Ove doesn't care.</p>
 
     <h3>Docker</h3>
-    <p>The Dockerfile builds an image with Bun, git, openssh-client, and Claude CLI baked in. Just mount your config and go.</p>
+    <p>The Dockerfile builds an image with Bun, git, openssh-client, and Claude CLI baked in. Install Codex CLI separately if needed. Just mount your config and go.</p>
 <pre data-label="docker-compose.yml">services:
   ove:
     build: .
@@ -868,9 +882,12 @@ sudo systemctl enable --now ove</pre>
 <pre data-label="shell"># Bun
 curl -fsSL https://bun.sh/install | bash
 
-# Claude Code
+# Claude Code (default runner)
 npm install -g @anthropic-ai/claude-code
 
+# Or Codex CLI (alternative runner)
+# npm install -g @openai/codex
+
 # GitHub CLI
 sudo apt install gh
 gh auth login
@@ -915,7 +932,7 @@ journalctl -u ove -f</pre>
 </div>
 
 <footer>
-  Built by <a href="https://www.jacksoncage.se/">Love Billingskog Nyberg</a> &middot; Powered by <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>
+  Built by <a href="https://www.jacksoncage.se/">Love Billingskog Nyberg</a> &middot; Powered by <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> &amp; <a href="https://github.com/openai/codex">Codex</a>
 </footer>
 
 </body>

package/docs/plans/2026-02-21-codex-runner-design.md

@@ -0,0 +1,51 @@
+# Codex Runner Design
+
+Add OpenAI Codex CLI as a second agent runner alongside Claude Code CLI.
+
+## Config
+
+Global default runner + per-repo override:
+
+```json
+{
+  "runner": { "name": "claude" },
+  "repos": {
+    "my-app": {
+      "url": "git@github.com:user/my-app.git",
+      "defaultBranch": "main",
+      "runner": { "name": "codex", "model": "o3" }
+    }
+  }
+}
+```
+
+`RunnerConfig`: `{ name: "claude" | "codex"; model?: string }`. Defaults to `"claude"` if omitted.
+
+## New Types
+
+`RunnerConfig` added to `config.ts` on both `Config` (global) and `RepoConfig` (per-repo). `RunOptions` gets optional `model` field.
+
+## CodexRunner (`src/runners/codex.ts`)
+
+Implements `AgentRunner`. Spawns `codex exec --json --yolo --skip-git-repo-check --ephemeral -C <workDir> "prompt"`.
+
+Key differences from ClaudeRunner:
+- No `--max-turns` (exec mode runs one turn, unlimited tool calls)
+- No `--mcp-config` flag (Codex reads MCP from `~/.codex/config.toml`)
+- JSONL output format (one JSON object per line) instead of Claude's stream-json
+- Uses `CODEX_API_KEY` / `OPENAI_API_KEY` env vars
+
+JSONL event mapping to `StatusEvent`:
+- `item.completed` + `agent_message` -> `{ kind: "text" }` + final output
+- `item.started` + `command_execution` -> `{ kind: "tool", tool: "shell" }`
+- `item.started` + `file_change` -> `{ kind: "tool", tool: "file_change" }`
+- `item.started` + `mcp_tool_call` -> `{ kind: "tool", tool: <name> }`
+- `turn.failed` -> error output
+
+## Runner Selection (`index.ts`)
+
+Factory function creates runners by name. Per-task resolution: repo config -> global default -> "claude". Runners cached by name.
+
+## Unchanged
+
+`AgentRunner` interface, `RunResult`, `StatusEvent`, queue, router, adapters — all untouched.