omp

🤖 KB under OMP

Universal speedrun for running @dustinbyrne/kb under OMP against any target repo, with local-first access and optional password-protected dashboard exposure.

@dustinbyrne/kb is the aggressive Kanban option: the board does not just show work, it drives it. Tasks flow through triage, dependency-aware scheduling, isolated git worktrees, executor/reviewer agents, in-review, and optional auto-merge.

Use it when you want the board to keep OMP saturated with real repo work. Use pi-kanban when you only want session observability.

Access model#

KB itself serves the dashboard on its own HTTP port and, in @dustinbyrne/kb@0.4.1, does not provide a built-in dashboard password wall. It does expose auth endpoints for model/provider login, but that is not the same thing as protecting the board UI.

Use one of these patterns:

private/local-first
browser ── ssh tunnel / tailscale / local LAN ── kb on 127.0.0.1:4040

public/passworded
browser ── HTTPS + username/password ── reverse proxy ── kb on 127.0.0.1:4040

If you only need personal access, the first pattern is simpler. Use the reverse proxy only when you want a normal web URL with password protection.

Speedrun#

1. Start from the target repo root#

Run KB only from the exact repository it is allowed to mutate:

cd /path/to/your/repo

This is load-bearing. In @dustinbyrne/kb@0.4.1, KB uses process.cwd() as the repo root for task state, worktrees, and git operations.

KB stores state under that repo:

.kb/config.json
.kb/tasks/<KB-ID>/task.json
.kb/tasks/<KB-ID>/PROMPT.md
.kb/tasks/<KB-ID>/agent.log
.worktrees/<generated-name>/

If you start it from the wrong directory, .kb/ and .worktrees/ land in the wrong place and git actions target the wrong repo.

2. Preserve the Pi-facing contract, adapt at the OMP boundary#

Put runtime compatibility in environment, not in package source:

export PI_CODING_AGENT_DIR=/home/mc/.omp/agent
export PI_SKIP_VERSION_CHECK=true
export PI_DISCORD_ENV_FILE=/home/mc/.env

If a KB-adjacent plugin ever shell-spawns an agent, force it through OMP:

export PI_DISCORD_SPAWN_COMMAND=/home/mc/.local/bin/omp-plugin-env
export PI_DISCORD_SPAWN_ARGS=--allow-home

Important: @dustinbyrne/kb@0.4.1 creates agent sessions through @mariozechner/pi-coding-agent in-process. Verify that auth/session discovery uses the intended OMP-compatible state before letting it work on valuable branches.

3. Install#

Pi extension route:

pi install npm:@dustinbyrne/kb

Standalone route:

npm install -g @dustinbyrne/kb

Inside OMP, /kb starts the same dashboard/engine child process:

/kb          # default port 4040
/kb status
/kb stop
/kb 4041     # custom port

Standalone equivalent:

kb dashboard --port 4040 --no-open

4. Make it autonomous on purpose#

Defaults in 0.4.1 are already automation-forward:

{
  "maxConcurrent": 2,
  "maxWorktrees": 4,
  "pollIntervalMs": 15000,
  "groupOverlappingFiles": false,
  "autoMerge": true,
  "recycleWorktrees": false
}

Recommended high-autonomy baseline:

{
  "nextId": 1,
  "settings": {
    "globalPause": false,
    "enginePaused": false,
    "maxConcurrent": 2,
    "maxWorktrees": 4,
    "pollIntervalMs": 15000,
    "groupOverlappingFiles": true,
    "autoMerge": true,
    "recycleWorktrees": true,
    "worktreeInitCommand": "npm install",
    "includeTaskIdInCommit": true,
    "taskPrefix": "KB"
  }
}

Write it before first launch, or edit via the dashboard settings after launch:

mkdir -p .kb/tasks
$EDITOR .kb/config.json

Use groupOverlappingFiles: true for a busy autonomous board. It serializes tasks whose generated ## File Scope overlaps, reducing worktree merge fights without disabling parallel work.

5. Run KB locally first#

Start KB from the target repo on an internal port:

cd /path/to/your/repo
kb dashboard --port 4040 --no-open

Smoke checks:

curl -fsS http://127.0.0.1:4040/api/tasks
curl -fsS http://127.0.0.1:4040/api/settings

6. Pick an access path#

Option A: simplest personal access#

Keep KB local and reach it through an SSH tunnel, Tailscale, or another private transport. This is the simplest choice if you do not need a public URL.

Option B: normal web URL with simple username/password#

If you want “simple user/password”, put that in front of KB with a reverse proxy. The proxy is just the password/HTTPS front door:

browser -> proxy (password) -> kb on 127.0.0.1:4040

Nginx pattern:

server {
    listen 443 ssl http2;
    server_name kb.example.invalid;

    auth_basic "OMP KB";
    auth_basic_user_file /etc/nginx/htpasswd-kb;

    location / {
        proxy_pass http://127.0.0.1:4040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

Create the password file with your real username/password locally; do not write either into the wiki:

sudo htpasswd -c /etc/nginx/htpasswd-kb <user>
sudo nginx -t
sudo systemctl reload nginx

SSE needs proxy_buffering off and a long read timeout, otherwise live task/log updates appear flaky.

Whatever path you choose, do not expose raw KB directly to the internet. Keep public traffic forced through the passworded front door if you enable one.

7. Feed the board#

Create focused tasks from CLI:

kb task create "Audit the dashboard Socket.IO reconnect path and fix any stale-state bug"
kb task create "Add regression tests for relay contract parsing" --depends KB-001
kb task create "Review public wiki pages for stale OMP spawn guidance"

Or from chat:

Create a kb task to inspect moincraft/bots/dashboard for stale backend-status rendering. Keep scope to the dashboard UI and tests.

Good KB task prompts include:

- repo area
- observable bug or desired behavior
- files intentionally in scope
- verification command expected
- what must not be changed

Operating rules#

Let it run, but keep brakes live#

Pause all automation:

{
  "settings": {
    "globalPause": true
  }
}

Pause only new scheduling while current sessions finish:

{
  "settings": {
    "enginePaused": true
  }
}

Pause one task:

kb task pause KB-003

Resume:

kb task unpause KB-003

Keep auto-merge, with guardrails#

Auto-merge is the point of high autonomy, but do not let it merge blind changes into the wrong branch.

Before enabling it on a repo:

git branch --show-current
git status --short
kb task list

Then prove one disposable task end-to-end:

kb task create "Create and then remove a harmless KB smoke-test file; verify git status is clean after merge"

Accept auto-merge only after you have observed:

.kb/tasks/<id>/PROMPT.md exists
task moves triage → todo → in-progress → in-review → done
worktree lives under .worktrees/
commit includes the KB id
no unrelated files changed

Keep secrets out of tasks#

Attachments are stored under .kb/tasks/<id>/attachments/. Attach screenshots, logs, JSON, YAML, and text only after checking they do not contain keys, tokens, cookies, private session transcripts, or production credentials.

Verification checklist#

• kb dashboard --port 4040 --no-open starts from the intended target repo root.
• curl http://127.0.0.1:4040/api/settings returns settings locally.
• If using private/local-first access, the board is reachable only through the private path you chose.
• If using a public URL, that URL requires a password and direct public access to :4040 fails.
• If using a public URL, live updates still stream after a task changes.
• A smoke task creates .kb/tasks/<id>/ and a .worktrees/* worktree.
• Agent sessions use the intended OMP-compatible auth/env, not an unexpected ~/.pi default.
• groupOverlappingFiles is enabled before running parallel repo-wide work.
• Auto-merge has been proven on a disposable branch/task before live use.

Failure matrix#

Sources#

• https://pi.dev/packages/@dustinbyrne/kb
• https://raw.githubusercontent.com/dustinbyrne/kb/main/README.md
• @dustinbyrne/kb@0.4.1 package source (dist/bin.js, dist/extension.js)
• Pi Plugin Compatibility
• Kanban under OMP